Claude Code 확장 설계 — hooks·skills·sub-agents로 워크플로 자산 만들기
Claude Code를 "잘 쓰는 것"과 "내 것으로 만드는 것"은 다르다. hooks로 생명주기를 제어하고, skills로 지식을 온디맨드로 내려주고, sub-agents로 역할을 분리하는 확장 설계를 정리했습니다.
Claude Code 확장 설계 — hooks·skills·sub-agents로 워크플로 자산 만들기
Claude Code 입문기는 이제 넘쳐난다. 문제는 그 다음이다. 기본 프롬프트를 넘어서는 순간 — “이 프로젝트의 관례를 어떻게 가르치지?”, “긴 작업을 어떻게 감시하지?”, “컨텍스트가 새는 걸 어떻게 막지?” — 답이 없어서 매번 손으로 때우게 된다.
이 글은 그 답을 설계로 정리한다. hooks, skills, sub-agents를 각각의 용도에 맞게 배치하는 방법과, 제가 듀얼 플랫폼(Codex 포함) 환경에서 이 자산을 지키는 방식이다.
1. 컨텍스트 예산이 모든 설계의 출발점
확장 설계를 하기 전에 받아들여야 할 사실이 하나 있다. 컨텍스트는 찰 수록 모델이 둔해진다. 실효 컨텍스트는 체감상 절반 이하로 보는 게 안전하고, 60%쯤 찼으면 긴 작업을 새로 시작하지 말고 세션을 나눠야 한다.
그래서 모든 확장 설계의 기준은 “언제 컨텍스트에 들어가는가”다.
| 장치 | 컨텍스트 진입 시점 | 적합한 지식 |
|---|---|---|
| CLAUDE.md | 항상 | 프로젝트 최소 계약 (10줄 이내 권장) |
| Skills | 관련 있을 때만 | 도메인 지식 전체 (500줄 이내) |
| Commands | 호출 시에만 | 반복 작업의 절차 |
| Hooks | 안 들어감 (셸에서 실행) | 알림, 강제, 검증 |
초보자의 실수는 CLAUDE.md에 모든 것을 우겨넣는 것. 그러면 모든 세션이 비용을 물고 시작한다. 최소 계약은 CLAUDE.md에, 나머지는 전부 지연 로딩이 원칙이다.
2. Skills — “I know Kung Fu” 구조
Skills는 SKILL.md와 참조 파일로 이뤄진 폴더고, 메타데이터만 시스템 프롬프트에 올라간다. 모델이 필요하다고 판단할 때 본문을 읽는다. 즉 도메인 전문지식의 온디맨드 다운로드다.
제 구성 예시:
.claude/skills/frontend-release/
SKILL.md # 이 스킬이 언제 필요한지 + 목차
refs/gates.md # 릴리즈 게이트 상세
refs/rollback.md # 롤백 절차
스킬 설계의 핵심은 SKILL.md를 목차로 쓰는 것이다. “이 기능을 다룰 때 이 스킬을 읽어라”는 판단 기능을 description에 명확히 써두면, 호출 정확도가 확 올라간다.
이 구조의 진짜 이점은 이식성이다. 스킬이 프로젝트 지식의 표준 포맷이 되면, Claude Code와 Codex를 병행하는 제 환경에서도 같은 문서 자산을 양쪽에서 재활용할 수 있다.
3. Hooks — 생명주기의 톱니바퀴
Hooks는 에이전트 루프의 특정 시점에 셸 스크립트를 끼워 넣는 장치다. 컨텍스트를 안 쓰므로, 부수 효과가 필요한 자리에 최적이다.
{
"hooks": {
"Stop": [
{ "hooks": [{ "type": "command", "command": "notify-send '작업 종료'" }] }
],
"UserPromptSubmit": [
{ "hooks": [{ "type": "command", "command": ".claude/scripts/context-check.sh" }] }
]
}
}
실전에서 유용했던 패턴 세 가지:
- Stop 알림 — 긴 작업을 던져놓고 다른 일 할 때 필수
- 제출 전 컨텍스트 점검 — 프롬프트 제출 시점에 잔여 예산을 경고
- “계속” 주입 — 응답이 끝나도 다음 단계를 이어가게 하는 Do more 패턴 (단, 무한 루프 주의)
4. Sub-agents — 역할 분리와 어텐션 보존
sub-agents는 메인 에이전트가 스폰하는 별도 인스턴스다. 기본 타입만 잘 써도 구조가 달라진다.
- Explore (읽기 전용) — 코드베이스 조사를 맡긴다. 새 컨텍스트에서 시작하므로 메인 세션이 깨끗하다.
- Plan — 구현 전 설계안을 뽑게 해서, 구현 에이전트와 계획 에이전트를 분리한다.
주의점 하나. Explore는 요약(손실 압축)을 반환한다. 그래서 판단에 중요한 파일은 메인 에이전트가 직접 읽게 해서 어텐션이 맥락을 가로지르게 하는 게 정확도에 유리하다. 조사는 싸게, 판단은 비싸게.
5. Commands — 절차의 자산화
반복하는 프롬프트가 정적이고 절차적이면 커스텀 명령으로 만든다. .claude/commands/에 마크다운 하나 넣으면 끝난다.
제 목록 중 가장 자주 쓰는 것:
/handoff— 세션 종료 전, 다음 세션을 위한 상태 요약을 남긴다/gate— 릴리즈 준비도 체크리스트를 절차로 실행한다
명령은 스킬과 다르게 순서가 있는 절차에 강하다. 체크리스트를 사람이 읽으며 확인하는 대신, 명령으로 만들어두면 에이전트가 매번 같은 순서로 검사하고 결과를 표로 돌려준다.
마치며 — 도구가 아니라 자산을 설계하라
정리하면 이렇다.
- 지식은 skills로 지연 로딩하고
- 부수 효과는 hooks로 컨텍스트 밖에서 처리하며
- 역할은 sub-agents로 분리하고
- 절차는 commands로 자산화한다
이 네 가지는 Claude Code의 기능이지만, 설계 자체는 도구를 초월한다. 에이전트가 바뀌어도 “지식/효과/역할/절차”의 분리는 유효하다. 워크플로를 도구에 맞추지 말고, 도구가 죽어도 남는 자산 구조로 쌓아야 한다.