윈도우에서 AI 코딩 도구 설치할 때 자주 막히는 지점: Cursor는 쉬운데 Claude Code가 꼬이는 이유

윈도우에서 AI 코딩 도구 설치할 때 자주 막히는 지점은 대개 도구 자체가 아니라 실행 환경이 둘로 갈라지는 문제입니다. Cursor나 VS Code의 GitHub Copilot은 윈도우 앱처럼 설치하면 끝나는 편이지만, Claude Code, Codex CLI, MCP 서버처럼 터미널을 많이 쓰는 도구는 WSL2, Node.js, Python, Git, 환경변수 위치가 맞지 않으면 바로 막힙니다.

Cursor와 Claude Code를 함께 쓸 예정이라면, 먼저 WSL 기준으로 프로젝트 폴더와 환경변수 위치를 정리한 뒤 설치를 시작하세요.

제가 윈도우 11 노트북에서 Cursor는 네이티브로 두고, Claude Code와 MCP 서버는 WSL2 Ubuntu 안에 몰아넣어 써보니 가장 안정적이었습니다. 결론부터 말하면 GUI 에디터는 윈도우에 설치하고, 에이전트 CLI와 개발 의존성은 WSL 안에서 관리하는 구성이 덜 꼬입니다.

왜 윈도우에서만 유독 설치가 헷갈릴까

맥이나 리눅스 기준으로 작성된 AI 코딩 도구 문서를 그대로 따라 하면 윈도우에서는 한 단계씩 어긋납니다. 같은 npm install -g 명령어라도 PowerShell에서 실행했는지, WSL Ubuntu 터미널에서 실행했는지에 따라 설치 위치가 완전히 다릅니다.

예를 들어 Claude Code를 WSL에 설치했는데 Cursor의 터미널은 PowerShell로 열려 있으면, 방금 설치한 명령어를 찾지 못합니다. 반대로 윈도우에 Node.js를 설치하고 WSL에서 명령어를 실행하면 WSL은 그 Node를 기본으로 보지 못하는 경우가 많습니다.

처음 설치 전에 확인할 6가지

• WSL2 설치 여부: Claude Code, MCP 서버, Docker 기반 워크플로는 WSL2가 편합니다.
• Node.js 위치: 윈도우용 Node와 WSL용 Node를 섞지 않는 것이 좋습니다. WSL에서는 nvm 사용을 추천합니다.
• Git 설정: Git for Windows와 WSL Git이 따로 동작합니다. 프로젝트를 어디에서 열지 먼저 정하세요.
• API 키 저장 위치: OpenAI, Anthropic 키를 PowerShell에 넣었는지, WSL의 ~/.bashrc에 넣었는지 구분해야 합니다.
• VS Code/Cursor 터미널: 기본 터미널이 PowerShell인지 WSL인지 확인하세요.
• Docker Desktop: MCP나 로컬 DB를 쓸 경우 WSL integration이 켜져 있어야 합니다.

도구별로 막히는 포인트가 다르다

모든 AI 코딩 도구를 같은 방식으로 설치하려고 하면 시간이 더 걸립니다. Cursor는 앱 중심, GitHub Copilot은 확장 중심, Claude Code와 Codex 계열 CLI는 터미널 중심으로 보는 편이 현실적입니다.

구체적인 셋업 예시: Cursor + Claude Code + MCP

가상의 예로, Next.js로 작은 SaaS 관리자 페이지를 만든다고 해보겠습니다. 화면 수정과 파일 탐색은 Cursor에서 하고, 큰 리팩터링이나 테스트 생성은 WSL 터미널에서 Claude Code에 맡기는 식입니다. DB 문서나 GitHub 이슈를 읽히고 싶다면 MCP 서버를 WSL 안에서 실행합니다.

이때 프로젝트 폴더는 C:\Users\... 아래보다 WSL의 ~/projects 아래에 두는 편이 낫습니다. 윈도우 파일시스템을 WSL에서 계속 건드리면 패키지 설치와 파일 감시가 느려질 수 있습니다. Cursor에서는 “WSL에서 폴더 열기” 방식으로 연결하면 체감이 훨씬 안정적입니다.

제가 실제로 가장 많이 막힌 지점

1. API 키를 넣었는데 도구가 못 읽는 문제

