클로드 코드 파워셸 도구 — 켜는 법·한글 깨짐·종료 코드 1의 뜻

윈도우에서 AI 코딩 도구를 쓰면 명령이 어느 셸로 도는지가 은근히 문제가 됩니다. 파워셸 문법으로 적었는데 안 먹거나, 한글이 물음표로 바뀌어 나오거나요.

명령을 파워셸로 바로 돌리는 도구가 따로 있습니다. 그런데 언제 저절로 켜지는지가 환경마다 다르고, 한글이 깨지던 문제도 특정 판부터 고쳐진 것이라 알고 쓰는 편이 낫습니다.

📌 30초 요약

• 깃 배시가 없는 윈도우면 저절로 켜집니다. 나머지는 조건이 다릅니다.
• 한글이 물음표로 바뀌던 것은 특정 판부터 고쳐졌습니다.
• 종료 코드 1이 실패가 아닌 명령들이 따로 정리돼 있습니다.
• 셸을 고르는 자리가 세 군데고 조건이 각각 다릅니다.

1. 언제 저절로 켜지나

이 도구가 켜지면 윈도우에서 명령이 깃 배시를 거치지 않고 파워셸에서 바로 돕니다. 켜져 있을 때 클로드는 파워셸을 주된 셸로 여기고, 깃 배시가 깔려 있다면 배시 도구도 그대로 남아 있어 필요할 때 쓸 수 있습니다.

내 환경	기본 상태
윈도우 · 깃 배시 없음	저절로 켜짐
윈도우 · 깃 배시 있음	개인·콘솔 계정은 켜짐 · 세 클라우드 경유는 직접 켜야 함
리눅스·맥·리눅스 계층	직접 켜야 함 · 파워셸 7 이상 필요

켜고 끄는 건 환경 변수 하나입니다. 설정 파일에 적어 둬도 되고요. 윈도우에서는 파워셸 7을 먼저 찾고 없으면 5.1로 물러나 동작합니다. 리눅스 계층에서 쓰려면 파워셸 7을 따로 깔고 경로에 잡아 줘야 하는데, 그 환경의 다른 제약은 리눅스 계층 세션 글에 정리해 뒀습니다.

2. 한글이 물음표로 바뀌던 이유

한국어로 쓰는 사람에게 가장 크게 와닿는 대목입니다. 파워셸 5.1에서 결과를 파일로 넘기면 예전에는 다른 글자 인코딩으로 저장됐습니다. 그 파일을 다른 도구가 읽으면 깨져 보이는 게 당연했죠.

⚠️ 옛 판에서는 세 가지가 동시에 깨졌습니다

특정 판 이전에는 ⑴파일로 넘긴 결과가 다른 인코딩으로 저장됐고 ⑵아스키가 아닌 글자를 명령에 흘려보내면 물음표로 도착했으며 ⑶파이썬 스크립트가 한글을 출력하다 인코딩 오류로 죽는 일까지 있었습니다.

셋 다 한국어 환경에서만 유난히 자주 보이던 증상이라, 내 설정을 잘못 만졌다고 생각하기 딱 좋았습니다. 지금 판에서는 전부 고쳐졌으니 비슷한 증상이 있으면 판 번호부터 확인하세요.

지금은 파일로 넘기는 결과도, 명령에 흘려보내는 글자도 모두 같은 인코딩으로 통일됩니다. 덤으로 두 가지가 더 정리됐습니다 — 오류 출력에서 색을 입히는 제어 문자가 제거되고, 입력을 기다리는 자식 프로그램이 멈춰 서지 않고 입력 끝 신호를 받습니다.

마지막 항목이 은근히 중요합니다. 입력을 기다리는 명령을 무심코 돌렸다가 아무 반응 없이 멈춰 있는 경험이 한 번쯤 있으실 텐데, 그게 이 문제였을 수 있습니다. 이제는 바로 끝나고 결과가 돌아옵니다.

3. 종료 코드 1이 실패가 아닌 경우

셸 명령은 0이면 성공, 아니면 실패로 읽는 게 보통입니다. 그런데 「없음」이나 「다름」을 1로 알리는 명령들이 있어서, 그대로 읽으면 멀쩡한 결과를 실패로 착각하게 됩니다.

명령 갈래	종료 코드 1의 뜻
글자 찾기 도구들	일치하는 것이 없음 · 실패 아님
차이 비교 도구들	차이가 있음 · 실패 아님
경로 찾기 도구	찾은 것이 없음 · 실패 아님
대량 복사 도구	0~7은 정보성 결과 · 8부터 실패

여기에 미묘한 단서가 하나 붙습니다. 출력을 없애 버린 형태, 그러니까 조용히 돌리는 옵션을 붙였거나 결과를 빈 곳으로 흘려보낸 경우에는 같은 종료 코드 1이라도 실패로 봅니다. 출력이 있어야 「없음」이라는 답으로 읽어 준다는 뜻이죠.

