[Claude Code 하네스] 에이전트 팀을 설계하는 법 — 스킬, 에이전트, 훅 완벽 가이드

 

안녕하세요!

재아군의 관찰인생입니다.

 

Claude Code를 단순한 AI 코딩 도구로만 쓰고 계신가요? 오늘은 Claude Code를 프로젝트 전용 AI 자동화 시스템으로 탈바꿈시키는 핵심 개념, 하네스(Harness)를 깊이 있게 분석합니다.

하네스를 구축하면 "블로그 글 써줘"라고 말했을 때 키워드 조사 → 본문 작성 → SEO 검수 → 이미지 생성 → 발행까지 전문 에이전트 팀이 자동으로 처리하는 시스템을 만들 수 있습니다. 저도 이 블로그 자체를 하네스로 운영하고 있습니다.

 

이 글은 Claude Code를 이미 사용 중인 개발자를 대상으로 합니다.
하네스의 구성 요소 → 설계 원칙 → 실전 구축 → 고급 패턴 순서로 진행합니다.

 

 

---

1. 하네스란 무엇인가?

핵심 정의

하네스(Harness)는 Claude Code의 동작을 프로젝트에 맞게 커스터마이징하는 설정 + 에이전트 + 스킬의 총체입니다. 말(馬)에게 하네스를 채우면 제어할 수 있듯, Claude Code에게 하네스를 씌우면 프로젝트의 규칙과 워크플로우를 정확히 따르게 됩니다.

하네스 없이 Claude Code를 쓰는 것은 범용 AI에게 매번 프로젝트 맥락을 설명하는 것과 같습니다. 하네스를 구축하면 프로젝트의 규칙, 패턴, 워크플로우를 미리 학습한 전문가 팀처럼 동작합니다.

하네스의 4대 구성 요소

구성 요소	위치	역할
CLAUDE.md	프로젝트 루트/CLAUDE.md	프로젝트 컨텍스트 — 빌드 방법, 규칙, 주의사항
에이전트	.claude/agents/*.md	특정 역할의 전문가 정의 (SEO 리뷰어, 코드 분석가 등)
스킬	.claude/skills/*/SKILL.md	구체적인 작업 절차서 (이미지 생성 방법, 블로그 작성 규칙 등)
훅(Hooks)	.claude/settings.json	이벤트 기반 자동화 — 파일 편집 후 린트, 세션 시작 시 상태 체크 등

비유하면 CLAUDE.md는 회사 소개서, 에이전트는 팀원, 스킬은 업무 매뉴얼, 훅은 자동화 규칙입니다.

 

 

---

2. 에이전트 — 전문가 팀 구성하기

에이전트란?

에이전트는 특정 역할과 전문성을 가진 AI 페르소나입니다. .claude/agents/ 디렉토리에 마크다운 파일로 정의하며, Claude Code의 Agent 도구를 통해 호출됩니다.

# .claude/agents/seo-reviewer.md
---
name: seo-reviewer
description: "블로그 글의 SEO 점수를 산정하고 개선점을 제안하는 전문가.
  트리거: SEO 검수, 검수해줘, optimize, review"
---

# SEO Reviewer — 블로그 SEO 전문가

당신은 블로그 SEO 최적화 전문가입니다.

## 핵심 역할
- frontmatter(title, description, tags) 완성도 검증
- H2/H3 키워드 배치 점검
- 이미지 alt 텍스트, 내부 링크 확인
- 가독성(문장 길이, 단락 길이) 평가

## 점수 기준
| 항목 | 배점 |
|------|------|
| 키워드 배치 | 30점 |
| 구조화 요소(표, 목록, 코드) | 25점 |
| 메타 데이터 | 20점 |
| 이미지 & 시각 요소 | 15점 |
| 가독성 | 10점 |

## 출력 형식
점수/100 + 항목별 진단 + 개선 제안을 구조화된 리포트로 출력합니다.

에이전트 분리 기준

모든 역할을 하나의 에이전트에 넣으면 컨텍스트가 비대해지고 정확도가 떨어집니다. 다음 기준으로 분리합니다:

• 전문성이 다르면 분리 — SEO 전문가와 코드 리뷰어는 필요한 지식이 다름
• 독립 실행 가능하면 분리 — 이미지 생성과 본문 작성은 병렬 수행 가능
• 컨텍스트 부담이 크면 분리 — 레퍼런스가 많은 전문 영역은 별도 에이전트로
• 재사용성이 높으면 분리 — 팩트체크 에이전트는 여러 프로젝트에서 공유 가능

에이전트 아키텍처 패턴

패턴	구조	적합한 시나리오
파이프라인	A → B → C (순차)	블로그 파이프라인: 키워드 → 본문 → 이미지 → SEO
팬아웃/팬인	A → [B, C, D] → E (병렬)	SNS 멀티채널 변환: 원문 → X/LinkedIn/뉴스레터 동시 생성
생성-검증	A ↔ B (반복)	콘텐츠 생성 → 팩트체크 → 수정 → 재검증
전문가 풀	라우터 → 적합한 전문가 선택	기술 블로그 vs 건강 블로그 — 주제에 따라 다른 에이전트

 

 

