Windows에서 Claude Code: 개발자를 위한 설정

Windows에서 Claude Code 전문 설정: IT 전문가를 위한 핵심 팁

Windows에서 Claude Code를 설정하려면 OS 특성을 고려하고 개발 도구와의 통합을 해야 합니다. 이 글에서는 AWS, PowerShell, Git Bash와 함께 오류 없이 작동하는 검증된 구성 방법을 공유합니다.

환경 준비

Claude Code가 제대로 작동하려면 기본 구성 요소를 올바르게 설정하세요. 먼저 Git Bash를 설치하세요. Claude Code 설치 프로그램이 명령어를 실행하는 데 이 도구를 사용하기 때문입니다:

winget install Git.Git

Git 설치 중에는 Explorer 통합과 PATH 추가를 포함한 모든 기본 설정을 유지하세요. PowerShell에 특별히 주의하세요: Windows는 기본적으로 .NET Framework 기반의 구버전 5.1을 사용합니다. 최신 프로젝트에는 PowerShell 7+가 필요합니다:

winget install Microsoft.PowerShell

설치 후 pwsh를 실행하세요. powershell.exe가 아닙니다. 버전을 확인하세요:

pwsh --version

중요: 이후 모든 명령어는 PowerShell 7+에서 실행해야 합니다. 편의를 위해 여러 셸을 병렬로 사용할 수 있는 Windows Terminal을 추천합니다.

설치 및 인증

주요 설치 특징:

• 공식 스크립트 사용:

irm https://claude.ai/install.ps1 | iex

• WinGet 대안은 수동 업데이트가 필요:

winget install Anthropic.ClaudeCode

• 특정 버전의 경우:

& ([scriptblock]::Create((irm https://claude.ai/install.ps1))) 2.1.105

설치 후 작동 확인:

claude --version
claude doctor

command not found 오류가 발생하면 경로를 수동으로 추가하세요:

$userPath = [Environment]::GetEnvironmentVariable("PATH", "User")
[Environment]::SetEnvironmentVariable("PATH", 
  "$userPath;$env:USERPROFILE\.local\bin", 
  "User")

인증 방법:

• 대부분의 사용자: claude 실행 후 브라우저로 로그인
• API 과금의 경우 키 설정:

[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-ant-api03-...", "User")

Windows 전용 설정

PowerShell 문제 해결

기본적으로 Claude Code는 Git Bash를 사용해 PowerShell 구문과 충돌이 발생합니다. 정상 작동을 위해 %USERPROFILE%\.claude\settings.json에 추가하세요:

{
  "env": {
    "CLAUDE_CODE_USE_POWERSHELL_TOOL": "1",
    "CLAUDE_CODE_GIT_BASH_PATH": "C:\\Program Files\\Git\\bin\\bash.exe"
  },
  "defaultShell": "powershell"
}

이 설정으로 다음이 활성화됩니다:

• pwsh.exe 자동 감지
• 대화형 명령어 PowerShell로 리다이렉트
• 내부 작업은 Git Bash 유지

경로 및 파일 시스템 작업

NTFS는 Linux 파일 시스템과 근본적으로 다릅니다:

• 파일 이름 대소문자 무시
• 심볼릭 링크 권한 요구
• 줄 끝 처리 특성 (CRLF vs LF)

중요 설정:

• 항상 백슬래시로 된 Windows 경로 사용
• 스크립트의 줄 끝 변환 추가:

(Get-Content script.sh) -replace "`r`n", "`n" | Set-Content -NoNewline script.sh

• 글로벌 지침 (%USERPROFILE%\.claude\CLAUDE.md)에 명시:

# 파일 경로
- Windows 경로 사용: C:\\Users\\<user>\\projects\\...
- Unix 경로 사용 금지

클라우드 서비스 통합

AWS와 PowerShell

PowerShell을 통한 AWS 작업:

• AWS Tools for PowerShell 설치
• %USERPROFILE%\.aws\credentials에 프로필 구성
• CLAUDE.md에 추가:

# 사용 가능한 도구
- AWS 작업은 aws-powershell 사용
- SSM 문서는 PowerShell과 함께 사용

MCP 서버 문제 해결

MCP는 Windows에서 사용할 수 없는 Unix 도메인 소켓을 사용합니다. 우회 방법:

{
  "mcpServers": {
    "filesystem": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:/Projects"]
    }
  }
}

중요:

• JSON 경로에는 슬래시 사용
• 서버 코드에서 하드코딩된 Unix 경로 피함
• 임시 파일은 Windows 전용 경로 명시

핵심 포인트

• PowerShell 7+ 필수 — 5.1 버전은 최신 시나리오 미지원
• Git Bash 필수 — PowerShell 사용 시에도 내부 작업에 필요
• Windows 스타일 경로 — Claude Code는 Unix 경로나 ~-단축어를 인식하지 않음
• MCP 문제 — Windows에서는 cmd /c를 통한 수동 설정 필요
• 줄 끝 — 스크립트에서 CRLF→LF 자동 변환 필수

러시아 개발자를 위한 팁

2026년부터 러시아에서 Claude Code의 공식 액세스가 제한됩니다. 추천 해결책:

• 클라우드 제공자(AWS Bedrock)를 통한 기업 계정
• 인증이 포함된 프록시 서버
• 선불 API 과금
• 로컬라이즈된 경로를 가진 대체 MCP 서버

중요: API 키 사용 시 활성 상태이고 작동하는 계정에 연결되어 있는지 확인하세요. claude /status로 상태 확인.

결론

Windows에서 Claude Code 설정의 핵심은 적절한 PowerShell 구성, NTFS 적응, MCP 서버 수정입니다. AWS 개발자의 경우 구성 파일의 경로 지정과 줄 끝 처리가 중요합니다. 이 지침을 따르면 Linux 수준의 성능을 발휘할 수 있습니다.

— Editorial Team