윈도우 환경 Claude Code 프리징 현상의 원인과 해결 방법

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

윈도우에서 Claude Code가 Git Bash를 기본 쉘로 사용하여 발생하는 프리징 문제를 PowerShell 강제 설정과 내장 도구 활용 지침으로 해결하는 방법을 제시한다.

배경

윈도우 환경에서 Claude Code를 사용할 때 find, ls 등의 명령 실행 시 화면이 멈추는 현상이 발생했다. 작성자는 이 문제의 원인이 Git Bash(MSYS)의 경로 변환 오버헤드임을 확인하고 이를 해결하기 위한 설정 파일 수정법을 공유했다.

의미 / 영향

윈도우 환경에서 AI 에이전트 도구를 사용할 때는 운영체제 간 쉘 구현 차이로 인한 성능 병목을 고려해야 한다. 명시적인 쉘 경로 설정과 에이전트 행동 지침 최적화를 통해 도구의 안정성과 실행 속도를 확보하는 것이 실무적으로 중요하다.

커뮤니티 반응

많은 사용자가 윈도우 환경에서 겪던 고질적인 성능 문제를 해결해주는 실질적인 가이드라는 반응이다.

실용적 조언

설정 변경 후에는 반드시 Claude Code를 완전히 종료하고 다시 실행해야 변경된 쉘 설정이 적용된다.
PowerShell 경로 입력 시 JSON 파일 내에서 백슬래시(\)를 이중(\\)으로 표기해야 함에 주의한다.
성능 향상을 위해 CLAUDE.md에 '파일 탐색 시 쉘 명령 대신 내장 도구를 사용하라'는 지침을 명시하는 것을 권장한다.

섹션별 상세

Claude Code는 윈도우에서 실행되더라도 Git이 설치되어 있으면 내부적으로 Git Bash(MSYS)를 기본 쉘로 선택한다. 이 과정에서 MSYS가 D:와 같은 윈도우 경로를 /d/ 형식으로 변환하며, 파일 접근 시마다 발생하는 이 변환 작업이 성능 저하를 유발한다.

기업용 백신 프로그램이 설치된 환경에서는 Claude Code가 새로운 쉘 프로세스를 생성할 때마다 실시간 검사가 수행된다. 이로 인해 간단한 쉘 명령어도 수 분 동안 응답이 없거나 전체 프로그램이 프리징되는 현상이 나타난다.

json

{
  "shellPath": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe",
  "env": {
    "SHELL": "C:\\Windows\\System32\\WindowsPowerShell\\v1.0\\powershell.exe"
  }
}

Claude Code 설정 파일에서 내부 쉘을 PowerShell로 강제 지정하는 JSON 설정

C:\Users\<사용자>\.claude\settings.json 파일을 수정하여 shellPath를 PowerShell 경로로 명시하면 Claude Code가 Git Bash를 찾는 과정을 건너뛴다. 설정 파일의 우선순위가 환경 변수나 PATH 검색보다 높기 때문에 가장 확실한 해결책이 된다.

프로젝트 루트에 CLAUDE.md 파일을 생성하고 Claude에게 쉘 명령어 대신 자체적인 Glob이나 Read 도구를 사용하도록 지시하면 프로세스 생성 횟수를 줄일 수 있다. 이는 보안 제약이 심한 환경에서 실행 속도를 비약적으로 향상시키는 효과가 있다.

실무 Takeaway

윈도우 프리징의 핵심 원인은 Git Bash의 경로 변환 오버헤드와 보안 프로그램의 프로세스 감시 간섭이다.
settings.json에서 shellPath와 env.SHELL을 PowerShell 실행 파일 경로로 직접 지정하여 문제를 해결한다.
CLAUDE.md를 통해 에이전트가 외부 쉘 명령 대신 내장 도구를 우선 사용하도록 유도하는 것이 성능 최적화에 유리하다.

언급된 도구

Claude Code추천

터미널 기반 자율 AI 코딩 에이전트

PowerShell추천

윈도우 기본 명령줄 쉘 및 스크립트 환경

Git Bash비추천

윈도우용 유닉스 쉘 에뮬레이션 환경