Files
claude-harness/plugins/harness/skills/lead/SKILL.md
T
DongHyeonka b2e6a5ea7f feat(lead): 첫 평가 결과로 리뷰어 수를 변경 크기와 작성자로 정한다
문제: 첫 판 비교(과제 A: 48줄짜리 기능 커밋에 분야마다 결함 하나씩 6개를
심은 백엔드 리뷰, 판마다 2번)에서 렌즈 리뷰어 셋에 나눈 v2가 혼자 본
v1과 같은 6/6을 찾고, 틀린 발견은 둘 다 0, 출력 토큰은 2.08배를 썼다.
리드 창 최대는 0.75배로 작았다. 미리 정한 기준(심은 결함 +2 이상)을
못 넘었다. 렌즈 수로 리뷰어 수를 정하던 규칙이 작은 변경에 과하다.

고른 방법: lead ①에서 리뷰어 수를 변경 크기와 누가 고쳤나로 정한다.
남이 쓴 300줄 아래 변경은 0명(리드가 이미 새 눈, 렌즈 스킬을 직접 읽음),
리드가 고친 300줄 아래 변경은 1명(렌즈가 셋 넘으면 2명), 300줄 이상이나
파일 10개 이상은 2~4명. 크기(작음·중간·큼)는 일의 무게로만 쓴다.
설계 7.1절에 결과 표와 기준 대조를, 장부에 이 작업의 estimate 줄,
eval 줄 넷(v1·v2 각 둘), retro 줄(fix lens-small-diff)을 더한다.
버린 대안: v2 되돌리기. 품질은 같았고 과제가 천장이라 렌즈 리뷰의
이득을 잴 수 없었다. 변별력 있는 과제 A2·B로 다시 본다.

위험: 서브에이전트로 판을 흉내 냈다(헤드리스 인증 없음). 실제 세션의
스킬 목록·paths 발동과 다를 수 있다. 실행 수가 판마다 2번뿐이다.

검증: scripts/check.sh 통과. ledger.py compare --task harness-v2-eval로
표를 다시 뽑았다.
2026-11-11 22:34:50 +09:00

11 KiB

name, description
name description
lead Use when a change, review, or design spans more than one expert area (for example persistence plus API contract, or UI plus design system plus accessibility), before a PR to decide which area knowledge skills and fresh-context reviewers from docs/work/experts.md to use, or when expert findings conflict — to pick lenses by changed paths and risk, brief reviewers, run them in parallel, verify findings by refutation, route hand-offs, cap review rounds, and decide conflicts. 여러 분야에 걸친 변경·리뷰·설계에서 분야 지식과 리뷰어를 고르고 맡기고 합칠 때, 의견이 부딪칠 때 부른다.

lead — 분야 지식을 고르고, 맡기고, 합친다

리드는 지금 대화하는 메인 세션이다(하위 세션을 나눠 맡기는 총괄이면 총괄). 명단·경로표·넘김 지도·말뜻은 그 repo의 docs/work/experts.md이고, 이 스킬은 어느 repo에서나 같은 절차다. 둘이 다르면 repo 문서가 맞다. 이유는 claude-harness docs/experts.md다.

분야 전문가 = 지식 스킬(paths). 고칠 때는 메인이 그 스킬을 부르고 직접 고친다.
새 눈이 필요하면 = reviewer 서브에이전트에 렌즈(읽을 지식 스킬)를 주고 띄운다.

①쓸지 ─> ②렌즈 ─> ③brief ─> ④물결 1(병렬) ─> ⑤합치기·반증 ─> ⑥물결 2(넘김) ─> ⑦충돌 ─> ⑧고치기 ─> ⑨재확인
         └────────────────── 라운드 하나 ──────────────────┘                       라운드는 세 번까지
  • 물결: 리뷰어를 한꺼번에 띄우는 차례. 한 라운드에 두 번까지(처음 + 넘김).
  • 라운드: 리뷰 → 고치기 → 재확인 한 바퀴. 세 번까지.

① 쓸지 정하기

  • 서브에이전트 하나는 별도 컨텍스트이고 토큰을 몇 배 쓴다. 역할(계획·구현·시험·리뷰)이나 분야마다 나누지 않는다. 쓸 때는 셋뿐이다: 새 눈이 필요한 리뷰·검증, 파일 10개 넘게 읽어야 하는 조사, 출력이 긴 실행(앱·브라우저·게이트).

  • 크기(작음·중간·큼)는 일의 무게다. brief가 정한 것을 쓴다. 없으면: 분야 하나·파일 몇 개는 작음, 분야 둘은 중간, 분야 셋 이상이거나 공개 계약·마이그레이션·인증이 걸리면 큼. 큼은 소유자 검토가 먼저다. 리뷰어 수는 아래 표로 따로 정한다.

  • 리뷰어 수는 변경 크기와 누가 고쳤나로 정한다. 렌즈 수로 정하지 않는다.

    경우 리뷰어
    남이 쓴 변경, 바뀐 줄 300 아래 0명. 리드가 이미 새 눈이다. 렌즈 스킬을 직접 읽고 리뷰한다
    리드(이 세션)가 고친 변경, 바뀐 줄 300 아래 1명. 렌즈를 모아 준다(셋 넘으면 2명)
    바뀐 줄 300 이상이거나 파일 10개 이상 렌즈를 13개씩 묶어 24명

    한 물결에 4명을 넘기지 않는다. 근거: 2026-11-11 평가에서 48줄 변경을 리드 혼자 본 판(v1)과 리뷰어 셋에 나눈 판(v2)이 심은 결함을 똑같이 6/6 찾았고, 나눈 판이 토큰을 약 2.1배 썼다(claude-harness docs/experts.md 7절).

  • 기능을 고치는 사람이 그 시험도 고친다. 시험만 따로 맡기지 않는다.

