에이전트 팀·스킬 하네스 설계기 · @cliphijack

⓪ 이 스킬이면 뭘 할 수 있나?

"이 일 좀 자동화해줘" 한마디에, 그 도메인 전용 AI 팀을 통째로 설계해줘요. 무슨 에이전트가 필요한지(누가), 각자 어떤 스킬로 일하는지(어떻게), 누가 언제 협업하는지(오케스트레이터)를 파일로 찍어내고, CLAUDE.md에 트리거까지 등록해서 다음 세션부터 말 한마디로 그 팀이 가동되게 만듭니다.

재사용: 에이전트·스킬이 파일(.claude/agents, .claude/skills)로 남아 세션이 바뀌어도 그대로
자체 조율: 팀원들이 서로 메시지·작업목록으로 알아서 협업 (감독 최소화)
진화: 한 번 만들고 끝이 아니라, 실행 피드백을 받아 에이전트·스킬·워크플로우를 계속 개선

한 번 깔아두면 "기획팀", "코드리뷰팀", "콘텐츠 양산팀" 같은 걸 말로 찍어내는 공장을 갖게 돼요.

① 한 줄 정의

도메인을 분석해 전문 에이전트 팀 + 각자의 스킬 + 오케스트레이터를 .claude/에 생성하고, CLAUDE.md에 트리거 포인터를 등록하며, 피드백으로 지속 갱신하는 메타 스킬.

② 언제 쓰나?

"하네스 구성/구축/설계", "에이전트 팀 짜줘", "이 작업 자동화 체계 만들어줘"
기존 하네스에 에이전트·스킬 추가/수정/확장
"하네스 점검/감사", "에이전트·스킬 동기화" 등 운영·유지보수
같은 유형의 작업을 반복하게 되어 전담 팀으로 굳히고 싶을 때

③ 사전 요구

에이전트 팀·서브에이전트 도구를 지원하는 실행 환경 (TeamCreate / Agent / TaskCreate / SendMessage 류). 도구명은 환경마다 다를 수 있으니, 없으면 "서브에이전트만으로" 폴백 설계.
대상 프로젝트 폴더 (읽기/쓰기 권한). 산출물은 그 프로젝트의 .claude/에 생성.
외부 레포·계정·API 불필요 (로컬 파일 생성만).

④ 핵심 원칙 (먼저 새겨라)

1. 에이전트(누가) ↔ 스킬(어떻게)을 분리한다. 에이전트는 역할·협업 프로토콜, 스킬은 방법론.

2. 에이전트 팀이 기본 실행 모드다. 2명 이상이 협업하면 팀 우선(서로 직접 통신+공유 작업목록으로 자체 조율). 통신이 구조적으로 불필요할 때만 서브에이전트.

3. CLAUDE.md엔 포인터만: 트리거 규칙 + 변경 이력. 에이전트·스킬 목록은 넣지 마라(중복·드리프트 원인).

4. 하네스는 진화한다: 매 실행 후 피드백 → 에이전트·스킬·오케스트레이터·CLAUDE.md 갱신.

⑤ 단계별 절차

Phase 0 — 현황 감사 (항상 먼저)

대상 프로젝트의 .claude/agents/, .claude/skills/, CLAUDE.md를 읽고 분기:

신규: 비어있음 → Phase 1부터 전체
확장: 기존 + 추가 요청 → 필요한 Phase만 (에이전트 추가=Phase 3·6, 스킬 추가=Phase 4·6)
운영: 감사·수정·동기화 → 아래 "운영 워크플로우"

파일 목록과 CLAUDE.md 기록을 대조해 불일치(drift)를 감지하고, 계획을 사용자에게 확인받는다.

Phase 1 — 도메인 분석

요청에서 도메인·핵심 작업유형(생성/검증/편집/분석)을 식별. 코드베이스 탐색으로 스택·데이터모델 파악. 사용자 숙련도를 감지해 용어·톤 조절(초보에겐 전문용어 설명 동반).

Phase 2 — 팀 아키텍처 설계

실행 모드 선택: 팀(기본) / 서브에이전트(결과만 반환하면 충분) / 하이브리드(Phase별 혼합).
아키텍처 패턴: 파이프라인 · 팬아웃/팬인 · 전문가 풀 · 생성-검증 · 감독자 · 계층적 위임 중 작업에 맞게.
에이전트 분리 기준: 전문성·병렬성·컨텍스트 격리·재사용성 4축.

Phase 3 — 에이전트 정의 생성

모든 에이전트는 반드시 .claude/agents/{name}.md 파일로 정의(프롬프트에 역할 직접 주입 금지 — 재사용·협업품질 위해). 빌트인 타입을 쓰더라도 정의 파일은 만든다. 필수 섹션: 핵심 역할 · 작업 원칙 · 입출력 프로토콜 · 에러 핸들링 · 협업(팀 모드면 팀 통신 프로토콜 추가). 추론 품질이 결과를 좌우하므로 고성능 모델을 명시한다.

QA 에이전트는 읽기전용 타입 금지(검증 스크립트 실행 필요), "존재 확인"이 아니라 경계면 교차 비교(API 응답 ↔ 프론트 훅 shape 대조), 전체 후 1회가 아니라 모듈별 점진 실행.

Phase 4 — 스킬 생성

각 에이전트의 스킬을 .claude/skills/{name}/SKILL.md로. 구조: frontmatter(name·description 필수) + 본문(+ 선택적 references/·scripts/).

