스킬·에이전트를 만들어주는 스킬
B-5에서 에이전트와 스킬을 손으로 하나씩 만들어봤습니다. 그런데 역할이 5개, 10개로 늘어나면 누가 무엇을 맡고 어떻게 주고받을지부터 설계해야 합니다.
하네스(harness)는 그 설계와 파일 생성을 대신하는 플러그인입니다. 내가 하는 일은 "우리 팀이 무슨 일을 하는지" 한 문장 설명이고, 결과로 .claude/agents/ 와 .claude/skills/ 가 채워집니다.
플러그인 붙이기
Claude Code 안에서 두 줄이면 끝납니다. 첫 줄은 마켓플레이스 등록, 둘째 줄은 설치입니다.
/plugin marketplace add revfactory/harness /plugin install harness@harness-marketplace
플러그인 없이 스킬만 쓰고 싶으면 폴더를 복사해도 됩니다.
cp -r skills/harness ~/.claude/skills/harness
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
한 문장으로 팀 만들기
설치 후에는 평소처럼 말하면 됩니다. 아래 문장이 트리거입니다.
하네스 구성해줘
(영어) Build a harness for this project
Design an agent team for this domain그다음 어떤 일을 하는 팀인지만 알려주면 됩니다. 구체적일수록 결과가 좋습니다.
하네스 구성해줘. 우리 팀은 매주 월요일 주간보고를 만든다. - 입력: 지난주 커밋 로그, 지라 티켓, 팀원 3명의 한 줄 메모 - 출력: 경영진용 1페이지 요약 + 팀 내부용 상세본 - 검토: 숫자가 원본과 맞는지 확인하는 단계가 반드시 필요하다
팀을 어떤 모양으로 묶나
하네스는 미리 정의된 6가지 구조 중에서 도메인에 맞는 것을 고릅니다. 이름만 알아두면 결과를 읽기 쉽습니다.
| 패턴 | 모양 | 언제 맞나 |
|---|---|---|
| 파이프라인 Pipeline | A → B → C | 앞 결과가 있어야 다음이 되는 일 — 수집 → 분석 → 보고 |
| 팬아웃 · 팬인 Fan-out/Fan-in | 여럿이 동시에 → 합침 | 서로 상관없는 일을 병렬로 — 파일 20개 각각 검사 |
| 전문가 풀 Expert Pool | 상황 보고 골라 부름 | 들어온 질문 종류에 따라 담당이 달라질 때 |
| 생산자 · 검토자 Producer-Reviewer | 만드는 쪽 ↔ 보는 쪽 | 품질이 중요한 산출물 — 초안 후 반드시 검토 |
| 감독자 Supervisor | 중앙에서 배분 | 일이 들어올 때마다 누가 할지 정해야 할 때 |
| 계층 위임 Hierarchical | 위에서 아래로 쪼갬 | 큰 과제를 단계적으로 잘라 내려야 할 때 |
생성된 파일 읽기
실행이 끝나면 파일이 실제로 만들어집니다. 하나씩 열어보면 B-5에서 손으로 만든 것과 같은 형식입니다.
.claude/
├── agents/{이름}.md # 역할 · 원칙 · 협업 규칙
└── skills/
├── {이름}/SKILL.md # 작업 절차 (+ references/ scripts/)
└── orchestrator/SKILL.md # 누가 언제 무엇을 — 전체 흐름
CLAUDE.md # 하네스 포인터 + 버전 이력만
_workspace/ # 중간 산출물 (01_analyst_요구사항.md …)| 파일 | 담는 것 |
|---|---|
| agents/{이름}.md | 이 에이전트의 역할, 지켜야 할 원칙, 다른 에이전트와 주고받는 방법 |
| skills/{이름}/SKILL.md | 실제 작업 절차. 길면 references/ 로 분리 |
| orchestrator/SKILL.md | 전체 지휘 — 순서, 데이터 전달 방식, 실패 시 처리 |
| _workspace/ | 단계별 중간 결과물. 어디서 틀어졌는지 추적할 수 있습니다 |
안에서 무슨 일이 일어나나
하네스는 정해진 단계를 따릅니다. 중간에 확인을 요청하니, 그때 방향을 잡아주면 됩니다.
점검 — 기존 것 먼저 본다
이미 있는 에이전트·스킬·CLAUDE.md를 읽고 중복과 어긋남을 찾습니다. 새로 만들지, 덧붙일지 정합니다.
도메인 분석
무슨 일인지, 핵심 작업이 무엇인지, 기술 스택과 내 숙련도를 파악합니다. 여기서 질문이 옵니다.
팀 설계
에이전트 팀으로 갈지 서브에이전트로 갈지, 6패턴 중 무엇을 쓸지, 역할을 어떤 기준으로 나눌지 정합니다.
에이전트 정의
.claude/agents/ 에 역할별 파일을 만듭니다. 기존 것과 겹치면 합칩니다.
스킬 생성
.claude/skills/ 에 절차서를 만듭니다. 길면 references/ 로 나눕니다.
통합 — 오케스트레이터
전체를 묶는 지휘 스킬을 만들고, CLAUDE.md에 포인터만 남깁니다.
검증
각 스킬을 현실적인 프롬프트 2~3개로 테스트하고, 불려야 할 때 불리는지 / 안 불려야 할 때 안 불리는지 확인합니다.
진화
써본 뒤 피드백을 반영해 해당 부분만 고치고, 버전 이력에 남깁니다.
무엇이 달라지나
| 손으로 만들기 (B-5) | 하네스 | |
|---|---|---|
| 내가 하는 일 | 파일 형식·필드를 직접 익혀 작성 | 도메인 한 문장 설명 |
| 구조 설계 | 직접 고민 | 패턴 6종에서 자동 선택 |
| 적합한 규모 | 스킬 1~2개 | 역할 3개 이상이 협업 |
| 결과물 | 내가 의도한 그대로 | 초안 — 읽고 고쳐야 함 |
생성물은 초안이다
| 주의 | 이유 |
|---|---|
| 생성 결과를 반드시 읽는다 | 내 업무와 안 맞는 절차가 섞일 수 있습니다. 커밋 전에 확인하세요 |
| 중복을 확인한다 | 이미 있는 스킬과 역할이 겹치면 어느 쪽이 불릴지 불안정해집니다 |
| description을 손본다 | 스킬이 언제 불릴지는 이 문장이 전부입니다. 어색하면 직접 고치세요 |
| 작게 시작한다 | 에이전트 8개보다 2~3개가 확실히 도는 것이 낫습니다 |
| 실험 기능임을 감안한다 | 에이전트 팀은 플래그로 켜는 실험 기능이라 동작이 바뀔 수 있습니다 |
- 플러그인을 설치하고 /plugin 목록에서 확인했다
- 내 업무를 입력 · 출력 · 검토 기준으로 설명해봤다
- 생성된 orchestrator/SKILL.md 를 읽고 흐름을 이해했다
- 패턴 6종 중 내 업무에 맞는 것을 고를 수 있다
- 생성물이 초안이라는 것을 알고 직접 고쳐봤다