본문으로 건너뛰기

AI Coding Tools · EP 04

Claude Code 확장 설계 — hooks·skills·sub-agents로 워크플로 자산 만들기

Claude Code를 "잘 쓰는 것"과 "내 것으로 만드는 것"은 다르다. hooks로 생명주기를 제어하고, skills로 지식을 온디맨드로 내려주고, sub-agents로 역할을 분리하는 확장 설계를 정리했습니다.

· 3분 읽기

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" }] }
    ]
  }
}

실전에서 유용했던 패턴 세 가지:

  1. Stop 알림 — 긴 작업을 던져놓고 다른 일 할 때 필수
  2. 제출 전 컨텍스트 점검 — 프롬프트 제출 시점에 잔여 예산을 경고
  3. “계속” 주입 — 응답이 끝나도 다음 단계를 이어가게 하는 Do more 패턴 (단, 무한 루프 주의)

4. Sub-agents — 역할 분리와 어텐션 보존

sub-agents는 메인 에이전트가 스폰하는 별도 인스턴스다. 기본 타입만 잘 써도 구조가 달라진다.

  • Explore (읽기 전용) — 코드베이스 조사를 맡긴다. 새 컨텍스트에서 시작하므로 메인 세션이 깨끗하다.
  • Plan — 구현 전 설계안을 뽑게 해서, 구현 에이전트와 계획 에이전트를 분리한다.

주의점 하나. Explore는 요약(손실 압축)을 반환한다. 그래서 판단에 중요한 파일은 메인 에이전트가 직접 읽게 해서 어텐션이 맥락을 가로지르게 하는 게 정확도에 유리하다. 조사는 싸게, 판단은 비싸게.

5. Commands — 절차의 자산화

반복하는 프롬프트가 정적이고 절차적이면 커스텀 명령으로 만든다. .claude/commands/에 마크다운 하나 넣으면 끝난다.

제 목록 중 가장 자주 쓰는 것:

명령은 스킬과 다르게 순서가 있는 절차에 강하다. 체크리스트를 사람이 읽으며 확인하는 대신, 명령으로 만들어두면 에이전트가 매번 같은 순서로 검사하고 결과를 표로 돌려준다.

마치며 — 도구가 아니라 자산을 설계하라

정리하면 이렇다.

  • 지식은 skills로 지연 로딩하고
  • 부수 효과는 hooks로 컨텍스트 밖에서 처리하며
  • 역할은 sub-agents로 분리하고
  • 절차는 commands로 자산화한다

이 네 가지는 Claude Code의 기능이지만, 설계 자체는 도구를 초월한다. 에이전트가 바뀌어도 “지식/효과/역할/절차”의 분리는 유효하다. 워크플로를 도구에 맞추지 말고, 도구가 죽어도 남는 자산 구조로 쌓아야 한다.

Related

· 3 min read AI Coding Tools

Claude Code vs Codex — 둘 다 쓰는 사람의 실전 비교 (2026년 말)

한쪽만 쓰는 리뷰는 많지만, 두 에이전트를 매일 같이 돌리는 사람의 비교는 드물다. 확장성(hooks/skills/sub-agents)과 안정성, 교차 리뷰 구조까지 — 듀얼 에이전트 사용자의 실전 관점을 정리했습니다.

프론트엔드AI
→