문제: 이 대화를 모르는 서브에이전트에게 lead·명단 양식·new-expert·설계 일부만 주고 리뷰를 시켰더니(cold-read) 짐작한 곳 22개가 나왔다. 실질적인 것: 크기 기준이 없음, 물결과 라운드가 같은지 모름, 사실 다툼과 가치 충돌의 순서, 남의 브랜치를 리드가 고쳐도 되나, 넓은 paths로 렌즈가 다섯 붙음, 렌즈를 묶는 기준, 시험 파일을 누구 렌즈에, 심각도 단계, reviewer·arch-reviewer·verify·simplifier를 언제, 기준 커밋 정의, 리뷰어가 시험을 돌려도 되나, 소유자가 누구인가, 멈춤 조건. 고른 방법: lead에 물결·라운드 정의와 그림, 크기 기준(brief 우선), merge-base 기준 커밋, 렌즈는 후보이고 상관없는 것은 뺌, 묶는 기준 (같은 물음끼리, 반대 입장은 나눔), 시험 파일 배정, 리뷰어 종류, 심각도 네 단계, 사실 먼저 반증 → 가치 충돌만 순위, 소유자 정의, 남의 브랜치는 돌려줌, 멈춤 조건을 넣는다. 명단 양식에는 말뜻(렌즈·물결· 라운드·하위 세션·게이트)과 소유자 단서를 넣는다. 설계 4절에 규칙 셋, 5.1에 초안이 실제 repo로 맞춘 백엔드 경로를 반영한다. 버린 대안: 말뜻을 lead 스킬 안에 모두 두기. 스킬 본문이 길어지고 repo마다 쓰는 이름이 달라 명단 문서가 맞는 자리다. 위험: lead 본문이 약 120줄로 늘었다(상한 500줄 안). 프론트 경로는 아직 실제 repo와 맞추지 않았다. 검증: python3 -m unittest discover -s tests → 11건 통과, claude plugin validate --strict plugins/harness → 통과.
4.3 KiB
4.3 KiB
전문가 — 누가 무엇을 보고 어떻게 주고받나
이 repo의 분야 전문가 명단과 협업 규칙이다. 절차(쓸지 → 렌즈 고르기 → brief → 병렬 → 합치기·반증 → 넘김 → 충돌 판정 → 고치기 → 재확인 세 라운드까지)는 하네스 플러그인의 lead 스킬이고, 왜 이 모양인지는 claude-harness docs/experts.md다. 이 문서는 이 repo에서 다른 것만 적는다. 전문가를 더할 때는 new-expert 스킬.
고치는 메인 세션 ──그 분야 파일을 만짐──> 지식 스킬이 목록에 뜸 ──부름──> 함정·점검표·검증대로 직접 고친다
리드(메인 세션) ──brief + 렌즈(지식 스킬 경로)──> reviewer(새 눈, 판정만) ──발견·넘길 것──> 리드 ──> 고치기
이 문서에서 쓰는 말
- 분야 전문가 = 지식 스킬: 한 분야의 함정·점검표·검증 명령.
paths를 걸어 그 파일을 만질 때만 목록에 뜬다. - 렌즈: 리뷰어에게 "이 지식 스킬로 보라"고 주는 스킬 경로 1~3개.
- 리드: 렌즈를 고르고 리뷰어를 띄우고 합치는 메인 세션. 하위 세션을 나눠 맡기는 총괄이면 총괄.
- 물결: 리뷰어를 한꺼번에 띄우는 차례(한 라운드에 두 번까지). 라운드: 리뷰 → 고치기 → 재확인 한 바퀴(세 번까지).
- 서브에이전트: 한 세션 안에서 띄우는 별도 창. 결과만 돌려준다. 하위 세션: 사람이 열어 보고 멈출 수 있는 별도 세션. 파일을 바꾸는 큰 위임은 하위 세션이다.
- 게이트: 이 repo 검증 진입점(
scripts/verify.sh등)이 돌리는 검사. 리뷰어의 "통과"는 게이트를 대신하지 않는다.
1. 큰 그림을 읽는 순서
메인 세션과 리뷰어가 같은 순서로 읽는다.
- 루트
AGENTS.md(무엇인가 · 꼭 지킬 것 · 지도) - 이 문서의 명단에서 맡은 렌즈의 줄
- 렌즈인 지식 스킬(「함정」부터)
- 작업 파일과 가장 가까운 폴더의
AGENTS.md - 스킬이 가리키는 정본 문서(필요한 절만)
2. 명단
| 전문가 | 형태 | 파일 | 언제 | 내는 것 |
|---|---|---|---|---|
| 리드 | 메인 세션 + lead 스킬 |
플러그인 | 둘 이상 분야, PR 전, 의견 충돌 | 고른 렌즈, 합친 발견, 충돌 판정 |
| (채울 것: 분야) | 지식 스킬 | .claude/skills/<접두>-<분야>/ |
(발동 조건, paths) |
함정·점검표·검증 |
| reviewer | 서브에이전트 | .claude/agents/reviewer.md |
분야 판정(렌즈를 받아) | lead 공통 양식 |
| (채울 것: 일) | 서브에이전트 | .claude/agents/<이름>.md |
(계층 경계 리뷰, 실행 검증 등) | lead 공통 양식 |
3. 경로 → 전문가(렌즈)
리드가 바뀐 경로로 렌즈 후보를 고르는 표다. 지식 스킬의 paths와 맞춘다. 후보 중 변경 내용과 상관없는 것은 리드가 뺀다.
| 경로(glob) | 렌즈(지식 스킬) | 이럴 때 더한다 |
|---|---|---|
| (채울 것) |
4. 넘김 지도
리뷰어가 「넘길 것」에 자주 쓰는 길이다. 넘김은 리드를 거친다(서로 직접 부르지 않는다).
| 보낸 렌즈 | 받는 렌즈 | 무엇을 |
|---|---|---|
| (채울 것) |
5. 충돌 — 이 repo에서 정해 둔 것
사실 다툼(받는 쪽이 있나, 실제로 깨지나)은 반증으로 먼저 가린다. 가치가 부딪칠 때의 순위는 lead 스킬 ⑦이다(데이터 손실·보안 → 공개 계약 → 꼭 지킬 것 → 검증 가능 → 성능·접근성 예산 → 디자인·UX 일관성 → 단순함). 공개 계약을 바꾸는 선택, 되돌릴 수 없는 방식 고르기, 같은 순위끼리의 충돌은 소유자가 정한다. 같은 충돌이 두 번 나오면 여기에 한 줄 더한다.
| 날짜 | 부딪친 것 | 정한 것 | 근거 |
|---|
6. 비용
- 서브에이전트 설명은 모든 세션의 컨텍스트에 들어간다. 이 repo 서브에이전트 설명의 합을 재고(예:
grep -h '^description:' .claude/agents/*.md | wc -c) 늘면 줄인다. - 지식 스킬은
paths를 걸어 그 파일을 만질 때만 목록에 뜨게 한다. - 전문가를 더하거나 바꾼 뒤 첫 큰 일은
harness-eval로 바꾸기 전과 견준다.