この記事は、2026年6月時点での自分の考えを整理したものです。
世の中の意見や別の立場を否定したいわけではなく、あくまで今の自分にはこう見えている、という話として書いています。
AIエージェントや開発現場を取り巻く状況は変化が速いので、今後の経験や環境によって、自分の考え方も変わっていくと思っています。
はじめに
最近、AIエージェントを使って開発する中で、ドキュメントの見え方が少し変わってきました。
以前は、ドキュメントというと、人間に説明するためのものという感覚が強かったです。
プロジェクトの概要を書く。
設計方針を書く。
起動方法を書く。
仕様を書く。
注意点を書く。
もちろん、今でもその役割はあります。
ただ、AIエージェントに作業を任せるようになると、ドキュメントは人間に説明するためだけのものではなくなってきた気がしています。
AIに前提を渡すためのもの。
AIが作業するときに読むコンテキスト。
AIの出力を確認するための手がかり。
そういう役割が、少しずつ増えているように見えます。
AIがコードを読めるなら、ドキュメントはいらなくなるのではなく、むしろ逆かもしれません。
AIに何を読ませるかが、開発の安定感にかなり効いてくる。
最近は、そんなふうに感じています。
AIはコードを読める。でも前提までは勝手に分からない
AIエージェントは、コードをかなり読めます。
ファイル構成を見たり、処理の流れを追ったり、関数やクラスの役割を整理したりできます。
既存コードの調査を頼むと、人間が最初に読むより速く全体像をつかんでくれることもあります。
これはかなり便利です。
ただ、コードを読めることと、プロジェクトの前提を理解していることは少し違います。
コードには、今の実装は残っています。
でも、次のようなことはコードだけでは分かりにくいです。
- なぜこの設計にしたのか
- どこを変更してはいけないのか
- どの仕様は顧客や関係者と合意済みなのか
- どの処理は暫定対応なのか
- どの制約を受け入れているのか
- 何を確認すれば完了なのか
- どこまでが今回の作業範囲なのか
こういう情報がないままAIに作業を任せると、AIはかなり頑張って推測します。
そして、推測したまま、もっともらしい修正をしてしまうことがあります。
それが怖いところです。
AIが悪いというより、こちらが前提を渡せていない。
そういう場面がある気がしています。
ドキュメントは、AIへのコンテキストになる
人間同士の開発でも、前提共有は大事でした。
ただ、人間の場合は、会話の中で補えます。
「ここは触らないでください」
「その仕様は今回は対象外です」
「その処理は過去の経緯で残っています」
「この機能は一見不要に見えますが、運用で使っています」
こういう話を、会議やチャットやレビューで補足できます。
でもAIに作業を任せる場合、その前提がドキュメントとして残っていないと、毎回プロンプトで説明することになります。
それはけっこう大変です。
毎回説明し忘れることもあります。
説明の粒度もぶれます。
前回は伝えたのに、今回は伝えていない、ということも起きます。
だから、AIに読ませる前提として、ドキュメントを残しておきたくなります。
これは、人間に親切な説明資料というより、AIに作業前提を渡すためのコンテキストに近いです。
AIに「このプロジェクトではこう考えてください」と伝えるための土台です。
AIに渡したいドキュメント
AIに渡すドキュメントは、長ければよいというものではないと思っています。
むしろ、AIが作業するときに必要な前提が、どこにあるか分かることの方が大事に見えます。
たとえば、次のようなものです。
| ドキュメント | AIに渡す意味 |
|---|---|
| README | プロジェクトの入口、起動方法、全体像 |
| architecture.md | 構成、責務、主要な依存関係 |
| decision-log.md | なぜそう決めたのか |
| constraints.md | 変更してはいけないこと、制約 |
| test-guide.md | 何をどう確認するか |
| ai-rules.md | AIに守らせたい作業ルール |
| known-issues.md | 既知の問題、暫定対応 |
| glossary.md | 用語、業務固有の意味 |
もちろん、全部をきれいに用意するのは大変です。
最初から完璧なドキュメントセットを作ろうとすると、それ自体が重くなってしまいます。
ただ、AIに任せる作業が増えるほど、
- このプロジェクトでは何を大事にしているのか
- どこは触ってよいのか
- どこは慎重に扱うのか
- 何を確認すればよいのか
- 何を勝手に判断してはいけないのか
を残しておく価値は上がる気がしています。
コンテキストがないと、AIは毎回推測で動く
AIエージェントは、かなり親切に動いてくれます。
こちらが曖昧に依頼しても、それなりに形にしてくれます。
ただ、それは便利である一方で、怖いところでもあります。
前提が足りなくても、AIは止まらずに進んでしまうことがあります。
たとえば、
- 既存仕様を変えてはいけないのに、自然な改善として変えてしまう
- 今回のスコープ外の機能まで直してしまう
- 暫定対応として残していた処理を、不要な処理として削ってしまう
- 業務用語を一般的な意味で解釈してしまう
- テストがない部分を、見た目の自然さだけで判断してしまう
こういうことは起きそうです。
AIは、与えられた情報の中で自然に見える方向へ進みます。
だからこそ、自然に見えるけれど現場としては困る方向に進まないように、前提を渡しておきたくなります。
ドキュメントは、そのためのガードレールにもなると思っています。
ハーネスは、AIの作業結果を確認する仕組み
AIに前提を渡すだけでは、まだ少し足りません。
AIに作業を任せるなら、作業結果を確認する仕組みも欲しくなります。
最近よく「ハーネス」という言葉を見かけます。
自分の理解では、AI開発におけるハーネスは、ざっくり言うと、AIが変更した結果を確認するための仕組みに近いです。
たとえば、次のようなものです。
| ハーネス | 役割 |
|---|---|
| テスト | 期待動作を確認する |
| Lint | コーディングルールを確認する |
| 型チェック | 型の不整合を検出する |
| ビルド | 実行可能な状態か確認する |
| E2Eテスト | ユーザー操作として動くか確認する |
| スクリーンショット比較 | 画面崩れを検出する |
| API疎通確認 | 外部連携が壊れていないか確認する |
| 確認手順 | 人間が最後に見るポイントを揃える |
AIに「実装して」と頼むだけだと、最終的な確認が人間の目に寄りすぎます。
もちろん、人間が見ることは大事です。
ただ、すべてを人間が差分で読んで確認するのは、だんだん大変になっていく気がします。
AIが速く実装できるほど、確認する量も増えます。
だから、
変更したら、このテストを通す
このコマンドでビルドする
この画面を確認する
このAPIを叩く
この観点で差分を説明する
という仕組みが欲しくなります。
これは、AIを信用しないためではなく、AIに安心して任せるための仕組みに近いと思っています。
コンテキストとハーネスはセットで考えたい
AIに任せるときは、コンテキストとハーネスをセットで考えたくなります。
コンテキストは、AIが作業する前提です。
- 何を作るのか
- 何を変えてはいけないのか
- どの制約があるのか
- どの判断履歴があるのか
- どのルールを守るのか
一方で、ハーネスは、AIが作業した後の確認です。
- テストが通るか
- ビルドできるか
- 画面が崩れていないか
- APIが壊れていないか
- 期待した動作になっているか
- 人間が最後に見るべき点はどこか
この2つがあると、AIに任せる作業が少し安定する気がしています。
逆に、コンテキストもハーネスもない状態でAIに任せると、かなりAIの推測に寄ってしまいます。
AIは速く進めてくれます。
でも、どちらに進んでよいかを示す前提と、進んだ結果を確認する仕組みがないと、後から人間が不安になります。
だから、AI時代のドキュメントは、単に読ませるものではなく、AIに任せるための土台になっていくのだと思います。
AIが発達するほど、何を残すかが効いてくる
AIがもっと賢くなれば、ドキュメントはいらなくなる。
そういう見方もあると思います。
たしかに、AIがコードを読める範囲は広がっていくと思います。
コードから構成を整理したり、設計資料を作ったり、影響範囲を推測したりする力も上がっていくはずです。
ただ、それでも、コードに残っていない前提はあります。
- なぜそう決めたのか
- 誰と確認したのか
- 何をスコープ外にしたのか
- どの判断を保留したのか
- どの制約を受け入れたのか
- どこを人間が最後に見るのか
こういう情報は、人間が残さないと消えていきます。
そして、AIが作業する時代には、それが単に人間向けの記録ではなく、AIに渡す前提にもなります。
そう考えると、AIが発達するほど、ドキュメントの価値が下がるというより、何を残すか、どう残すかの重みが増す気がしています。
おわりに
AI時代のドキュメントは、人間に説明するためだけのものではなくなっていく気がしています。
AIに前提を渡すためのコンテキスト。
AIの作業結果を確認するためのハーネス。
人間が最後に判断するための手がかり。
そういう役割が増えていくのだと思います。
もちろん、すべてのプロジェクトで最初から完璧なドキュメントを用意するのは現実的ではありません。
ただ、AIに開発を任せる場面が増えるほど、
- AIに何を読ませるか
- どの前提を残すか
- 何を検証できるようにするか
- どこを人間が確認するか
を考える場面は増えていきそうです。
AIが賢くなるほど、ドキュメントはいらなくなる。
最初はそう見えるかもしれません。
でも今の自分には、少し逆に見えています。
AIが賢くなるほど、AIに渡す前提が効いてくる。
だから、ドキュメントはなくなるというより、人間とAIが同じ前提で開発するためのコンテキストになっていくのかもしれません。
まだ自分も試行錯誤中です。
しばらく、このあたりを考え続けることになりそうです。