---

3. 스킬 — 전문 작업 매뉴얼

에이전트 vs 스킬

헷갈리기 쉬운 개념이므로 명확히 정리합니다:

• 에이전트 = "누가" 하는가 (역할, 페르소나, 도구 접근 권한)
• 스킬 = "어떻게" 하는가 (구체적 절차, 출력 형식, 레퍼런스 데이터)

하나의 에이전트가 여러 스킬을 사용할 수 있고, 하나의 스킬이 여러 에이전트에 공유될 수도 있습니다.

스킬 파일 구조

# 디렉토리 구조
.claude/skills/
├── image-generator/
│   ├── SKILL.md              # 스킬 본체 (워크플로우, 도구 사용법)
│   └── references/
│       └── image-style-guide.md  # 레퍼런스 (디자인 시스템 사양)
├── seo-review/
│   └── SKILL.md
├── blog-pipeline/
│   └── SKILL.md              # 오케스트레이터 스킬
└── fact-check/
    └── SKILL.md

스킬 작성 예시

# .claude/skills/image-generator/SKILL.md
---
name: image-generator
description: "블로그 본문용 PNG 이미지 5장을 HTML/CSS 기반으로 생성하는 스킬.
  트리거: 이미지 생성, image, PNG, 다이어그램"
---

# Image Generator 스킬

## 레퍼런스 (반드시 참조)
1. `references/image-style-guide.md` — 이미지 디자인 시스템 사양

## 기술 스택
- 렌더링 엔진: `node-html-to-image` (Puppeteer 기반)
- 출력: 800x500px PNG

## 이미지 5종 사양
| ID | 이름 | CSS 핵심 |
|----|------|----------|
| 01 | 개요 다이어그램 | 중심 노드 + 4개 카드 |
| 02 | 핵심 포인트 | 3개 카드 그리드 |
| 03 | 프로세스 흐름 | 4단계 + 화살표 |
| 04 | 비교 테이블 | Before/After 패널 |
| 05 | 실전 체크리스트 | 체크박스 리스트 |

## 텍스트 배치 규칙 (⚠️ 필수)
- 모든 제목에 `word-break: keep-all` 적용
- 키워드 길이에 따라 font-size 동적 조정
- 카드 내부 라벨은 8자 이내

핵심은 레퍼런스 분리입니다. 스킬 본체(SKILL.md)에는 워크플로우와 규칙만 적고, 세부 사양(색상 코드, 크기 등)은 references/ 하위에 분리하면 유지보수가 쉬워집니다.

---

4. 훅(Hooks) — 이벤트 기반 자동화

훅은 Claude Code의 특정 이벤트에 셸 명령을 자동 실행하는 메커니즘입니다. .claude/settings.json에 정의합니다.

훅 이벤트 유형

이벤트	실행 시점	활용 예시
SessionStart	Claude Code 세션 시작 시	프로젝트 상태 체크, 이전 작업 복원
UserPromptSubmit	사용자 메시지 전송 시	입력 검증, 키워드 자동 감지
postToolUse	도구 실행 후	파일 편집 후 Prettier, 빌드 후 타입 체크
postResponse	Claude 응답 완료 후	활동 로그 기록, 알림 전송

실전 훅 설정

// .claude/settings.json
{
  "hooks": {
    "SessionStart": [
      {
        "command": "node .bkit/hooks/session-start.js",
        "timeout": 5000
      }
    ],
    "UserPromptSubmit": [
      {
        "command": "node .bkit/hooks/prompt-submit.js \"$PROMPT\"",
        "timeout": 3000
      }
    ],
    "postToolUse": [
      {
        "matcher": "Edit",
        "command": "npx prettier --write \"$CLAUDE_FILE_PATH\""
      },
      {
        "matcher": "Bash(npm test*)",
        "command": "echo '[TEST] $(date)' >> .claude/test-log.txt"
      }
    ]
  }
}

가장 유용한 패턴은 SessionStart 훅입니다. 세션이 시작될 때 이전 작업 상태를 불러와서 Claude에게 "지난번에 여기까지 했고, 다음 단계는 이것"이라는 컨텍스트를 자동으로 주입할 수 있습니다.

 

 

---

5. 실전 사례 — 블로그 자동화 하네스

이 블로그(재아군의 관찰인생)를 실제로 운영하는 하네스 구조를 공개합니다.

에이전트 팀 구성

# 블로그 자동화 에이전트 팀

.claude/agents/
├── keyword-hunter.md       # 트렌드 크롤링 → 주제 발굴
├── market-analyst.md       # 경쟁 콘텐츠 분석 → 차별화 전략
├── seo-optimizer.md        # SEO 점수 산정 → 자동 수정
├── fact-checker.md         # 기술 정확성 → 할루시네이션 검출
├── auto-poster.md          # Playwright → 티스토리 자동 발행
└── channel-adapter.md      # 원문 → X/LinkedIn/뉴스레터 변환

파이프라인 흐름

# "Supabase에 대한 글 작성해줘"라고 말하면:

1️⃣ keyword-hunter   → 키워드 최적화, 제목 생성
        ↓
