Claude Code에서 독자적인 타이밍의 hooks를 직접 제작하기

이 기사는 Claude on SonicGarden의 기사입니다. SonicGarden의 프로그래머가 Claude Code의 활용에 대해 쓰고 있습니다. #claude_on_sonicgarden

Claude Code의 hooks 기능(hooks function)을 사용하려고 할 때, "발생시키고 싶은 타이밍과 조금 다르네"라고 느낀 적은 없으신가요? Stop이나 PreToolUse 등 준비되어 있는 이벤트는 편리하지만, 모두 "Claude Code 자신의 라이프사이클(lifecycle)"에 묶여 있어, 자신이 원하는 타이밍에 딱 맞지 않을 때가 있습니다.

그럴 때는, 워크플로우(workflow)를 TodoWrite를 사용한 스킬(skill)로 만듦으로써, 자신이 실행하고 싶은 타이밍의 hook을 직접 제작할 수 있다는 이야기입니다.

추가: 최근 버전에서는 태스크 리스트용 도구가 TodoWrite에서 Task* 계열 도구(TaskCreate / TaskUpdate 등)로 변경되었습니다. 이 기사의 메커니즘은 Task*에서도 그대로 성립합니다(각 단계를 TaskCreate로 등록하고, TaskUpdate로 하나씩 소화해 나가는 방식). 새로 스킬을 작성한다면 Task*가 좋을 것 같습니다. 아래의 TodoWrite는 Task*로 읽어주세요.

표준으로 준비되어 있는 hooks가 발생할 수 있는 타이밍은 2026년 4월 시점에서 27종류가 있습니다 (공식 문서). 대표적인 것을 들면:

• SessionStart / SessionEnd
• UserPromptSubmit / Stop
• PreToolUse / PostToolUse
• SubagentStart / SubagentStop
• TaskCreated / TaskCompleted
• PreCompact / PostCompact 등입니다. 모두 "Claude Code가 이런 상태가 되면"이 기점이며, "자작 워크플로우의 이 단계가 끝나면"과 같은 요구사항은 포착할 수 없습니다.

하는 일은 단순합니다.

• 워크플로우를 스킬화한다.
• 스킬의 서두에서 모든 단계를 TodoWrite에 등록시킨다.
• hook을 발생시키고 싶은 타이밍용 Todo도 다른 단계와 나란히 등록해 둔다.

각 단계가 Todo로서 나열되므로, Claude Code는 하나씩 in_progress → completed로 소화해 나갑니다. 원하는 타이밍용 Todo를 섞어 두면, 그 타이밍에 hook이 실행된다는 메커니즘입니다.

hook이라고 해도 특별한 장치가 있는 것이 아니라, Todo 리스트에 나열되는 하나의 단계에 불과합니다. 다만, 나열하는 타이밍을 자유롭게 선택할 수 있으므로, "테스트 후 · 리뷰 전"과 같이 표준 hooks로는 표현할 수 없는 타이밍을 만들 수 있습니다.

Markdown에 "Step 1, Step 2, ..."라고 나열하기만 하면, 페이즈(phase)를 건너뛰거나, 리뷰를 한 번에 끝내버리거나, 애초에 규칙이 지켜지지 않을 수 있습니다. TodoWrite에 나열해 두면 하나씩 completed로 만드는 동작이 되므로, 독자적인 타이밍의 hook도 지켜지기 쉬워집니다.

이 이야기는 별도의 기사에서 자세히 썼으므로 여기서는 깊게 다루지 않겠습니다.

실례로서, 제가 공개하고 있는 dev-workflow라는 스킬의 내용을 소개합니다. 계획 → 리뷰 → 구현 → 체크 → 코드 리뷰 → 규칙 업데이트라는 흐름을 돌리는 스킬입니다.

스킬의 서두에서 다음과 같은 등록을 하게 합니다.

Register all workflow phases with `TodoWrite`:
- Step 2: Create Plan
- Step 3: Plan Review
...

워크플로우 본체는 스킬에 하드코드(hard-code)되어 있어 팀에서 공유하는 것을 전제로 하지만, 거기에 단 한 곳 개인이 자유롭게 처리를 끼워 넣을 수 있는 hook 포인트를 마련해 두었습니다. 그것이 Step 10입니다.

사용자가 설정 파일에 다음과 같이 작성하면, 워크플로우 완료 시 임의의 스킬이나 명령어를 실행할 수 있습니다.

# .claude/dev-workflow.local.md
hooks:
  on_complete:
    ...

.local.md

.local.md는 개인 설정 파일로, .gitignore에 포함되는 것을 전제로 합니다. 즉, 팀 공유 워크플로우 (workflow)는 변경하지 않으면서, 자신만이 실행하고 싶은 프로세스를 삽입할 수 있는 설계입니다. PR 생성용 스킬 (skill)을 호출하거나, 완료 알림을 보내는 등 원하는 작업을 자유롭게 할 수 있습니다.

스킬 (skill) 측에서는, 최상단 설정 로드 단계에서 on_complete가 설정되어 있다면 Step 10: Completion Hooks를 TodoWrite에 등록합니다. Step 10의 처리 내용은 "등록된 엔트리 (entry)를 순서대로 실행한다"뿐입니다.

### Step 10: Completion Hooks
`hooks.on_complete`가 구성되지 않았다면 이 단계를 건너뜁니다.
1. `hooks.on_complete`의 각 엔트리를 순서대로 실행합니다:
...

표준 Stop 훅 (hook)으로도 유사한 작업을 할 수 있을 것 같지만, "이 스킬을 사용한 워크플로우 (workflow)가 정상적으로 완료되었을 때만"이라는 스코프 (scope)로 한정할 수 있다는 점이 차이점입니다. 일반적인 방식으로 Claude Code를 사용할 때는 트리거 (trigger)되지 않습니다.

동일한 설계로 "Step 5 (구현)가 끝난 후에 실행하는 훅 (hook)", "Step 8 (코드 리뷰) 전에 실행하는 훅 (hook)"과 같이, 원하는 타이밍을 위한 훅 (hook) 포인트 (point)를 늘리는 것도 가능하며, 아마 앞으로도 늘어나게 될 것입니다.

TodoWrite에 나열했다고 해서 100% 준수되는 것은 아닙니다. 도중에 경로를 이탈하여 Todo를 completed 상태로 만들지 못하거나, Todo가 남아 있음에도 다음 단계로 진행할 가능성은 있습니다.

하지만 실제로 사용해 본 느낌으로는 대부분의 케이스에서 의도한 대로 실행되어 주므로 충분히 현실적인 수단이라고 생각합니다.

워크플로우 (workflow)를 스킬 (skill)화하여 TodoWrite로 진행 관리를 하면, Claude Code의 표준 훅 (hook)으로는 도달할 수 없는 독자적인 타이밍에 프로세스를 삽입할 수 있습니다. dev-workflow에서는 팀 공유 워크플로우 (workflow)에 대해 개인별로 삽입할 수 있는 완료 훅 (completion hook)을 마련하는 방식으로 운용하고 있습니다.

독자적인 워크플로우 (workflow) 스킬 (skill)을 작성하고 계신 분들은, 훅 (hook) 삽입 포인트를 의도적으로 설계해 보는 것도 재미있을 것입니다.

이번에 구현 예시로 소개한 dev-workflow 스킬 (skill)은 아래 리포지토리 (repository)에서 공개하고 있습니다.

hiroro-work/claude-plugins

이 기사는 Zenn/Qiita에 크로스 포스트 (cross-post)되어 있습니다.