description = 유일한 트리거. 보수적으로 안 걸리니 적극적("pushy")으로: 하는 일 + 구체적 트리거 상황 + 후속 키워드("다시 실행/수정/보완")까지. 나쁜 예 "PDF 처리 스킬" → 좋은 예 "PDF 읽기·추출·병합·OCR 등 모든 PDF 작업. .pdf 언급/산출 요청 시 반드시 사용."
본문 원칙: Why를 설명(ALWAYS/NEVER 강압 대신 이유 → 엣지케이스 판단력) · Lean(500줄 이내, 넘으면 references로) · 일반화(오버피팅 금지) · 명령형 어조 · 반복 스크립트는 scripts/에 번들.
Progressive Disclosure: metadata(항상) → SKILL.md 본문(트리거 시, <500줄) → references/(필요할 때만). 도메인별 변형은 references/<도메인>.md로 쪼개 관련 파일만 로드.

Phase 5 — 통합·오케스트레이션

"누가 언제 어떤 순서로 협업하는가"를 정의하는 오케스트레이터 스킬 1개 생성(확장이면 기존 수정).

팀 패턴: 리더가 팀 구성+작업 할당, 팀원이 직접 통신으로 자체 조율, 결과 종합.
데이터 전달: 메시지(실시간 조율) + 작업목록(진행·의존) + 파일(_workspace/{phase}_{agent}_{artifact} 대용량·감사) 조합. 중간 산출물은 보존.
에러 핸들링: 1회 재시도 후 실패하면 그 결과 없이 진행(보고서에 누락 명시), 상충 데이터는 삭제 말고 출처 병기.
팀 크기: 소규모 2~3명 / 중 3~5명 / 대 5~7명. 집중된 3명 > 산만한 5명.
CLAUDE.md 포인터 등록: 목표 한 줄 + 트리거 규칙 + 변경 이력 테이블만. (목록·디렉토리구조·상세규칙 넣지 마라)
후속 작업 보장: 오케스트레이터 description에 후속 키워드, Phase 1에 컨텍스트 확인(초기/새/부분 재실행 판별), 에이전트 정의에 "이전 산출물 있을 때 행동" 명시.

Phase 6 — 검증·테스트

구조: 에이전트 파일 위치·frontmatter·참조 일관성, 커맨드(.claude/commands/) 미생성 확인.
실행 테스트: 스킬마다 현실적 프롬프트 2~3개, 가능하면 With-skill vs Without-skill 병렬로 부가가치 확인, 정성(리뷰)+정량(assertion) 평가, 문제는 일반화해서 수정 후 재테스트.
트리거 검증: should-trigger 8~10 + should-NOT-trigger 8~10(경계 모호한 near-miss가 좋은 테스트). 기존 스킬과 트리거 충돌도 확인.
드라이런: Phase 순서·데이터 전달 dead link·에러 폴백 경로 점검.

Phase 7 — 진화

매 실행 후 피드백 요청(강요 X, 기회는 항상). 유형별 반영: 결과품질→해당 스킬, 역할→에이전트 정의, 순서→오케스트레이터, 트리거 누락→description. 모든 변경은 CLAUDE.md 변경 이력에 기록(퇴행 방지). 같은 피드백 2회↑·반복 실패·사용자가 수동 우회 시 먼저 진화를 제안.

운영/유지보수 워크플로우

① 감사(파일 목록 ↔ 오케스트레이터 구성 대조 → 불일치 보고) ② 점진 추가/수정(한 번에 하나, 각 변경 후 즉시 동기화) ③ CLAUDE.md 변경 이력 갱신 ④ 검증(구조 + 트리거 영향 시 트리거검증 + 대규모면 실행·드라이런).

⑥ 산출물 체크리스트

[ ] .claude/agents/ — 에이전트 정의 파일(빌트인 타입이라도) 생성됨
[ ] .claude/skills/ — 스킬들(SKILL.md + 필요시 references/)
[ ] 오케스트레이터 스킬 1개 (데이터 흐름 + 에러 핸들링 + 테스트 시나리오)
[ ] 실행 모드 명시 (팀/서브/하이브리드)
[ ] 모든 에이전트 호출에 고성능 모델 명시
[ ] .claude/commands/ — 아무것도 안 만듦
[ ] description이 적극적 + 후속 키워드 포함
[ ] SKILL.md 본문 500줄 이내(초과 시 references/ 분리)
[ ] 테스트 프롬프트 2~3개 실행 + 트리거 검증 완료
[ ] CLAUDE.md에 하네스 포인터(트리거 + 변경 이력) 등록

⑦ 함정·기본값

1. 커맨드 만들지 마라 — 하네스는 에이전트+스킬+오케스트레이터로 구성. .claude/commands/는 비워둔다.

2. 에이전트를 프롬프트에 인라인하지 마라 — 반드시 .md 파일로(재사용·협업품질).

3. CLAUDE.md 비대화 금지 — 포인터 + 변경 이력만. 목록 넣으면 드리프트.

4. SKILL.md 500줄 넘으면 references/로 분리하고 본문엔 "언제 읽어라" 포인터만.

5. description 보수적이면 안 걸린다 — pushy하게, 후속 키워드까지.

6. 팀 과다 금지 — 조율 오버헤드. 집중된 소수가 낫다.

7. 확장 시 새로 만들지 말고 기존 수정 — 오케스트레이터·CLAUDE.md를 갱신, drift 감지부터.