② 렌즈 고르기

  1. 기준 커밋은 git merge-base <들어갈 브랜치> HEAD다. git diff --name-only <기준>...HEAD로 바뀐 경로를 본다.
  2. docs/work/experts.md 「경로 → 전문가」로 경로마다 지식 스킬을 고른다. 이것이 렌즈 후보다. 변경 내용과 상관없는 후보는 뺀다(뺀 이유 한 줄).
  3. 위험 신호가 있으면 그 렌즈를 더한다: 공개 계약(경로·필드·오류 코드·이벤트·env 키), 되돌릴 수 없는 것(마이그레이션·데이터 삭제), 인증·인가·비밀, 성능·접근성 예산, 빌드·CI 설정.
  4. 리뷰어 하나에 렌즈 1~3개. 같은 코드를 같은 물음으로 보는 렌즈끼리 묶는다(영속성+성능 = 조회 비용, 계약+시험 = 호환을 증명하나). 반대 입장이 필요한 렌즈는 나눈다(보안과 계약). 같은 렌즈를 두 리뷰어에게 주지 않는다.
  5. 시험 파일은 그 시험이 지키는 분야의 렌즈에 붙인다. 시험 렌즈(*-testing)는 시험 자체의 품질(거짓 통과, 흔들림)만 본다.
  6. 리뷰어 종류: 분야 판정은 reviewer+렌즈, 계층 경계·「꼭 지킬 것」은 arch-reviewer, 앱을 띄워 봐야 아는 것은 verify-*, 정리 제안은 code-simplifier(고를 때만). 이름은 그 repo docs/work/experts.md 명단이 정한다.

③ brief — 리뷰어는 이 대화를 못 본다

목표: 한 문장. 무엇을 판정하나
렌즈: 읽을 지식 스킬 경로(.claude/skills/<이름>/SKILL.md) 1~3개
큰 그림: 이 변경이 하려는 것 3줄, 관련 결정(그 repo 결정 기록과 experts.md 「정해 둔 것」에서, 내용으로)
범위: 기준 커밋과 diff 명령. 판정하지 않을 것(다른 리뷰어 몫)
제약: 파일을 고치지 않는다. 읽기 명령(git·grep·문서 검사)은 써도 되고, 시험·빌드·앱 실행은 하지 않는다(그것은 리드나 verify-*)
출력: 아래 공통 양식, 60줄 이하
  • 결론을 미리 주지 않는다. "이게 맞는지"가 아니라 "이 범위를 판정해 줘"로 쓴다.
  • 파일 내용·대화 이력·다른 리뷰어의 긴 보고를 붙여 넣지 않는다. 경로, diff 명령, 발견 한 줄을 준다.
  • 리뷰어는 이름으로 부른다(subagent_type). 설명만 보고 저절로 불리기를 기대하지 않는다.

④ 병렬 실행

  • 한 물결의 리뷰어는 한 메시지에서 함께 띄운다. 오래 걸리는 실행 검증은 백그라운드로 띄우고 리드는 다른 일을 한다.
  • 결과를 기다리며 같은 일을 리드가 따로 하지 않는다.

⑤ 합치기와 반증

공통 양식:

판정: 통과 / 고칠 것 있음 / 판단 못 함
발견: [Critical|High|Medium|Low] 파일:줄 — 무엇이 문제인가 — 근거(규칙·문서·실행 결과) — 고치는 방향
넘길 것: → <렌즈 또는 사람>: 확인할 것 (왜 내 몫이 아닌가)
확인 못 한 것: 읽지 못한 것, 실행해야만 알 것
  • 심각도: Critical(데이터 손실·보안 사고·운영 중단) · High(공개 계약 깨짐, 꼭 지킬 것 위반, 틀린 동작) · Medium(고쳐야 하지만 당장 깨지지 않음) · Low(작은 개선). 렌즈 밖에서 본 것은 판정하지 않고 「넘길 것」에 쓴다.
  • 같은 원인·같은 위치는 하나로 묶고 찾은 리뷰어를 모두 적는다. 같은 부류가 여러 곳이면 "부류"로 묶어 모든 곳을 고치게 한다.
  • 스타일·취향 발견은 버린다(리뷰어 하나에 Low 3건까지). 근거 칸이 빈 발견, 추측은 「확인 못 한 것」으로 내린다.
  • High 이상은 반증해서 살아남은 것만 남긴다. 리드가 코드에서 직접 보거나, 발견 하나를 general-purpose 서브에이전트에 "이 발견이 틀렸음을 파일:줄로 보여라. 못 보이면 참이다"로 맡긴다(물결과 따로 세고, 한 번에 둘까지). 보고는 증거가 아니다.

