Claude Code, 프롬프트만으로는 부족하다 — 4계층 하네스 완전 가이드

프롤로그: 모델이 아니라 하네스가 이긴다

AI 코딩 경쟁에서 반복적으로 관찰되는 패턴이 있습니다. 더 강한 모델로 교체해도 팀 생산성이 크게 달라지지 않는 반면, 같은 모델에 구조를 더하자 결과가 극적으로 바뀌는 사례들입니다.

가장 선명한 예는 LangChain의 사례입니다. 그들은 모델을 전혀 교체하지 않은 채 하네스 구조만 개선해 Terminal Bench 2.0에서 52.8%에서 66.5%로 성능을 끌어올렸습니다. 순위는 Top 30에서 Top 5로 뛰었습니다. Claude Code가 출시 6개월 만에 연간 매출 10억 달러를 돌파한 것도 Anthropic이 더 나은 모델을 만들었기 때문만이 아닙니다. 스트리밍 에이전트 루프, 권한 통제 툴 디스패치 시스템, 세션 전반에 걸친 컨텍스트 관리 계층, 즉 하네스를 제대로 설계했기 때문입니다.

공식은 간단합니다.

Agent = Model + Harness

하네스는 모델 이외의 모든 것입니다. 규칙, 절차, 검증 게이트, 격리 실행 환경. 이 네 가지를 Claude Code에서 담당하는 것이 CLAUDE.md, Skills, Hooks, Subagents입니다.

이 글은 이 4계층 각각의 역할이 무엇이고, 언제 무엇을 써야 하며, 어떻게 통합해 프로덕션 수준의 운영 구조를 만드는지를 단계별 예시와 함께 설명합니다.

---

1. 하네스의 4계층 개요

Claude Code 하네스는 크게 네 개의 계층으로 나뉩니다. 각 계층은 역할이 다르고 책임 범위가 다릅니다. 하나로 합쳐질 수 없습니다.

계층	구성 요소	핵심 역할	지속성
Layer 1	CLAUDE.md	규칙·컨텍스트·장기 기억	세션 영구
Layer 2	Skills	절차 자동화·도메인 전문성	호출 시 활성
Layer 3	Hooks	결정론적 실행 게이트	이벤트마다 발동
Layer 4	Subagents	격리 실행·병렬 작업	요청 단위 독립

왜 4계층이어야 하는가

프롬프트 하나에 모든 것을 넣으려는 시도는 일정 규모를 넘으면 반드시 무너집니다. 규칙과 절차가 같은 공간에 섞이면 모델은 무엇을 우선해야 할지 혼란스러워합니다. 검증이 프롬프트에 의존하면 모델이 실수할 때 검증도 같이 실패합니다. 격리 없이 하나의 세션에서 모든 것을 처리하면 컨텍스트 오염이 쌓입니다.

4계층은 이 문제들을 각각의 계층에서 독립적으로 해결합니다.

---

2. Layer 1: CLAUDE.md — 에이전트의 장기 기억

CLAUDE.md가 하는 일

세션이 시작될 때마다 Claude Code는 프로젝트 루트의 CLAUDE.md를 자동으로 읽습니다. 이것이 에이전트의 세션 간 기억입니다. 인간으로 치면 "이 팀에 입사할 때 받는 온보딩 문서"에 해당합니다.

CLAUDE.md가 없으면 에이전트는 매 세션마다 처음 입사한 사람처럼 동작합니다. 기술 스택이 무엇인지, 어떤 컨벤션을 따르는지, 어떤 파일을 절대 건드리면 안 되는지 모릅니다.

무엇을 담아야 하는가

담아야 하는 것:

• 기술 스택과 버전 (어떤 패키지 매니저, 어떤 프레임워크)
• 코드 컨벤션 (변수 네이밍, 파일 구조 규칙)
• 금지 행동 (절대 수정하면 안 되는 파일, 절대 쓰면 안 되는 패턴)
• 프로젝트 아키텍처 핵심 구조 (어떤 계층이 어떤 역할)
• 커밋·PR 메시지 형식
• 테스트 실행 방법

