Files
clean-architecture-backend-…/docs/ledger
DongHyeonka 5f0bf17bd2
pr / done (pull_request) Successful in 13m24s
docs(ledger): PR 단계 Jetty attempt deadline 시험의 흔들림을 더한다
desktop에서 main c7a18ec7의 prCheck를 돌렸을 때(시작 부하 11~15)
JettyAttemptDeadlineTest#aSlowDripExchangeIsAbortedAtTheAttemptDeadline이
1.68초로, 상한 1.5초를 넘어 실패했다. #34가 고친 벽시계 시험 범위 밖에 남은
것이다. 고치는 일은 벽시계 시험을 맡은 쪽에 넘겼다.

검증: python3 -m unittest scripts/tests/test_ledger.py 통과.
2026-11-13 20:42: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(고친 커밋이나 문서).