この記事は、2026年6月時点での自分の考えを整理したものです。
世の中の意見や別の立場を否定したいわけではなく、あくまで今の自分にはこう見えている、という話として書いています。
AIエージェントや開発現場を取り巻く状況は変化が速いので、今後の経験や環境によって、自分の考え方も変わっていくと思っています。
はじめに
最近、AIエージェントを使って開発する中で、ドキュメントの役割が少し変わってきている気がしています。
これまでドキュメントは、どちらかというと「成果物」として見られることが多かったと思います。
設計書を作る。
仕様書を作る。
READMEを書く。
納品物としてまとめる。
引き継ぎ資料として残す。
もちろん、今でもそういう役割はあります。
ただ、AIエージェントが開発に入ってくると、ドキュメントは単に人間が読む成果物ではなくなっていくように見えます。
AIがドキュメントを読む。
AIがその前提でコードを書く。
AIがコードを読んで、またドキュメントを作る。
人間がそれを確認して、また前提を更新する。
こうなると、ドキュメントは一度作って終わりの資料というより、AIと人間が同じ前提で開発を続けるための環境の一部に近づいていくのではないか。
最近は、そんなふうに感じています。
これまでのドキュメントは、人間が読むものだった
これまでの開発では、設計書やドキュメントは基本的に人間が読むものでした。
人間が設計書を書く。
人間が設計書を読む。
人間がコードを書く。
人間がレビューする。
人間が保守する。
もちろん、ツールによる自動生成や、コードからのドキュメント生成は以前からありました。
ただ、それでも多くの場合、ドキュメントの主な読者は人間だったと思います。
顧客に説明するため。
チーム内で認識を合わせるため。
あとから入った人が理解するため。
納品物として残すため。
そういう意味では、ドキュメントは「人間に説明するための資料」という色が強かったと思います。
ただ、この形にはよくある問題もあります。
コードは変わる。
仕様も変わる。
運用も変わる。
でも、ドキュメントは更新されない。
結果として、設計書と実装がずれていく。
これはかなりよくある話だと思います。
古いドキュメントは、人間にとっても困ります。
でも、人間はまだ「この資料、古そうだな」と疑うことができます。
現場の人に聞くこともできます。
コードと照らし合わせて、違和感に気づけることもあります。
AI時代になると、ここに少し別の怖さが出てくる気がしています。
AI時代は、ドキュメントをAIが読む
AIエージェントを使うようになると、ドキュメントの読者にAIが加わります。
READMEを読む。
設計メモを読む。
作業ルールを読む。
制約事項を読む。
テスト手順を読む。
判断履歴を読む。
そして、その前提でコードを書いたり、修正したり、調査したりします。
これはかなり便利です。
毎回プロンプトで全部説明しなくても、ドキュメントに前提が残っていれば、AIはそれを読んで作業できます。
ただし、ここで問題になるのは、AIが読むドキュメントが正しいとは限らないことです。
もし古いREADMEが残っていたら。
もし昔の設計方針がそのまま残っていたら。
もし今は使っていない制約が書かれていたら。
もしすでに変わった仕様が、まだ残っていたら。
AIはそれを前提として読んでしまうかもしれません。
人間なら「これ本当に今も正しいですか？」と確認する場面でも、AIは与えられた情報をかなり自然に使って作業してしまうことがあります。
つまり、古いドキュメントは、単に読みにくい資料ではなくなります。
AIに間違った前提を渡してしまうものになる可能性があります。
ここが、AI時代のドキュメントでかなり怖いところだと思っています。
設計書からコードへ、コードから設計書へ
AI時代のドキュメントで面白いのは、流れが一方通行ではなくなりそうなところです。
これまでは、どちらかというとこういう流れでした。
人間が設計書を書く
↓
人間が設計書を読む
↓
人間がコードを書く
↓
コードが変わる
↓
設計書が古くなる
もちろん、実際には設計書を更新することもあります。
ただ、現場感としては、コードの変化にドキュメントが追いつかないことも多かった気がします。
AI時代は、ここに別の流れが入ってきます。
人間が合意や制約をドキュメントに残す
↓
AIがドキュメントを読む
↓
AIがコードを書く・修正する
↓
AIがコードから設計資料を逆生成する
↓
人間が確認する
↓
ドキュメントを更新する
↓
またAIが読む
つまり、設計書からコードへ進むだけではありません。
コードから設計資料へ戻ることもできます。
そして、そこからまたドキュメントを更新し、次の作業でAIが読む。
設計書からコードへ。コードから設計書へ。そしてまた設計書からコードへ。
こういうサイクルが発生していくのかもしれません。
これはかなり大きな変化だと思っています。
設計書は、実装前に一度作って終わるものではなくなります。
コードも、設計書と切り離された実装結果だけではなくなります。
両方が行き来しながら、開発の前提を作っていく。
そう考えると、ドキュメントは納品物というより、開発環境の一部に見えてきます。
ドキュメントが古いと、AIも古い前提で動く
AIにドキュメントを読ませるなら、そのドキュメントが古いことの影響はかなり大きくなります。
たとえば、ドキュメントにこう書いてあったとします。
- この機能は使われていない
- この画面は将来削除予定
- このAPIは一時的な対応
- このディレクトリには新規機能を追加しない
- このテーブルは参照専用として扱う
もしこれが最新の情報なら、AIにとってかなり良い前提になります。
でも、もし古い情報だったらどうでしょうか。
すでにその機能が使われている。
その画面は削除予定ではなくなった。
一時対応が正式仕様になった。
新規機能を追加しない方針が変わった。
参照専用ではなく更新するようになった。
こういう状態でAIが古いドキュメントを読んでしまうと、かなり危ないです。
AIは、古い前提に沿って自然な修正をしてしまうかもしれません。
しかも、その修正は見た目にはそれっぽいことがあります。
だから、古いドキュメントは「読まれないから問題ない」とは言いにくくなります。
AIが読むようになると、古いドキュメントは実際に作業へ影響してしまう。
ここは、人間だけが読んでいた時代よりも重くなる気がしています。
ドキュメントもコードと同じようにレビューしたくなる
そう考えると、ドキュメントもコードと同じように扱いたくなります。
コードを変更したらレビューします。
テストします。
差分を確認します。
必要なら戻します。
同じように、AIに読ませるドキュメントも、ある程度は更新・レビュー・保守したくなります。
たとえば、コード変更と一緒に、次のようなものを見る必要が出てくるかもしれません。
| 変更したもの | 一緒に見たいもの |
|---|---|
| 新しい機能を追加した | README、画面一覧、操作手順 |
| アーキテクチャを変えた | architecture.md、依存関係の説明 |
| 仕様判断を変えた | decision-log.md、合意メモ |
| 制約が変わった | constraints.md、ai-rules.md |
| テスト方法を変えた | test-guide.md、確認手順 |
| 既知の問題を解消した | known-issues.md |
| 用語や業務ルールを変えた | glossary.md、仕様メモ |
こういう運用が、少しずつ必要になるのかもしれません。
もちろん、全部を毎回きれいに更新するのは大変です。
ただ、AIに読ませる前提として使うなら、放置されたドキュメントは扱いが難しくなります。
人間向けの説明資料なら、多少古くても「参考程度に見てください」と言えます。
でもAIに読ませる場合は、参考程度のつもりでも、AIが前提として使ってしまうことがあります。
だから、AIに読ませるドキュメントには、少なくとも次のような情報が欲しくなります。
- いつ時点の内容か
- どの範囲に有効か
- 何が未確定か
- どこは古い可能性があるか
- どの情報を優先すべきか
これは、人間向けのドキュメントとは少し違う考え方です。
AIにドキュメント更新も手伝ってもらう
とはいえ、ドキュメントを人間だけで完璧に保守するのは大変です。
コードが変わるたびに、設計書もREADMEも判断履歴も全部人間が直す。
これは、現実的にはかなり重いと思います。
そこで、AIにドキュメント更新も手伝ってもらう使い方が増えるのではないかと思っています。
たとえば、
- 今回のコード変更から、READMEに追記すべき内容を出してもらう
- 変更内容をもとに、設計資料の差分案を作ってもらう
- 仕様変更の判断理由を decision-log の形式に整えてもらう
- テスト手順の変更点を整理してもらう
- 古くなっていそうなドキュメントを指摘してもらう
こういう使い方です。
もちろん、AIが出したドキュメント更新案をそのまま信じるのは怖いです。
特に、なぜそう判断したのか、誰と合意したのか、何をスコープ外にしたのかは、人間が確認する必要があります。
ただ、何が変わったのかを整理したり、更新案を作ったりするところは、AIにかなり手伝ってもらえる気がしています。
つまり、ドキュメントをAIに読ませるだけではなく、ドキュメントを更新する作業にもAIが入ってくる。
ここでも、設計書とコードのサイクルが回り始めます。
ドキュメントは、AIと人間が共有する開発環境になる
ここまで考えると、ドキュメントは単なる成果物ではなく、開発環境の一部に見えてきます。
ソースコード。
テスト。
ビルド手順。
Lintや型チェック。
CI。
README。
設計メモ。
制約事項。
判断履歴。
AIに読ませるルール。
これらが組み合わさって、AIと人間が開発する環境を作っていく。
そんなイメージです。
開発環境というと、エディタや実行環境、CI/CD、テスト環境のようなものを想像しがちです。
でもAI時代には、ドキュメントもそこに入ってくるのではないかと思っています。
AIはドキュメントを読んで作業します。
人間もドキュメントを読んで判断します。
コードが変われば、ドキュメントも変わります。
ドキュメントが変われば、AIの作業前提も変わります。
そう考えると、ドキュメントは静的な説明資料ではなく、開発を動かす前提の一部です。
ドキュメントは、AIと人間が同じ前提で作業するための共有コンテキストになる。
今の自分には、そんなふうに見えています。
おわりに
AI時代のドキュメントは、成果物として一度作って終わりではなくなっていく気がしています。
人間が読む。
AIが読む。
AIがコードを書く。
AIがコードから設計資料を逆生成する。
人間が確認する。
ドキュメントを更新する。
またAIが読む。
こういうサイクルが増えていくなら、ドキュメントは納品物というより、開発環境の一部に近づいていきます。
だから、古いドキュメントを放置することの意味も変わります。
人間が少し迷うだけではなく、AIに古い前提を渡してしまうかもしれません。
その一方で、ドキュメントの更新そのものもAIに手伝ってもらえるようになります。
人間が合意や判断の背景を残し、AIがコードや資料の差分を整理する。
そして、人間が確認してまた前提を更新する。
そうやって、ドキュメントを育てながら開発していく。
今後は、そういう形が少しずつ増えていくのかもしれません。
まだ自分も整理中です。
ただ、今の自分には、AI時代のドキュメントは、成果物ではなく開発環境の一部として見えてきています。