담지 말아야 하는 것:

• 일회성 지시 (이번 세션에서만 유효한 것은 대화에서 처리)
• 너무 긴 코드 블록 (긴 예시는 별도 파일 참조)
• 자주 바뀌는 비즈니스 로직 (하드코딩하면 유지보수 비용 증가)
• Skills나 Hooks로 처리할 수 있는 절차 (계층 혼용 금지)

실전 예시: Claude Code 프로젝트용 CLAUDE.md

# 프로젝트 개요
Next.js 15 + TypeScript 프로젝트. App Router 사용.
패키지 매니저: npm (절대 yarn/pnpm 사용 금지)

# 핵심 아키텍처
- app/ : 라우트 (서버 컴포넌트 우선)
- components/ : 재사용 UI
- lib/ : 비즈니스 로직 (서버 전용)
- hooks/ : 클라이언트 훅

# 코드 규칙
- 컴포넌트: PascalCase, 파일명도 동일
- 변수/함수: camelCase
- 상수: UPPER_SNAKE_CASE
- import 순서: 외부 패키지 → 내부 절대경로 → 상대경로

# 절대 금지
- lib/ 아래 파일에서 useState/useEffect 사용 금지
- any 타입 신규 추가 금지
- console.log 커밋 금지 (console.error는 허용)
- node_modules, .env 파일 절대 수정 금지

# 테스트
npm run test:unit  # 유닛 테스트
npm run test:e2e   # E2E (로컬에서만)

# 커밋 형식
feat(scope): 설명
fix(scope): 설명
refactor(scope): 설명

계층화: 서브디렉터리 CLAUDE.md

프로젝트 규모가 커지면 루트 CLAUDE.md 하나로는 부족합니다. Claude Code는 서브디렉터리에 CLAUDE.md를 두는 것을 지원합니다. 에이전트가 해당 디렉터리에서 작업할 때 추가로 로드합니다.

project/
├── CLAUDE.md              # 전체 프로젝트 공통 규칙
├── app/
│   └── CLAUDE.md          # 라우트별 특수 규칙
├── lib/
│   └── CLAUDE.md          # 서버 로직 규칙
└── tests/
    └── CLAUDE.md          # 테스트 작성 규칙

예를 들어 lib/CLAUDE.md에는 다음처럼 특화 규칙을 담을 수 있습니다.

# lib/ 전용 규칙
이 디렉터리의 모든 파일은 서버 전용입니다.
- React 훅 import 절대 금지
- 외부 API 호출 시 반드시 lib/fetcher.ts의 공통 클라이언트 사용
- 새 파일 추가 시 lib/index.ts에 re-export 추가 필수
- 에러 처리: throw new AppError(...) 패턴 사용 (Error 직접 throw 금지)

안티패턴: CLAUDE.md 비대화

CLAUDE.md가 200줄을 넘기 시작하면 위험 신호입니다. 모델이 어느 규칙을 우선해야 하는지 판단하기 어려워지고 준수율이 오히려 낮아집니다. 규칙, 절차, 자동 검사를 분리하는 것이 핵심입니다.

• 규칙: CLAUDE.md (무엇을 해야 하는가)
• 절차: Skills (어떻게 해야 하는가)
• 강제 검사: Hooks (확실히 실행되어야 하는가)

---

3. Layer 2: Skills — 에이전트의 도메인 전문성

Skills가 하는 일

Skills는 Claude Code에서 반복되는 작업 절차를 /슬래시 커맨드로 캡슐화한 것입니다. 비유하자면 회사의 SOP(표준 운영 절차)를 에이전트가 언제든 꺼내 쓸 수 있는 형태로 저장한 것입니다.

CLAUDE.md가 "무엇을 알아야 하는가"라면, Skills는 "무엇을 어떻게 해야 하는가"입니다.

