Harness — Agent Team & Skill Architect
도메인/프로젝트에 맞는 하네스를 구성하고, 각 에이전트의 역할을 정의하며, 에이전트가 사용할 스킬을 생성하는 메타 스킬.
핵심 원칙:
- 에이전트 정의(
.claude/agents/)와 스킬(.claude/skills/)을 생성한다. - 에이전트 팀을 기본 실행 모드로 사용한다.
- CLAUDE.md에 하네스 포인터를 등록한다. — 새 세션에서 오케스트레이터 스킬이 트리거되도록 최소한의 포인터(트리거 규칙 + 변경 이력)만 기록한다.
- 하네스는 고정물이 아니라 진화하는 시스템이다. — 매 실행 후 피드백을 반영하고, 에이전트·스킬·CLAUDE.md를 지속 갱신한다.
워크플로우
Phase 0: 현황 감사
하네스 스킬이 트리거되면 가장 먼저 기존 하네스 현황을 확인한다.
-
프로젝트/.claude/agents/,프로젝트/.claude/skills/,프로젝트/CLAUDE.md를 읽는다 -
현황에 따라 실행 모드를 분기한다:
- 신규 구축: 에이전트/스킬 디렉토리가 없거나 비어있음 → Phase 1부터 전체 실행
- 기존 확장: 기존 하네스가 있고 새 에이전트/스킬 추가 요청 → 아래 Phase 선택 매트릭스에 따라 필요한 Phase만 실행
- 운영/유지보수: 기존 하네스의 감사·수정·동기화 요청 → Phase 7-5 운영/유지보수 워크플로우로 이동
기존 확장 시 Phase 선택 매트릭스:
변경 유형 Phase 1 Phase 2 Phase 3 Phase 4 Phase 5 Phase 6 에이전트 추가 건너뜀 (Phase 0 결과 활용) 배치 결정만 필수 전용 스킬 필요 시 오케스트레이터 수정 필수 스킬 추가/수정 건너뜀 건너뜀 건너뜀 필수 연결 변경 시 필수 아키텍처 변경 건너뜀 필수 영향받는 에이전트만 영향받는 스킬만 필수 필수 -
기존 에이전트/스킬 목록과 CLAUDE.md 기록을 대조하여 불일치(drift)를 감지한다
-
감사 결과를 사용자에게 요약 보고하고, 실행 계획을 확인받는다
Phase 1: 도메인 분석
- 사용자 요청에서 도메인/프로젝트 파악
- 핵심 작업 유형 식별 (생성, 검증, 편집, 분석 등)
- Phase 0 감사 결과를 기반으로 기존 에이전트/스킬과의 충돌/중복 분석
- 프로젝트 코드베이스 탐색 — 기술 스택, 데이터 모델, 주요 모듈 파악
- 사용자 숙련도 감지 — 대화의 맥락 단서(사용 용어, 질문 수준)로 기술 수준을 파악하고, 이후 커뮤니케이션 톤을 조절한다. 코딩 경험이 적은 사용자에게는 "assertion", "JSON schema" 같은 용어를 설명 없이 쓰지 않는다.
Phase 2: 팀 아키텍처 설계
2-1. 실행 모드 선택
에이전트 팀이 최우선 기본값이다. 2개 이상의 에이전트가 협업할 때는 반드시 에이전트 팀을 먼저 검토한다. 팀원 간 직접 통신(SendMessage)과 공유 작업 목록(TaskCreate)으로 자체 조율하며, 발견 공유·상충 토론·누락 보완이 결과 품질을 높인다.
| 모드 | 언제 사용 | 특성 |
|---|---|---|
| 에이전트 팀 (기본) | 2명 이상 협업, 실시간 조율·피드백 교환이 필요, 중간 산출물 상호 참조 | TeamCreate + SendMessage + TaskCreate로 자체 조율 |
| 서브 에이전트 (대안) | 단일 에이전트 작업, 결과만 메인에 반환하면 충분, 팀 통신 오버헤드가 과할 때 | Agent 도구 직접 호출, run_in_background로 병렬 |
| 하이브리드 | Phase마다 특성이 다를 때 — 예: 병렬 수집(서브) → 합의 기반 통합(팀) | Phase 단위로 팀/서브를 섞어 구성 |
의사결정 순서:
- 먼저 에이전트 팀으로 설계 가능한지 검토한다 — 2명 이상이면 기본값
- 팀 통신이 구조적으로 불필요하고(결과 전달만), 팀 오버헤드가 이득보다 클 때만 서브 에이전트 선택
- Phase별 특성이 확연히 다르면 하이브리드 고려 — 각 Phase의 실행 모드를 오케스트레이터에 명시
상세 비교표와 패턴별 의사결정 트리는
references/agent-design-patterns.md의 "실행 모드" 참조.
2-2. 아키텍처 패턴 선택
- 작업을 전문 영역으로 분해
- 에이전트 팀 구조 결정 (아키텍처 패턴은
references/agent-design-patterns.md참조)- 파이프라인: 순차 의존 작업
- 팬아웃/팬인: 병렬 독립 작업
- 전문가 풀: 상황별 선택 호출
- 생성-검증: 생성 후 품질 검수
- 감독자: 중앙 에이전트가 상태 관리 및 동적 분배
- 계층적 위임: 상위 에이전트가 하위에 재귀적 위임
2-3. 에이전트 분리 기준
전문성·병렬성·컨텍스트·재사용성 4축으로 판단한다. 상세 기준표는 references/agent-design-patterns.md의 "에이전트 분리 기준" 참조.
Phase 3: 에이전트 정의 생성
모든 에이전트는 반드시 프로젝트/.claude/agents/{name}.md 파일로 정의한다. 에이전트 정의 파일 없이 Agent 도구의 prompt에 역할을 직접 넣는 것은 금지한다. 이유:
- 에이전트 정의가 파일로 존재해야 다음 세션에서 재사용 가능
- 팀 통신 프로토콜이 명시되어야 에이전트 간 협업 품질 보장
- 하네스의 핵심 가치는 에이전트(누가)와 스킬(어떻게)의 분리
빌트인 타입(general-purpose, Explore, Plan)을 사용하더라도 에이전트 정의 파일은 생성한다. 빌트인 타입은 Agent 도구의 subagent_type 파라미터로 지정하고, 에이전트 정의 파일에는 역할·원칙·프로토콜을 담는다.
모델 설정: 모든 에이전트는 model: "opus"를 사용한다. Agent 도구 호출 시 반드시 model: "opus" 파라미터를 명시한다. 하네스의 품질은 에이전트의 추론 능력에 직결되며, opus가 최고 품질을 보장한다.
팀 재구성: 에이전트 팀은 세션당 한 팀만 활성화할 수 있지만, Phase 간에 팀을 해체하고 새 팀을 구성할 수 있다. 파이프라인 패턴처럼 Phase별로 다른 전문가 조합이 필요하면, 이전 팀의 산출물을 파일로 저장한 뒤 팀을 정리하고 새 팀을 생성한다.
각 에이전트를 프로젝트/.claude/agents/{name}.md에 정의한다. 필수 섹션: 핵심 역할, 작업 원칙, 입력/출력 프로토콜, 에러 핸들링, 협업. 에이전트 팀 모드에서는 ## 팀 통신 프로토콜 섹션을 추가하여 메시지 수신/발신 대상과 작업 요청 범위를 명시한다.
정의 템플릿과 실제 파일 전문은
references/agent-design-patterns.md의 "에이전트 정의 구조" +references/team-examples.md참조.
QA 에이전트 포함 시 필수 사항:
- QA 에이전트는
general-purpose타입을 사용하라 (Explore는 읽기 전용이므로 검증 스크립트 실행 불가) - QA의 핵심은 "존재 확인"이 아니라 "경계면 교차 비교" — API 응답과 프론트 훅을 동시에 읽고 shape을 비교
- QA는 전체 완성 후 1회가 아니라, 각 모듈 완성 직후 점진적으로 실행 (incremental QA)
- 상세 가이드:
references/qa-agent-guide.md참조
Phase 4: 스킬 생성
각 에이전트가 사용할 스킬을 프로젝트/.claude/skills/{name}/SKILL.md에 생성한다. 상세 작성 가이드는 references/skill-writing-guide.md 참조.
4-1. 스킬 구조
skill-name/
├── SKILL.md (필수)
│ ├── YAML frontmatter (name, description 필수)
│ └── Markdown 본문
└── Bundled Resources (선택)
├── scripts/ - 반복/결정적 작업용 실행 코드
├── references/ - 조건부 로딩하는 참조 문서
└── assets/ - 출력에 사용되는 파일 (템플릿, 이미지 등)
4-2. Description 작성 — 적극적 트리거 유도
description은 스킬의 유일한 트리거 메커니즘이다. Claude는 트리거를 보수적으로 판단하는 경향이 있으므로, description을 **적극적("pushy")**으로 작성한다.
나쁜 예: "PDF 문서를 처리하는 스킬"
좋은 예: "PDF 파일 읽기, 텍스트/테이블 추출, 병합, 분할, 회전, 워터마크, 암호화, OCR 등 모든 PDF 작업을 수행. .pdf 파일을 언급하거나 PDF 산출물을 요청하면 반드시 이 스킬을 사용할 것."
핵심: 스킬이 하는 일 + 구체적 트리거 상황을 모두 기술하고, 유사하지만 트리거하면 안 되는 경우와 구분되도록 작성.
4-3. 본문 작성 원칙
| 원칙 | 설명 |
|---|---|
| Why를 설명하라 | "ALWAYS/NEVER" 같은 강압적 지시 대신, 왜 그렇게 해야 하는지 이유를 전달한다. LLM은 이유를 이해하면 엣지 케이스에서도 올바르게 판단한다. |
| Lean하게 유지 | 컨텍스트 윈도우는 공공재다. SKILL.md 본문은 500줄 이내를 목표로, 무게를 벌지 않는 내용은 삭제하거나 references/로 이동한다. |
| 일반화하라 | 특정 예시에만 맞는 좁은 규칙보다, 원리를 설명하여 다양한 입력에 대응할 수 있게 한다. 오버피팅 금지. |
| 반복 코드는 번들링 | 테스트 실행에서 에이전트들이 공통으로 작성하는 스크립트가 발견되면 scripts/에 미리 번들링한다. |
| 명령형으로 작성 | "~한다", "~하라" 형태의 명령형/지시형 어조를 사용한다. |
4-4. Progressive Disclosure (단계적 정보 공개)
스킬은 3단계 로딩 시스템으로 컨텍스트를 관리한다:
| 단계 | 로딩 시점 | 크기 목표 |
|---|---|---|
| Metadata (name + description) | 항상 컨텍스트에 존재 | ~100단어 |
| SKILL.md 본문 | 스킬 트리거 시 | <500줄 |
| references/ | 필요할 때만 | 무제한 (스크립트는 로딩 없이 실행 가능) |
크기 관리 규칙:
- SKILL.md가 500줄에 근접하면 세부 내용을 references/로 분리하고, 본문에 "언제 이 파일을 읽으라"는 포인터를 남긴다
- 300줄 이상의 reference 파일에는 상단에 **목차(ToC)**를 포함한다
- 도메인/프레임워크별 변형이 있으면 references/ 하위에 도메인별로 분리하여, 관련 파일만 로드한다
cloud-deploy/
├── SKILL.md (워크플로우 + 선택 가이드)
└── references/
├── aws.md ← AWS 선택 시만 로드
├── gcp.md
└── azure.md
4-5. 스킬-에이전트 연결 원칙
- 에이전트 1개 ↔ 스킬 1~N개 (1:1 또는 1:다)
- 여러 에이전트가 공유하는 스킬도 가능
- 스킬은 "어떻게 하는가"를 담고, 에이전트는 "누가 하는가"를 담는다
상세 작성 패턴, 예시, 데이터 스키마 표준은
references/skill-writing-guide.md참조.
Phase 5: 통합 및 오케스트레이션
오케스트레이터는 스킬의 특수한 형태로, 개별 에이전트와 스킬을 하나의 워크플로우로 엮어 팀 전체를 조율한다. Phase 4에서 생성한 개별 스킬이 "각 에이전트가 무엇을 어떻게 하는가"를 정의한다면, 오케스트레이터는 "누가 언제 어떤 순서로 협업하는가"를 정의한다. 구체적 템플릿은 references/orchestrator-template.md 참조.
기존 확장 시 오케스트레이터 수정: 신규 구축이 아닌 기존 확장일 때는 오케스트레이터를 새로 생성하지 않고 기존 오케스트레이터를 수정한다. 에이전트 추가 시 팀 구성·작업 할당·데이터 흐름에 새 에이전트를 반영하고, description에 새 에이전트 관련 트리거 키워드를 추가한다.
Phase 2-1에서 선택한 실행 모드에 따라 오케스트레이터 패턴이 달라진다:
5-0. 오케스트레이터 패턴 (모드별)
에이전트 팀 패턴 (기본):
오케스트레이터가 TeamCreate로 팀을 구성하고, TaskCreate로 작업을 할당한다. 팀원들은 SendMessage로 직접 통신하며 자체 조율한다. 리더(오케스트레이터)는 진행 상황을 모니터링하고 결과를 종합한다.
[오케스트레이터/리더]
├── TeamCreate(team_name, members)
├── TaskCreate(tasks with dependencies)
├── 팀원들이 자체 조율 (SendMessage)
├── 결과 수집 및 종합
└── 팀 정리
서브 에이전트 패턴 (대안):
오케스트레이터가 Agent 도구로 서브 에이전트를 직접 호출한다. 병렬 실행은 run_in_background: true, 결과는 메인에게만 반환된다. 팀 통신이 불필요하고 오버헤드를 줄이고 싶을 때 사용.
[오케스트레이터]
├── Agent(agent-1, run_in_background=true)
├── Agent(agent-2, run_in_background=true)
├── 결과 대기 및 수집
└── 통합 산출물 생성
하이브리드 패턴: Phase마다 다른 모드를 섞어 구성한다. 자주 쓰이는 조합:
- 병렬 수집(서브) → 합의 통합(팀): Phase 2에서 서브 에이전트로 독립 자료를 병렬 수집 → Phase 3에서 팀을 만들어 토론·합의 기반 통합
- 팀 생성(팀) → 검증(서브): Phase 2에서 팀이 초안 생성 → Phase 3에서 단일 서브 에이전트가 독립 검증
- Phase 간 팀 재구성: 각 Phase마다
TeamDelete후 새TeamCreate, 사이에 서브 에이전트 호출 삽입
하이브리드 선택 시 오케스트레이터의 각 Phase 섹션 상단에 해당 Phase의 실행 모드를 명시한다 (예: **실행 모드:** 에이전트 팀).
5-1. 데이터 전달 프로토콜
오케스트레이터 내에 에이전트 간 데이터 전달 방식을 명시한다:
| 전략 | 방식 | 적용 모드 | 적합한 경우 |
|---|---|---|---|
| 메시지 기반 | SendMessage로 팀원 간 직접 통신 | 팀 | 실시간 조율, 피드백 교환, 가벼운 상태 전달 |
| 태스크 기반 | TaskCreate/TaskUpdate로 작업 상태 공유 | 팀 | 진행상황 추적, 의존 관계 관리, 작업 자체 요청 |
| 파일 기반 | 약속된 경로에 파일을 쓰고 읽음 | 팀 + 서브 | 대용량 데이터, 구조화된 산출물, 감사 추적 필요 |
| 반환값 기반 | Agent 도구의 반환 메시지 | 서브 | 서브 에이전트 결과를 메인이 직접 수집 |
권장 조합 (팀 모드): 태스크 기반(조율) + 파일 기반(산출물) + 메시지 기반(실시간 소통) 권장 조합 (서브 모드):