Claude Code 자동화 길잡이: 지시 파일·스킬·훅·비대화형 실행 고르기

Claude Code에 빌드 명령을 또 설명하고 있거나, CLAUDE.md에 “반드시”라고 적어 둔 규칙이 어느 날 슬쩍 건너뛰어졌다면 이제 한 단계 올릴 때가 된 거예요. 문제는 어디로 올리느냐입니다. 지시 파일, 스킬, 훅, claude -p까지 고를 게 많거든요.

이 사이트에 자동화 쪽 글이 꽤 쌓여서, 어떤 상황에 어느 글부터 열면 되는지 제 나름의 지도를 만들어 뒀습니다.

큰 줄기는 간단해요. 같은 설명을 세 번째 하고 있다면 CLAUDE.md나 스킬로 옮기고, 한 번이라도 건너뛰면 곤란한 일(편집 후 포맷, 위험한 명령 차단)은 훅으로 겁니다.

사람 없이 돌리는 claude -p로 넘어가기 전에는 권한 규칙·샌드박스·워크트리로 애초에 못 하게 막을 곳부터 정하세요. /rewind는 Bash 명령이 바꾼 파일을 되돌리지 못하니까요.

훅 관련 내용은 2026년 9월 21일 Claude Code 훅 문서 기준입니다. 설정 방법과 직접 실행한 결과는 링크한 각 글에 있고, 지시 파일 단계는 Codex CLI·Gemini CLI도 비슷하지만 훅 이후 단계는 Claude Code 기준이에요.

상황별로 먼저 열 글

같은 말을 또 하고 있거나, 걸어 둔 규칙이 안 지켜졌거나, 밤새 돌려 두고 싶은 작업이 생겼다면 찾는 답은 대개 아래에 있습니다.

• 매 세션 같은 설명(빌드 명령, 코드 규칙)을 반복한다 → CLAUDE.md에 무엇을 적고 /init 초안을 어디까지 줄일지
• 긴 절차를 필요할 때만 불러 쓰고 싶다 → SKILL.md 작성부터 호출 확인까지
• 훅·스킬·규칙 파일 중 어디에 넣을지 모르겠다 → 같은 일을 세 자리에 넣고 비교한 기준
• Codex·Gemini CLI와 지시 파일을 같이 쓴다 → CLAUDE.md·AGENTS.md·GEMINI.md가 겹치는 부분
• 편집 후 포맷, 커밋 전 테스트, 폴더 보호를 반드시 걸고 싶다 → 훅 설정 방법과 예제
• 훅을 걸었는데 안 돈다 → 훅이 어디서 멈췄는지 4단계 점검
• 실행 전에 계획부터 확인하고 싶다 → plan 모드에 들어가는 법 3가지와 건너뛸 기준
• 승인 없이 어디까지 맡길지 정하고 싶다 → 권한 모드별로 무엇을 묻고 무엇을 넘기는지
• 스크립트나 CI에서 돌리고 싶다 → claude -p의 출력 형식과 종료 코드
• 큰 작업을 나눠 맡기고 싶다 → 조사와 검토를 서브에이전트로 나누는 방법, 세션마다 워크트리로 파일을 나누는 법
• 잘못된 변경을 되돌리고 싶다 → /rewind로 되돌아가는 것과 안 되는 것

사람이 옆에 있어야 하나

“이건 훅인가 스킬인가”부터 고민하면 오히려 막힙니다. 대신 이 일이 돌 때 사람이 옆에 있어야 하는지부터 물어보세요. 제가 보기엔 그 질문 하나로 단계가 거의 저절로 정해집니다.

단계	쓰는 것	사람의 자리	지켜진다는 보장	되돌릴 수단
1. 매번 설명	대화	매 요청마다	그 요청 안에서만	대화를 멈춤
2. 파일로 고정	CLAUDE.md, 스킬	결과를 봄	없음	편집 승인, 되감기
3. 훅으로 강제	훅	결과를 봄	있음	되감기, 권한 규칙
4. 사람 없이 실행	claude -p, 서브에이전트, 워크트리	끝난 뒤에 봄	있음	좁아짐

한 번 하고 말 일이라면 1단계, 그냥 대화로 충분합니다. 파일로 만드는 데 시간이 더 들어요. 올릴 때가 됐다는 신호는 같은 설명을 세 번째 하고 있을 때고요.

표의 “지켜진다는 보장”과 “되돌릴 수단” 칸은 제가 Windows 11 · Claude Code 2.1.296에서 직접 돌려 본 결과와도 맞았습니다.

단계	해 본 것	결과	자세한 글
2. 파일	CLAUDE.md에 “편집한 뒤 스크립트 실행” 한 줄, 파일 두 개 편집	세 번 모두 1회 실행(편집마다가 아님)	훅·스킬·규칙 비교
3. 훅	같은 일을 PostToolUse 훅으로	세 번 모두 2회, 편집마다 실행	같은 글
4. 사람 없이	처음 보는 폴더에서 claude -p	저장소의 훅·MCP 서버는 묻지 않고 실행, 허용 규칙만 무시	프롬프트 인젝션 방어
4. 사람 없이	claude -p로 파일 한 줄 수정	체크포인트 스냅샷이 남지 않아 /rewind 대상이 아님	체크포인트와 /rewind

특히 마지막 두 줄이 4단계로 넘어가기 전에 막을 곳부터 정하라는 이유예요. 확인 단계도, 되감기도 대화형일 때만큼 받쳐 주지 않습니다.

