Molayo

© 2026 Molayo

Zenn헤드라인2026. 06. 20. 21:17

Windows + PowerShell 5.1에서 Claude Code를 실운용하며 겪은 함정과 대책

요약

Windows PowerShell 5.1 환경에서 Claude Code를 사용할 때 발생하는 구문 에러, 리다이렉션 오류, 인코딩 문제 등 주요 함정과 해결 방법을 정리합니다. macOS/Linux 기반의 bash 환경과 다른 PowerShell 5.1만의 특성을 고려한 실무 대책을 다룹니다.

핵심 포인트

  • PowerShell 5.1은 &&, || 연산자를 지원하지 않으므로 주의 필요
  • stderr 리다이렉션 시 성공 여부($?)가 잘못 판정될 수 있음
  • 파일 작성 시 UTF-16 BOM 방지를 위해 -Encoding utf8 명시 필수
  • bash 명령어(head, tail 등)의 PowerShell 대응 명령어 숙지 필요

개인 개발 서비스를 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이 "잘못된 실패"를 유발함

  1. 네이티브 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에 없거나 의미가 다릅니다. 자주 사용하는 대응표:

하고 싶은 것bashPowerShell 5.1
앞 N행head -n 20Get-Content f -TotalCount 20
뒤 N행tail -n 20Get-Content f -Tail 20
경로 취득which node(Get-Command node).Source
빈 파일 생성touch fNew-Item -ItemType File f
출력 폐기2>/dev/null2>$null
환경 변수FOO=x cmd$env:FOO='x'; cmd

히어 도큐먼트(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

AI 자동 생성 콘텐츠

본 콘텐츠는 Zenn AI의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0