本記事について
当サイトを閲覧いただきありがとうございます。 本記事はシリーズ『生成AI時代のアーキテクチャ超入門』の「開発運用アーキテクチャ」カテゴリ第14弾として、ドキュメンテーションについて解説する記事です。
ドキュメントは書く前に「どこに置くか」を決めるのが先で、場所を間違えると書く意味が消えます。本記事ではADR・README・APIドキュメント・docs-as-codeを、「書いたものが読まれる／AIが読める／半年後にも腐っていない」状態に保つ実務として扱います。
本記事のテーマについてさらに詳しく知りたい方は『アーキテクトの教科書』も参考にしてみてください。
この記事の結論
- ドキュメントはGitリポジトリに寄せる（docs-as-code）
- 後戻りできない判断はADRで残す
- コードと仕様（OpenAPI等）は自動同期にする
この記事を読む前に
本記事は開発・テスト・リリース・監視といった、サービスを作って動かし続ける工程の話が中心です。IT用語にあまり馴染みがない方は、基礎編の「開発から運用までの流れ」を先に読んでおくと格段に分かりやすくなると思います。また、読んでいて分からない用語が出てきたときは用語集で調べながら読み進められます。
そもそもドキュメンテーションとは何か
家族への引き継ぎメモを想像してください。「ゴミ出しは月・木」「給湯器の操作はこのボタン」──自分がいなくても家が回るように、必要な情報を残す行為です。書かなければ、自分が不在の間に誰も正しい手順がわかりません。
ソフトウェア開発のドキュメンテーションも同じです。なぜこの設計にしたか・どう起動するか・APIの使い方は何かを、半年後の自分や新メンバーが迷わないように記録する活動です。
もしドキュメントがなければ、設計の経緯は退職者の頭の中に消え、新メンバーのオンボーディングは「隣の人に聞いて」の口伝えだけになります。
なぜドキュメンテーションが必要か
第一に、設計の「なぜ」は半年後に消えるからです。コードを読めば「何をしているか」はわかりますが、「なぜこの設計にしたか」は読めません。第二に、新メンバーのオンボーディングを属人化させないためです。READMEが整備されていれば、自走できるまでの時間が劇的に短縮されます。第三に、AIがドキュメントを読んで判断する時代だからです。ADRやOpenAPIがGitにあれば、AIエージェントも設計意図を理解した上でコードを生成できます。ドキュメントは人だけでなく機械の読者も持つ時代です。
ドキュメントの4種類を区別する
「ドキュメント」と一言で呼ばれるものは、実は目的・寿命・更新頻度の違う4種類が混ざっています。これを区別せずに「Confluenceに全部入れる」と、検索性も更新性も同時に劣化します。
| 種類 | 目的 | 寿命 | 置く場所 |
|---|---|---|---|
| README（リポジトリ紹介・起動手順） | 入口の道案内 | 中（リポジトリと同寿命） | リポジトリ root |
| ADR（設計判断の記録） | なぜその選択をしたかの理由 | 永続（追加のみ） | リポジトリ docs/adr/ |
| APIドキュメント | 仕様の機械可読な定義 | コード同期 | OpenAPI YAML／TypeDoc |
| 業務知識・運用手順 | 組織知識の蓄積 | 短〜中（陳腐化しやすい） | Confluence／Notion／Wiki |
最初の3種類はGitリポジトリにコミットするのが現代の鉄板です。コードと一緒にPR・レビュー・履歴管理ができ、AIも読める。Confluence／Notionに置くのは「業務知識・運用手順」のみに絞るのが、検索性と更新性を両立する設計です。
ADR — 設計判断の記録
ADRは、Michael Nygardが2011年に提唱した、なぜこの技術を選んだかを1ファイル1判断で残す形式です。現時点では、OSS・SaaS・エンタープライズを問わず、設計記録の事実上の標準フォーマットになっています。
# ADR-0007: PostgreSQL を主DBとして採用する
## Status
Accepted (2026-03-15)
## Context
SQLite では同時接続・リードレプリカ要件を満たせない。
## Decision
PostgreSQL 16 を採用。MySQL・MongoDB を比較し、JSON型と
リレーショナル設計の両取りを評価。
## Consequences
- 全文検索・地理空間で拡張性確保
- 特殊な水平分散には別プロダクトが必要短く（1ページ以内）、追加のみで上書きしない（過去の判断はStatusを Superseded by ADR-XX にする）のがコツ。意思決定の歴史が残ることで、半年後の新人が「なぜこうなっているのか」をGitの履歴から再構築できます。
ADRを書くタイミング — One-way Door判定
ADRは「すべての設計判断」に書くものではありません。書きすぎると陳腐化し誰も読まなくなる。One-way Door（一度通ったら戻りにくい判断、Amazonの意思決定フレームワーク）に該当するものだけに絞るのが実用的です。
| 書くべき判断 | 書かなくていい判断 |
|---|---|
| DBの選定（PostgreSQL vs MongoDB） | ライブラリ A から B への乗り換え |
| 言語・フレームワークの追加 | 関数の引数の型変更 |
| 認証方式の決定（OAuth／Passkey） | エンドポイント名の変更 |
| マイクロサービス分割 | 個別 API のリファクタ |
| クラウドベンダーの選定 | EC2 のインスタンスサイズ変更 |
「やり直しに3か月以上かかる」がADRラインの目安です。これより軽いものはPR descriptionで十分です。逆にOne-way Door判定の判断をADRに残さないと、3年後に「なぜこうしたのか」が誰も説明できなくなる──これがエンタープライズで頻発する負債の入口です。
READMEとdocs-as-code
READMEはリポジトリを開いた人が最初に見る案内板です。多くのチームで「プロジェクト名と1行説明だけ」か「全部入りで誰も読まない」の二極化に陥ります。本命は5分で起動できる手順 + 必要最低限の文脈に絞る構成で、プロジェクトの目的（1段落）・コピペで動く起動手順・開発環境の前提・関連リンクだけを置き、詳細な設計説明はADRへ、APIリファレンスは別ファイルへ逃がします。「コピペで起動できる」が最重要で、コマンドが古いまま放置されたREADMEは新人を最初の30分で挫折させる装置になります。
docs-as-codeは、ドキュメントをコードと同じ仕組み（Markdown + Git + PRレビュー）で管理する考え方です。Gitの履歴で完全なバージョン管理ができ、PRでコードと同じワークフローでレビューでき、grep / IDEで瞬時に検索でき、AIが標準フォーマットとして読める。図表もMermaid・PlantUMLでコード化できます。Confluence / Notionは業務知識・組織情報には向きますが、コードと密結合のドキュメントを置くと検索性とレビュー性が劣化します。
ドキュメントを書く段階 — 段階別の実務
「いつドキュメントを書くか」も曖昧にすると形骸化します。書くタイミングと粒度を段階で切るのが実用的です。
| 段階 | いつ書くか | 何を書くか | どこに置くか |
|---|---|---|---|
| ①設計検討 | 実装前 | ADR（採用案・代替案・理由） | docs/adr/NNNN-title.md |
| ②PR提出時 | 実装直後 | PR description（変更内容・動作確認） | GitHub PR |
| ③マージ後 | 必要に応じて | README更新・APIドキュメント生成 | リポジトリ内 |
| ④リリース | 機能公開時 | CHANGELOG・リリースノート | CHANGELOG.md（自動生成） |
| ⑤障害発生時 | 復旧後24h以内 | ポストモーテム | docs/postmortems/ |
PR descriptionは「そのコミットだけで全文脈が分かるレベル」を目指します。「なぜこの変更が必要か」「他の選択肢を検討したか」「動作確認の手順」の3点を本文に書くのが本命。これを徹底するだけで、3年後に git blame で辿った人が即座に文脈を再構築できます。
OpenAPIとMermaid — コードから自動生成する
API仕様書は手書きすると必ず腐ります。OpenAPI（REST APIの機械可読な仕様フォーマット）を使えば、サーバ実装・クライアントSDK・モックサーバ・ドキュメントHTMLまで全て1つのYAMLから生成でき、CIで「コードとYAMLが同期しているか」を検証する仕組みがドキュメント劣化を防ぐ最大の防衛線になります。GraphQLならSchema（SDL）、gRPCなら .proto がそのまま仕様になり、ライブラリはTypeDoc（TypeScript）・rustdoc（Rust）等でコメントから自動生成します。コードのコメント・型がそのままドキュメントになる設計が現代の鉄板です。
図表は腐りやすい代表格です。Lucidchartやdraw.ioで作ったPNGをリポジトリに貼ると、ソースが行方不明になり更新不能になる事故が頻発します。MermaidやPlantUMLはテキストで図を定義する仕組みで、Markdown内に直接書けます。
sequenceDiagram
User->>Frontend: ログイン要求
Frontend->>AuthAPI: POST /auth/login
AuthAPI->>DB: ユーザー認証
DB-->>AuthAPI: 認証結果
AuthAPI-->>Frontend: JWT発行GitHub・GitLab・VS Codeが標準でMermaidをレンダリングします。テキストなので差分が読める・PRで変更レビューできる・AIが理解できるの3点が圧倒的に強く、「図が腐らない」仕組みが手に入ります。
ポストモーテム — 障害から学ぶ仕組み
ポストモーテム（障害発生後の振り返り文書）はSREプラクティスの中核です。障害後24〜48時間以内に書き、個人を責めるのではなく仕組みを改善するためのドキュメントです。
# Postmortem: 2026-03-20 認証障害（45分間）
## 影響
全ユーザーがログイン不可 / 影響時間 14:23-15:08 JST / 機会損失 約120万円
## タイムライン
- 14:23 アラート発火
- 14:38 原因特定（Redis 接続プール枯渇）
- 15:08 正常化確認
## 原因（5 Whys分析）
## アクションアイテム
- [ ] 接続プール監視を Grafana に追加
- [ ] 負荷試験シナリオに本ケース追加Blameless（責めない）が鉄則です。「Aさんがミスした」ではなくミスを防げない仕組みだったと書くことで、再発防止が個人依存から仕組み改善に変わります。書いたものは社内全員に公開し、学びを組織知化するのがGoogle SRE流の運用です。
3つのシナリオで考える
個人開発・スタートアップの場合
READMEの起動手順と軽量なADRの2つだけで十分だと思います。READMEは「コピペでlocalhostまで動く」ことを死守して、DB選定や認証方式のようなOne-way Doorの判断だけADRに3行で残しておきます。最初の読者は未来の自分自身ですね。
中小SaaSの場合
docs-as-codeとPR descriptionのテンプレート、OpenAPIの自動生成を文化として確立する段階です。コードと密結合の情報は全てGitへ置いて、Notionは組織情報のみに絞ります。図もMermaidでテキスト化しておけば、「図が腐らない」仕組みが手に入ります。
大企業の場合
リポジトリが数百になってきますので、Backstage TechDocsのようなドキュメントポータルでの横断検索と、ADR・ポストモーテムの全社テンプレート統一が本題になります。Confluenceの墓場化を防ぐためにも、「コード密結合はGit・組織情報はConfluence」という線引きをガバナンスとして明文化しておくべきでしょう。
AI判断軸 ― Gitのドキュメントは AIの知識ベースになる
Gitリポジトリ内のドキュメントはAIの知識ベースになる
README・ADR・OpenAPI YAMLがGitリポジトリ内にある場合、AIはこれらを直接参照してコード生成の精度を上げられます。たとえばADRに「認証はJWTではなくCookieセッションを選定した」と記録されていれば、AIは新しい認証関連コードでもCookieベースの実装を提案します。ConfluenceやNotionに置かれたドキュメントは、AIの開発ツール（Copilot・Claude Code等）から直接参照できないため、毎回コンテキストとして手動でコピーする必要があります。
ADRがAIの設計判断のガードレールになる
ADRに過去の設計判断とその理由を記録しておくと、AIがその判断に反するコードを書いた時に「ADRの方針と矛盾している」と指摘できます。人間のレビューでも「なぜこう決めたか」がADRに残っていれば判断の根拠が明確になります。ドキュメントの置き場所が、AI時代の開発速度を直接左右します。
やってはいけないこと
ドキュメントの最大の罠は書いた後に更新されないこと。古い情報が残っているドキュメントは「ドキュメントがない」状態より悪く、読んだ人を間違った方向に誘導します。特に危険な6つに絞ります。
| 禁じ手 | なぜダメか → どうするか |
|---|---|
| READMEに古いコマンドが残る | 新人が初日に動かず挫折 → 起動手順をCIで実行可能に保つ |
| API仕様書をWord / Excelで配布 | コードと同期せず半年で誤情報の塊に → OpenAPI等でコードから自動生成する |
| 図をPNG / JPGだけで管理 | ソースが行方不明で更新不能 → Mermaid / PlantUMLでテキスト化する |
| 全部Confluenceに投げ込む | 検索不能・PRレビュー不可・AIが読めない → コード密結合の情報はGitへ |
| SlackのDMで設計判断を共有 | 組織にとって存在しないのと同じ → Slackは議論場、結論はGitに残す |
| 「書く」が評価されず「コードを書く」だけ評価 | 誰も書かない文化が定着 → PR descriptionテンプレとADRを仕組みで強制する |
対策の核はドキュメントをコードと同じ場所に置き、PRで更新を強制する仕組み化です。コードから自動生成できる種類はすべて自動化し、人間が手で更新するドキュメントを最小化するのが現代の防衛線です。
筆者メモ — 「Confluenceの墓場」が殺した移行プロジェクト
ある中規模SaaSで、3年分のアーキテクチャ判断・運用手順・障害対応がすべてConfluenceに蓄積されていた事例があります。問題は、新人が必要な情報を見つけられないこと。検索しても10年前のドラフト・別チームの古い設計案・コピペで残された重複ページがヒットし、正しい情報を見つけるのに数時間かかる状態が常態化していました。
このチームは段階的にConfluenceからGitリポジトリ内Markdownへの移行を実施し、最終的に「コードと密結合の情報は全てGitへ・組織情報のみConfluence」に整理。新人のキャッチアップ時間が劇的に短縮されただけでなく、AIエージェントがGitのドキュメントを読んでコードを生成できるようになり、開発速度も向上した──という事例です。ドキュメントの置き場所が、組織の競争力を決める時代になっています。
決めるべきこと — 自分のプロジェクトでの答えは？
以下の項目について、自分のプロジェクトの答えを1〜2文で言語化してみてください。曖昧なまま着手すると、必ず後から「なぜそう決めたんだっけ」が問われます。
- ドキュメントの置き場所（リポジトリMarkdown / Confluence / Notion）
- ADRの運用（書く対象・テンプレ・置き場所）
- READMEの最低ライン（起動手順がコピペで動くか）
- API仕様の管理方法（OpenAPI / GraphQL SDL /
.proto） - 図表の管理方法（Mermaid / PlantUML / 画像）
- PR descriptionのテンプレ
- ポストモーテムの運用（書くタイミング・公開範囲）
- ドキュメント更新責任のルール（変更PRで同時更新）
この記事に関連する記事
まとめ
本記事はドキュメンテーションについて、4種類の区別・ADR・README・docs-as-code・OpenAPI・Mermaid・ポストモーテム・AI時代の置き場所まで含めて解説しました。如何だったでしょうか。
ドキュメントはGitリポジトリに寄せ、ADRでOne-way Doorを残し、コードと仕様を自動同期し、PR descriptionで意図を強制する。これが2026年のドキュメンテーション設計の現実解です。
次回はチケット・プロジェクト管理（Issue・カンバン・WIP制限）について解説します。
シリーズ目次に戻る → 『生成AI時代のアーキテクチャ超入門』の歩き方
本記事で扱った内容の詳細は GitHub Docs も合わせて参考にしてください。
それでは次の記事も閲覧いただけると幸いです。
📚 シリーズ：生成AI時代のアーキテクチャ超入門（73/95）