문제: 첫 평가(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.
문제: 착수 때 예측(작업 중 40/55/85분, 호출 100/150/230, 출력
17만/25만/36만)과 견줄 실측 줄이 없다.
고른 방법: ledger.py actual 초안에 커밋과 이유를 채운다. 시간은 p80 안
(63분). 호출·출력은 서브에이전트 16개를 더해 크게 넘었다. 예측 근거가
"서브에이전트는 세션 기록에 안 잡힌다"고 잘못 봤다(usage는 subagents/를
더한다). 메인만 보면 p50 근처다. 결과는 partial(템플릿 적용 전).
위험: 없음(장부 한 줄). 이 줄은 회고 대기로 잡힌다(why가 있다).
검증: ledger.py pending에 이 작업이 회고 대기로 보인다.
문제: 첫 판 비교(과제 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로
표를 다시 뽑았다.
문제: 이 대화를 모르는 서브에이전트에게 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 → 통과.
문제: 소유자는 두 템플릿에 분야별 전문가 서브에이전트·스킬과 리드
역할, 협업 매뉴얼을 넣으라고 했다. 지금 하네스는 장치의 자리만 있고
분야 지식과 분야 사이 협업 규칙이 없다. 무엇을 어떤 장치로 둘지
근거가 필요하다.
고른 방법:
- 조사 기록(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 바이너리 문자열로만 확인했다.
검증: 문서만. 링크와 출처 번호를 손으로 대조했다.
문제: 하네스 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개가 모두 시험에 걸렸다.
문제: design-docs 위임 장부 55줄과 백엔드 템플릿 예측 장부 6줄이
쌓였는데 원인을 나눈 회고가 한 번도 없었다.
고른 방법: retro 스킬의 일곱 원인으로 빗나간 줄마다 원인 하나를
붙였다. 위임 장부에는 시간 예측이 없어서 「질문·위반·재작업·불일치·
소유자 개입 없이 끝난다」를 예측으로 보고, 막힘만 있는 줄은 게이트가
제 일을 한 것이라 뺐다. 결과: 빗나간 42줄 중 지시 모호 34, 예측 근거
없음 4, 착수 전 조사 부족 2, 외부 대기 2. 예측 장부 4건은 모두 p30
아래였고 실측/p50 중앙값은 시간 0.43·호출 0.52·출력 0.53이다.
H11 보고 언어 훅과 매뉴얼 빈틈 수정 1~3차는 장부 숫자로 효과를
판정했다. 다른 repo·설정에서 고칠 후보 일곱 개(C1~C7)를 적었다.
이 repo 장부에는 이 작업의 예측 줄과 h2-harness-repo의 retro 줄
(fix calib-median)을 더했다.
위험: 위임 장부의 원인은 lessons 한 줄을 읽고 붙인 것이라 세션
기록까지 다시 보지 않았다. 백엔드 장부의 retro 줄은 그 repo에 쓰지
않고 문서 7절에 더할 줄로만 두었다(범위 밖).
검증: scripts/check.sh rc=0. ledger.py pending → 회고할 줄 없음,
판정 대기 calib-median 뒤 실측 0건.
문제: 예측·실측 장부 줄은 쌓이는데 회고한 줄이 0이다. 회고는 사람이
「주 1회」를 기억해야 돌고, 고친 뒤 효과가 없으면 되돌린다는 규칙을
적을 칸도 없다. 지난 4작업은 모두 실측이 p30 아래였는데(실측/p50
시간 중앙값 0.43), 매번 이유 한 줄만 바꿔서 치우침이 그대로 남았다.
고른 방법:
- precedents 끝에 보정 줄을 낸다: 실측/p50 중앙값(시간·호출·출력)과
p30 아래·p80 위 건수. --ledger를 여러 번 받아 다른 repo 장부를 더한다.
estimate 스킬에 「중앙값이 0.8 아래나 1.25 위면 세 값에 곱한다」 한 줄.
- pending은 예측 밖(p30~p80 밖이거나 why가 있음)인데 retro 줄이 없는
작업만 보이고, 효과 판정이 없는 개선도 보인다.
- retro 줄에 fix(개선 id)·applied_at, 새 줄 verdict(effective·reverted).
판정은 개선 뒤에 예측 줄을 쓴 다른 작업 2건의 실측이 끝나면 한다.
개선 전에 예측한 작업은 그 개선의 영향을 받지 않아 세지 않는다.
- SessionStart에 ledger.py nudge를 따로 건다. startup일 때만, 같은
repo(worktree를 git common dir로 묶어)에 20시간에 한 번 한 줄.
append가 actual 줄을 쓸 때 예측 밖이면 그 자리에서 한 줄 알린다.
버린 대안: session-start 장부 훅에서 출력(장부 훅 출력 0 규칙을 깬다),
매 세션 넛지(하위 세션마다 같은 줄이 컨텍스트에 쌓인다), 별도
retro 스크립트(이미 있는 ledger.py 명령으로 충분하다).
위험: 넛지는 그 repo의 첫 세션이 하위 세션이어도 나온다. 문구에
「맡은 일이 회고가 아니면 넘긴다」를 넣었다. 다른 repo 장부에 retro
줄이 더해질 때까지 그 repo에서는 하루 한 번 넛지가 나온다.
보정 규칙은 같은 4건으로 잰 값이라 아직 효과를 모른다.
검증: scripts/check.sh rc=0(플러그인 시험 21개 OK, expected failure 1,
템플릿 시험 10개 OK, plugin validate --strict 통과). 새 조건 15개를
하나씩 끈 사본에서 LedgerTest가 15번 모두 실패했다. 백엔드 템플릿
장부에 nudge를 돌리면 「회고 안 한 빗나간 예측 3건」 한 줄이 나왔다
(상태 폴더는 scratchpad).
이 repo를 만든 작업(h2-harness-repo)의 착수 예측(2026-11-07 23:39)과
실측을 장부 첫 두 줄로 둔다. 작업 중 38분·호출 125·출력 19.3만으로
예측 p30(70분·200·25만)보다 작았다. 틀린 이유와 다음에 바꿀 것은 actual
줄의 why 칸에 있다.
검증: ledger.py append가 칸을 검사해 통과했고 precedents가 두 줄을
묶어 보였다.
문제: 새 프로젝트마다 루트 지침, Claude Code 설정, 검증 진입점, 비전·
문제 정의 양식, 장부를 손으로 다시 만든다. 플러그인으로는 루트 문서와
권한 deny를 나눠 줄 수 없다(플러그인 CLAUDE.md·권한은 읽히지 않는다).
고른 방법: 공통 동작은 플러그인, 프로젝트 파일은 template/ 복사로
나눈다(결정 Q15). scripts/new-project.sh가 template/을 빈 폴더에 복사하고
이름·설명·마켓 주소를 바꾼 뒤 git init까지 한다. 커밋은 하지 않는다.
- AGENTS.md 양식(40줄 이하, 결정 Q2)과 CLAUDE.md(@AGENTS.md)
- .claude/settings.json: .env deny, 마켓과 harness 플러그인 켜기.
Agent deny는 넣지 않는다(결정 Q5)
- scripts/verify.sh: 단계(docs·unit·pr·app) 뼈대와 --on <호스트> 운반부.
작업 트리를 패치로 옮겨 기준 커밋의 새 worktree에 적용하고 트리 해시를
맞춘 뒤 잠금 아래에서 돌린다. push하지 않는다(설계 6.1절)
- 빈 양식: docs/vision.md, docs/problem-statement.md, docs/adr/0000-template.md
- docs/ledger/: 빈 장부와 형식 설명, .gitattributes merge=union(결정 Q11)
repo 자신의 AGENTS.md·README·docs/README.md(설계와 다르게 정한 것)와
scripts/check.sh도 같이 둔다.
버린 대안: 템플릿만(공통 훅 수정이 모든 repo 손작업), 플러그인만(루트
문서·deny를 못 준다).
위험: verify.sh의 원격 운반부는 가짜 ssh(같은 기계)로만 시험했다. 실제
desktop에서는 아직 돌리지 않았다. unit·pr·app 단계 본문은 비어 있다
(종료 코드 3).
검증: scripts/check.sh 통과(플러그인 17, 템플릿 10, validate --strict).
템플릿 시험은 이름 바꾸기, 남은 {{…}} 없음, AGENTS.md 40줄 이하,
settings의 플러그인·deny, 빈 폴더가 아니면 멈춤, verify docs, 가짜 ssh로
패치 적용·트리 해시·worktree 정리와 원격 실패(종료 코드 4)를 본다.
scratchpad에 만든 시험 프로젝트에서 같은 것을 손으로 확인했다.