Harness — Agent Team & Skill Architect

도메인/프로젝트에 맞는 하네스를 구성하고, 각 에이전트의 역할을 정의하며, 에이전트가 사용할 스킬을 생성하는 메타 스킬.

핵심 원칙:

1. 에이전트 정의(.claude/agents/)와 스킬(.claude/skills/)을 생성한다.
2. 에이전트 팀을 기본 실행 모드로 사용한다.
3. CLAUDE.md에 하네스 포인터를 등록한다. — 새 세션에서 오케스트레이터 스킬이 트리거되도록 최소한의 포인터(트리거 규칙 + 변경 이력)만 기록한다.
4. 하네스는 고정물이 아니라 진화하는 시스템이다. — 매 실행 후 피드백을 반영하고, 에이전트·스킬·CLAUDE.md를 지속 갱신한다.

워크플로우

Phase 0: 현황 감사

하네스 스킬이 트리거되면 가장 먼저 기존 하네스 현황을 확인한다.

1. 프로젝트/.claude/agents/, 프로젝트/.claude/skills/, 프로젝트/CLAUDE.md를 읽는다

2. 현황에 따라 실행 모드를 분기한다:

   • 신규 구축: 에이전트/스킬 디렉토리가 없거나 비어있음 → Phase 1부터 전체 실행
   • 기존 확장: 기존 하네스가 있고 새 에이전트/스킬 추가 요청 → 아래 Phase 선택 매트릭스에 따라 필요한 Phase만 실행
   • 운영/유지보수: 기존 하네스의 감사·수정·동기화 요청 → Phase 7-5 운영/유지보수 워크플로우로 이동

   기존 확장 시 Phase 선택 매트릭스:

   변경 유형	Phase 1	Phase 2	Phase 3	Phase 4	Phase 5	Phase 6
   에이전트 추가	건너뜀 (Phase 0 결과 활용)	배치 결정만	필수	전용 스킬 필요 시	오케스트레이터 수정	필수
   스킬 추가/수정	건너뜀	건너뜀	건너뜀	필수	연결 변경 시	필수
   아키텍처 변경	건너뜀	필수	영향받는 에이전트만	영향받는 스킬만	필수	필수

3. 기존 에이전트/스킬 목록과 CLAUDE.md 기록을 대조하여 불일치(drift)를 감지한다

4. 감사 결과를 사용자에게 요약 보고하고, 실행 계획을 확인받는다

Phase 1: 도메인 분석

1. 사용자 요청에서 도메인/프로젝트 파악
2. 핵심 작업 유형 식별 (생성, 검증, 편집, 분석 등)
3. Phase 0 감사 결과를 기반으로 기존 에이전트/스킬과의 충돌/중복 분석
4. 프로젝트 코드베이스 탐색 — 기술 스택, 데이터 모델, 주요 모듈 파악
5. 사용자 숙련도 감지 — 대화의 맥락 단서(사용 용어, 질문 수준)로 기술 수준을 파악하고, 이후 커뮤니케이션 톤을 조절한다. 코딩 경험이 적은 사용자에게는 "assertion", "JSON schema" 같은 용어를 설명 없이 쓰지 않는다.

Phase 2: 팀 아키텍처 설계

2-1. 실행 모드 선택

에이전트 팀이 최우선 기본값이다. 2개 이상의 에이전트가 협업할 때는 반드시 에이전트 팀을 먼저 검토한다. 팀원 간 직접 통신(SendMessage)과 공유 작업 목록(TaskCreate)으로 자체 조율하며, 발견 공유·상충 토론·누락 보완이 결과 품질을 높인다.

의사결정 순서:

1. 먼저 에이전트 팀으로 설계 가능한지 검토한다 — 2명 이상이면 기본값
2. 팀 통신이 구조적으로 불필요하고(결과 전달만), 팀 오버헤드가 이득보다 클 때만 서브 에이전트 선택
3. Phase별 특성이 확연히 다르면 하이브리드 고려 — 각 Phase의 실행 모드를 오케스트레이터에 명시

상세 비교표와 패턴별 의사결정 트리는 references/agent-design-patterns.md의 "실행 모드" 참조.

2-2. 아키텍처 패턴 선택

1. 작업을 전문 영역으로 분해
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. 본문 작성 원칙

4-4. Progressive Disclosure (단계적 정보 공개)

스킬은 3단계 로딩 시스템으로 컨텍스트를 관리한다:

크기 관리 규칙:

• 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. 데이터 전달 프로토콜

오케스트레이터 내에 에이전트 간 데이터 전달 방식을 명시한다:

권장 조합 (팀 모드): 태스크 기반(조율) + 파일 기반(산출물) + 메시지 기반(실시간 소통) 권장 조합 (서브 모드):