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

커뮤니티 반응

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

실용적 조언

설정 변경 후에는 반드시 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 도구를 사용하도록 지시하면 프로세스 생성 횟수를 줄일 수 있다. 이는 보안 제약이 심한 환경에서 실행 속도를 비약적으로 향상시키는 효과가 있다.

용어 해설

MSYS: — 윈도우 환경에서 유닉스 계열의 도구와 라이브러리를 사용할 수 있도록 지원하는 소프트웨어 배포판이다. 윈도우의 드라이브 경로 형식을 유닉스 스타일로 변환하는 과정에서 오버헤드가 발생하며, 특히 보안 프로그램이 활성화된 환경에서 성능 저하의 원인이 된다.
쉘 경로(Shell Path): — 운영체제에서 명령어를 해석하고 실행하는 프로그램인 쉘의 실행 파일 위치를 의미한다. 애플리케이션이 내부적으로 명령을 수행할 때 어떤 환경을 사용할지 결정하는 핵심 설정값이다.
글로브 도구(Glob Tool): — 와일드카드 문자를 사용하여 특정 패턴과 일치하는 파일 이름들을 찾아내는 프로그래밍 기법이나 도구이다. 외부 쉘 명령을 호출하지 않고 언어 자체의 기능을 활용하므로 프로세스 생성 비용을 줄일 수 있다.

언급된 도구

Claude Code추천

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

PowerShell추천

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

Git Bash비추천

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