はじめに
みなさんはAIでコーディングする際さまざまなドキュメント,skills,mdを参照させていると思います。特にOpenSpec等を利用した仕様駆動開発ではドキュメントが溜まりサイロ化してしまうことが多いです。私の周りでも長時間放置してしまっていて時間がかかるのでやる気が出ない等の声をよく耳にします。
今回はそういった方々にもドキュメント掃除の大切さを知って掃除を始めて欲しい！！という記事です。
なぜ AI のコンテキストファイルは必ず腐るのかと放置する代償
まずは当たり前のことですがなぜ AI のコンテキストファイルは必ず腐るのかについてです。
仕様駆動開発のドキュメントは、書き手が複数 × 時間で積層される構造を持ってます。
また、大半の人はskills等のドキュメントをAIに書かせているでしょう。（それが悪いというわけではなくむしろ私もそうですが）そうすると端から端まで人間がレビューしていないことが多いため下記のような事象が増加します。
| 増える理由 | 結果 |
|---|---|
| PBI を重ねるたびに「補足ルール」が追記される | 段落が増えて 300 行・500 行・1000 行に! |
| 完了 PBI の言及は消されずに残る（履歴として残しがち） | 「進行中」と書かれたまま完了済の参照が累積（AIが完了しているかわざわざ見に行くのは無駄です。） |
| 似た事故が再発するたびに似た注意書きが各所に追記される | 重複セクションが 3 箇所、5 箇所に分裂 |
| ファイル名・パスをリファクタしてもリンクは追従しない |
[link](old-path.md) の死亡リンクが残る |
| 「2025-XX 直近で」みたいな相対表現が 1 年経って古びる | 古い日付 + 「直近」「最新」の組み合わせが意味反転 |
上記のゴミとなったドキュメントが長期間放置されると。。。
管理されていないドキュメントの増加→AIのハルシネーション→やり直しでトークン数の増加となりコストが増大し成果物の品質が低下することが考えられます。
特に最近のLLMモデルはトークン消費が激しいものが多く定額プランで上限に当たり開発効率が著しく低下することも多いです。
ドキュメントサイロ化を解消する1歩目
冒頭でも出てきましたが、「長時間放置してしまっていて時間がかかるのでやる気が出ない」となる方が多くいるかもしれません。これは人間がドキュメントレビューしなければと重く考えているからだと考えています。
しかしこれもAIに大部分をやらせれば良いのです。すごい当たり前のことですが意外と「人間がドキュメントレビューしなければ」という固定観念に縛られやすいと感じます。
AIがメインでドキュメントを整理することで今まで貯めてきた知見や実装ルール等がうまく動かなくなるのではと思うかもしれませんもちろんその可能性はあります。
しかし仮に失敗したとしても対象としているのは元から破綻していたドキュメントです。そう考えると心理的ハードルは下がるのではないかなと思います。
また、Git管理をしていればすぐに戻せるので誤った書かれ方になっていたとしてもすぐに復旧できます。そこまで恐れることでもないのです。
実行している掃除方法
現在私は検出 → 壁打ち → apply を一気通貫でやる skillsを2週間に1度実行ということを行なっています。このskillsはサイロ化しているため最初こそ半日程度整理に時間を要しましたが、以降は1時間程度で完了しているためかなり手軽に運用できています。
Skillsの動作フロー
1. 走査
/cleanup-context を入力すると、skill は allowlist 内のファイルを列挙して次で説明するR1〜R6 を全件適用し検査する。
2. レポート出力
検出結果はstdout と pending md に同一内容で出力されます。
例
# cleanup-context レポート
- 実行日時: 2026-06-11 16:28 JST
- 走査対象: 約 20 ファイル
- 検出件数: R1=1 / R2=4 / R3=7 / R4=2 (合計 14 件)
## .claude/agents/abc.md
- [ ] .claude/agents/abc.md:L207 [R2] 陳腐化記述 → 「vite dev 不要」へ更新
## def/CLAUDE.md
- [ ] def/CLAUDE.md:L42 [R3] 「計 18 Phase」表現 → JSDoc 一次資料化に書き換え
3. 壁打ちフェーズ（ここが skill の核心）
ここで AI は項目ごとに人間に確認していく。判断は 3 通りのいずれかに必ず収束させます。
- apply 確定: 「R1 死亡リンク 3 件、削除で OK？」→ 人間「OK」→ pending md はそのまま
- 方針変更: 「R2 で XLINKRE-XXX を進行形と判定したけど、これ履歴として残したい？」→ 人間「残す形に書き換えて」→ pending md を Edit で更新
- 見送り: 「R4 で CLAUDE.md 529 行検出したけど、これ集約 by design？」→ 人間「集約意図」→ pending md から削除
4. 最終承認 + apply
壁打ちが終わったら最終承認を AskUserQuestion で取ります。
壁打ち完了。確定した修正は N 件（R1=a / R2=b / ...）。この内容で apply してよい？
- OK → Edit を順次実行
- NG（壁打ちに戻る） → やり直し
- NG（中断） → skill 終了。pending md は残置
＊フローはOpenSpecのフローをベースにしています。
Skillsの検出観点
| ID | 検出内容 | 例 |
|---|---|---|
| R1 | 死亡リンク |
[guide](docs/old-guide.md) の参照先が test -f で fail |
| R2 | 完了済 PBI への現在進行形参照 | 完了 PBI 番号 + 同段落の「進行中」「対応中」 |
| R3 | スナップショット禁止句 | 「計 18 Phase」「Item 1〜8」みたいな更新が要る数値表現 |
| R4 | 行数肥大化 |
wc -l で 300 行超 |
| R5 | 重複セクション | 同じ見出しが複数ファイル、本文類似度 80% 超 |
| R6 | 古い日付 + 現在進行形 | 6 か月以上前の日付 + 「直近」「最新」 |
最後に
AIのドキュメントの掃除は人間が全部読んでレビューする前提だと億劫ですが、検出と整理の下書きをAIに任せ、人間は壁打ちと最終承認だけするという分担にすれば、2週間に1度1時間で回せます。
特に仕様駆動開発をしていてskillsやmdが増えてきた方は、最初の1回だけ気合いを入れて掃除し、以降は定期実行に乗せるのがおすすめです。最初の1回さえ越えれば、あとは差分掃除なので軽くなります。
またその最初の１回もAIを使えるので想像しているよりずっと少ない工数で終えられます。
「この記事がドキュメントが腐っているのは分かっているけど、手をつけられていない」という方の重い腰を上げるきっかけになれば嬉しいです。
補足:細かいフロー図
