개인 개발 서비스를 Claude Code로 작성하고 있는데, 개발 환경은 Windows 11 + Windows PowerShell 5.1입니다. Claude Code나 이러한 종류의 AI 에이전트는 macOS / Linux + bash를 전제로 한 문서가 많아서, Windows + PowerShell 5.1(PowerShell 7이 아닌 OS에 동봉된 5.1)로 상용하면 은근히 빠지기 쉬운 함정들이 몇 군데 있었습니다. 이 기사에서는 그 함정과 실제로 효과가 있었던 대책을 정리합니다.

전제

• OS: Windows 11
• 셸(Shell): Windows PowerShell 5.1 (pwsh가 아닌 powershell.exe)
• Claude Code를 일상적인 구현·운용 플로우에 사용

PowerShell 7로 올리면 해결되는 부분도 있지만, "순정 Windows 상태 그대로 사용하고 싶다"는 사정 때문에 5.1을 계속 사용하고 있습니다. 같은 환경을 사용하는 분들에게 참고가 되었으면 합니다.

&& / ||로 명령어를 연결할 수 없음

1. bash 방식대로 npm run build && git push라고 쓰면, PowerShell 5.1에서는 **파서 에러(Parser Error)**가 발생합니다 (파이프라인 연결 연산자는 PowerShell 7부터 지원).

# NG (5.1에서는 구문 에러)
npm run build && git push
# OK: 직전의 성공 여부를 $?로 확인하여 분기
...

에이전트에게 작업을 시킬 때도, 이 차이점을 처음에 명시해 두면 불필요한 실패를 줄일 수 있습니다.

2>&1이 "잘못된 실패"를 유발함

2. 네이티브 exe 파일에 대해 PowerShell 5.1로 git 등 네이티브 실행 파일의 표준 에러(stderr)를 2>&1로 리다이렉트하면, stderr의 각 행이 NativeCommandError (ErrorRecord)로 감싸져, 종료 코드 0(성공)임에도 불구하고 $?가 $false가 되는 경우가 있습니다. git은 진행 상황을 stderr로 출력하기 때문에, 이 문제에 여러 번 걸려들었습니다.

# 위험: 성공해도 실패로 취급되기 쉬움
git push 2>&1
# 기본적으로는 그대로 실행 (stderr는 그대로 표시됨)
...

"성공했는데 스크립트가 실패로 판정될" 때는, 먼저 이 패턴을 의심해 보는 것이 좋습니다.

3. 파일의 문자 코드가 UTF-16 BOM이 됨

Out-File / Set-Content의 기본 인코딩은 5.1에서 **UTF-16 LE (BOM 포함)**입니다. 다른 도구(Node 스크립트, Git, 각종 CLI)가 읽는 JSON이나 .md 파일을 이것으로 작성하면, 앞부분의 BOM이나 글자 깨짐 때문에 읽을 수 없게 됩니다.

# 다른 도구가 읽는 파일은 반드시 utf8을 명시
"{ ""ok"": true }" | Out-File -Encoding utf8 config.json

상태 관리용 JSON을 스크립트로 교체하는 운용을 하고 있는데, 이 부분을 -Encoding utf8로 고정하기 전까지는 가끔 JSON 파싱이 깨져서 원인 규명에 시간을 허비했습니다.

4. bash 유래의 명령어·기법은 그대로 작동하지 않음

head / tail / which / touch / 2>/dev/null 등은 PowerShell에 없거나 의미가 다릅니다. 자주 사용하는 대응표:

히어 도큐먼트(Here-document) 작성법도 다릅니다. @'...'@의 닫는 '@

는 행두(인덴트 없음) 위치에 있어야 구문 오류(Syntax Error)가 발생하지 않습니다.

5. POSIX가 필요할 때만 bash로 넘기기

그렇다고 모든 것을 PowerShell로만 처리하려고 하면 금방 지치게 됩니다. find / grep을 다용하는 처리나, bash를 전제로 하는 원라이너(One-liner)는 Windows에서도 사용할 수 있는 bash(Git Bash 등)로 명시적으로 넘기는 것이 현실적이었습니다.

"표준은 PowerShell, POSIX 셸이 필요할 때만 bash를 사용한다"라는 방침을 프로젝트 지시 파일에 적어두면, 에이전트(Agent)도 그에 따라 움직이므로 사고가 줄어듭니다.

요약

Windows + PowerShell 5.1에서의 Claude Code 운용은,

&& / ||는 사용할 수 없음 → ; if ($?) { } 사용

• 네이티브 exe에 대한 2>&1은 잘못된 실패를 유발함 → 솔직하게 실행
• 다른 도구가 읽는 파일은 -Encoding utf8을 명시
• bash 유래 명령어는 대응표로 치환하고, 필요한 경우에만 bash로 넘기기

이 4가지 사항을 프로젝트 지시 파일(CLAUDE.md / AGENTS.md 등)에 처음부터 적어두는 것이 결국 가장 효과적이었습니다. 에이전트는 매번 그것을 읽고 움직이기 때문에, 같은 실수(ハマり)를 반복하지 않게 됩니다.

참고로, 이러한 "Claude Code나 프롬프트의 실운용 노하우"를 매매할 수 있는 마켓을 개인이 만들어 운영하고 있습니다 👉 equaliA(이코리아). 마찬가지로 AI 도구를 업무에 도입하고 계신 분들은 한 번 살펴보시기 바랍니다.

Discussion