feat(plugin): 분야 전문가 협업(lead)과 하네스 판 비교를 더하고 0.3.0으로 올린다 #3

Merged
donghyeon.kang merged 10 commits from donghyeon.kang/harness-v2-experts AGit into main 2026-11-11 14:15:32 +00:00
Owner

무엇을, 왜

소유자가 두 템플릿에 분야별 전문가(서브에이전트·스킬)와 큰 그림을 보는 리드, 그 협업 매뉴얼을 넣으라고 했다. 지금 하네스(0.2.0)는 장치의 자리만 있고 분야 지식과 분야 사이 협업 규칙이 없다. 이 PR은 공용 부분을 만든다.

  • 조사 기록 docs/research/2026-11-11-harness-v2.md: Claude Code 공식 문서 14쪽, Anthropic 글 25편(2025-06~2026-11), 제작자 1차 발언 13건(Cherny·Wu·Hollman·Shihipar·Wolff), 공개 repo 6곳, 2차 3건, 이 기계 실측. 격차 표 17행.
  • 설계·공용 매뉴얼 docs/experts.md: 분야 전문가는 paths 지식 스킬(백엔드 10·프론트 9 목록), 서브에이전트는 일마다(렌즈를 받는 새 눈 reviewer + 있는 실행 검증), 리드는 메인 세션, 평가 계획.
  • 플러그인 0.3.0: lead(쓸지 → 렌즈 고르기 → brief → 병렬 → High 반증 → 넘김 물결 한 번 → 사실 먼저, 가치 충돌은 일곱 순서 → 리뷰-수정 세 라운드까지), new-expert(전문가 모양), harness-eval(판 비교 절차), 장부 eval 줄과 compare, usage의 start_context·agent_calls·agent_return_chars.
  • template/: docs/work/experts.md 빈 양식, AGENTS.md·CLAUDE.md 한 줄씩.