왜 이런 구분이 필요하냐면, 이걸 안 해 두면 클로드가 멀쩡한 검색 결과를 「명령이 실패했다」고 받아들이고 엉뚱한 재시도를 하기 때문입니다. 같은 이유로 대량 복사 도구는 0부터 7까지를 정보성 결과로 따로 묶어 뒀습니다. 파일을 복사했다거나 여분 파일을 찾았다는 뜻이지 오류가 아니거든요.

4. 셸을 고르는 세 자리

도구를 켜는 것과 별개로 어디에서 파워셸을 쓸지를 세 군데에서 정합니다. 설정 파일에서 기본 셸을 지정하면 내가 직접 치는 명령이 파워셸로 가고, 개별 훅과 스킬 머리말에서도 따로 지정할 수 있습니다.

조건이 미묘하게 다릅니다. 기본 셸과 스킬 쪽은 도구가 켜져 있어야 동작하지만, 훅은 파워셸을 직접 띄우기 때문에 도구 활성화와 무관하게 먹습니다. 훅을 거는 방법 자체는 셸 없이 도는 훅에서 다뤘고요.

두 갈래가 같은 규칙을 쓰는 대목도 있습니다. 명령이 끝날 때마다 작업 폴더가 프로젝트 자리로 되돌아가는 동작은 파워셸 쪽에도 똑같이 적용되고, 그걸 끄는 환경 변수도 같은 것을 씁니다. 한 명령에서 폴더를 옮겨 두고 다음 명령이 그 자리에 있기를 기대했다가 어긋나는 일이 여기서 생깁니다. 훅이 받는 명령 문자열이 담기는 자리도 배시 도구와 동일해서, 검사 논리는 그대로 두고 이름만 두 갈래로 맞춰 주면 됩니다.

여기서 놓치기 쉬운 함정이 하나 있습니다. 셸 명령을 검사하는 훅을 만들어 뒀다면 배시 도구 이름만 맞춰서는 부족합니다. 파워셸 도구로 도는 명령은 그 훅에 안 걸리니까요. 두 이름을 함께 맞추도록 고쳐 두셔야 막으려던 명령이 다른 길로 새지 않습니다. 윈도우에서 못 쓰는 기능들이 더 있는지는 세션끼리 대화가 윈도우에서 안 되는 이야기도 참고하시고, 도입 순서는 AI 도입 한 바퀴에서 잡아 보세요.

자주 묻는 질문 (FAQ)

Q. 스크립트 실행이 막혀 있는 회사 노트북에서도 되나요?

기본 설치 상태라면 됩니다. 파워셸을 띄울 때 그 프로세스 범위에서만 정책을 비켜 가도록 해 두어서, 기계 설정을 바꾸지 않고도 스크립트와 모듈이 동작합니다. 다만 조직이 정책으로 내려 둔 제한은 그대로 적용됩니다. 프로세스 범위 우회로는 그걸 못 덮거든요. 반대로 기계의 정책을 그대로 따르게 하고 싶다면 그렇게 하라는 환경 변수가 따로 있습니다.

Q. 내 프로필 설정이 그대로 적용되나요?

아닙니다. 미리보기 단계의 제약으로 파워셸 프로필을 불러오지 않습니다. 별칭이나 함수를 프로필에 정의해 두고 쓰시는 분이라면 그것들이 없는 상태로 명령이 돈다는 뜻입니다. 꼭 필요한 것은 명령 안에서 직접 정의하거나 스크립트 파일로 빼 두는 편이 안전합니다.

Q. 격리 기능도 같이 쓸 수 있나요?

윈도우에서는 안 됩니다. 미리보기 제약에 윈도우에서 격리가 지원되지 않는다고 명시돼 있습니다. 명령을 가둬 두고 돌리고 싶다면 리눅스 계층이나 컨테이너 쪽을 쓰셔야 합니다. 격리를 전제로 권한을 설계했다면 윈도우에서는 그 전제가 성립하지 않는다는 점을 감안하세요.

Q. 배시 도구는 이제 안 쓰나요?

둘 다 남아 있습니다. 도구가 켜지면 클로드가 파워셸을 주된 셸로 여기지만, 깃 배시가 깔려 있다면 배시 도구도 그대로 쓸 수 있습니다. 리눅스 문법으로 짜인 스크립트를 돌려야 할 때 유용하죠. 다만 앞서 말한 훅 함정이 여기서 나옵니다 — 두 갈래가 공존한다는 것은 검사도 두 갈래로 해야 한다는 뜻입니다.

정리하면

• 한글이 깨진다면 판 번호부터 확인하세요.
• 종료 코드 1이 늘 실패인 건 아닙니다.
• 훅은 두 셸 이름을 함께 맞추세요.
• 윈도우에서는 격리를 전제하지 마세요.

※ 공개된 도구 참조 문서를 읽고 정리했습니다. 환경 변수·설정 항목·명령 이름은 우리말로 풀어 적었고, 판 번호별 차이를 직접 재현해 보지는 않았습니다.

※ 어느 판부터 무엇이 고쳐졌는지는 문서에 번호로 적혀 있으나 본문에서는 「특정 판」으로 뭉쳤습니다. 내 환경이 해당하는지는 지금 쓰는 판 번호와 원문을 대조해 확인하세요. 미리보기 단계라 제약이 바뀔 수 있습니다.