Harness v2, 에이전트 팀과 스킬 설계

프로젝트에 맞는 하네스를 설계한다. 각 에이전트의 역할을 정의하고, 에이전트가 작업할 때 따를 스킬을 만든다.

핵심 원칙

1. 에이전트 정의는 프로젝트/.claude/agents/에, 스킬은 프로젝트/.claude/skills/에 만든다. 에이전트에는 누가 일하는지를, 스킬에는 그 일을 어떻게 하는지를 적는다.
2. 작업 흐름에 따라 실행 모드를 고른다. 순서와 반복 조건을 코드로 정할 수 있으면 워크플로로 조율한다. 같은 전문가와 피드백을 주고받아야 하면 지속형 에이전트를 쓴다. 결과를 한 번만 받으면 되는 작업은 서브에이전트에 맡긴다. 자세한 선택 기준은 2단계에서 다룬다.
3. 업무의 복잡도, 작업 기간, 자율성, 응답 속도에 맞춰 모델을 고른다. 계획을 세워 장기간 자율적으로 실행해야 하는 최고 난도 업무에는 fable, 설계·코드 생성·복잡한 분석·교차 검증에는 opus, 로그 분석·형식 변환·단순 수집 같은 일상 업무에는 sonnet을 쓴다. 자세한 기준은 3단계에서 다룬다.
4. 새 세션에서도 오케스트레이터 스킬을 불러올 수 있도록 CLAUDE.md에 호출 조건과 변경 이력만 기록한다.
5. 실행 결과에서 배운 내용을 에이전트·스킬·CLAUDE.md에 계속 반영한다. 회고하고 변경 사항을 찾아내는 작업은 harness:evolve 스킬이 맡는다.
6. 생성하는 에이전트 정의, 스킬, 오케스트레이터, CLAUDE.md 기록은 사용자가 대화에 쓰는 언어로 작성한다. 이 스킬 문서와 references/의 템플릿이 한국어로 쓰였다는 이유로 산출물을 한국어로 쓰지 않는다. 템플릿의 제목과 예시 문구도 그 언어로 옮긴다. 사용자가 언어를 따로 정하면 그 언어를 따르고, 따로 정하지 않은 채 기존 하네스를 확장하면 기존 파일의 언어를 따른다.

진행 절차

0단계: 현재 상태 점검

하네스 스킬을 불러오면 기존 구성을 먼저 확인한다.

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

2. 현재 상태에 따라 진행할 절차를 고른다.

   • 새로 구축: 에이전트나 스킬 디렉터리가 없거나 비어 있으면 1단계부터 모두 실행한다.
   • 기존 구성 확장: 기존 하네스에 에이전트나 스킬을 추가해야 하면 아래 표에서 필요한 단계만 실행한다.
   • 운영·유지 보수: 기존 하네스를 점검·수정·동기화해야 하면 7단계의 운영 절차로 이동한다.

   변경 내용	1단계	2단계	3단계	4단계	5단계	6단계
   에이전트 추가	생략하고 0단계 결과 사용	어떤 실행 모드에서 어느 팀과 단계에 둘지만 결정	필수	전용 스킬이 필요할 때	오케스트레이터 수정	필수
   스킬 추가·수정	생략	생략	생략	필수	연결이 바뀔 때	필수
   구조·실행 모드 변경	생략	필수	영향을 받는 에이전트만	영향을 받는 스킬만	필수	필수

3. 기존 오케스트레이터에 TeamCreate, TeamDelete, CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS가 있으면 v1 산출물이다. 현재 실행 환경에서는 작동하지 않으므로 v2로 옮기자고 제안한다. 자세한 방법은 references/execution-modes.md의 「v1에서 v2로 전환」을 따른다.

4. 실제 에이전트·스킬 목록과 CLAUDE.md 기록을 대조해 불일치를 찾는다.

5. 점검 결과와 실행 계획을 사용자에게 알리고 확인받는다.

1단계: 분야와 작업 분석