From 9d65a41d820584743cd52e69320f8e12cfffd20b Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sun, 8 Nov 2026 17:25:27 +0900 Subject: [PATCH] =?UTF-8?q?chore(ledger):=20=EC=98=88=EC=B8=A1=C2=B7?= =?UTF-8?q?=EC=8B=A4=EC=B8=A1=20=EC=9E=A5=EB=B6=80=EB=A5=BC=20=EB=91=90?= =?UTF-8?q?=EA=B3=A0=20=EC=9D=B4=20=EC=9E=91=EC=97=85=EC=9D=98=20=EC=B0=A9?= =?UTF-8?q?=EC=88=98=20=EC=98=88=EC=B8=A1=EC=9D=84=20=EB=82=A8=EA=B8=B4?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 작업마다 착수할 때의 예측과 끝날 때의 실측을 남길 곳이 프론트에 없었다. 소유자 결정(2026-11-07 Q11)은 repo마다 docs/ledger/estimates.jsonl이다. docs/ledger/README.md(백엔드와 같은 형식)와 estimates.jsonl을 두고, 여러 브랜치가 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes가 merge=union을 준다. 첫 줄은 이 작업(fe-c-harness)의 착수 예측이다. 위험·한계: 복사한 프로젝트는 템플릿의 줄을 받는다. README 지워도 되는 표에 "줄을 비운다"로 적는다(뒤 커밋). 검증: python3 -m unittest scripts/tests/test_ledger.py 통과. Refs: design-docs harness/01-harness-design.md 10절·13절 Q11 --- .gitattributes | 1 + docs/ledger/README.md | 49 ++++++++++++++++++++++++++++++ docs/ledger/estimates.jsonl | 1 + scripts/tests/test_ledger.py | 59 ++++++++++++++++++++++++++++++++++++ 4 files changed, 110 insertions(+) create mode 100644 .gitattributes create mode 100644 docs/ledger/README.md create mode 100644 docs/ledger/estimates.jsonl create mode 100644 scripts/tests/test_ledger.py diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..e977fa64 --- /dev/null +++ b/.gitattributes @@ -0,0 +1 @@ +docs/ledger/estimates.jsonl merge=union diff --git a/docs/ledger/README.md b/docs/ledger/README.md new file mode 100644 index 00000000..f6e01776 --- /dev/null +++ b/docs/ledger/README.md @@ -0,0 +1,49 @@ +# 예측·실측 장부 + +작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)를 고칠 곳을 찾는 것이 목적이다. 질타가 아니라 측정이다(소유자 결정 2026-11-07). + +```text +착수(첫 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`를 가리킨다. + +## 줄의 칸 + +모든 줄: + +| 칸 | 형식 | 뜻 | +| --- | --- | --- | +| `schema` | 정수 | 이 형식의 판. 지금 1 | +| `kind` | `estimate` · `actual` · `retro` | 줄의 종류 | +| `task` | 문자열 | 작업 이름. 세 종류의 줄을 묶는 키다(예: 세션 이름) | +| `recorded_at` | ISO 8601 | 이 줄을 쓴 시각 | +| `transcript` | 문자열 | Claude Code 세션 기록 파일 이름(`~/.claude/projects//<이 값>.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`(고친 커밋이나 문서). diff --git a/docs/ledger/estimates.jsonl b/docs/ledger/estimates.jsonl new file mode 100644 index 00000000..5a2d1992 --- /dev/null +++ b/docs/ledger/estimates.jsonl @@ -0,0 +1 @@ +{"schema": 1, "kind": "estimate", "task": "fe-c-harness", "recorded_at": "2026-11-08T16:55+09:00", "transcript": "710988b0-b66b-4749-9bee-e0a2de8282e3", "started_at": "2026-11-08T16:47:38+09:00", "base": "ad3a071f", "task_kind": "docs-writing+improve", "size": "large", "minutes": {"p30": 80, "p50": 115, "p80": 170}, "calls": {"p30": 180, "p50": 260, "p80": 380}, "output_tokens": {"p30": 250000, "p50": 350000, "p80": 500000}, "basis": "착수 노트(공유 노트 fe-c-harness.md, 16:55)에 쓴 값을 옮겼다. 선례 h3-backend-harness 작업 중 68분·호출 270·출력 34.6만(손 판단 결정 약 25, desktop 실행 3회). 이번 결정 약 22(훅 언어와 범위, verify.sh 운반부, 템플릿 계약 분류, PR #6 11개를 playbook 6개와 reference로 나누기, 테스트 영향 셋)와 새로 쓰는 문서가 h3보다 많다(약 1,500줄 출력). desktop은 merge 단계 1~2회(한 번 약 25분, 잠금 대기는 시간에서 뺌). h3의 교훈대로 파일 수가 아니라 결정 수와 desktop 실행 횟수로 잡았다"} diff --git a/scripts/tests/test_ledger.py b/scripts/tests/test_ledger.py new file mode 100644 index 00000000..6fe81cf3 --- /dev/null +++ b/scripts/tests/test_ledger.py @@ -0,0 +1,59 @@ +"""docs/ledger/estimates.jsonl의 줄이 docs/ledger/README.md 형식인지 본다. 빈 파일(복사한 프로젝트)도 통과한다. + + python3 -m unittest discover -s scripts/tests +""" + +from __future__ import annotations + +import json +import unittest +from datetime import datetime +from pathlib import Path + +REPO = Path(__file__).resolve().parent.parent.parent +LEDGER = REPO / "docs/ledger/estimates.jsonl" +KINDS = {"estimate", "actual", "retro"} +COMMON = ("schema", "kind", "task", "recorded_at") +RANGES = ("minutes", "calls", "output_tokens") + + +def lines() -> list[dict]: + if not LEDGER.exists(): + return [] + return [json.loads(line) for line in LEDGER.read_text(encoding="utf-8").splitlines() if line.strip()] + + +class LedgerTest(unittest.TestCase): + def test_lines_merge_by_union(self) -> None: + self.assertIn("docs/ledger/estimates.jsonl merge=union", + (REPO / ".gitattributes").read_text(encoding="utf-8").splitlines()) + + def test_every_line_is_json_with_the_common_fields(self) -> None: + for number, entry in enumerate(lines(), start=1): + self.assertTrue(set(COMMON) <= entry.keys(), f"line {number}: {sorted(set(COMMON) - entry.keys())}") + self.assertEqual(entry["schema"], 1, number) + self.assertIn(entry["kind"], KINDS, number) + datetime.fromisoformat(entry["recorded_at"]) + + def test_an_estimate_has_ordered_ranges_and_a_basis(self) -> None: + for entry in (e for e in lines() if e["kind"] == "estimate"): + for field in RANGES: + values = entry[field] + self.assertLessEqual(values["p30"], values["p50"], (entry["task"], field)) + self.assertLessEqual(values["p50"], values["p80"], (entry["task"], field)) + self.assertTrue(entry["basis"].strip(), entry["task"]) + + def test_an_actual_follows_its_estimate_and_names_the_band_it_fell_in(self) -> None: + entries = lines() + for position, entry in enumerate(entries): + if entry["kind"] != "actual": + continue + estimates = [e for e in entries[:position] if e["kind"] == "estimate" and e["task"] == entry["task"]] + self.assertTrue(estimates, f"{entry['task']}: an actual line needs an earlier estimate line") + bands = estimates[-1]["minutes"] + expected = next((band for band in ("p30", "p50", "p80") if entry["active_minutes"] <= bands[band]), "over") + self.assertEqual(entry["within"], expected, entry["task"]) + + +if __name__ == "__main__": + unittest.main()