반복 설명은 파일로

반복되는 설명은 파일로 옮기되, 늘 필요한 것과 가끔 필요한 것을 나눠 두세요.

• 늘 필요한 것은 CLAUDE.md. 세션마다 자동으로 읽히지만, 늘 컨텍스트를 차지하니 길수록 손해입니다.
• 가끔 필요한 긴 절차는 스킬. 필요할 때만 읽혀서 CLAUDE.md를 짧게 유지할 수 있어요.

여기서 꼭 알아 둘 게 있습니다. CLAUDE.md와 스킬은 전부 지시라서, 대체로 지켜지지만 보장은 없어요. 대화가 길어지거나 상황이 애매하면 건너뛸 수 있습니다.

“반드시 하라”고 적으면 지켜질 확률은 높아져도 보장이 되지는 않고요. 제가 보기엔 “반드시”가 필요한 일을 이 단계에 두는 것이 가장 흔한 실수입니다.

대개 잘 돌다가 어느 한 번 건너뛴 게 커밋이나 배포에 섞이고, 오류가 안 나니 늦게 알아채게 되거든요. “열 번 중 아홉 번”으로 부족한 일, 안 지켜졌을 때 대가가 큰 일은 훅으로 올리세요. 대가가 작으면 여기 두는 편이 설정이 간단합니다.

꼭 지켜야 하는 일은 훅으로

훅은 모델이 판단해서 부르는 게 아니라, 이벤트가 나고 매처가 맞으면 Claude Code가 자동으로 실행합니다. 여기서 처음으로 “반드시 실행된다”는 보장이 생겨요.

막고 싶다면 도구가 실행되기 전 이벤트(PreToolUse)에 걸고 exit 2로 끝내면 됩니다. 다만 막을 수 있는 범위가 정해져 있어서 그걸 먼저 알고 거는 게 좋아요.

• exit 2가 같은 훅의 JSON 결정을 이깁니다. 막을 수 있는 이벤트에서 exit 2로 끝내면, 훅이 JSON으로 permissionDecision을 "allow"로 내도 차단돼요.
• 2026년 9월 21일 기준 exit 2로 막을 수 있는 이벤트는 네 개입니다. PreToolUse(도구 호출), UserPromptSubmit(프롬프트 처리, 프롬프트 삭제), UserPromptExpansion(확장), PreModelSwitch(모델 전환). 이벤트는 30개가 넘지만 나머지에 건 훅은 실행만 되고 동작을 멈추지 못합니다.
• 권한 요청 이벤트는 예외예요. 여기서는 exit 2가 인정되지 않고 권한 흐름이 그대로 진행됩니다. 거부하려면 종료 코드 대신 결정 객체를 돌려줘야 합니다.

주의: 도구가 끝난 뒤에 도는 이벤트로 결과를 막으려는 설계는 통하지 않습니다. 훅은 실행되고 로그도 남지만 막지는 못해서, 가장 조용하게 실패합니다.

반대로 무엇을 막을지 모르는 채 서둘러 훅을 걸어도 탈이 납니다. 넓게 잡은 매처가 정상 작업까지 막다가, 결국 훅을 통째로 끄게 되거든요.

그래서 저는 두세 번 반복해서 패턴이 보인 것만 훅으로 올리고, 올린 직후 일부러 한 번 걸려 보길 권합니다. 그게 가장 싼 확인이에요.

설정 방법과 예제는 훅 가이드에 있습니다.

사람 없이 돌리기 전에

승인할 사람이 없으니 실행 방식과 권한을 정하는 쪽이 달라집니다. 스크립트에서 돌리는 법은 claude -p 글에 있고, 일이 커지면 두 갈래로 나눠요.

• 컨텍스트를 나누려면 서브에이전트 — 조사와 검토를 나누는 커스텀 에이전트
• 파일을 나누려면 워크트리 — 병렬 세션을 돌리는 법과 안전한 정리

이 단계에서 제일 약한 게 되돌리기입니다. /rewind는 Claude가 파일 편집 도구로 고친 것만 되돌리고, Bash 명령이 옮기거나 지운 파일, 백그라운드 서브에이전트가 고친 파일, 세션 밖에서 손댄 파일에는 닿지 않아요. 사람 없이 돌릴수록 Bash 명령과 병렬 서브에이전트가 늘어나니, 되돌리기보다 애초에 못 하게 막는 쪽을 같이 세워 두세요.

• 묻지 않고 실행할 범위 — allow·deny 규칙의 평가 순서와 자주 새는 패턴
• 규칙이 닿지 않는 하위 프로세스까지 가두기 — 샌드박스와 권한 규칙의 차이
• 되돌리는 대신 버리면 되는 자리 만들기 — 워크트리

훅과 권한 규칙 자체는 설정 파일에서 지우면 되돌릴 수 있습니다. 되돌리기 어려운 건 그 단계에서 이미 실행된 결과예요.

마치며

자동화를 어디까지 맡길지는 결국 “안 지켜지면 무슨 일이 생기나”와 “사람이 언제 보나”의 문제라고 생각합니다. 위 단계를 한꺼번에 다 갖출 필요는 없고, 반복이 보일 때마다 한 칸씩 올리면 충분해요.

이번 주에 같은 설명을 두 번 이상 했다면, 그 내용을 프로젝트의 CLAUDE.md에 한 줄로 옮기는 것부터 해 보세요. 무엇을 적고 무엇을 뺄지는 CLAUDE.md 작성법에 정리해 뒀습니다.