Skill 파일 구조

Skill은 .claude/skills/ 디렉터리에 마크다운 파일로 저장합니다.

.claude/
└── skills/
    ├── commit.md
    ├── review-pr.md
    ├── create-component.md
    └── deploy-check.md

모든 Skill 파일은 두 부분으로 구성됩니다.

1. YAML frontmatter: Claude가 언제 이 Skill을 쓸지 결정하는 메타데이터
2. 마크다운 본문: Claude가 실행할 때 따르는 단계별 지시

실전 예시 1: 커밋 Skill

---
name: commit
description: 스테이징된 변경사항을 분석하고 컨벤셔널 커밋 메시지로 커밋한다
triggers:
  - "커밋"
  - "commit"
  - "변경사항 저장"
---

## 커밋 절차

1. `git diff --staged`로 스테이징된 변경사항 전체 파악
2. 변경 유형 분류 (feat/fix/refactor/chore/docs/test)
3. 영향 범위(scope) 결정 — 변경된 주요 모듈명 사용
4. 50자 이내 한글 설명 작성
5. 파괴적 변경(BREAKING CHANGE)이 있으면 body에 명시
6. 커밋 실행 전 반드시 사용자에게 메시지 확인 요청

### 커밋 메시지 형식

{type}({scope}): {description}

[optional body] [optional footer]

### 금지 사항
- git add -A 또는 git add . 사용 금지
- 테스트 실패 상태로 커밋 금지
- .env 파일이 스테이징에 포함된 경우 즉시 중단 후 사용자에게 알림

실전 예시 2: PR 리뷰 준비 Skill

---
name: review-pr
description: PR을 제출하기 전 코드 품질과 안전성을 자체 점검한다
triggers:
  - "PR 리뷰"
  - "pr review"
  - "PR 제출 전 점검"
---

## PR 리뷰 체크리스트

### 1. 범위 확인
- 변경된 파일 목록 확인: `git diff --name-only origin/main`
- 의도하지 않은 파일이 포함되지 않았는지 확인

### 2. 코드 품질
- TypeScript 타입 오류 확인: `tsc --noEmit`
- 린트 통과 여부: `npm run lint`
- 새로 추가한 함수에 테스트가 있는지 확인

### 3. 보안 점검
- 하드코딩된 시크릿(API 키, 비밀번호) 없는지 확인
- 외부 입력 검증 로직이 있는지 확인

### 4. PR 설명 작성
다음 구조로 PR description 초안 작성:
- **무엇을 바꿨나:** 1-3 bullet points
- **왜 바꿨나:** 비즈니스/기술 이유
- **테스트 방법:** 검증 단계
- **스크린샷:** UI 변경 시 첨부 필요 표시

자동 발동 vs 수동 호출

Skills의 frontmatter에 triggers를 지정하면 Claude가 관련 작업을 감지할 때 자동으로 해당 Skill을 활성화합니다. 반면 /commit처럼 슬래시 커맨드로 직접 호출할 수도 있습니다.

자동 발동 권장 케이스:

• 항상 같은 방식으로 처리해야 하는 반복 작업
• 절차가 복잡하지만 트리거가 명확한 작업

수동 호출 권장 케이스:

• 사용자가 명시적으로 개시해야 하는 작업 (배포, 대규모 리팩터링)
• 실수로 발동되면 비용이 큰 작업

팀 재사용 구조

Skills의 가장 큰 장점은 팀 자산화입니다. 개인의 프롬프트 노하우를 .claude/skills/에 파일로 저장하면 저장소를 clone하는 모든 팀원이 동일한 절차를 사용할 수 있습니다.

# 팀 공유 Skills 추천 목록
.claude/skills/
├── commit.md              # 커밋 메시지 표준
├── review-pr.md           # PR 리뷰 체크리스트
├── create-component.md    # 컴포넌트 생성 템플릿
├── write-test.md          # 테스트 작성 가이드
├── debug-error.md         # 에러 디버깅 절차
└── deploy-check.md        # 배포 전 최종 점검

