docs(ledger): 작업마다 예측과 실측을 쌓는 repo 장부를 둔다
작업 시간을 예측해도 실제와 비교해 기록하는 곳이 없어서, 틀린 예측에서 하네스를 고칠 단서를 얻지 못한다. 소유자가 2026-11-07에 자료의 방식대로 repo마다 docs/ledger/estimates.jsonl을 두기로 정했다(design-docs harness/01-harness-design.md 10절, 13절 Q11). - docs/ledger/README.md: 줄 셋(estimate·actual·retro)과 칸, p30·p50·p80의 뜻, 시간 기준은 작업 중 시간이라는 것, 더하기만 한다는 것. - 첫 줄은 이 작업의 착수 예측이다(21:46, 공유 노트 착수 보고와 같은 값). 실측 줄은 끝 보고 직전에 더한다. - 여러 브랜치가 파일 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes에 merge=union을 줬다(설계가 걱정한 병합 충돌). - docs/work/README.md 6절(보고)과 delegate.md 4.1절에 착수 보고와 장부를 더했고, docs/README.md 지도에 ledger/ 행을 더했다. - scripts/tests/test_ledger.py: 줄마다 공통 칸, 예측의 p30 ≤ p50 ≤ p80과 근거, 실측이 앞선 예측을 가지며 들어간 구간이 맞는지 본다. 버린 대안: design-docs 위임 장부를 schema 2로 넓히기(설계 권함, 소유자가 repo 장부로 정함). 위임 장부는 대조용으로 그대로 두고 task로 이 줄을 가리킨다. 위험: Gitea 서버 쪽 병합이 .gitattributes의 merge=union을 쓰는지는 확인하지 못했다. 충돌이 나면 두 쪽 줄을 다 남기면 된다. 검증: unittest, check-docs(지도 검사 포함), check-work-docs, check-repo-layout rc=0. git check-attr로 merge: union을 확인했다.
This commit is contained in:
@@ -7,6 +7,7 @@
|
||||
*.yml text eol=lf
|
||||
*.yaml text eol=lf
|
||||
*.json text eol=lf
|
||||
*.jsonl text eol=lf
|
||||
*.md text eol=lf
|
||||
gradlew text eol=lf
|
||||
gradlew.bat text eol=crlf
|
||||
@@ -20,3 +21,6 @@ gradlew.bat text eol=crlf
|
||||
*.jar binary
|
||||
*.zip binary
|
||||
*.gz binary
|
||||
|
||||
# Ledger lines are only appended; a union merge keeps both branches' new lines (docs/ledger/README.md).
|
||||
docs/ledger/estimates.jsonl merge=union
|
||||
|
||||
@@ -21,6 +21,7 @@
|
||||
| --- | --- |
|
||||
| `work/` | 작업 매뉴얼: 이 repo에서 하는 일(새 기능, 개선, 조사·설계, 문서 작성, 운영, 일 나누기)의 절차서. 루트 `AGENTS.md` 다음에 읽는다 |
|
||||
| `manual/` | 개발 매뉴얼: 새 기능을 만드는 순서와 판단 지점, 생성 명령(`scripts/new-feature.sh`). 입구는 `work/new-feature.md` |
|
||||
| `ledger/` | 예측·실측 장부: 작업마다 착수 예측(p30·p50·p80과 근거)과 끝 실측을 한 줄씩 쌓는다(`ledger/estimates.jsonl`, 형식은 `ledger/README.md`) |
|
||||
| `testing/` | 테스트 전략: 테스트 종류 다섯, source set, 어떤 테스트를 어디에 두나, Gradle 실행 계층 |
|
||||
|
||||
### 계약과 스냅숏
|
||||
|
||||
@@ -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/<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`(고친 커밋이나 문서).
|
||||
@@ -0,0 +1 @@
|
||||
{"schema": 1, "kind": "estimate", "task": "h3-backend-harness", "recorded_at": "2026-11-07T21:46+09:00", "transcript": "d5a4c736-f1d6-45ab-acbe-8857526585b9", "started_at": "2026-11-07T21:37:50+09:00", "base": "b3f63be6", "task_kind": "docs-writing+improve", "size": "large", "minutes": {"p30": 150, "p50": 210, "p80": 300}, "calls": {"p30": 450, "p50": 600, "p80": 850}, "output_tokens": {"p30": 450000, "p50": 600000, "p80": 850000}, "basis": "선례 h1-harness-design 작업 중 23분·호출 100·출력 13.6만(바꾼 파일 3, Gradle 없음)에서 분당 호출 4.3, 호출당 출력 1,400. 이번에 바꿀 파일 약 120(하위 문서 이동 28, 새 CLAUDE.md 32, 문서의 AGENTS.md 참조 93줄, 검사기 2, 훅 6, 시험 3, Java 테스트 3, 에이전트·스킬·규칙 8), 매뉴얼 항목 약 60(선례 manual-gap-fix-2가 52건을 한 세션에), desktop 대기 30~50분"}
|
||||
@@ -17,3 +17,4 @@
|
||||
| 4 | `.claude/settings.json`에 repo 훅을 걸었다(본체 `scripts/hooks/hooks.py`, 설명 `scripts/hooks/README.md`): 편집 직후 Java 한 파일 포맷과 레이어 의존 알림, 문서 검사 알림, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단. 실제 `.env`·`.env.local`·`.env.lane` 읽기·쓰기를 권한으로 막는다 | 서비스가 `.claude/settings.json`을 고쳤다면 두 쪽을 합친다. 훅은 `src/config/architecture/modules.json`, `src/gradle/libs.versions.toml`의 `googleJavaFormat`, `applied-migrations.sha256`을 읽으므로 그 경로를 옮긴 서비스는 `hooks.py` 머리의 상수를 맞춘다. 훅이 맞지 않으면 그 항목을 지운다 |
|
||||
| 5 | Agent 도구 금지를 풀었다(`.claude/settings.json`의 `"Agent"` deny 삭제). 결과만 받는 일은 서브에이전트(`.claude/agents/`의 `arch-reviewer`·`verify-api`·`code-simplifier`)에 맡기고, 파일을 바꾸는 위임은 하위 세션에 맡긴다(`docs/work/delegate.md` 4.3절). `.gitignore`에 `!.claude/agents/`를 더했다 | 서비스가 Agent 도구를 계속 막으려면 자기 `.claude/settings.json`에 `"Agent"` deny를 남긴다. `verify-api`는 소유자 환경(desktop, 공유 잠금)을 가정하므로 서비스 환경에 맞게 고치거나 지운다 |
|
||||
| 6 | repo 스킬 둘을 더했다: `.claude/skills/new-feature`(새 기능 실행 순서), `.claude/skills/desktop-gates`(Gradle·Docker를 desktop에서 돌리는 순서). 모델이 설명의 발동 조건을 보고 부른다. 설치된 스킬이 없던 `skills-lock.json`을 지웠다. `.gitignore`에 `!.claude/skills/`를 더했다 | `desktop-gates`는 소유자 환경을 가정하므로 서비스 환경에 맞게 고치거나 지운다. 서비스가 `skills-lock.json`을 썼다면 merge에서 삭제 충돌이 난다. 쓰면 남긴다 |
|
||||
| 7 | 예측·실측 장부 `docs/ledger/estimates.jsonl`(형식 `docs/ledger/README.md`)을 두었다. `.gitattributes`가 이 파일에 `merge=union`을 준다 | 서비스는 템플릿의 줄을 지우고 자기 작업의 줄부터 쌓는다. 템플릿 줄은 템플릿 작업의 기록이다 |
|
||||
|
||||
@@ -58,6 +58,7 @@
|
||||
- 그다음 변경, 확인(명령 · 실행 위치 · rc · 로그 경로), 범위 밖에서 본 것(위치와 내용, 고치지 않음), 남은 문제를 쓴다. 남은 문제를 숨기지 않는다.
|
||||
- 보고는 쉬운 한국어로 쓴다. 코드·명령·로그 인용만 원문 그대로 둔다.
|
||||
- 숫자(테스트 수, 실패 수, 태스크 이름)는 로그에서 옮긴다. 기억으로 쓰지 않는다. 테스트 수는 성공한 Gradle 로그에 없으니 결과 XML 사본에서 센다([reference/gates.md](reference/gates.md) 4절).
|
||||
- 착수할 때 예측(p30·p50·p80과 근거)을, 끝 보고 직전에 실측을 `docs/ledger/estimates.jsonl`에 한 줄씩 더한다(형식 `docs/ledger/README.md`).
|
||||
- 사고 순서 흔적 칸을 둔다(`conventions/work-thinking-order.md` 3절). 다른 세션이 맡긴 일이면 design-docs `conventions/delegation-loop.md` 5절 양식을 쓴다.
|
||||
|
||||
## 7. 필요할 때만 읽는 문서
|
||||
|
||||
@@ -30,6 +30,8 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기
|
||||
|
||||
이 repo에서 더할 것:
|
||||
|
||||
- 착수 보고(이해한 것, 모호한 점과 고른 가정, 예측)는 하위 세션이 공유 노트에 쓰고 기다리지 않는다. 예측과 실측은 그 세션이 `docs/ledger/estimates.jsonl`에 한 줄씩 더한다. 위임 장부 줄은 그 `task`를 가리킨다.
|
||||
|
||||
- brief의 「작업 종류」는 이 repo의 `docs/work/<종류>.md`다. 「이미 아는 것」에는 [reference/decisions.md](reference/decisions.md)의 결정을 **내용으로** 옮긴다. 검증 명령은 [reference/gates.md](reference/gates.md)와 빌드 파일에서 실제 태스크 이름을 확인해 쓴다.
|
||||
- 검증 칸에는 실행 위치와 증거 위치를 쓴다: desktop worktree, `flock /tmp/claude-gates/heavy.lock`, 로그 `~/<작업 이름>-logs/`([operate.md](operate.md) 4.1절). 7절에는 커밋 허용과 자기 브랜치 push 허용을 따로 쓴다.
|
||||
- 수정 묶음 brief에는 보고의 「새로 가정하는 것」 칸을 요구한다. 확인 리뷰 brief에는 그 칸과 「정한 기본값」부터 보라고 적고, 지난 라운드에서 열린 채 넘어온 「Declined to judge」와 README 남은 항목을 다시 판정시킬지도 적는다.
|
||||
|
||||
@@ -0,0 +1,53 @@
|
||||
"""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]:
|
||||
return [json.loads(line) for line in LEDGER.read_text(encoding="utf-8").splitlines() if line.strip()]
|
||||
|
||||
|
||||
class LedgerTest(unittest.TestCase):
|
||||
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()
|
||||
Reference in New Issue
Block a user