| name | doc-sync |
| description | L# の slice を開始・完了するときに、ISSUES.md / TODO.md / docs/adr / 運用記録のどれを更新すべきかを判定し、正本を同期する。実装の前 (doc-RED) と後 (doc-GREEN) の両方で使う。 |
doc-sync — 正本ドキュメントの同期
このリポジトリの正本は 4 つあり、役割が重ならないよう分けられている。混ぜると二重管理になる。
| 正本 | 持つもの | 持たないもの |
|---|
ISSUES.md | 何が問題か・根拠・状態 | チェックボックス、やること |
TODO.md | 未完了タスクだけ | [x]、完了項目、日付ログ、test 名、hash |
docs/adr/decisions-*.md | 判断と却下理由 | 進捗 |
docs/development/operations/ | 実測値と運用手順 | 判断 |
ISSUE.md (単数形) は作らない。参照方向は ISSUES → TODO / ADR / 設計ドキュメントの一方向。
実装前 (doc-RED)
- この変更は判断を含むか判定する。含まないなら (typo / rustfmt / test split / 挙動不変の
リファクタ) 何も書かずに進んでよい。
- 新しく認識した問題があるか。 あれば
ISSUES.md に採番して追加する。
- 採番:
grep -nE '^### (D|I|DOC)-[0-9]+' ISSUES.md | tail で最大番号を確認し次番号。欠番は再利用しない
- サマリー表の行と本文エントリの両方を足す。
<a id="i-10"></a> のアンカーも忘れない
- 状態は
open / in-design / deferred / documented-limitation / resolved から選ぶ
- これからやることを
TODO.md に置く。 [ ] で始める。
受入条件と「この項目に含めない範囲」を書く。範囲を書かないと後で一括完了扱いされる。
- 設計判断をしたなら ADR を先に書く。 却下した選択肢とその理由を必ず含める。
ファイル名は
docs/adr/decisions-<topic>.md。Status / Date / Scope / Related のヘッダを付ける。
Evidence 節は空でよい (実装後に埋める)。
実装後 (doc-GREEN)
-
ADR の Evidence 節に実測値・test 名・受入判定を埋める。
-
受入条件を満たせなかったなら、その事実を書く。 数字を静かに直さない。条件を後から緩めない。
「文言どおりには満たしていないが意図は満たしている」と判断したなら、その判断と根拠を書く。
-
計測をしたなら docs/development/operations/ の該当ファイルへ、取得条件つきで記録する。
-
完了した TODO 項目は削除する — ADR / 運用記録へ移してから。[x] は付けない。
partial parity / Rust-only / external boundary / 未検証 ABI は [~] のまま残す。
数十行を超える削除では、削除前に必ず救出走査をかける。 TODO.md の進捗ログには
原因の特定と却下した案が埋まっており、これを移送せずに消すと git log -S でしか
到達できなくなる (DOC-09 の実例: 0bd8bd47 が 1,364 行を削除し ADR を 1 件も作らなかった)。
git diff -U0 -- TODO.md | awk '/^--- a\//{h=1;next} /^\+\+\+ b\//{next} /^-/ && h {print substr($0,2)}' \
| grep -nE '原因|判明|症状|真因|突き止|に絞|絞られ|化ける|却下|見送|不採用|断念'
1 行でも出たら、その主題の ADR を先に作ってから削除する。移送しないと決めた行は
その理由を ADR の「移送しなかったもの」節に書く (進捗ログ本文 / commit hash 列 /
artifact パスは移送しなくてよい)。
-
日常の作業手順が変わった (新しいスクリプトを足した等) なら AGENTS.md に追記する。
-
新しいドキュメントを作ったら、既存ドキュメントから参照を張る。孤立したファイルは無いのと同じ。
最終チェック
git status --porcelain -- ISSUES.md TODO.md AGENTS.md docs
grep -n '\[x\]' TODO.md
bash scripts/audit_docs.sh
git diff --check
ISSUES.md に新しい ID を足したなら、サマリー表とアンカーが本文と一致しているかを目視する。
落とし穴
TODO.md は 2,800 行あり、v0.3 milestone 節が 2 箇所ある (ISSUES.md の DOC-08)。
項目を足す前に既存項目を検索し、二重計上しない。- 「今回の作業のスコープ外だが気づいたこと」は捨てずに
ISSUES.md へ入れる。
これを捨てるのが台帳未記載の既知問題を生む主因である。
- 一つの slice が閉じた範囲を越えて完了を宣言しない。focused test の GREEN、summary、
stale artifact、Rust host fallback の成功だけでは完了としない。