---

4. Layer 3: Hooks — 결정론적 실행 게이트

Hooks가 Skills와 다른 결정적 이유

Skills는 Claude가 "이 절차를 따르도록" 유도합니다. 하지만 모델은 실수할 수 있습니다. 또는 컨텍스트가 부족할 때 절차를 건너뛸 수 있습니다.

Hooks는 다릅니다. Hooks는 모델 행동과 무관하게 항상 실행됩니다. 프롬프트가 아닌 시스템 수준의 강제 실행입니다. git hooks와 같은 개념이지만 Claude Code의 에이전트 라이프사이클 전반에 적용됩니다.

비유하면 이렇습니다:

• Skills: "출근 전 이 체크리스트를 따르세요" (권고)
• Hooks: "출입 카드 없으면 문이 열리지 않습니다" (강제)

Hooks 발동 시점

Claude Code Hooks는 두 가지 주요 시점에 발동합니다.

발동 시점	용도
PreToolUse	도구 실행 전 — 차단 또는 수정 가능
PostToolUse	도구 실행 후 — 결과 검증 또는 후처리

실전 예시 1: 시크릿 스캔 Hook (PreToolUse)

파일을 저장하거나 커밋하기 전에 API 키나 비밀번호가 포함되지 않았는지 확인합니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c \"echo '$CLAUDE_TOOL_INPUT' | python3 scripts/secret-scan.py\""
          }
        ]
      }
    ]
  }
}

secret-scan.py 스크립트가 시크릿 패턴을 발견하면 Claude Code가 해당 파일 저장 작업을 중단합니다. 모델이 실수로 API 키를 코드에 하드코딩하려 해도 물리적으로 차단됩니다.

실전 예시 2: 자동 린트 Hook (PostToolUse)

파일을 수정할 때마다 자동으로 린트를 실행합니다.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint -- --fix $CLAUDE_TOOL_INPUT_PATH 2>&1 | tail -5"
          }
        ]
      }
    ]
  }
}

모델이 파일을 수정할 때마다 lint가 자동으로 실행되고, 수정 가능한 문제는 자동으로 고쳐집니다. 사람이 나중에 오 린트 오류가 있네를 발견할 일이 줄어듭니다.

실전 예시 3: 위험 파일 접근 차단 Hook

특정 경로의 파일을 절대 수정하지 못하도록 강제합니다.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 -c \"\nimport json, sys, os\ntool_input = json.loads(os.environ.get('CLAUDE_TOOL_INPUT', '{}'))\npath = tool_input.get('file_path', '') or tool_input.get('path', '')\nprotected = ['.env', 'secrets/', 'migrations/']\nif any(p in path for p in protected):\n    print(f'BLOCKED: {path} is a protected file')\n    sys.exit(1)\n\""
          }
        ]
      }
    ]
  }
}

Hooks 배치 위치

Hooks 설정은 두 곳에 배치할 수 있습니다.

• 프로젝트 수준: .claude/settings.json — 저장소에 공유, 팀 전체 적용
• 사용자 수준: ~/.claude/settings.json — 개인 머신 전체 적용

.claude/
├── settings.json          # 팀 공유 Hooks (저장소에 커밋)
└── settings.local.json    # 개인 Hooks (gitignore)

Hooks를 쓸 때 주의할 것

Hooks는 강력하지만 무거워지면 느려집니다. 모든 파일 저장에 복잡한 검사를 거는 것은 에이전트 속도를 크게 낮춥니다. 다음 기준으로 선별하세요.

• 반드시 실행되어야 하는 것만 Hooks에
• 권고 수준은 Skills에
• 무거운 검사는 CI/CD에

---

5. Layer 4: Subagents — 격리 실행과 병렬 작업

