셸 없이 도는 훅

AI 도구에 내 스크립트를 끼워 자동으로 돌리는 기능을 쓰다 보면, 정작 발목을 잡는 건 로직이 아니라 경로에 낀 공백과 따옴표입니다. 폴더 이름에 띄어쓰기 하나 들어갔다고 명령이 두 조각으로 쪼개져 실패하는 일이 흔하죠. 이걸 셸에 넘기지 않고 실행 파일을 바로 띄우는 방식으로 풀 수 있게 됐습니다. 여기에 훅이 데스크톱 알림을 낼 수 있는 길까지 함께 열렸습니다. 다만 윈도우에서는 이 방식으로 안 뜨는 것들이 따로 있어, 그 함정까지 같이 정리했습니다.

📌 30초 요약

• 인자를 목록으로 적으면 셸을 안 거칩니다 — 명령을 실행 파일로 곧장 띄웁니다.
• 따옴표가 필요 없습니다 — 목록의 한 칸이 곧 인자 하나라 공백이 끼어도 안 쪼개집니다.
• 대신 파이프·연결·리다이렉트도 안 됩니다 — 셸 기능이 필요하면 예전 방식 그대로.
• ⚠️ 윈도우 함정 — npm이 깔아주는 실행 파일은 이 방식으로 못 띄웁니다.
• 훅이 알림을 낼 수 있습니다 — 데스크톱 알림·창 제목·벨을 별도 항목으로 요청합니다.
• 끼울 수 있는 시점이 서른 곳이 넘습니다 — 세션 시작부터 폴더 변경까지.

따옴표가 사라진 이유

기존 방식은 명령을 문자열 하나로 적어 셸에 넘기는 것이었습니다. 셸이 그 문자열을 토막 내고, 변수를 펼치고, 파이프와 연결 기호를 해석합니다. 편한 대신 내가 의도하지 않은 해석이 끼어듭니다. 경로 중간에 공백이 있으면 인자 두 개로 쪼개지고, 작은따옴표나 달러 기호가 들어가면 또 다르게 읽힙니다.

새로 생긴 방식은 인자를 목록으로 따로 적는 것입니다. 목록을 적어두면 명령을 셸에 넘기지 않고 실행 파일을 직접 찾아 띄웁니다. 목록의 한 칸이 그대로 인자 하나가 되기 때문에, 공백이 몇 개 들어 있든 쪼개지지 않습니다. 작은따옴표·달러 기호·역따옴표 같은 특수문자도 해석할 셸이 없으니 적은 그대로 넘어갑니다.

항목	셸에 넘기는 방식	바로 띄우는 방식
언제 켜지나	인자 목록을 안 적었을 때	인자 목록을 적었을 때
공백 있는 경로	따옴표로 감싸야 함	그냥 적으면 됨
파이프·연결·리다이렉트	됨	안 됨
특수문자	셸이 해석함	적은 그대로 넘어감
고를 기준	셸 기능이 필요할 때	경로 자리표시자를 쓸 때

문서가 고를 기준을 아예 못 박아 뒀다는 점이 눈에 띕니다. 경로 자리표시자를 쓰는 훅이면 목록 방식을 쓰라고 적혀 있습니다. 확장을 만들어 배포하면 설치 위치가 사람마다 달라져 자리표시자로 경로를 받게 되는데, 그 값에 공백이 들어 있을지 만든 쪽은 알 수가 없습니다. 반대로 파이프나 연결이 필요하면 예전 방식, 둘 다 해당 없으면 아무거나 쓰면 된다고 정리해 뒀습니다. 확장을 붙여 쓰는 여러 갈래는 스킬과 연결 서버의 차이를 정리하면서 짚어둔 적이 있는데, 훅은 그중 내 스크립트를 직접 끼우는 쪽에 해당합니다.

윈도우에서 안 뜨는 것들

⚠️ npm이 깔아준 것은 실행 파일이 아닙니다

윈도우에서 이 방식은 진짜 실행 파일만 띄울 수 있습니다. 그런데 npm·npx·문법 검사 도구 같은 것들이 프로젝트 폴더 안에 깔아주는 건 실행 파일이 아니라 셸을 거쳐야 도는 껍데기입니다. 그래서 이름만 적으면 안 뜹니다. 해결책은 문서가 직접 제시해 뒀습니다 — 런타임을 명령으로 지정하고, 껍데기 대신 그 안의 실제 스크립트 파일을 인자로 넘기는 것입니다. 즉 도구 이름을 부르는 대신 그 도구의 알맹이 파일 경로를 직접 가리키면 됩니다.

