AI がコードを書くのは速い。ときに速すぎるほど速い。問題は、ドキュメントがその速度についていけないことだ。
八雲では Claude Code を業務基盤の本番運用に投入してから、コードの変更頻度が体感として以前の数倍になった。それ自体は喜ばしいことだが、ある時点から「仕様書に書いてある動作と実際の挙動が違う」「README を読んでも現状のコードと噛み合わない」という状態が散見されるようになった。AI 駆動開発において、ドキュメントの陳腐化は古くて新しい問題だ。
課題：AI が書くコードはドキュメントを置き去りにする
人間がコードを書いていた時代、ドキュメントの更新忘れは「うっかりミス」だった。コミットを書く時間に余裕があれば、自然と README も直す。しかし AI にコードを書かせると、その「余裕の時間」が存在しない。
Claude Code は局所的な問題を解決するのが得意だ。「このスクリプトにバグがある」「この設定ファイルに項目を追加する」といったタスクを渡すと、該当箇所を的確に修正して返してくる。しかしその修正が、ドキュメント体系のどこに影響するかを自発的に考える設計にはなっていない。
具体的にどういうことが起きるか。たとえば config/ 配下に新しい JSON ファイルを追加したとき、その設定の意味と参照関係を書いた仕様書が更新されないまま残る。あるいはスクリプトを追加したとき、スクリプト一覧を管理している specs/scripts.md が古いままになる。個々の変更は小さいが、積み重なると全体像が把握しにくくなる。
人間が書く時代と根本的に違うのは、変更の速度と量だ。AI は一度に多くの変更を加えられる。だからこそ、「変更したら何を更新するか」のルールを明示的に設計しておく必要がある。
アプローチ：CLAUDE.md に「変更 → 更新対象」の対応表を持つ
SSOT（Single Source of Truth）という概念がある。あるデータを一箇所にだけ持ち、他はすべてそこを参照する設計だ。「顧客コードは config/clients.json だけが持つ。Notion も Drive もそこを参照する」というように、二重管理を禁止することで一貫性を保つ。
同じ発想を docs にも適用できる。
「scripts/ にスクリプトを追加したら specs/scripts.md を更新する」「.claude/agents/ にエージェントを追加したら specs/skills.md を更新する」——これらは本来、開発者の暗黙の了解として存在していた。しかし AI に作業を委譲する場合、暗黙の了解は機能しない。ルールを明示的に書き下ろす必要がある。
CLAUDE.md は Claude Code がプロジェクトを読み込む際に最初に参照する設定ファイルだ。ここに「変更内容 → 更新対象」の対応表を置くと、AI はコードを変更するたびにその表を参照し、必要なドキュメント更新を自動で行うようになる。
なぜ CLAUDE.md がこの位置づけに最適か。それは Claude Code の文脈で「コンテキストの起点」だからだ。CLAUDE.md はすべてのタスク開始前に読まれる。他の仕様書（specs/*.md 等）は必要なときだけ読まれる。だからプロジェクト横断のルール——「変更したときに必ずやること」——を置く場所として最も確実性が高い。
実例：弊社内製の業務基盤での運用
弊社では Google Workspace / Notion / GitHub を横断して動くエージェントシステムを内製している。このシステムの CLAUDE.md には、以下のような対応表が存在する。
<!-- synapse/CLAUDE.md より抜粋（一部抽象化） -->
## ドキュメント自動更新ルール
以下の変更を行った場合、対応するドキュメントも同時に更新すること:
| 変更内容 | 更新対象 |
|---|---|
| `scripts/` にスクリプトを追加・変更・削除 | `specs/scripts.md` |
| `config/templates/*.json` にDocsテンプレを追加・変更 | `config/templates/README.md` の一覧表。**必ず `scripts/templates/sync-doc-templates.py` で Drive に反映すること** |
| `.claude/agents/` にエージェントを追加・変更 | `specs/skills.md` |
| `.claude/skills/` にスキルを追加・変更 | `specs/skills.md` |
| `config/launchd/*.plist` の変更（launchd 設定追加・削除・間隔変更） | `specs/skills.md`（スケジュール自動化セクション）と `specs/notion-tasks.md` を更新 |
| `docs/` にファイルを追加・削除 | `docs/README.md`（目次を更新） |各行を読んでいくと、それぞれに「なぜそのルールが必要か」が透けて見える。
scripts/ の変更を specs/scripts.md に反映するのは、システムに何のスクリプトが存在するかを人間とAIの両方が把握するためだ。スクリプト一覧が陳腐化すると、類似機能を重複実装したり、既存スクリプトの存在に気づかず同じ問題を手動で解くという無駄が生じる。
テンプレートの変更に Drive への反映コマンドを紐付けているのは、ローカルの設定ファイルが SSOT であり、Drive 上のテンプレートはその複製だからだ。「ローカルを直したのに Drive が古いまま」という状態を防ぐため、同期コマンドの実行をルールに組み込んでいる。
エージェントとスキルの変更が specs/skills.md に集約されているのは、「どんな自動化が存在するか」の一覧を一箇所にまとめるためだ。エージェントシステムは構成要素が増えるほど全体像が見えにくくなる。スキル定義を変更したときに必ず specs を更新することで、onboarding 時に「この組織はどう動いているか」を一本のドキュメントで把握できる状態を保っている。
運用してわかった効果と落とし穴
対応表を CLAUDE.md に置いて数ヶ月運用した感触として、まず「AI がドキュメント更新を忘れる頻度が体感として下がった」ことが挙げられる。以前は「コードは変わったのに specs が古い」という状態にたびたび気づいていたが、現在は変更とドキュメント更新がまとめて1コミットに収まることが多くなった。
レビュー時の利点も感じる。変更の pull request を見るとき、「対応表で紐付いたドキュメントも更新されているか」をチェックポイントとして使えるようになった。「コードが変わったのに specs は変わっていない」という場合に対応表が参照基準になる。
onboarding の場面でも、新しい作業者（人間・AI 問わず）に「何を変えたら何を更新するか」を説明するコストが下がった実感がある。対応表を見れば、少なくとも主要な変更箇所と連動する docs の関係が把握できる。
一方で落とし穴もある。対応表自体の維持コストだ。プロジェクトが成長するにつれて、新しいディレクトリや設定ファイルが増える。それらを対応表に追加するルールが存在しないと、対応表が不完全なまま運用されることになる。いわば「対応表の更新ルールがない」という再帰的な問題だ。
弊社では今のところ「プロジェクト構造に大きな変更を加えたときは CLAUDE.md も見直す」という緩やかなルールで対処している。対応表を完璧に保つのではなく、「主要な変更箇所を拾えていれば十分」と割り切る姿勢が長続きするコツかもしれない。
まとめ
AI 駆動開発でドキュメントを追従させるには、「変更したら何を更新するか」を暗黙の了解ではなく明示的なルールとして設計する必要がある。SSOT の発想を docs にも拡張し、CLAUDE.md に対応表を持つことは、その第一歩として手軽で効果を感じやすい手段だ。
次の記事では、こうしたルール設計をさらに一歩進めた仕組みとして、Claude Code の pre-tool hook による変更の事前検証を取り上げる予定だ（pre-tool hook で AI の副作用を制御する）。また、AI エージェントをどのように役割分担させてプロジェクトを動かしているかについては 八雲の AI 駆動開発の全体像 にまとめている。