왜 하나의 에이전트로 모든 것을 처리하면 안 되는가

Claude Code의 단일 세션에서 탐색·구현·리뷰를 모두 처리하면 두 가지 문제가 생깁니다.

컨텍스트 오염: 탐색하면서 쌓인 노이즈(읽은 파일들, 중간 메모들)가 구현 단계의 판단을 흐립니다.

책임 불분명: 리뷰 단계에서 모델은 자신이 구현한 코드를 평가합니다. 자기 작업에 관대해지는 경향이 있습니다.

Subagents는 이 두 문제를 모두 해결합니다. 독립된 컨텍스트 창에서 독립된 목적으로 실행되기 때문입니다.

Subagent의 3가지 핵심 활용 패턴

패턴 1: 역할 분리 (탐색 → 구현 → 리뷰)

가장 기본적이고 효과적인 패턴입니다.

Main Agent
├── [Subagent A: Research]
│   목적: 코드베이스 탐색 및 요구사항 분석
│   출력: 구현에 필요한 컨텍스트 요약
│
├── [Subagent B: Implement]
│   목적: 탐색 결과를 받아 코드 구현
│   입력: A의 컨텍스트 요약만 (전체 탐색 로그 아님)
│
└── [Subagent C: Review]
    목적: B의 구현 결과 독립 검토
    입력: 구현된 코드 + 원본 요구사항
    (B의 사고 과정은 전달하지 않음)

Claude Code에서 서브에이전트를 명시적으로 사용하는 방법:

/fork research
이 저장소에서 UserAuthService가 어떻게 동작하는지 분석하고
세션 토큰 처리 방식, 만료 로직, 관련 테스트 파일을 요약해줘.

탐색 결과를 받은 뒤:

/fork implement
[탐색 요약 붙여넣기]
위 분석을 바탕으로 리프레시 토큰 로테이션 기능을 추가해줘.
기존 인터페이스는 변경하지 말고, 새 메서드만 추가할 것.

구현 완료 후:

/fork review
[구현된 코드 파일 경로 나열]
위 파일들이 다음 요구사항을 충족하는지 독립적으로 검토해줘:
1. 기존 인터페이스 변경 없음
2. 토큰 만료 엣지 케이스 처리
3. 보안 취약점 없음

패턴 2: 병렬 독립 작업

서로 의존성이 없는 작업을 동시에 처리합니다. 예를 들어 세 개의 독립된 컴포넌트를 동시에 만들거나, 여러 파일의 테스트를 동시에 작성하는 것입니다.

# 병렬 서브에이전트 예시
Main Agent → [Subagent A: Header 컴포넌트 구현]
          → [Subagent B: Footer 컴포넌트 구현]
          → [Subagent C: Sidebar 컴포넌트 구현]

세 작업이 동시에 진행되므로 순차 처리 대비 시간이 크게 줄어듭니다.

패턴 3: 전문화된 에이전트 팀

특정 도메인에 특화된 서브에이전트를 만들어 두고 재사용합니다. 예를 들어 "보안 검토 전문 에이전트", "성능 분석 전문 에이전트"처럼요.

.claude/agents/ 디렉터리에 커스텀 에이전트 설정을 저장할 수 있습니다.

---
name: security-reviewer
description: 보안 취약점 전용 코드 리뷰 에이전트. 새 코드가 추가될 때 자동 호출.
model: claude-sonnet-4-6
tools: Read, Grep
---

당신은 보안 전문 코드 리뷰어입니다.
다음 항목을 반드시 확인하세요:

1. SQL 인젝션 가능성 (쿼리에 외부 입력 직접 삽입 여부)
2. XSS 취약점 (DOM 조작 시 이스케이프 여부)
3. 인증 우회 가능성 (권한 검사 누락)
4. 하드코딩된 시크릿
5. 민감한 데이터 로깅

각 항목별로 위험도(High/Medium/Low)와 해결 방안을 제시하세요.

