문제: 이 대화를 모르는 서브에이전트에게 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 → 통과.
문제: 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가 가리키는지).
문제: 하네스 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개가 모두 시험에 걸렸다.
문제: 예측·실측 장부 줄은 쌓이는데 회고한 줄이 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).
문제: 템플릿 프로젝트를 비대화형(claude -p)으로 열면 .claude/settings.json에
적힌 마켓과 플러그인을 설치하지도 묻지도 않는다(2026-11-08 시험 프로젝트에서
확인). 또 claude plugin install --scope project가 settings.json을 다시 쓰면서
마켓 source의 "ref": "main"을 빼서, 템플릿과 설치 뒤 파일이 달라진다.
고른 방법: 템플릿의 마켓 source에서 ref를 뺀다(기본 브랜치 main과 같은 뜻).
new-project.sh 끝 안내와 README에 그 폴더에서 한 번 돌릴 두 줄
(marketplace add, install --scope project)을 적는다.
버린 대안: new-project.sh가 claude plugin을 직접 부르기. 스크립트가 사용자의
~/.claude/plugins 상태를 바꾸게 된다.
위험: 대화형 앱이 폴더를 믿을 때 설치를 묻는지는 공식 문서 설명이고 직접
보지 않았다(README에 그렇게 적음).
검증: scripts/check.sh 통과. 시험 프로젝트에서 두 줄을 돌린 뒤 claude plugin
list가 harness@claude-harness 0.1.0 project 범위 enabled를 보였고,
settings.json은 ref 한 칸 말고 내용이 같았다.
문제: 새 프로젝트마다 루트 지침, 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에 만든 시험 프로젝트에서 같은 것을 손으로 확인했다.