또 하나, 명령 칸에는 실행 파일 이름이나 경로만 들어가야 합니다. 예전 습관대로 "런타임 이름 + 스크립트 이름"을 한 칸에 붙여 적고 인자 목록까지 같이 주면, 그런 이름의 실행 파일이 세상에 없으니 실패합니다. 이 경우 도구가 경고를 남겨 알려주긴 하지만, 왜 안 되는지 모른 채 시간을 쓰기 쉬운 자리입니다. 붙여 적은 뒷부분은 인자 목록으로 옮기면 됩니다.

반대로 말하면 맥이나 리눅스에서는 이 함정이 거의 없습니다. 윈도우에서 훅이 안 도는데 로그도 애매하다면, 껍데기를 띄우려 한 게 아닌지 먼저 의심해 보시는 게 빠릅니다. 훅 자체를 어떻게 설계하고 어느 시점에 끼우는지는 훅 기능을 통째로 정리했던 글에 있습니다.

훅이 소리를 낼 수 있게 됐습니다

두 번째 변화는 훅이 사용자에게 말을 거는 방법입니다. 그동안 훅은 제어 터미널 없이 자기 세션에서 도는 구조라, 훅이 만든 프로세스가 화면에 직접 무언가를 띄울 수 없었습니다. 맥과 리눅스에서는 터미널 장치를 열 수 없었고, 윈도우에는 그런 장치 개념 자체가 없습니다. 그래서 훅에서 알림 명령을 실행해도 조용히 아무 일도 안 일어나는 경우가 있었습니다.

새 방식은 훅이 직접 내보내지 않고, 도구에게 내보내 달라고 부탁하는 형태입니다. 훅이 결과를 돌려줄 때 별도 항목에 원하는 신호를 적어두면 도구가 대신 화면 쪽으로 흘려보냅니다. 이걸로 데스크톱 알림, 창 제목 바꾸기, 벨 울리기가 가능합니다. 긴 작업이 끝났을 때 다른 창에서 일하고 있어도 알아채게 만드는 용도로 바로 쓸 수 있습니다.

사용자에게 글로 한마디 남기고 싶을 때는 이것 말고 별도 항목이 따로 있습니다. 다만 시점에 따라 그 메시지를 버리거나 다른 곳에 표시하는 경우가 있으니, "알림을 내고 싶은가"와 "기록을 남기고 싶은가"를 구분해서 골라야 합니다. 여러 개를 백그라운드로 돌려두는 방식이라면 이 알림이 특히 값이 나오는데, 세션을 목록으로 늘어놓고 관리하는 화면과 같이 쓰면 "어느 줄이 나를 부르는지"를 두 겹으로 확인하게 됩니다.

끼울 수 있는 자리가 서른 곳이 넘습니다

문서를 열어보고 가장 놀란 건 훅을 끼울 수 있는 시점의 개수였습니다. 세션이 시작될 때와 끝날 때, 프롬프트를 넣기 직전, 도구를 쓰기 전과 후, 도구가 실패했을 때만, 여러 도구가 한꺼번에 끝났을 때, 권한을 물을 때, 자동 모드가 거절했을 때, 답이 끝났을 때, 오류로 끝났을 때… 여기까지가 흔히 쓰는 축입니다.

그다음부터가 잘 안 알려진 자리들입니다. 보조 에이전트가 뜨고 끝날 때, 작업 폴더가 바뀔 때, 지켜보던 파일이 디스크에서 바뀔 때, 설정 파일이 도중에 바뀔 때, 지시문 파일을 읽어들일 때, 컨텍스트를 압축하기 전과 후, 격리 폴더를 만들고 지울 때까지 전부 잡을 수 있습니다. "AI가 뭘 하는지 못 보겠다"는 문제의 상당수는 이 목록에서 답이 나옵니다 — 못 보는 게 아니라 어디를 잡아야 하는지 몰랐던 쪽에 가깝습니다.

🔁 셸 명령을 미리 줄 세워 두는 법

셸을 거치지 않는 쪽을 봤으니 반대로 셸 명령을 쓰는 자리도 한 줄 적어 둡니다. 느낌표를 붙인 셸 명령은 클로드가 일하는 중에도 쳐 둘 수 있고, 차례가 완전히 끝난 뒤 하나씩 실행됩니다. 「작업 끝나면 검사부터 돌려 줘」 같은 흐름을 미리 짜 두는 셈이죠. 다만 회수 조건이 까다로워서 입력창이 비어 있고 다른 대기 항목도 없을 때만 도로 꺼낼 수 있습니다. 위험한 명령은 애초에 줄 세우지 않는 편이 안전합니다.

🔁 자리가 많아도 안 도는 자리가 있습니다