⑥ 넘김 — 물결 한 번 더

  • 「넘길 것」을 모아 두 번째 물결을 한 번 띄운다. 받는 쪽 brief에 넘긴 쪽의 발견 한 줄을 넣는다.
  • 세 번째 물결은 없다. 남은 넘김은 보고의 「남은 문제」다. 다른 repo로 넘길 것(예: 프론트가 본 API 계약 차이)은 총괄에게 넘긴다.
  • 이미 띄운 리뷰어에게 다시 물을 때는 새로 띄우지 말고 SendMessage로 이어 묻는다.

⑦ 충돌 판정

먼저 사실인지 가린다. "받는 쪽이 있나", "실제로 깨지나" 같은 사실 다툼은 ⑤의 반증으로 먼저 푼다. 사실이 같은데 무엇이 중요한지가 갈릴 때만 이 순서로 정한다. 위가 이긴다.

  1. 데이터 손실·보안
  2. 공개 계약 호환(이미 받는 쪽이 있거나 있을 수 있는 경로·필드·이벤트·오류 코드)
  3. 그 repo의 「꼭 지킬 것」(아키텍처 불변식)
  4. 검증할 수 있음(시험·게이트로 증명되는가)
  5. 성능·접근성 예산
  6. 디자인·UX 일관성
  7. 단순함
  • 리드가 정하지 않고 소유자(그 repo에 목표를 준 결정권자)에게 묻는 것: 공개 계약을 바꾸는 선택, 되돌릴 수 없는 방식 고르기(예: 데이터를 지우는 마이그레이션과 남기는 마이그레이션 중), 같은 순위끼리의 충돌. 근거와 권하는 안을 붙인다.
  • 정한 것은 보고에 "무엇과 무엇이 부딪쳤고 몇 번으로 정했다"로 남긴다. 같은 충돌이 두 번 나오면 docs/work/experts.md 「정해 둔 것」에 한 줄 더한다.

⑧ 고치기

  • 서브에이전트는 파일을 고치지 않는다. 고치는 것은 리드가 직접, 크거나 소유자가 열어 봐야 하면 하위 세션이다.
  • 남의 브랜치는 리드가 고치지 않는다. 발견을 그 브랜치의 작성자(사람이나 그 하위 세션)에게 돌려준다. brief가 고치라고 했을 때만 고친다.
  • 고칠 때는 그 분야 지식 스킬을 부르고 「함정」과 「검증」을 따른다(리뷰어가 본 기준과 같은 기준).

⑨ 재확인 — 라운드 세 번까지

  • 두 번째 라운드부터는 고친 diff와 지난 발견 목록(한 줄씩)만 준다. "내 발견이 풀렸나"는 그 발견을 낸 리뷰어에게 SendMessage로 묻는다. "새 결함이 있나"는 새 인스턴스에 맡긴다(이어 물으면 전에 본 것에 끌려간다).
  • 게이트는 그 repo의 검증 진입점으로 돌린다. 리뷰어의 "통과"는 게이트를 대신하지 않는다.
  • 멈춤: High 이상이 없고 게이트가 통과하면 끝. Medium·Low는 이번에 고치거나 보고의 「남은 문제」로 넘긴다. 세 번째 라운드가 끝났는데 High가 남거나 새로 나오면 더 돌지 않고 멈춘다. 접근 자체가 문제라는 신호이니 소유자에게 다시 정할 것을 묻는다.

보고

끝 보고에 칸 하나를 더한다: 쓴 렌즈와 리뷰어 수, 물결·라운드 수, 발견 수(묶은 뒤), 반증으로 버린 수와 이유, 충돌 판정. 하네스 판을 비교하는 평가 중이면(harness-eval 스킬) 장부에 실행 한 줄을 남긴다.

하지 않는 것

  • 정의와 brief에 경력·자질 소개(「당신은 20년 차 …」)를 쓰지 않는다. 역할은 "무엇을 판정하나" 한 줄이면 된다.
  • 서브에이전트가 또 서브에이전트를 띄우게 하지 않는다. 물결은 리드만 띄운다.
  • agent teams(실험 기능)를 기본으로 켜지 않는다. 대화형에서만 돌고, 팀원에게 정의의 skills가 실리지 않으며, 토큰을 크게 쓴다.
  • 리뷰어끼리 직접 일을 주고받게 하지 않는다. 넘김은 리드를 거친다.