AI開発支援ツールを使っていると、最初は「できるだけ多くの情報を渡した方がよい」と考えがちです。
プロジェクトの仕様。
過去の修正履歴。
守ってほしいルール。
リリース手順。
サーバー情報。
過去に起きた事故と、その反省。
全部を1つのファイルにまとめておけば、AIは毎回それを読んで、正しく作業してくれるはず。
私も最初はそう考えていました。
実際、WordPress保守管理アプリの開発では、新しいChatや別セッションでも作業を再開できるように、PROJECT.mdにかなり多くの情報を詰め込んでいました。
しかし、ある時点でこのやり方は限界が見えてきました。
ファイルが大きくなりすぎると、AIが重要ルールを守りきれない。
確認必須事項が漏れる。
優先度の高い禁止事項が、長い履歴の中に埋もれる。
その漏れを人間がチェックするタスクが増える。
そして、チェックするためのルールをまたPROJECT.mdに追記する。
この悪循環に入りかけていました。
情報を増やすほど、精度が上がるわけではなかった
AIに渡す情報が少なすぎれば、もちろん精度は落ちます。
プロジェクトの前提が分からなければ、AIは一般論で判断します。
それは危険です。
ただし、情報を増やせば増やすほど精度が上がるかというと、そう単純ではありません。
長い仕様書の中に、P1の絶対ルール、P2の基本ルール、P3の提案レベルのルール、過去の履歴、設計メモ、リリース手順、プロモーション方針が全部入っていると、重要度の差が見えにくくなります。
人間でも、長い資料の中から毎回本当に大事な数項目を拾い続けるのは大変です。
AIも同じです。
むしろAIの場合、文章としては読んでいても、作業中にどの情報を優先すべきかが安定しないことがあります。
「書いてあるのに守られない」という状態は、AIが怠けているというより、情報設計が悪い可能性があります。
大きなPROJECT.mdが、重要ルールを埋もれさせていた
WordPress保守管理アプリの開発では、守るべきルールが多くあります。
たとえば、Macビルド時にarm64で上書きしてはいけない。
新しいcoreモジュールを追加したら、PyInstallerのhidden importにも登録する。
LPを更新するなら日本語版と英語版を同時に更新する。
利用規約は複数ファイルを同時に更新する。
リリースノートをフライング公開しない。
本番配信に関わるversion.jsonは最後にアップロードする。
どれも重要です。
ただ、過去の修正履歴や開発メモが増えるほど、こうしたルールが埋もれていきました。
AIに「PROJECT.mdを読んで」と頼んでも、毎回同じ精度で拾えるとは限りません。
そして、漏れが起きるたびに「このルールも追記しよう」となります。
結果として、PROJECT.mdはさらに長くなり、次回の読み取りはさらに難しくなる悪循環を生んでいました。
毎回読むものと、必要なときだけ読むものを分けた
そこで、PROJECT.mdの構造を見直しました。
方針は単純です。
毎回読むものと、必要なときだけ読むものを分ける。
現在のPROJECT.mdには、常時必要なコア情報だけを残すようにしました。
- AIへのP1、P2、P3ルール
- アプリの概要
- ファイル構成の概要
- 現在のバージョンや状態
- 必要に応じて読むドキュメント索引
一方で、詳細な履歴やリリース手順、設計詳細、プロモーション方針などはdocs配下に分けました。
たとえば、リリース作業をするときだけリリース手順のファイルを読む。
過去の修正経緯を確認するときだけリリースログを読む。
設計判断を確認するときだけ仕様詳細を読む。
このように、PROJECT.mdを「全部入りの百科事典」ではなく、「入口と索引」に寄せました。
カスケード化すると、AIが迷いにくくなる
この分け方をすると、AIに最初に渡す情報が軽くなります。
そして、重要なルールが目立ちます。
作業開始時に必ず読むのは、コアのPROJECT.md。
そこには、絶対に守るべきルールと現在の状態、必要な文書への索引がある。
リリース作業なら、そこからリリース手順を読む。
Qiita記事なら、プロモーション方針を読む。
設計判断なら、仕様詳細を読む。
つまり、情報を段階的に読ませる形です。
これをカスケード化と考えると分かりやすいです。
最初に読むのは小さなコア。
次に、作業内容に応じて必要な詳細へ降りる。
必要がなければ、重い履歴や細かい設計までは読まない。
この構造にすると、AIは最初から情報の海に沈みにくくなります。
人間側のチェック負担も減った
PROJECT.mdを小さくした効果は、AIだけに出たわけではありません。
人間側のチェックもしやすくなりました。
以前は、AIがルールを漏らすたびに、「読んだはずなのになぜ守らないのか」を確認する必要がありました。
そのたびに、該当ルールがどこに書いてあるのかを探す。
本当に書いてあるのかを見る。
ルールの表現が弱いのか、位置が悪いのか、長すぎて埋もれているのかを考える。
これはかなり消耗します。
今は、P1ルールはコア文書の上部にあり、詳細は索引からたどる形です。
漏れがあったときも、原因を見つけやすくなります。
ルールそのものが悪いのか。
索引が足りないのか。
必要な詳細ファイルを読ませる条件が曖昧なのか。
問題を切り分けやすくなりました。
仕様書は、短ければよいわけでもない
ここで誤解したくないのは、仕様書は短ければよい、という話ではないことです。
プロジェクトには、長い履歴や細かな設計メモが必要です。
過去に起きた事故の記録も必要です。
リリース手順のように、細かく書かなければ危険なものもあります。
問題は、全部を毎回読ませることです。
毎回読むべき情報と、必要なときに読むべき情報は違います。
本当に大事なのは、情報量を減らすことではありません。
情報の置き場所と読み方を設計することです。
コアには、常に必要な判断基準を置く。
詳細には、特定作業で必要になる手順や履歴を置く。
索引には、どの作業で何を読むべきかを書く。
この3つが揃うと、AIにも人間にも扱いやすい仕様書になります。
AI時代の仕様書は、検索しやすさより優先順位が大事
仕様書というと、情報が検索できればよいと考えがちです。
もちろん検索しやすさは大事です。
ただ、AIと一緒に使う場合は、検索しやすさだけでは足りません。
優先順位が必要です。
絶対に守ること。
基本的に守ること。
余裕があれば提案すること。
作業内容によって読むこと。
この差が文書の構造として見えていることが重要です。
AIにとっても、人間にとっても、すべてが同じ重さで並んでいる文書は扱いにくいです。
特に、本番作業やリリース作業のように失敗できない場面では、優先順位がないドキュメントは危険です。
AIに読ませる仕様書では、「何が書いてあるか」だけでなく、「何を先に守るべきか」まで設計した方がよいです。
まとめ
AIに毎回読ませる仕様書を小さくしたら、開発精度は上がりました。
正確には、仕様書を短くしたから良くなったのではありません。
毎回読むコア情報と、必要なときだけ読む詳細情報を分けたことで、重要なルールが埋もれにくくなりました。
AIも迷いにくくなり、人間側のチェック負担も減りました。
AI開発支援でルール漏れが増えてきたとき、プロンプトを足す前に、ドキュメント構造を見直す価値があります。
全部を1つのファイルに詰め込むのではなく、入口、優先順位、索引、詳細ファイルに分ける。
それだけで、AIとの作業はかなり安定します。
AIに何を読ませるかは大事です。
でも、それと同じくらい、どの順番で、どの粒度で読ませるかも大事です。
仕様書は、AIに渡す情報の山ではありません。
AIと人間が同じ判断基準で作業するための、情報設計なのだと思います。