PowerShell에서 setx ANTHROPIC_API_KEY를 해놓고 WSL에서 Claude Code를 실행하면 키가 없다고 나올 수 있습니다. 둘은 다른 셸입니다. WSL에서는 ~/.bashrc나 ~/.zshrc에 별도로 export해야 합니다.

2. npm 전역 설치 후 명령어를 못 찾는 문제

윈도우에서 AI 코딩 도구 설치할 때 자주 막히는 지점 중 하나가 바로 PATH입니다. npm -g로 설치했는데 명령어가 안 보이면 설치 실패가 아니라 경로 문제일 때가 많습니다. WSL에서는 nvm으로 Node를 설치한 뒤 터미널을 새로 여는 것이 안전합니다.

3. PowerShell 실행 정책 오류

일부 CLI는 PowerShell에서 스크립트 실행이 막히며 오류가 납니다. 이 경우 무작정 보안 설정을 낮추기보다, 개발용 명령은 WSL에서 실행하는 쪽이 관리가 쉽습니다. 꼭 PowerShell을 써야 한다면 공식 문서에 나온 범위 안에서 ExecutionPolicy를 조정하세요.

누구에게 어떤 구성이 맞을까

처음 AI 코딩을 시작하는 사용자라면 Cursor + GitHub Copilot 조합이 가장 덜 피곤합니다. 설치가 단순하고, 윈도우 네이티브 앱만으로도 코드 설명·수정·자동완성을 바로 쓸 수 있습니다.

에이전트에게 파일 수정, 테스트 실행, 커밋 전 점검까지 맡기고 싶다면 WSL2 기반으로 Claude Code나 Codex CLI를 붙이는 편이 좋습니다. 이 단계부터는 “설치”보다 “작업 환경 분리”가 중요합니다.

MCP, n8n, Docker, 로컬 DB까지 연결하는 빌더라면 처음부터 WSL에 개발 도구를 모으세요. 중간에 옮기면 node_modules, Python venv, 환경변수 정리가 더 번거롭습니다.

바로 따라 할 다음 행동

1. 윈도우 터미널에서 wsl --install로 WSL2 Ubuntu를 준비합니다.
2. WSL 안에서 nvm, Node.js LTS, Git을 설치합니다.
3. Cursor를 설치하고 프로젝트 폴더를 WSL 경로에서 엽니다.
4. Anthropic, OpenAI API 키는 사용하는 셸에 맞게 각각 저장합니다.
5. 새 도구를 설치할 때마다 “윈도우에 설치했는지, WSL에 설치했는지”를 메모합니다.

FAQ

Q. Cursor만 쓸 거면 WSL이 꼭 필요한가요?

아닙니다. 단순한 프론트엔드 수정, 코드 리뷰, 자동완성 중심이면 윈도우 앱만으로도 충분합니다. 다만 Docker, MCP, 리눅스 기준 CLI를 같이 쓸 계획이면 WSL을 빨리 도입하는 편이 좋습니다.

Q. Claude Code를 PowerShell에서 바로 쓰면 안 되나요?

가능한 구성도 있지만, 공식 지원 범위와 패키지 의존성 때문에 WSL에서 더 안정적으로 굴러가는 경우가 많습니다. 특히 기존 문서와 튜토리얼 대부분이 유닉스 셸 기준이라 문제 해결이 쉽습니다.

Q. API 키는 어디에 저장하는 게 안전한가요?

블로그 글이나 코드에 직접 붙여넣지 말고 환경변수나 도구가 제공하는 인증 방식을 쓰세요. 개인 프로젝트라도 GitHub에 올라갈 수 있으니 .env는 반드시 .gitignore에 포함해야 합니다.

정리하면, 윈도우에서 AI 코딩 도구 설치할 때 자주 막히는 지점은 대부분 “어느 터미널에서 실행했는가”로 되돌아갑니다. 오늘 새 도구를 하나 더 설치하기 전에, 먼저 Cursor는 윈도우 앱, 에이전트 CLI는 WSL이라는 기준선을 잡아두면 이후 시행착오가 크게 줄어듭니다.

관련 링크

• ai 코딩 구독 요금 비교: Claude Code·Cursor·Copilot, 빌드용으로 돈값 하는 조합
• claude code artifacts, 웹 미리보기 대신 파일로 남기는 실전 작업법
• claude code 모델 추천: 실제 빌드 작업에서 Sonnet과 Opus를 나눠 쓰는 기준
• 관련 태그 더 보기
• 카테고리 더 보기
• 검색 결과 더 보기
• 참고 링크