Subagents를 쓸 때 주의할 것

서브에이전트는 비용이 따릅니다. 각 서브에이전트는 독립적인 컨텍스트 창을 사용하므로 토큰 비용이 추가됩니다. 다음 기준으로 판단하세요.

• 컨텍스트 오염이 실제 문제가 되는 규모의 작업에만 사용
• 독립 검증이 필요한 중요 작업에 우선 적용
• 단순 파일 수정 같은 소규모 작업은 단일 세션에서 처리

---

6. 4계층 통합: 실제 PR 워크플로우

이제 4계층이 실제 작업에서 어떻게 함께 동작하는지 전체 흐름으로 봅니다.

시나리오: 새 기능 추가 → PR 제출

[세션 시작]
  └─ CLAUDE.md 자동 로드
      ├─ 기술 스택 (Next.js 15, TypeScript)
      ├─ 코드 컨벤션 (import 순서, 네이밍)
      └─ 금지 행동 (any 타입 금지, console.log 금지)

[탐색 단계: Subagent A 호출]
  └─ 요구사항 관련 기존 코드 구조 파악
      └─ 출력: 컨텍스트 요약 문서

[구현 단계: Subagent B 호출]
  └─ 컨텍스트 요약 기반 코드 작성
      ├─ 파일 저장 시 → PreToolUse Hook 발동
      │   └─ 시크릿 스캔 통과 여부 확인
      └─ 파일 저장 후 → PostToolUse Hook 발동
          └─ 자동 린트 실행 + 수정

[리뷰 단계: Subagent C 호출]
  └─ 독립적으로 구현 결과 검토
      └─ 체크리스트 기반 리포트 출력

[PR 제출 준비: /review-pr Skill 호출]
  └─ PR 설명 초안 자동 생성
      ├─ tsc --noEmit 타입 검사
      ├─ 변경 범위 확인
      └─ PR description 템플릿 완성

[커밋: /commit Skill 호출]
  └─ 컨벤셔널 커밋 메시지 자동 생성
      └─ 사용자 확인 후 실행

이 흐름에서 사람이 직접 판단하는 것은 두 단계뿐입니다.

1. 리뷰 에이전트의 리포트 검토
2. 커밋 메시지 최종 확인

나머지는 하네스가 처리합니다.

무엇을 어느 계층에 넣어야 하는가: 결정 프레임워크

다음 세 가지 질문으로 배치를 결정합니다.

Q1: 이것을 에이전트가 항상 알고 있어야 하는가?
    → YES: CLAUDE.md

Q2: 이것은 반복 가능한 절차인가?
    → YES: Skills

Q3: 이것은 반드시 실행되어야 하는가? (모델 실수도 허용 안 됨)
    → YES: Hooks

Q4: 이것은 독립된 컨텍스트가 필요한가?
    → YES: Subagents

---

7. 팀 도입 로드맵: 4단계

하네스 4계층을 한꺼번에 도입하려 하면 부담이 큽니다. 다음 순서로 단계적으로 구축하세요.

Week 1: CLAUDE.md 작성

가장 쉽고 즉각적인 효과를 냅니다.

할 일:

• 현재 팀이 사용하는 기술 스택, 컨벤션, 금지 항목 문서화
• 팀원들이 에이전트에게 반복적으로 설명하는 것이 무엇인지 수집
• 루트 CLAUDE.md 초안 작성 후 팀 피드백으로 1주 다듬기

성공 지표: 팀원들이 같은 작업에서 더 이상 같은 설명을 반복하지 않는다

Week 2-3: 핵심 Hooks 구현

보안과 품질의 최소 보호막부터 시작합니다.

할 일:

• 시크릿 스캔 Hook (파일 저장 전)
• 린트 자동 실행 Hook (파일 수정 후)
• 위험 파일 접근 차단 Hook

성공 지표: AI가 실수로 .env 파일을 수정하거나 API 키를 코드에 넣는 사고가 없어진다