두 템플릿의 분야 스킬 적용은 진행 중인 PR(백엔드 relayout, 프론트 #14·#15·#16)이 병합된 뒤 각 repo PR로 한다.

고른 방법과 버린 대안

  • 분야마다 서브에이전트를 두지 않는다. 소유자 요청과 다르다. Anthropic 2026-10-22 「When to fold subagents into your main agent loop」(분야·팀마다 서브에이전트 = 조직도를 닮음, 스킬 가진 단일 에이전트가 자주 낫고 쌈), 2026-01-23 「Building multi-agent systems」(역할 분리는 조정에 토큰을 더 씀), 2026-04-07 「subagents in Claude Code」(로스터가 크면 위임이 흔들림), 현행 best practices가 같은 방향이다. 분야 지식은 스킬 하나에 두고, 리뷰할 때 같은 reviewer를 분야 렌즈로 여러 번 띄운다. 첫 초안(템플릿당 서브에이전트 9개)은 버렸다.
  • 지식 스킬은 paths로 목록 밖에. 지금 스킬 목록이 예산(창의 1%) 근처다(33,093자). CLI가 paths 스킬을 맞는 파일을 만질 때까지 따로 둔다는 것을 바이너리에서 확인했다.
  • agent teams는 기본으로 쓰지 않는다. 실험 기능, 대화형만, 팀원에 skills 미적용, 약 7배 토큰.
  • 분야 에이전트를 플러그인에 넣지 않는다. 플러그인 에이전트는 harness: 아래 이름이라 템플릿 것과 둘 다 목록에 뜬다.
  • 새 스킬 셋은 13절 Q9대로 모델 호출형이다. harness-eval은 설명에 "시킬 때만"을 쓴다.

위험과 영향

  • 스킬 셋 설명(약 400~500자씩)이 플러그인을 켠 모든 세션의 스킬 목록에 더해진다.
  • agent_return_chars는 앱의 대기열 알림 모양(queued_command의 <agent-message 머리)에 기댄다. 모양이 바뀌면 값이 조용히 준다(시험이 지금 모양을 고정).
  • paths 스킬이 목록에서 빠지는 것은 새 세션에서 직접 보지 못했다(헤드리스 인증 없음). 템플릿 적용 때 확인한다.
  • 받는 쪽(두 템플릿)은 claude plugin marketplace update claude-harness와 새 세션이 있어야 0.3.0을 받는다.

검증

  • scripts/check.sh → 통과(플러그인 시험 24건·알려진 실패 1, 템플릿 시험 11건, claude plugin validate --strict 둘).

  • 장부 변경: 조건을 하나씩 끈 변이 9개가 모두 시험에 걸렸다.

  • 매뉴얼 cold-read: 이 대화를 모르는 서브에이전트에게 lead·명단 양식·new-expert·설계 일부만 주고 다분야 리뷰를 시켰다. 짐작한 곳 22개가 나왔고, 실질적인 것(크기 기준, 물결과 라운드, 사실 다툼과 가치 충돌의 순서, 남의 브랜치는 돌려줌, 렌즈 묶는 기준, 심각도 네 단계, 리뷰어 종류, 기준 커밋, 멈춤 조건, 말뜻)을 9735c33에서 메웠다.

  • 평가 과제 A(백엔드 템플릿 로컬 복제의 그럴듯한 기능 커밋 하나에 분야마다 결함 하나씩 6개, 판마다 2번, 실행하는 쪽은 목록을 모름): ledger.py compare --task harness-v2-eval

    판 작업 중 분 호출 출력 토큰 리드 창 최대 심은 결함 틀린 발견
    v1 11 64 52,419 198,911 6/6 0
    v2 10.5 133.5 108,912 148,979 6/6 0

    미리 정한 기준(심은 결함 +2 이상)을 못 넘었다. 과제가 쉬워 둘 다 천장이었다. v2는 토큰 2.08배, 리드 창 0.75배, 심각도를 더 맞게 매겼다. 정한 대로 리뷰어 수를 줄였다(b2e6a5e: 남의 작은 변경은 0명, 자기 작은 변경은 1명, 큰 변경만 2~4명, 장부 retro lens-small-diff). 변별력 있는 과제 A2(repo 고유 함정)와 프론트 과제 B는 템플릿 적용 PR에서 돌린다.

  • 판은 데스크톱 앱 세션의 서브에이전트로 흉내 냈다(세션 시작 지침·스킬 목록·에이전트 정의를 프롬프트로). v2 지식 스킬 10개는 심은 목록을 모르는 서브에이전트가 백엔드 문서만 보고 썼다(공유 노트로 넘김, 템플릿 적용 때 쓴다).

  • 실제 세션 평가(claude plugin eval, 468b26e, 설계 7.2절): 판마다 평가용 플러그인을 만들어 opus-5-5로 돌렸다(판정 sonnet). 판 셋 = none(플러그인 없음)·v1·v2.

    과제 none v1 v2
    A 리뷰(결함 6) 6/6 ×2 6/6 ×2 6/6 ×2
    A2 리뷰(repo 고유 규칙 결함 6) 6/6 ×2 6/6 ×2 6/6 ×2
    구현(repo 규칙 검사 8개) 12/16 30/40 (75%) 37/40 (92.5%)
    그중 동시 인덱스 규칙 0/2 0/5 3/5
    시작 컨텍스트(샌드박스) 18.5k 20.5k 23.2k

    리뷰는 하네스와 상관없이 천장이다. 구현에서 v2가 나았다(표본 작음, 한쪽 검정 p≈0.08). lead는 다분야 리뷰 4번·단순 질문 4번 모두 불리지 않았다. 샌드박스의 시작 비용 13% 증가는 지식 스킬을 플러그인으로 실었기 때문이다(플러그인 스킬은 paths가 있어도 목록에 듦). 실제 템플릿은 프로젝트 스킬이고, 프로젝트 paths 스킬이 시작 목록에 없는 것을 실제 세션으로 확인했다. 장부 harness-v2-eval-real 줄 24개.

  • 하지 않은 것: 프론트 과제 B(프론트 지식 스킬 초안 전), 프로젝트 스킬 상태의 실제 세션 시작 비용(템플릿 적용 때).

리뷰어가 볼 곳

  • docs/experts.md 0절(소유자 요청과 다른 이유)과 4절(협업 규칙의 근거).
  • plugins/harness/skills/lead/SKILL.md: 절차의 정본.
  • plugins/harness/scripts/ledger.py scan·summarize·cmd_compare.

소유자·총괄이 볼 것

  • 소유자 승인 2026-11-11 「W3 설계대로」. design-docs에 넣을 결정 문장은 공유 노트 w3-harness-v2.md에 있다(총괄이 반영).
  • 스킬 목록이 예산 근처다(앱 표시 9,549토큰). 13절 Q8(안 쓰는 개인 스킬을 name-only·off)이 아직 적용되지 않은 것으로 보인다.
  • design-docs harness/01-harness-design.md 2.2절 11·12·16·19·21번 "확인 못 함"이 1차로 확인됐다(조사 기록 G16). design-docs는 이 PR 범위 밖이다.

관련

  • 설계 정본(v1): design-docs harness/01-harness-design.md 13절
  • 정리 프로그램: design-docs template-program/README.md 4절 W3
## 무엇을, 왜 소유자가 두 템플릿에 분야별 전문가(서브에이전트·스킬)와 큰 그림을 보는 리드, 그 협업 매뉴얼을 넣으라고 했다. 지금 하네스(0.2.0)는 장치의 자리만 있고 분야 지식과 분야 사이 협업 규칙이 없다. 이 PR은 공용 부분을 만든다. - 조사 기록 `docs/research/2026-11-11-harness-v2.md`: Claude Code 공식 문서 14쪽, Anthropic 글 25편(2025-06~2026-11), 제작자 1차 발언 13건(Cherny·Wu·Hollman·Shihipar·Wolff), 공개 repo 6곳, 2차 3건, 이 기계 실측. 격차 표 17행. - 설계·공용 매뉴얼 `docs/experts.md`: 분야 전문가는 `paths` 지식 스킬(백엔드 10·프론트 9 목록), 서브에이전트는 일마다(렌즈를 받는 새 눈 `reviewer` + 있는 실행 검증), 리드는 메인 세션, 평가 계획. - 플러그인 0.3.0: `lead`(쓸지 → 렌즈 고르기 → brief → 병렬 → High 반증 → 넘김 물결 한 번 → 사실 먼저, 가치 충돌은 일곱 순서 → 리뷰-수정 세 라운드까지), `new-expert`(전문가 모양), `harness-eval`(판 비교 절차), 장부 `eval` 줄과 `compare`, `usage`의 `start_context`·`agent_calls`·`agent_return_chars`. - `template/`: `docs/work/experts.md` 빈 양식, `AGENTS.md`·`CLAUDE.md` 한 줄씩. 두 템플릿의 분야 스킬 적용은 진행 중인 PR(백엔드 relayout, 프론트 #14·#15·#16)이 병합된 뒤 각 repo PR로 한다. ## 고른 방법과 버린 대안 - **분야마다 서브에이전트를 두지 않는다.** 소유자 요청과 다르다. Anthropic 2026-10-22 「When to fold subagents into your main agent loop」(분야·팀마다 서브에이전트 = 조직도를 닮음, 스킬 가진 단일 에이전트가 자주 낫고 쌈), 2026-01-23 「Building multi-agent systems」(역할 분리는 조정에 토큰을 더 씀), 2026-04-07 「subagents in Claude Code」(로스터가 크면 위임이 흔들림), 현행 best practices가 같은 방향이다. 분야 지식은 스킬 하나에 두고, 리뷰할 때 같은 `reviewer`를 분야 렌즈로 여러 번 띄운다. 첫 초안(템플릿당 서브에이전트 9개)은 버렸다. - **지식 스킬은 `paths`로 목록 밖에.** 지금 스킬 목록이 예산(창의 1%) 근처다(33,093자). CLI가 `paths` 스킬을 맞는 파일을 만질 때까지 따로 둔다는 것을 바이너리에서 확인했다. - **agent teams는 기본으로 쓰지 않는다.** 실험 기능, 대화형만, 팀원에 `skills` 미적용, 약 7배 토큰. - **분야 에이전트를 플러그인에 넣지 않는다.** 플러그인 에이전트는 `harness:` 아래 이름이라 템플릿 것과 둘 다 목록에 뜬다. - 새 스킬 셋은 13절 Q9대로 모델 호출형이다. `harness-eval`은 설명에 "시킬 때만"을 쓴다. ## 위험과 영향 - 스킬 셋 설명(약 400~500자씩)이 플러그인을 켠 모든 세션의 스킬 목록에 더해진다. - `agent_return_chars`는 앱의 대기열 알림 모양(`queued_command`의 `<agent-message` 머리)에 기댄다. 모양이 바뀌면 값이 조용히 준다(시험이 지금 모양을 고정). - `paths` 스킬이 목록에서 빠지는 것은 새 세션에서 직접 보지 못했다(헤드리스 인증 없음). 템플릿 적용 때 확인한다. - 받는 쪽(두 템플릿)은 `claude plugin marketplace update claude-harness`와 새 세션이 있어야 0.3.0을 받는다. ## 검증 - `scripts/check.sh` → 통과(플러그인 시험 24건·알려진 실패 1, 템플릿 시험 11건, `claude plugin validate --strict` 둘). - 장부 변경: 조건을 하나씩 끈 변이 9개가 모두 시험에 걸렸다. - 매뉴얼 cold-read: 이 대화를 모르는 서브에이전트에게 `lead`·명단 양식·`new-expert`·설계 일부만 주고 다분야 리뷰를 시켰다. 짐작한 곳 22개가 나왔고, 실질적인 것(크기 기준, 물결과 라운드, 사실 다툼과 가치 충돌의 순서, 남의 브랜치는 돌려줌, 렌즈 묶는 기준, 심각도 네 단계, 리뷰어 종류, 기준 커밋, 멈춤 조건, 말뜻)을 `9735c33`에서 메웠다. - 평가 과제 A(백엔드 템플릿 로컬 복제의 그럴듯한 기능 커밋 하나에 분야마다 결함 하나씩 6개, 판마다 2번, 실행하는 쪽은 목록을 모름): `ledger.py compare --task harness-v2-eval` | 판 | 작업 중 분 | 호출 | 출력 토큰 | 리드 창 최대 | 심은 결함 | 틀린 발견 | |---|---|---|---|---|---|---| | v1 | 11 | 64 | 52,419 | 198,911 | 6/6 | 0 | | v2 | 10.5 | 133.5 | 108,912 | 148,979 | 6/6 | 0 | 미리 정한 기준(심은 결함 +2 이상)을 **못 넘었다**. 과제가 쉬워 둘 다 천장이었다. v2는 토큰 2.08배, 리드 창 0.75배, 심각도를 더 맞게 매겼다. 정한 대로 리뷰어 수를 줄였다(`b2e6a5e`: 남의 작은 변경은 0명, 자기 작은 변경은 1명, 큰 변경만 2~4명, 장부 retro `lens-small-diff`). 변별력 있는 과제 A2(repo 고유 함정)와 프론트 과제 B는 템플릿 적용 PR에서 돌린다. - 판은 데스크톱 앱 세션의 서브에이전트로 흉내 냈다(세션 시작 지침·스킬 목록·에이전트 정의를 프롬프트로). v2 지식 스킬 10개는 심은 목록을 모르는 서브에이전트가 백엔드 문서만 보고 썼다(공유 노트로 넘김, 템플릿 적용 때 쓴다). - **실제 세션 평가(`claude plugin eval`, `468b26e`, 설계 7.2절)**: 판마다 평가용 플러그인을 만들어 opus-5-5로 돌렸다(판정 sonnet). 판 셋 = none(플러그인 없음)·v1·v2. | 과제 | none | v1 | v2 | |---|---|---|---| | A 리뷰(결함 6) | 6/6 ×2 | 6/6 ×2 | 6/6 ×2 | | A2 리뷰(repo 고유 규칙 결함 6) | 6/6 ×2 | 6/6 ×2 | 6/6 ×2 | | 구현(repo 규칙 검사 8개) | 12/16 | 30/40 (75%) | **37/40 (92.5%)** | | 그중 동시 인덱스 규칙 | 0/2 | 0/5 | **3/5** | | 시작 컨텍스트(샌드박스) | 18.5k | 20.5k | 23.2k | 리뷰는 하네스와 상관없이 천장이다. 구현에서 v2가 나았다(표본 작음, 한쪽 검정 p≈0.08). `lead`는 다분야 리뷰 4번·단순 질문 4번 모두 불리지 않았다. 샌드박스의 시작 비용 13% 증가는 지식 스킬을 플러그인으로 실었기 때문이다(플러그인 스킬은 `paths`가 있어도 목록에 듦). 실제 템플릿은 프로젝트 스킬이고, 프로젝트 `paths` 스킬이 시작 목록에 없는 것을 실제 세션으로 확인했다. 장부 `harness-v2-eval-real` 줄 24개. - 하지 않은 것: 프론트 과제 B(프론트 지식 스킬 초안 전), 프로젝트 스킬 상태의 실제 세션 시작 비용(템플릿 적용 때). ## 리뷰어가 볼 곳 - `docs/experts.md` 0절(소유자 요청과 다른 이유)과 4절(협업 규칙의 근거). - `plugins/harness/skills/lead/SKILL.md`: 절차의 정본. - `plugins/harness/scripts/ledger.py` `scan`·`summarize`·`cmd_compare`. ## 소유자·총괄이 볼 것 - 소유자 승인 2026-11-11 「W3 설계대로」. design-docs에 넣을 결정 문장은 공유 노트 `w3-harness-v2.md`에 있다(총괄이 반영). - 스킬 목록이 예산 근처다(앱 표시 9,549토큰). 13절 Q8(안 쓰는 개인 스킬을 `name-only`·`off`)이 아직 적용되지 않은 것으로 보인다. - design-docs `harness/01-harness-design.md` 2.2절 11·12·16·19·21번 "확인 못 함"이 1차로 확인됐다(조사 기록 G16). design-docs는 이 PR 범위 밖이다. ## 관련 - 설계 정본(v1): design-docs `harness/01-harness-design.md` 13절 - 정리 프로그램: design-docs `template-program/README.md` 4절 W3
donghyeon.kang added 9 commits 2026-11-11 13:36:09 +00:00
문제: 하네스 v2(분야 전문가 협업)를 v1과 견주려면 같은 과제를 판마다
돌린 실행을 한 줄씩 남기고 비교해야 하는데, 장부에는 예측·실측만 있다.
실측도 시간·호출·토큰뿐이라 모든 세션의 시작 비용(첫 호출 입력 토큰)과
서브에이전트가 메인에 돌려준 양(컨텍스트 비용)을 볼 수 없다.

고른 방법:
- usage에 start_context(본 기록 첫 호출), subagents·subagent_output_tokens,
  agent_calls(Agent·Task 호출), agent_return_chars를 더한다. 반환 글자는
  Agent 도구 결과와, 백그라운드 결과가 들어오는 대기열 알림
  (queued_command의 <agent-message·<task-notification 머리)을 센다.
  2026-11-11 세션 기록에서 백그라운드 결과가 tool_result가 아니라
  알림으로 오는 것을 확인했다.
- 새 줄 종류 eval(arm·case 필수)과 명령 eval(초안)·compare(과제·판별
  중앙값, 마지막 판/첫 판 비율). precedents는 eval만 있는 작업을 세지 않는다.
- Stop 훅이 0.2.0이 저장한 상태 파일을 이어 읽어도 깨지지 않게 새 칸은
  setdefault로 채운다.
- 버린 대안: eval을 actual 줄에 arm 칸으로 붙이기. 같은 작업의 판 여럿이
  by_task에서 덮이고 회고 대기 계산에 섞인다.

위험: 대기열 알림 모양은 앱 내부 형식이다. 바뀌면 agent_return_chars가
조용히 줄어든다(시험이 지금 모양을 고정한다).

검증: python3 -m unittest discover -s plugins/harness/tests → 24건 통과
(알려진 실패 1). 조건을 하나씩 끈 변이 9개가 모두 시험에 걸렸다.
문제: 소유자는 두 템플릿에 분야별 전문가 서브에이전트·스킬과 리드
역할, 협업 매뉴얼을 넣으라고 했다. 지금 하네스는 장치의 자리만 있고
분야 지식과 분야 사이 협업 규칙이 없다. 무엇을 어떤 장치로 둘지
근거가 필요하다.

고른 방법:
- 조사 기록(docs/research/2026-11-11-harness-v2.md): 공식 문서 14쪽,
  Anthropic 글 25편, 제작자 발언 13건(Cherny·Wu·Hollman·Shihipar 등),
  공개 repo 6곳, 2차 3건, 이 기계 실측. 격차 표 17행.
- 설계(docs/experts.md): 분야 전문가는 paths를 건 지식 스킬(함정 → 점검표
  → 검증 순서), 서브에이전트는 분야가 아니라 일마다(렌즈를 받는 새 눈
  reviewer 하나 + 있는 실행 검증), 리드는 메인 세션. 공용(플러그인)은
  협업 장치만, 분야 지식은 각 템플릿에.
- 버린 대안: 분야마다 서브에이전트(첫 초안, 템플릿당 9개). Anthropic
  2026-10-22·2026-01-23·2026-04-07 글과 현행 best practices가 분야·역할
  분리를 반대하고, 에이전트 설명은 모든 세션과 서브에이전트마다 다시
  든다. agent teams는 실험 기능이고 팀원에 skills가 실리지 않는다.
- docs/README.md에 이 repo에서 새로 정한 것 셋(12~14)을 더한다.

위험: 소유자 요청("분야별 서브에이전트")과 다르다. 이유를 설계 0절에
밝히고 평가(7절)에서 렌즈 리뷰어가 v1보다 못하면 다시 시험한다.
paths 스킬이 목록에서 빠지는 것은 CLI 바이너리 문자열로만 확인했다.

검증: 문서만. 링크와 출처 번호를 손으로 대조했다.
문제: 여러 분야에 걸친 변경을 리뷰할 때 누구에게 무엇을 맡기고, 결과를
어떻게 합치고, 의견이 부딪치면 누가 정하는지 정한 절차가 없다. 전문가를
더하는 모양과 하네스 판을 비교하는 절차도 없다.

고른 방법:
- lead: 바뀐 경로·위험으로 분야 지식 스킬(렌즈)을 고르고, 고정 칸 brief로
  새 눈 reviewer를 병렬로 띄우고, High는 반증해 살아남은 것만 남기고,
  넘김은 한 번만 더, 충돌은 정한 일곱 순서로, 리뷰-수정은 세 번까지
  (두 번째부터 고친 diff만). 근거: Anthropic 위임 4요소, 공식 code-review의
  반증 필터, Claude Code 팀의 리뷰 라운드 상한.
- new-expert: 전문가 = paths 지식 스킬(함정이 맨 앞). 서브에이전트는 세
  조건(긴 출력, 버려도 되는 병렬, 지시 충돌·자기 리뷰) 중 하나를 보일 때만.
- harness-eval: 정답을 아는 과제를 판마다 돌려 장부 eval 줄로 비교.
  시킬 때만 돈다는 것을 설명에 쓴다.
- 13절 Q9(새 스킬은 모두 모델 호출, 발동 조건을 설명에)를 지킨다.
- 시험: 플러그인 스킬 목록을 고정하고, 설명이 1,024자 안이며
  PROACTIVELY·MUST·CRITICAL·IMPORTANT·<example>이 없는지 본다.
- 버린 대안: 분야 에이전트·범용 리뷰어를 플러그인에 싣기. 플러그인
  에이전트는 harness: 아래 이름이라 템플릿 것과 둘 다 목록에 뜬다.

위험: 세 스킬 설명(약 400~500자)이 모든 세션의 스킬 목록에 더해진다.
스킬 목록이 예산 근처인 기계에서는 덜 쓰는 스킬 설명이 먼저 잘린다.

검증: python3 -m unittest discover -s tests → 10건 통과,
claude plugin validate --strict plugins/harness → 통과.
문제: new-project.sh로 만든 프로젝트에는 분야 전문가를 어디에 적고,
리드가 바뀐 경로로 무엇을 고르고, 넘김과 충돌을 어떻게 남기는지 정한
자리가 없다. lead 스킬은 그 repo의 docs/work/experts.md를 읽는다.

고른 방법: template/docs/work/experts.md(큰 그림 읽는 순서, 명단,
경로 → 렌즈, 넘김 지도, 정해 둔 충돌, 비용 재는 법)를 빈 양식으로 두고,
루트 AGENTS.md 「일하는 방식」에 한 줄, CLAUDE.md에 플러그인 새 스킬과
전문가 모양 한 줄을 더한다. 루트 40줄 상한은 그대로 지킨다.
버린 대안: 빈 .claude/skills·agents 예시 파일. 예시가 그대로 남으면
모든 세션 목록에 들어가는 빈 전문가가 된다.

위험: 양식만이라 채우기 전에는 lead가 경로표 없이 고른다(스킬이
그때는 바뀐 경로와 위험 신호로만 고르게 되어 있다).

검증: python3 -m unittest discover -s tests → 11건 통과
(새 시험: 양식의 여섯 절, AGENTS.md·CLAUDE.md가 가리키는지).
문제: 루트 AGENTS.md 지도와 README 검증 절이 0.2.0의 스킬 셋만 적어,
이 repo를 고치는 세션이 lead·new-expert·harness-eval과 docs/experts.md,
docs/research/를 지도에서 찾지 못한다.

고른 방법: 지도 두 줄과 README 검증 한 줄만 고친다. 설명은 다시 쓰지
않고 정본(docs/experts.md, 각 SKILL.md)을 가리킨다.

위험: 없음에 가깝다. 루트 40줄 상한 시험이 그대로 돈다(29줄).

검증: python3 -m unittest discover -s tests → 11건 통과.
문제: `"|---|---|---|%s" % "---|" * n`에서 %가 *보다 먼저 묶여 구분선
문자열 전체가 n번 되풀이됐다. 마크다운 표가 깨진다. 첫 실제 평가
(harness-v2-eval v1 두 줄)에서 보였다.

고른 방법: 문자열을 더하기로 잇는다. 시험이 구분선을 단언한다.

위험: 없음(출력 모양만).

검증: 새 단언이 고치기 전에 실패하고 고친 뒤 통과. plugins 시험 24건 통과.
문제: 이 대화를 모르는 서브에이전트에게 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 → 통과.
문제: 첫 판 비교(과제 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로
표를 다시 뽑았다.
문제: 착수 때 예측(작업 중 40/55/85분, 호출 100/150/230, 출력
17만/25만/36만)과 견줄 실측 줄이 없다.

고른 방법: ledger.py actual 초안에 커밋과 이유를 채운다. 시간은 p80 안
(63분). 호출·출력은 서브에이전트 16개를 더해 크게 넘었다. 예측 근거가
"서브에이전트는 세션 기록에 안 잡힌다"고 잘못 봤다(usage는 subagents/를
더한다). 메인만 보면 p50 근처다. 결과는 partial(템플릿 적용 전).

위험: 없음(장부 한 줄). 이 줄은 회고 대기로 잡힌다(why가 있다).

검증: ledger.py pending에 이 작업이 회고 대기로 보인다.
donghyeon.kang added 1 commit 2026-11-11 14:11:09 +00:00
문제: 첫 평가(7.1)는 헤드리스 인증이 없어 이 세션의 서브에이전트로 판을
흉내 냈다. 실제 세션의 스킬 목록·paths 발동·도구 제한과 다를 수 있다.
소유자가 노트북 CLI에 로그인해 claude plugin eval을 쓸 수 있게 됐다.

고른 방법:
- 판마다 평가용 플러그인을 만들었다(평가는 대상 플러그인만 싣고 프로젝트
  .claude/·CLAUDE.md를 읽지 않는다). CLAUDE.md·AGENTS.md는
  append_system_prompt로, 작업 폴더는 scaffold로 백엔드 로컬 복제를 깔았다.
  opus-5-5 고정, 판정 sonnet.
- 과제 셋: A 리뷰(결함 6), A2 리뷰(repo 고유 규칙 결함 6), 구현(우선순위
  컬럼·인덱스·설정 키를 repo 규칙대로, 정규식 채점 8개). 판 셋: none(플러그인
  없음), v1, v2. 리뷰는 판마다 2번, 구현은 v1·v2 5번, none 2번.
- 결과: 리뷰는 none도 12/12로 천장. 구현은 v2 37/40(92.5%), v1 30/40(75%),
  none 12/16. 동시 인덱스 규칙은 v2 3/5, v1 0/5. lead는 다분야 리뷰 4번과
  단순 질문 4번 모두 불리지 않았다. 시작 컨텍스트는 샌드박스에서 v2가
  13% 컸다(플러그인 스킬은 paths가 있어도 목록에 든다. 프로젝트 스킬은
  안 든다는 것을 실제 세션으로 따로 확인했다).
- harness-eval 스킬에 실제 세션으로 돌리는 법(판을 플러그인으로, 리뷰보다
  구현 과제, 5번씩, 기록 뽑는 곳)을 더한다. 장부에 eval 줄 24개.
버린 대안: claude -p로 각 복제 폴더에서 돌리기. 사용자 전역 설정·훅·스킬이
섞여 판 차이를 가린다.

위험: 표본이 작다(구현 한쪽 검정 p≈0.08). v2가 be-persistence를 부른 것은
다섯 번 중 둘이라 효과를 그 스킬 하나로 설명하지 못한다. 평가용 판은
지식 스킬을 플러그인으로 실었고 실제 템플릿은 프로젝트 스킬이라 발동
조건이 다르다.

검증: scripts/check.sh 통과. ledger.py compare --task harness-v2-eval-real.
donghyeon.kang force-pushed donghyeon.kang/harness-v2-experts from 69bf158aa8 to 468b26e35e 2026-11-11 14:11:09 +00:00 Compare
donghyeon.kang merged commit 07471c1f10 into main 2026-11-11 14:15:32 +00:00
Sign in to join this conversation.
No Reviewers
No labels
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: donghyeon.kang/claude-harness#3