끼울 수 있는 자리가 서른 곳 넘는다고 했는데, 그 자리가 실제로 도는 조건은 따로 있습니다. 하위 에이전트 정의 파일에 적은 훅은 그 파일이 든 폴더를 신뢰하기 전까지 통째로 건너뜁니다. 에이전트 자체는 멀쩡히 도는데 훅만 빠지고, 오류는 디버그 기록에만 남습니다. 설정 파일에 적은 훅은 부모 폴더만 믿어도 도는데 안쪽에 적은 쪽이 오히려 더 까다롭다는 점이 함정이죠. 자리를 세는 것만큼 그 자리가 열려 있는지도 함께 확인해 두세요.

자주 묻는 질문 (FAQ)

Q. 기존에 쓰던 훅을 다 바꿔야 하나요?

아닙니다. 인자 목록을 안 적으면 예전 방식 그대로 돕니다. 새로 생긴 건 선택지지 교체가 아닙니다. 바꿔서 이득을 보는 건 경로 자리표시자를 쓰거나 공백 낀 경로를 다루는 훅이고, 파이프로 여러 명령을 잇거나 조건부 실행을 쓰고 있다면 바꾸면 오히려 깨집니다. 판단 기준은 하나입니다 — 셸이 해줘야 하는 일이 있는가.

Q. 윈도우인데 훅이 조용히 안 돕니다

목록 방식을 쓰고 있다면 명령 칸에 적은 게 진짜 실행 파일인지 먼저 보세요. 프로젝트 폴더 안에 깔린 도구 이름을 그대로 적었다면 그건 껍데기라 안 뜹니다. 런타임을 명령으로 두고 알맹이 스크립트를 인자로 넘기는 형태로 바꾸면 됩니다. 그리고 명령 칸에 공백이 섞여 있으면 경고가 남으니 로그를 한 번 확인해 보시는 게 빠릅니다.

Q. 알림 기능은 어디에 제일 쓸모 있나요?

기다림이 긴 자리입니다. 답이 끝나는 시점이나 권한을 묻는 시점에 걸어두면, 다른 창에서 일하다가도 화면을 안 보고 있어도 알아챌 수 있습니다. 반대로 도구를 쓸 때마다 걸면 알림이 쏟아져 금세 무시하게 되니, 턴이 끝나는 시점처럼 드문 자리부터 시작하시길 권합니다.

🧾 정직하게 밝혀둘 것

• ★주간 변경 노트에 적힌 항목 하나를 전용 문서에서 확인하지 못했습니다. "도구를 쓴 뒤 도는 훅이 거부 사유를 되돌려주고 턴을 이어가게 하는 설정"이 노트에는 있는데, 훅 문서의 표에는 그 시점은 차단할 수 없다고 되어 있습니다. 둘이 어긋나므로 이 글에서는 다루지 않았습니다 — 쓰시려면 최신 문서에서 직접 확인해 주세요.
• 직접 훅을 짜서 세 방식을 다 돌려보지는 않았습니다. 문서에 적힌 동작과 제약을 정리한 것입니다.
• 설정 항목 이름과 명령 표기는 읽기 쉽게 풀어 적었습니다. 정확한 철자와 구조는 원문 문서를 보셔야 합니다.
• 끼울 수 있는 시점 목록은 계속 늘어나는 중이고, 버전이 낮으면 일부는 아예 없습니다.
• 알림이 실제로 뜨는지는 터미널 프로그램과 운영체제 설정에 달려 있습니다. 도구가 신호를 보내도 받는 쪽이 꺼져 있으면 아무 일도 일어나지 않습니다.

✨ 정리하면

훅이 셸이라는 중간 단계를 건너뛸 수 있게 됐고, 대신 알림이라는 출구를 얻었습니다. 경로에 공백이 있어 따옴표와 씨름하던 자리, 알림을 걸었는데 조용하던 자리가 각각 정식 해법을 갖게 된 셈입니다. 다만 윈도우에서는 "실행 파일처럼 보이지만 아닌 것"이라는 함정이 하나 따라옵니다. 훅 전체 설계는 훅 기능 완전정리, 확장의 갈래는 스킬과 연결 서버의 차이, 여러 세션을 늘어놓고 쓰는 쪽은 한 화면에 모인 세션들, 도구에 드는 값을 통으로 잡는 흐름은 AI 지출 관리 허브에 모아뒀습니다.

※ 출처: Claude Code 주간 변경 노트 2026년 20주차(5월 11~15일, v2.1.139~v2.1.142)와 훅 공식 문서. 본문의 동작은 2026년 8월 기준으로 문서에 적힌 내용이며, 설정 항목과 끼울 수 있는 시점은 버전에 따라 달라집니다. 알림이 실제로 표시되는지는 사용하는 터미널 프로그램과 운영체제 알림 설정에 따라 다릅니다.