Week 4: Skills 표준화

팀에서 가장 반복되는 3-5가지 절차를 Skills로 만듭니다.

할 일:

• 커밋 메시지 Skill
• PR 리뷰 체크리스트 Skill
• 가장 자주 만드는 코드 패턴용 Skill (컴포넌트 생성, API 엔드포인트 추가 등)

성공 지표: 팀 전체가 같은 품질의 커밋 메시지와 PR을 생성한다

Month 2: Subagents 도입

탐색·구현·리뷰 분리 패턴을 팀 표준으로 확립합니다.

할 일:

• 복잡한 기능 작업에 3단계 서브에이전트 패턴 적용 시험
• 보안 리뷰 전용 에이전트 설정 파일 작성
• 병렬 작업이 효과적인 유형 식별

성공 지표: 복잡한 기능 PR에서 리뷰 중 발견되는 문제 수가 줄어든다

---

8. 위험 요소: 흔한 안티패턴 4가지

안티패턴 1: 모든 것을 CLAUDE.md에 넣기

규칙, 절차, 자동화를 구분하지 않고 CLAUDE.md 하나에 몰아넣으면 200줄이 넘어가면서 모델의 규칙 준수율이 떨어집니다. 길이가 두 배가 된다고 효과가 두 배가 되지 않습니다.

해결: 절차는 Skills로, 강제 실행은 Hooks로 분리

안티패턴 2: Skills를 Hooks 대신 사용

"보안 검사를 잘 해달라"는 Skill로 만드는 것은 권고일 뿐입니다. 모델이 실수하거나 컨텍스트 부족으로 건너뛰면 검사가 빠집니다.

해결: 반드시 실행되어야 하는 것은 무조건 Hooks로

안티패턴 3: 서브에이전트 남용

단순한 파일 수정에도 서브에이전트를 쓰면 토큰 비용이 불필요하게 증가하고 오히려 느려집니다.

해결: 컨텍스트 오염이 실제 문제가 되는 규모 이상에서만 서브에이전트 사용

안티패턴 4: 개인 하네스를 팀에 공유하지 않기

개인이 로컬에서만 잘 동작하는 하네스는 조직의 경쟁력이 되지 않습니다. 팀원마다 결과 품질이 다르다면 하네스가 공유되지 않은 신호입니다.

해결: .claude/ 디렉터리를 저장소에 커밋해 팀 전체가 동일한 하네스를 사용

---

9. 실무 의사결정 가이드

지금 어떤 계층이 필요한지 빠르게 진단하기

증상	원인	처방
에이전트가 팀 컨벤션을 자꾸 어긴다	CLAUDE.md 부재 또는 부실	Layer 1 강화
같은 절차를 매번 반복 설명한다	Skills 부재	Layer 2 도입
AI가 실수로 위험한 파일을 수정한다	Hooks 부재	Layer 3 구현
복잡한 기능 작업 후 예상치 못한 버그가 많다	컨텍스트 오염	Layer 4 적용
팀원마다 AI 결과 품질이 다르다	하네스가 개인 수준에 머뭄	저장소 공유 구조로 전환

역할별 빠른 체크리스트

개인 개발자라면

• 프로젝트 루트에 CLAUDE.md 있는가
• 가장 자주 반복하는 절차를 Skill로 만들었는가
• 시크릿 스캔 Hook이 설정되어 있는가
• 중요한 작업에 탐색/구현/리뷰를 분리하는가

팀 리드라면

• .claude/ 디렉터리가 저장소에 커밋되어 있는가
• 팀 공통 CLAUDE.md가 있는가
• 필수 Hooks (시크릿, 린트)가 팀 설정에 포함되어 있는가
• PR 리뷰 Skill이 팀 표준으로 사용되고 있는가

---

10. FAQ

Q1. CLAUDE.md와 .cursorrules의 차이는 무엇인가요?

