この記事は every Tech Blog Advent Calendar 2025 の 17 日目の記事です。
目次
はじめに
こんにちは。 開発本部開発1部トモニテ開発部所属の庄司(@ktanonymous)です。
本記事では、AI駆動開発を意識したドキュメント運用について、
どのような選択肢があるのか、社内での運用例、自チームでの運用方針などの側面から考えてみたことを簡単にまとめていきたいと思います。
なお、本記事の内容は「正解」ではないので、「それは違うのでは？」「もっと〇〇した方が良いよ」といったご指摘などがありましたら、
ぜひぜひ X(旧Twitter) などで取り上げていただけますと幸いです。
※ 本記事で触れないこと
- プロトコルや各種手法の原理
- マルチエージェント
- モデルやツールの比較
最近のAIの動向に関する所感
最近は、AI技術の発展により開発フローにとどまらずドキュメントの作成や運用のあり方も大きく変わってきていると感じています。
少し前までは、ドキュメントの作成・運用とその他の作業はほとんど独立していました。
「必要に応じてドキュメントを作成し、それを参照しながら開発する」という基本的な流れは、
LLMが登場してからもそれほど大きくは変化していなかったように思います。
精度向上に伴いAIを活用するシーンこそ増えていましたが、チャットベースでその都度コンテキストを与えながら、
局所的にサポートしてもらう形が主だったんじゃないかなという印象があります。
しかし、ここ1年くらいでMCP(Model Context Protocol)を筆頭にLLMの機能が目まぐるしい勢いで拡張され、
LLMの機能のツール化やLLM自体のツール化、LLM同士の協調などが可能になってきました。
エディタでのローカル開発ひとつ取っても、コードベースや要件がまとめられたドキュメントへのリンクなどの最低限のコンテキストだけを与えて依頼すれば、
「必要な情報を調べる -> 実装計画を提案する -> 計画に沿って実装する -> 実装結果をまとめる・レビューする」といった一連のフローを自律的に行わせることが可能になっています。
「AI駆動開発(AI-Driven Development)」という言葉も浸透してきているほどAIが担う役割が増えてきており、多くのAIサービスベンダーが「コンテキストエンジニアリング」を重要視しているように、
AIに与えるコンテキストの重要性も増してきています。
AIに与えたコンテキストからより正確な出力を得るうえで、内部の人間しか知り得ないプロジェクトに関する知識を含めることが重要になります。
そういった情報は何かしらのツールを用いて社内ドキュメントとしてまとめられていることが多いかと思います。
それらを踏まえて、何をドキュメンテーションするのか、どこにドキュメントを保存するのか、どのようにドキュメントを更新していくのか、
どのようにドキュメントを利用していくのか、といった観点が重要で難しい問題になるのかなと感じています。
AI駆動開発を意識したドキュメント運用の観点
前述の通り、AIとの共同作業においてはAIに与えるコンテキストが出力結果に大きく影響します。 今回は、AI駆動開発を意識したドキュメント運用を考えるにあたり、以下の4つの観点から整理していきたいと思います。
- 何をドキュメンテーションするか
- どこにドキュメントを保存するか
- どのようにドキュメントを更新するか
- どのようにAIに利用させるか
何をドキュメンテーションするか
ドキュメントを作成するにあたり、何を目的としてどんなドキュメントを残すのかという観点があります。
例えば、ドキュメントの読者が誰かという点について、エンジニアだけを想定するのか他の職種の読者も想定するのか、
もしくはAIが読めれば十分という考え方もあると思います。
ほかにも、何をドキュメントに残したいのか（要件定義書なのか、仕様書なのか、設計書なのか、etc...）ということも考えられます。
ドキュメントに記載すべき内容やその構成は、読者やドキュメントの役割のようなドキュメンテーションをする目的によって変わってくるので、 チーム内での認識の共有が重要になるかと思います。
どこにドキュメントを保存するか
そもそも、ドキュメントはどこにどんな構成で置いておくのが良いのかという観点もあります。
保存場所としては、GitHubやNotion、Confluenceなど様々な選択肢が考えられます。
構成についても、1箇所にまとめるのか分散させるのか、どのような単位でネームスペースを区切るのかなど様々な要素があると思います。
ここでは、AIにコンテキストとして渡しやすいか、人が読む際に必要な情報にアクセスしやすいかなどの側面から適した保存場所や構成が考えられると思います。
例えば、AIのコンテキストという観点ではローカルかMCP経由で参照しやすいツールの方が適しているかもしれません。
職種を問わずアクセスのしやすさを重視するのであれば、組織内で利用しているツールにまとめて、
開発などで使う際には別途AIに参照させられるような機構を作ってしまう方が良いかもしれません。
ドキュメントの管理方法については、コードベースごとに対応する内容のドキュメントをまとめるやり方や
コードベースとは別にドキュメントを集約するやり方など、そのほか様々な選択肢があるかと思います。
どのようにドキュメントを更新するか
ドキュメントをどのように更新していくかという観点も重要なポイントになります。
ドキュメントの更新に関しては、更新の方法やタイミング、誰が更新するのかなどの要素が挙げられます。
例えば、更新の方法については、人が手動で修正する方法やCIなどで自動生成する方法はもちろん、
AIに更新内容を渡してドキュメントを修正させるといったアプローチも採れるようになってきました。
また、更新のタイミングについても、変更が発生するたびに都度更新するのか、定期的に棚卸しをして対応するのか、
あるいは、1度作成したものは魚拓として更新はせずに変更は差分として新しくドキュメントを作成するという考え方もできるかもしれません。
更新する担当者に関しては、変更に携わる人が更新も担当するやり方や別途責任者を決めて更新作業を集約するやり方などが考えられると思います。
ドキュメントのAI活用を考慮する場合、ドキュメントの情報の正確性はAIに与えるコンテキストの質に大きく影響してしまいます。 ドキュメントの鮮度を維持する（最新情報が明確に判別できるようにする）ことが、AI駆動開発を意識する上では重要な要素になると言えるかと思います。
どのようにAIに利用させるか
整備したドキュメントを活用するために、コンテキストや参照情報としてドキュメントの情報をAIに与える方法も考える必要があります。
CursorやClaudeCodeのようなAIエディタを利用してローカルから参照させる方法もありますし、
手元の作業環境とは別に情報を集約するようなAIツールを作ってしまうという方法も考えられます。
最近では、MCPを利用したドキュメント参照が普及してきており、GitHubやAtlassianのMCPで組織内のコードやドキュメントを参照したり、
AWS Knowledge MCPのように外部ドキュメントを参照したりすることが日常的になっているかと思います。
これを踏まえると、MCP経由で情報を参照させるのが手っ取り早いと考えることもできるかもしれません。
Cursor の GitHub MCP でのファイル参照について
GitHub MCP には get_file_contents という tool があり、
ファイルパスを指定することで該当ファイルの内容を参照できるようになっています。
しかし、2025年12月10日時点で、 Cursor からこのツールでファイルの内容を参照しようとしても正しくレスポンスを読み取ることができずに失敗してしまうようです1。
古いバージョンを利用することで解決したという報告もありますが、コミット履歴やローカルからファイル内容を参照させることも検討する必要があります。
（※ 筆者が Cursor 以外で確認できていないので、Cursor 以外で同様の事象が発生するかは言及を避けさせていただきます）
また、単に接続するだけでなく「どのタイミングでどのドキュメントを参照すべきか」をAIに指示することも重要です。
例えば AGENTS.md2 などのルールファイルに「DB設計については docs/schema を参照すること」のようにドキュメントへの導線をAIのシステムプロンプトやルールに組み込むことで、
適切なタイミングで必要な情報を取得するように教えて効率よく質の高い出力を得やすくなります。
トモニテでの運用方針
トモニテでは、前述の観点も踏まえつつ、以下の状態を目指したドキュメント整備を構想しています。
- サービスの構成や施策の背景・仕様が確認できる
- AIが容易にコンテキストを取得できる
具体的に実践しようとしている内容を簡単に紹介します。
1. ドキュメント用リポジトリの作成
開発作業で自然に連携できるよう、ドキュメントは GitHub リポジトリにマークダウン形式で集約しようと考えています。 弊社ではエンジニアの他にPMも GitHub やAIエディタが利用できるような体制であり、 想定されるドキュメントの基本的な利用者がエンジニアとPMということもあり、GitHubを利用する判断をしました。 また、GitHubのマークダウン形式ではMermaid記法が利用でき、図をテキストベースで管理できるというメリットもあります。 テキストベースで管理できるため、画像ファイルよりもAIが内容を解釈しやすく、修正もしやすいのが良い点です。
なお、仕様の変更などが発生した場合は、その変更に関する担当者が責任を持ってドキュメントに反映するという運用方針でのドキュメント管理を意識しています。
2. ドキュメントリポジトリへのドキュメントの集約
トモニテではインフラ、APIサーバー、プロダクトAのフロントエンド、プロダクトBのフロントエンド、のように複数のリポジトリが存在しています。
（一部モノレポを採用しているケースもありますが、話の本筋は変わらないので個別に言及することはしません）
今回新たに作成したドキュメントリポジトリは、トモニテのドキュメントマスタとしての役割を持たせることを構想しています。
そのため、各施策の前提となるような、サービス全体の構成や各施策の背景・仕様が確認できるようなドキュメントはドキュメントリポジトリに作成し、
各領域にフォーカスした知識は各リポジトリにドキュメントを作成するような構成をイメージしています。
これにより、AIも人も、ドキュメントリポジトリを確認することで全体観を把握しつつ、
特定の領域に関する知識への導線から必要な情報を適切に取得することができるようになると考えています。
トモニテでのドキュメント運用イメージ
ドキュメントリポジトリ
/documents/ ├── project_a/ │ └── design_docs/ │ ├── overview.md │ ├── current_system.md │ ├── feature_a.md │ ├── feature_b.md │ ├── architecture.md │ ├── api_design.md │ ├── database.md │ ... │ └── README.md ... └── README.md
※ 既存ドキュメントが充実しておらず新しくジョインするメンバーもいたので現在のシステムを1つのドキュメントにまとめました。
APIサーバー
/api-server/ ├── .cursor/ │ └── rules/ │ └── docs-context.mdc ├── docs/ │ ... │ └── ai/ ... └── README.md
※ チームメンバー全員が cursor を利用していて、AGENTS.md がまだ普及していないタイミングだったので .cursor/rules/ ディレクトリを作成しました。
※ ツールごとにルールファイルを作りたくなかったので、docs/ai/ ディレクトリを参照するようにマスタとなるルールファイルを作成しました。
3. ドキュメントの活用
トモニテでのドキュメントリポジトリの運用は始めたばかりなので、まだまだ内容は不足していますが、 直近のプロジェクトで design docs3 を作成してリポジトリに保存しています。 プロジェクトを進めるにあたり、design docs を参照することでAIの実装精度が高まっていることも実感できていますし、 実装中に仕様に微修正が入った際に、実装PRを参照してドキュメントを更新させることもできています。
4. 今後について
AI駆動開発を見据えたドキュメント運用は、まだまだ対応すべきことも検討すべき課題も多いと感じています。 より本格的に運用を進めていかないと見えてこない課題もあるかと思います。 少しずつ運用を本格化していき、社内の他のチームや社外の事例からも学びながら、 より良いドキュメント運用を目指して改善していきたいと思います。
おわりに
今回の記事では、AI駆動開発を意識したドキュメント運用について幾つかの観点から考えたことを整理してみました。
これまでは人間が読むことを前提に作られていたドキュメントですが、AIのコンテキストとして利用することを意識すると、
保存場所や書き方の最適解も少しずつ変わってくるのかなと感じています。
ドキュメントの運用自体が始まったばかりで、まだまだ試行錯誤が必要な段階ではありますが、
実際の運用を通じて、自分たちのチームに合った形を少しずつ見つけていければと思います。
本記事の内容が、皆さんのチームでのドキュメント運用を考えるきっかけや参考になれば幸いです。
最後まで読んでいただき、ありがとうございました。
