Claude Code 하네스, Skill·subagent·hook만으로 시작하는 법

Claude Code 하네스를 처음부터 크게 짜야 할까. 공식 구조와 최근 변경 기록을 따라가면 답은 반대쪽에 가깝다. 이미 코드를 읽고 명령을 실행하는 에이전트 위에, Skill·subagent·hook을 필요한 만큼만 얹는 편이 관리와 검증에 유리하다.

하네스는 새 에이전트가 아니라 실행 환경이다

하네스는 Claude Code를 대신하는 별도 코딩 엔진이 아니다. 프로젝트 지침, 재사용 절차, 권한, 검증 시점을 묶어 행동 범위를 만드는 운영층이다. Anthropic 공식 저장소도 플러그인을 `commands/`, `agents/`, `skills/`, `hooks/`, `.mcp.json`의 조합으로 설명한다.

클코단 대화에서는 프롬프트와 마크다운, 훅만으로도 출발할 수 있다는 의견이 많았다. 공식 구조도 이 관찰을 뒷받침한다. 모든 구성요소를 한꺼번에 넣어야 플러그인이 되는 것은 아니다. 명령 하나만 둔 최소 플러그인과 Skill만 담은 플러그인도 공식 예시에 포함된다.

작게 시작해야 하는 이유는 기능 수보다 충돌 지점에 있다.

지침이 늘면 어떤 규칙이 현재 작업을 지배하는지 추적하기 어려워진다. 훅이 많아지면 편집마다 추가 명령이 실행될 수 있다. subagent를 남발할수록 전달 문맥과 결과 취합 비용도 커진다.

Skill과 subagent는 닮았지만 같은 부품이 아니다

Skill은 특정 일을 하는 방법을 현재 에이전트에 가르친다. 공식 plugin-dev 문서는 필수 `SKILL.md`와 선택적인 `scripts/`, `references/`, `assets/`를 기본 구조로 제시한다. 이름과 설명은 항상 노출된다. 본문은 발동할 때 읽고 세부 자료는 필요할 때만 불러온다. 이 점진적 공개 방식은 긴 지침이 매번 문맥을 차지하는 문제를 줄인다.

subagent 정의도 마크다운 본문과 YAML frontmatter를 쓴다. 그래서 두 파일이 비슷해 보인다는 커뮤니티 관찰은 타당하다. 차이는 실행 위치다. Skill은 메인 에이전트의 지식과 절차를 보강한다. subagent는 독립 문맥에서 여러 단계를 수행하고 결과를 부모에게 돌려준다.

공식 agent-development 자료에서 `description`은 호출 조건을 정하고 본문은 subagent의 시스템 프롬프트가 된다. `tools`로 사용할 도구를 좁히고 `model`도 지정할 수 있다. 읽기 전용 조사자라면 Read·Grep 계열만 주는 식이다. 별도 판단이나 병렬 작업이 필요하지 않다면 Skill 하나가 더 단순하다.

hook은 조언이 아니라 실행 시점을 고정한다

지침은 모델이 해석하지만 hook은 정해진 사건에 반응한다. Claude Code는 도구 실행 전후, 세션 시작과 종료, 중단, subagent 종료 같은 생명주기 지점을 제공한다. 공식 hook-development 자료는 프롬프트 기반 판단과 명령 기반 검사를 구분한다. 입력 검증이나 포맷 검사처럼 결과가 명확한 일은 명령 hook에 잘 맞는다.

예를 들어 파일 편집 뒤 린터를 돌리고 싶다면 `PostToolUse`에서 Edit·Write 계열만 걸러 검사 스크립트를 호출할 수 있다. 위험한 셸 명령을 사전에 막으려면 `PreToolUse`가 맞다. 작업이 끝났다는 주장 전에는 `Stop`으로 테스트 상태를 확인할 수 있다. hook은 표준 입력으로 사건 정보를 받고 종료 코드나 JSON으로 허용·차단·추가 문맥을 돌려준다.

강제력에는 비용이 따른다.

모든 편집에 무거운 테스트를 붙이면 응답이 느려진다. 잘못 만든 Stop hook은 종료를 반복해서 막을 수 있다. Anthropic의 공식 플러그인 디렉터리도 설치 전 코드를 신뢰할 수 있는지 확인하라고 경고한다. hook과 MCP 서버는 외부 프로그램까지 실행할 수 있기 때문이다.

최소 하네스는 한 작업을 세 파일로 나눈다

개인 개발자나 작은 팀이라면 반복해서 실패하는 작업 하나를 고르는 편이 좋다. 가령 인증 코드를 바꿀 때 회귀 검사를 자주 빼먹는다면, 먼저 `.claude/skills/auth-check/SKILL.md`에 호출 조건과 검토 순서를 적는다. API 규칙은 `references/`로 빼고 반복 가능한 검사는 `scripts/`에 둔다. 입력은 "인증 변경을 검토해줘"이고 산출물은 위험 목록과 실행한 검사 결과다.

다음 단계는 별도 문맥이 필요할 때만 연다. `.claude/agents/auth-reviewer.md`에 역할, 호출 조건, 출력 형식을 적고 도구를 읽기와 테스트 실행으로 제한한다. 메인 에이전트는 구현을 맡고 reviewer는 변경 파일과 테스트 결과를 독립적으로 확인한다. 여러 에이전트가 같은 파일을 동시에 고칠 가능성이 있다면 worktree 격리를 검토한다.

마지막에 `.claude/settings.json`의 hook 설정으로 검증 시점을 고정한다. 편집 직후에는 빠른 정적 검사만 실행하고 종료 시에는 관련 테스트를 확인하는 식으로 나눈다. Skill이 방법을 설명하고 subagent가 독립 검토를 맡으며 hook이 빠뜨릴 수 없는 검사를 실행한다. 세 층의 책임이 겹치지 않아야 고장이 난 위치도 찾기 쉽다.

최근 변화는 더 큰 하네스보다 경계 설계를 요구한다

Claude Code의 최근 변경 기록에는 worktree로 격리된 subagent의 체크아웃 처리, background agent 중단, Skill·command·agent 로딩과 관련한 수정이 이어진다. 기능이 이미 제품 안으로 깊게 들어왔다는 신호다. 사용자가 별도 오케스트레이터를 먼저 만들 이유는 줄었지만 공유 작업공간과 권한 경계는 더 세심하게 정해야 한다.

클코단에서는 hook을 하네스의 핵심으로 보는 의견과, 환경과 지침이 먼저라는 의견이 함께 나왔다. 둘은 우선순위가 다르다. 실패가 ‘방법을 몰라서’ 생기면 Skill이 먼저다. 독립 판단이 필요하면 subagent를 추가한다. 정해진 검사를 자꾸 건너뛸 때는 그때 hook을 붙인다.

좋은 하네스의 크기는 파일 수로 재지 않는다. 같은 실수를 다시 막고도, Claude Code가 원래 가진 판단력을 가리지 않는지가 기준이다. 한 가지 반복 실패를 세 책임으로 분리한 뒤에도 설명할 수 없다면, 하네스가 아니라 또 하나의 복잡한 제품을 만든 것이다.