Files
clean-architecture-backend-…/docs/ledger
DongHyeonka 88d35f7936
pr / done (pull_request) Canceled after 0s
docs(ledger): 흔들린 시험을 장부에 남기고 시간·순서 단언 규칙을 리뷰 기준에 건다
2026-11-12~13 백엔드 runner에서 흔들린 시험은 넷이다. 그런데 기록이 공유
노트와 세션 메시지에 흩어져 있다. 같은 모양(벽시계 상한, 스레드 시작
순서)이 다시 들어와도 리뷰 기준에는 「스레드 없음」 단언만 적혀 있어서
막을 근거가 없다.

- `docs/ledger/flaky-tests.jsonl`: 흔들림 하나가 한 줄이다. 칸과 범주의
  정본은 design-docs `ci/manual.md` 8.5절이다. 첫 네 줄:
  - compose 기동 경쟁(run 100, #13으로 고침)
  - gRPC 서버 deadline(run 221, #34)
  - HTTP client slow drip JDK(run 228, #34)
  - JPA 동시 writer replay 순서(run 260, #39 열림)
  `.gitattributes`에 `merge=union`을 준다. `scripts/tests/test_ledger.py`가
  칸·범주·날짜 형식을 본다.
- review-criteria.md 「타이밍에 기대지 않나」: 벽시계 상한 단언과 스레드
  시작 순서 단언을 더하고, 매뉴얼 8.4절을 가리킨다.
- gates.md 「원래 있던 실패 가리기」: 반복마다 시작 부하를 적게 한다.
  runner 실패면 그 시각에 잠금 아래 돈 desktop 실행도 적는다(runner는
  잠금 밖이다). 흔들림이면 장부에 한 줄을 더하고, 상한을 늘리거나 재시도를
  붙이지 않고 8.4절대로 고친다.

PR #12가 실패했다는 HTTP/2 흔들림은 넣지 않았다. 그 PR의 runner run은
모두 cancelled라 어느 시험인지 특정할 수 없다.

검증: scripts/verify.sh docs(노트북) rc=0. test_ledger의 새 시험이 잘못된
범주를 잡는지 한 줄을 바꿔 실패를 확인하고 되돌렸다.

Refs: design-docs ci/03-time-reduction-plan.md FLAKY-1
2026-11-13 19:46:21 +09:00
..

장부

이 폴더에는 줄을 더하기만 하는 JSON Lines 장부가 둘 있다.

  • estimates.jsonl: 작업의 예측·실측(아래 절).
  • flaky-tests.jsonl: 흔들린 시험. 흔들림 하나가 한 줄이다. 칸(date·test·category·first_run·verdict·quarantined_until·fixed_by)과 범주의 정본은 design-docs ci/manual.md 8.5절이고, 판정·처리 절차는 그 문서 8.3절이다. 고친 PR이 병합되면 그 줄의 fixed_by를 채운다.

두 파일 모두 .gitattributes가 merge=union을 준다. 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않는다.

예측·실측 장부

작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)를 고칠 곳을 찾는 것이 목적이다. 질타가 아니라 측정이다(소유자 결정 2026-11-07).

착수(첫 5분) ──> estimate 줄: p30·p50·p80 예측과 근거
끝 보고 직전 ──> actual 줄: 세션 기록에서 뽑은 실측
회고(주 1회) ──> retro 줄: 틀린 이유와 고칠 단계
  • 파일은 docs/ledger/estimates.jsonl 하나다. 한 줄이 JSON 하나다(JSON Lines). 줄을 고치거나 지우지 않고 더하기만 한다. 고칠 일이 있으면 같은 task로 "correction": true 줄을 더한다.
  • p30·p50·p80은 그 값 안에 끝날 확률이 30%·50%·80%라고 보는 세 값이다. p30이 도전값, p80이 안전값이다.
  • 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(바꿀 파일 수, 검증 대기)가 있을 때만 쓴다.
  • 위임 대조용 장부(design-docs delegation-loop/ledger.jsonl)는 그대로 둔다. 그 줄의 예측·실측 칸은 이 파일의 task를 가리킨다.

줄의 칸

모든 줄:

칸 형식 뜻
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(고친 커밋이나 문서).