템플릿에서 옮긴 메시징 이력 위에 새 repo의 작업 환경을 먼저 깐다.
claude-harness main 72078ca의 scripts/new-project.sh가 만든 파일을
그대로 복사했다: AGENTS.md·CLAUDE.md 양식, .claude/settings.json
(.env deny, 하네스 플러그인 harness@claude-harness 켜기),
scripts/verify.sh 뼈대, docs/vision.md·problem-statement.md·
adr/0000-template.md 양식, docs/ledger/ 빈 장부, .gitattributes,
.gitignore.
채울 자리(「(채울 것」)는 뒤 커밋에서 이 repo의 내용으로 채운다.
이 커밋 자체는 아직 빌드되지 않는다(Gradle 루트가 없다).
검증: new-project.sh 종료 코드 0, 남은 {{…}} 없음.
Refs: design-docs repo-structure/05-library-repos.md 14.2절
50 lines
3.2 KiB
Markdown
50 lines
3.2 KiB
Markdown
# 예측·실측 장부
|
|
|
|
작업마다 착수할 때의 예측과 끝날 때의 실측을 한 줄씩 쌓는다. 틀린 예측에서 하네스를 고칠 곳(아키텍처 → 게이트 → 지침 → 사용자 행동 순서)을 찾는 것이 목적이다. 질타가 아니라 측정이다.
|
|
|
|
```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이 안전값이다.
|
|
- 시간의 기준은 작업 중 시간이다. 끝 보고 뒤 다음 지시를 기다린 시간은 넣지 않는다. 배수는 근거(손으로 판단할 결정 수, 검증 실행 횟수와 대기)가 있을 때만 쓴다.
|
|
- Claude Code에서는 하네스 플러그인의 `estimate`·`retro` 스킬이 이 파일을 읽고 쓴다(`ledger.py precedents`·`actual`·`append`). 손으로 써도 형식은 같다.
|
|
|
|
## 줄의 칸
|
|
|
|
모든 줄:
|
|
|
|
| 칸 | 형식 | 뜻 |
|
|
| --- | --- | --- |
|
|
| `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` | 문자열 | 일의 종류, 작음·중간·큼(`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` | 문자열, 배열 | `done`·`partial`·`failed`, 만든 커밋 |
|
|
| `why` | 문자열 | 예측이 틀렸으면 이유 한 줄 |
|
|
|
|
`retro`: `cause`(지시 모호 · 착수 전 조사 부족 · 아키텍처 경직 · 검증 대기 · 외부 대기 · 범위 변경 · 예측 근거 없음), `level`(`architecture` · `gate` · `instructions` · `user`), `note`, `ref`(고친 커밋이나 문서).
|