흔들린 시험을 적는 곳이 없다. 2026-11-12~13 이틀에 프론트 흔들림이 여섯 건이었다. 재실행으로 통과시킨 것은 세션 노트에만 남았다. 같은 모양(첫 렌더 5초 창, 잠금 순서 가정)이 다시 들어와도 리뷰 기준에 막을 줄이 없다. docs/ledger/flaky-tests.jsonl을 두고 여섯 건을 첫 줄들로 넣는다. 칸은 design-docs ci/manual.md 8.5절이다(date·test·category·first_run·verdict· quarantined_until·fixed_by). 여기에 대응하는 표를 docs/ledger/README.md 「흔들림 기록」에 둔다. 이 파일도 estimates.jsonl처럼 더하기만 하고 .gitattributes merge=union으로 합친다. README 지워도 되는 파일 표와 docs/README.md 지도에 넣었다. testing.md 5절 조사 절차에 6번(기록)을 더했다. 리뷰 기준 2절 「헷갈리는 경우」에 벽시계 상한·시작 순서 단언을 구조적 위험으로 적고, gates.md 3절에서 둘을 가리킨다(ci/manual.md 8.4절). 버린 대안: scripts/verify.sh docs가 이 파일의 칸과 범주까지 검사하게 하는 안. 이번 범위(계획 FLAKY-1) 밖이라 뒤로 미뤘다. 지금은 손으로 맞춘다. 위험·한계: platform-overview.spec.ts:48(WebKit)은 원인 조사 전이다. 범주는 5초 창에서 실패한 꼴만 보고 fixed-time으로 적었다. 검증: scripts/verify.sh docs(노트북) OK, desktop verify:documentation.
4.1 KiB
4.1 KiB
예측·실측 장부
작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)를 고칠 곳을 찾는 것이 목적이다. 질타가 아니라 측정이다(소유자 결정 2026-11-07).
착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거
끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측
회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계
- 파일은
docs/ledger/estimates.jsonl하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은task로"correction": true줄을 더한다. - 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게
.gitattributes가 이 파일에merge=union을 준다. - p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다.
- 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(바꿀 파일 수, 검증 대기)가 있을 때만 쓴다.
- 위임 대조용 장부(design-docs
delegation-loop/ledger.jsonl)는 그대로 둔다. 그 줄의 예측·실측 칸은 이 파일의task를 가리킨다. - 흔들린 시험은
docs/ledger/flaky-tests.jsonl에 따로 쌓는다(아래 「흔들림 기록」).
줄의 칸
모든 줄:
| 칸 | 형식 | 뜻 |
|---|---|---|
schema |
정수 | 이 형식의 판. 지금 1 |
kind |
estimate · actual · retro |
줄의 종류 |
task |
문자열 | 작업 이름. 세 종류의 줄을 묶는 키다(예: 세션 이름) |
recorded_at |
ISO 8601 | 이 줄을 쓴 시각 |
transcript |
문자열 | Claude Code 세션 기록 파일 이름(~/.claude/projects/<cwd>/<이 값>.jsonl). 실측을 다시 셀 때 쓴다 |
estimate:
| 칸 | 형식 | 뜻 |
|---|---|---|
started_at |
ISO 8601 | 세션 첫 기록 시각 |
base |
문자열 | 기준 커밋 |
task_kind, size |
문자열 | docs/work/ playbook 이름, 작음·중간·큼(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 |
문자열, 배열 | 완료·부분·못 함, 만든 커밋 |
why |
문자열 | 예측이 틀렸으면 이유 한 줄 |
retro: cause(지시 모호 · 착수 전 조사 부족 · 아키텍처 경직 · 검증 대기 · 외부 대기 · 범위 변경 · 예측 근거 없음), level(architecture · gate · instructions · user), note, ref(고친 커밋이나 문서).
흔들림 기록
docs/ledger/flaky-tests.jsonl에 흔들린 시험 하나마다 JSON 한 줄을 더한다. 칸과 처리 절차의 정본은 design-docs ci/manual.md 8.3·8.5절이다. 이 파일도 더하기만 하고 merge=union으로 합친다.
| 칸 | 뜻 |
|---|---|
date |
처음 본 날(YYYY-MM-DD) |
test |
spec 파일:줄 또는 시험 파일:줄 |
category |
fixed-time · concurrency-order · resource-io · test-order · external |
first_run |
처음 본 runner run 번호, desktop이면 로그 경로 |
verdict |
판정 결과(예: 「8회 중 1회 실패」, 「재현 안 됨」)와 원인 |
quarantined_until |
격리했으면 기한, 아니면 빈 값 |
fixed_by |
고친 PR(프론트 #47 형식), 아직이면 빈 값 |