문제: 첫 평가(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.
예측·실측 장부
작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스를 고칠 곳(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)을 찾는 것이 목적이다. 질타가 아니라 측정이다.
착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거
끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측
회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계, 개선 id
판정(뒤 작업 2건) ──> verdict 줄: 그 개선이 효과가 있었나, 없으면 되돌림
평가(하네스 판 비교) ──> eval 줄: 같은 과제를 판마다 돌린 실행 하나씩
- 파일은
docs/ledger/estimates.jsonl하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은task로"correction": true줄을 더한다. - 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게
.gitattributes가 이 파일에merge=union을 준다. - p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다.
- 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(손으로 판단할 결정 수, 검증 실행 횟수와 대기)가 있을 때만 쓴다.
- Claude Code에서는 하네스 플러그인의
estimate·retro스킬이 이 파일을 읽고 쓴다(ledger.py precedents·actual·pending·append). 손으로 써도 형식은 같다. - 회고 대기(실측이 p30~p80 밖인데 retro 줄이 없음)나 판정 대기(개선 뒤에 예측한 다른 작업 2건의 실측이 쌓였는데 verdict 줄이 없음)가 있으면, 플러그인이 세션 시작 때 repo마다 하루 한 번 한 줄로 알린다.
줄의 칸
모든 줄:
| 칸 | 형식 | 뜻 |
|---|---|---|
schema |
정수 | 이 형식의 판. 지금 1 |
kind |
estimate · actual · retro · verdict · eval |
줄의 종류 |
task |
문자열 | 작업 이름. 같은 작업의 줄을 묶는 키다(예: 세션 이름) |
recorded_at |
ISO 8601 | 이 줄을 쓴 시각 |
transcript |
문자열 | Claude Code 세션 기록 파일 이름(~/.claude/projects/<폴더>/<이 값>.jsonl). 실측을 다시 셀 때 쓴다 |
estimate:
| 칸 | 형식 | 뜻 |
|---|---|---|
started_at |
ISO 8601 | 세션 첫 기록 시각 |
base |
문자열 | 기준 커밋 |
task_kind, size |
문자열 | 일의 종류, 작음·중간·큼(small·medium·large) |
minutes, calls, output_tokens |
{"p30","p50","p80"} 정수 |
작업 중 시간(분), 모델 호출 수, 출력 토큰 |
basis |
문자열 | 근거: 비교한 선례와 그 실측, 결정 수, 검증 대기 |
actual:
| 칸 | 형식 | 뜻 |
|---|---|---|
minutes, active_minutes |
정수 | 벽시계 시간, 작업 중 시간(세션 기록 사이 빈틈을 5분까지만 더한 시간) |
calls, output_tokens, cache_read_tokens, max_context |
정수 | 세션 기록 assistant 줄의 message.usage. 같은 message.id는 한 번만 센다 |
within |
문자열 | p30·p50·p80·over: 시간 실측이 들어간 가장 작은 예측 |
result, commits |
문자열, 배열 | done·partial·failed, 만든 커밋 |
why |
문자열 | 예측이 틀렸으면 이유 한 줄 |
retro:
| 칸 | 형식 | 뜻 |
|---|---|---|
cause |
문자열 | 지시 모호 · 착수 전 조사 부족 · 아키텍처 경직 · 검증 대기 · 외부 대기 · 범위 변경 · 예측 근거 없음 |
level |
문자열 | 고친 단계: architecture · gate · instructions · user |
note, ref |
문자열 | 무엇을 왜, 고친 커밋이나 문서 |
fix |
문자열 | 개선 id(예: calib-p50). 효과를 판정할 개선이면 붙인다. 같은 id를 다른 retro 줄에 다시 쓰지 않는다 |
applied_at |
ISO 8601 | 개선을 적용한 때. 빼면 이 줄을 쓴 때다. 이 뒤에 예측 줄을 쓴 다른 작업의 실측으로 효과를 본다 |
verdict(개선 하나의 효과 판정):
| 칸 | 형식 | 뜻 |
|---|---|---|
fix |
문자열 | 판정한 개선 id. 장부에 그 id의 retro 줄이 있어야 한다 |
effect |
effective · reverted |
효과 있음(유지), 효과 없음(되돌림) |
evidence |
문자열 | 근거: 개선 뒤 작업들과 같은 원인이 되풀이됐나 |
ref |
문자열 | reverted면 되돌린 커밋 |
task는 판정을 내린 작업 이름이다.
eval(하네스 판 비교의 실행 하나, harness-eval 스킬):
| 칸 | 형식 | 뜻 |
|---|---|---|
task |
문자열 | 평가 이름(예: harness-v2-eval). 같은 평가의 실행을 묶는다 |
arm, case |
문자열 | 판(예: v1·v2), 과제(예: review-seeded-be) |
active_minutes, calls, output_tokens, input_tokens_total |
정수 | actual과 같은 규칙. 서브에이전트 기록을 더한다 |
start_context, max_context |
정수 | 첫 호출의 입력 토큰(시작 비용), 가장 큰 호출의 입력 토큰 |
subagents, subagent_calls, agent_calls, agent_return_chars |
정수 | 서브에이전트 기록 수와 그 호출 수, 메인이 띄운 Agent 호출 수, 서브에이전트가 메인에 돌려준 글자 수(컨텍스트 비용) |
findings, false_findings |
정수 | 정답을 아는 과제에서 찾은 것, 틀린 발견 |
note |
문자열 | 실행 방식(새 세션인가, 서브에이전트로 흉내 냈나), 모델 |
ledger.py compare --task <평가 이름>이 과제·판마다 중앙값과 마지막 판/첫 판 비율을 보인다. precedents·회고 대기는 eval 줄을 세지 않는다.