なぜ「コード変更 → ドキュメント変更」を強制するのか

このページは英語版 why-code-change-doc-change.md の要約日本語訳です。

短い答え

ドキュメントの腐敗（doc rot）は時間ではなく PR 単位で起きる。1 つの PR でコードだけを変えてドキュメントを置き去りにすると、その瞬間からドキュメントは嘘になります。規律の境界線を「PR」に引くことで、ドキュメントの寿命をコードの寿命と一致させます。

長い答え

「あとで書く」は書かれない

これは古典的な観察です。「あとで書く」というのは、ほぼ確実に 書かない という意味です：

PR がマージされた瞬間、コードを書いた人の頭から「何を書こうとしていたか」が消える
1 週間後、別のタスクが優先される
1 か月後、当時のコンテキストを完全に思い出せる人はいなくなる
半年後、誰かが「このコードはなぜこうなっている？」と聞き、誰も答えられない

「コード変更 → ドキュメント変更」を 同じ PR で強制すると、この崩壊シーケンスをそもそも開始させません。

レビュアの認知負荷も下がる

PR レビューで「このコードはなぜこうなっているのか？」を考える時間が短くなります。コードと一緒に：

docs/architecture/05-runtime-view/<module>.md の更新
docs/arc42/09-decisions/NNNN-<title>.md の新規 ADR
docs/user-manual/how-to/<task>.md の新規 How-to

が同じ PR にあれば、レビュアは「なぜ」と「何」と「使い方」を 1 セットで読めます。

AI エージェントが規律を持つ唯一の方法

人間のレビュアは「ドキュメントが足りてない」と感じても、PR を通すことはできます。 AI エージェント（特に自律性が高い場合）には、この 規律の境界線が明示されていないと ドキュメントを書かない / 既存ドキュメントを更新しない、という挙動になります。

pentaglyph の WORKFLOW.md には次のような規律が書かれています：

## Spec-drift audit (DoD 必須、PR を出す前に必ず実行)

実行タイミング: feature/bugfix ブランチの最終 commit を作る直前。
git push する前。

手順 (5–10 分):
1. このブランチが触ったファイルの inventory: git diff --stat origin/develop...HEAD
2. backend/ または frontend/ のソース変更があれば、
   対応する docs/detailed-design/<module>.md を read して drift を確認
3. drift があれば、同じ PR で更新する

これがあることで、エージェントは「PR を出す前にやること」として明示的にドキュメント更新を組み込みます。

例外

すべてのコード変更にドキュメント更新が必要、というわけではありません：

typo 修正・コメント整形のみ → ドキュメント不要
既存ファイル内の 5 行未満のローカル変更 → ドキュメント不要
名前変更だけ（挙動変化なし） → API 変更を伴う場合のみドキュメント更新

それ以外は必ず同じ PR でドキュメントを更新する、というのが pentaglyph の規律です。

なぜ「コミット単位」ではなく「PR 単位」なのか

コミット単位だと粒度が細かすぎて、開発中の試行錯誤をドキュメント化する羽目になります（しかも翌コミットで変えるかもしれない）。PR 単位は「外部に対して『これが新しい正しい状態です』と宣言する境界線」なので、ドキュメントの更新粒度として最適です。

詳細・反論への応答・運用上の trade-off は英語版を参照してください。