기능적으로는 유사합니다. 둘 다 에이전트에게 프로젝트 맥락을 제공하는 파일입니다. 차이는 Claude Code의 CLAUDE.md는 서브디렉터리 계층화를 지원하고 Skills/Hooks 시스템과 통합된다는 점입니다. 만약 Claude Code를 쓴다면 CLAUDE.md를 저장소에 두는 것이 권장됩니다.

Q2. Hooks 설정은 JSON인가요, YAML인가요?

.claude/settings.json 형식으로 JSON입니다. 설정 파일은 저장소에 커밋해 팀 전체에 적용하거나, 개인 ~/.claude/settings.json에 넣어 로컬에만 적용할 수 있습니다.

Q3. 서브에이전트는 비용이 얼마나 더 드나요?

서브에이전트는 각각 독립적인 컨텍스트 창을 사용하므로 토큰 소모가 추가됩니다. 대략적으로 동일 작업을 단일 세션으로 처리할 때 대비 1.5~3배 토큰을 사용합니다. 하지만 병렬 실행으로 시간이 줄고, 리뷰 품질이 높아져 재작업 비용이 감소하는 효과가 있습니다.

Q4. Skills와 MCP 서버는 어떻게 다른가요?

Skills는 에이전트에게 절차를 가르치는 것이고, MCP(Model Context Protocol) 서버는 에이전트에게 외부 도구 접근 능력을 주는 것입니다. 예를 들어 "GitHub PR을 만드는 절차"는 Skill이 적합하고, "실시간으로 GitHub API를 호출해 PR 상태를 읽어오는 능력"은 MCP 서버가 적합합니다.

Q5. 소규모 팀(1-3인)도 이 구조가 필요한가요?

특히 더 필요합니다. 소규모 팀일수록 한 사람이 여러 역할을 하므로 하네스가 일관성을 유지해줍니다. 팀원이 늘어날 때 온보딩 비용도 크게 줄어듭니다. 최소한 CLAUDE.md와 시크릿 스캔 Hook부터 시작하세요.

---

에필로그: 하네스를 만드는 것이 곧 팀의 경쟁력이다

Claude Code가 좋아질수록, 그리고 경쟁 도구들이 비슷한 모델 수준에 도달할수록 차별점은 점점 하네스에서 나옵니다. 어떤 규칙을 어떻게 명시했는가. 어떤 절차를 자동화했는가. 어떤 검증 게이트를 설계했는가. 어떤 작업을 어떻게 격리했는가.

이것들은 모델이 업그레이드되어도 사라지지 않는 조직의 지식입니다. 오히려 모델이 더 강력해질수록 더 잘 설계된 하네스의 효과는 증폭됩니다.

4계층 하네스를 차근차근 쌓는 것. 그것이 지금 AI 코딩 시대에 팀이 만들어야 할 가장 중요한 자산입니다.

---

핵심 실행 요약

계층	구성 요소	지금 바로	1개월 내
Layer 1	CLAUDE.md	루트 CLAUDE.md 작성	서브디렉터리 계층화
Layer 2	Skills	커밋·PR 리뷰 Skill 2개	팀 공통 Skill 5개 표준화
Layer 3	Hooks	시크릿 스캔 Hook	린트 자동화 + 위험 파일 차단
Layer 4	Subagents	복잡한 작업 1건에 시험 적용	역할 분리 패턴 팀 표준화

함께 읽으면 좋은 글

• AI 코딩의 승부처는 왜 생성이 아니라 검증이 됐나: 하네스 엔지니어링의 부상
• Claude Code 고급 패턴 입문: Skills, Fork, Subagents를 어떻게 연결할까
• Cursor vs Claude Code vs GitHub Copilot: 2026년 3월 기준 AI 코딩 툴 3강 실전 비교

업데이트 기준

• 본문 기준 시점: 2026-04-11 (KST)
• 업데이트 주기: 월간
• 다음 예정 리뷰: 2026-05-12