2️⃣ seo-blog-writer  → 7개 섹션 구조로 본문 생성
        ↓ (병렬)
3️⃣ image-generator   → HTML/CSS → PNG 이미지 5장
        ↓
4️⃣ seo-optimizer     → SEO 100점 달성까지 자동 수정
        ↓
5️⃣ fact-checker      → 기술 정확성 검증
        ↓
6️⃣ auto-poster       → Playwright로 티스토리 임시저장
        ↓ (선택)
7️⃣ channel-adapter   → X 쓰레드, LinkedIn 등으로 변환

결과

이 하네스로 실제 운영한 결과:

• 글 1편 생산 시간: 수동 3~4시간 → 자동 5~10분
• SEO 점수: 평균 95/100 이상 (표, 코드블록, 이미지 자동 포함)
• 이미지: HTML/CSS 기반으로 일관된 디자인 시스템 유지
• 발행: Playwright 자동화로 티스토리 임시저장까지 원클릭

---

6. 하네스 설계 5원칙

1) 단일 책임 원칙

하나의 에이전트/스킬은 하나의 역할만 수행합니다. "글도 쓰고 이미지도 만드는" 에이전트보다 "글만 쓰는" + "이미지만 만드는" 2개가 낫습니다. 각각의 정확도가 올라가고, 디버깅이 쉬워집니다.

2) 레퍼런스 분리

스킬 본체에 모든 사양을 넣지 마세요. 스타일 가이드, 색상 팔레트, 템플릿 등은 references/에 분리하면 여러 스킬이 공유할 수 있고, 수정 시 한 곳만 변경하면 됩니다.

3) 트리거 키워드 명시

에이전트/스킬의 description 필드에 트리거 키워드를 적어두면, Claude Code가 사용자 입력에서 적합한 에이전트/스킬을 자동으로 매칭합니다.

# 좋은 예:
description: "블로그 SEO 점수를 산정하고 자동 수정하는 스킬.
  트리거: SEO, 검수, 점수, optimize, review, 검수해줘"

# 나쁜 예:
description: "SEO 관련 스킬입니다."

4) 오케스트레이터 패턴

개별 에이전트/스킬 위에 전체를 조율하는 상위 스킬을 하나 만드세요. "글 써줘"라고 하면 오케스트레이터가 어떤 에이전트를 어떤 순서로 호출할지 결정합니다.

5) 점진적 구축

처음부터 완벽한 하네스를 만들려 하지 마세요. CLAUDE.md부터 시작하고, 반복되는 작업이 보이면 스킬로, 역할이 분명해지면 에이전트로, 자동화할 수 있으면 훅으로 점진적으로 확장합니다.

---

7. 직접 만들어보기 — 5단계 가이드

지금 바로 하네스를 시작하는 방법입니다.

Step 1: CLAUDE.md 작성

# 프로젝트 루트에 CLAUDE.md 생성
# → 빌드 방법, 구조, 컨벤션, 주의사항 작성

Step 2: 반복 작업 식별

# 매번 같은 지시를 반복하고 있다면? → 스킬로 만들기
# 예: "커밋 메시지를 conventional commits 형식으로 작성해줘"
# → .claude/skills/commit-convention/SKILL.md

Step 3: 전문 에이전트 정의

# 역할이 다른 작업이 있다면? → 에이전트로 분리
# 예: 코드 리뷰 전문가, 테스트 작성 전문가
# → .claude/agents/code-reviewer.md
# → .claude/agents/test-writer.md

Step 4: 훅 추가

# 파일 저장 후 항상 포매팅한다면? → Hook으로 자동화
# → .claude/settings.json의 hooks.postToolUse

Step 5: 오케스트레이터 연결

# 여러 에이전트/스킬을 조합하는 상위 스킬 작성
# "배포해줘" → lint → test → build → deploy 파이프라인
# → .claude/skills/deploy-pipeline/SKILL.md

 

 

---

마무리

하네스는 Claude Code를 "범용 AI 도구"에서 "프로젝트 전용 자동화 시스템"으로 바꾸는 핵심 개념입니다.

핵심을 정리하면:

• CLAUDE.md — 프로젝트 맥락을 한 번만 설명하면 매 세션에 자동 적용
• 에이전트 — 역할별 전문가를 정의하여 정확도와 일관성 향상
• 스킬 — 반복 작업을 절차서로 문서화하여 매번 같은 품질 보장
• 훅 — 이벤트 기반 자동화로 수동 작업 제거
• 점진적 구축 — CLAUDE.md → 스킬 → 에이전트 → 훅 순서로 확장

한 번 구축하면 팀 전체가 공유할 수 있고, 새 프로젝트에도 패턴을 재활용할 수 있습니다. Claude Code를 이미 쓰고 계시다면, 오늘 CLAUDE.md 하나부터 시작해보세요.

 

이 글이 도움이 되셨다면 댓글과 공유 부탁드립니다.
하네스 구축 관련 궁금한 점이 있다면 언제든 댓글로 남겨주세요!

 

다음 글에서 더 깊이 있는 내용으로 찾아뵙겠습니다.

감사합니다!