本記事について
当サイトを閲覧いただきありがとうございます。 本記事はシリーズ『生成AI時代のアーキテクチャ超入門』の「開発運用アーキテクチャ」カテゴリ第14弾として、ドキュメンテーションについて解説する記事です。
ドキュメントは書く前に「どこに置くか」を決めるのが先で、場所を間違えると書く意味が消えます。本記事では ADR・README・API ドキュメント・docs-as-codeを、「書いたものが読まれる／AIが読める／半年後にも腐っていない」状態に保つ実務として扱います。
このカテゴリの他の記事
ドキュメントの4種類を区別する
「ドキュメント」と一言で呼ばれるものは、実は目的・寿命・更新頻度の違う4種類が混ざっています。これを区別せずに「Confluence に全部入れる」と、検索性も更新性も同時に劣化します。
flowchart TB
DOCS([ドキュメント])
subgraph GIT["Gitリポジトリ (docs-as-code)"]
README[README<br/>入口・起動手順]
ADR[ADR<br/>設計判断の記録]
API[APIドキュメント<br/>OpenAPI/TypeDoc]
end
subgraph WIKI["Confluence/Notion/Wiki"]
BIZ[業務知識・運用手順<br/>組織知識]
end
DOCS --> GIT
DOCS --> WIKI
GIT -.|PR/レビュー/履歴/<br/>AIが読める|.- L1[コードと一体]
WIKI -.|短〜中寿命<br/>陳腐化しやすい|.- L2[業務知識のみ]
classDef root fill:#fef3c7,stroke:#d97706;
classDef git fill:#dcfce7,stroke:#16a34a,stroke-width:2px;
classDef wiki fill:#dbeafe,stroke:#2563eb;
class DOCS root;
class GIT,README,ADR,API git;
class WIKI,BIZ wiki;| 種類 | 目的 | 寿命 | 置く場所 |
|---|---|---|---|
| README（リポジトリ紹介・起動手順） | 入口の道案内 | 中（リポジトリと同寿命） | リポジトリ root |
| ADR（設計判断の記録） | なぜその選択をしたかの理由 | 永続（追加のみ） | リポジトリ docs/adr/ |
| APIドキュメント | 仕様の機械可読な定義 | コード同期 | OpenAPI YAML／TypeDoc |
| 業務知識・運用手順 | 組織知識の蓄積 | 短〜中（陳腐化しやすい） | Confluence／Notion／Wiki |
最初の3種類はGitリポジトリにコミットするのが現代の鉄板です。コードと一緒に PR・レビュー・履歴管理ができ、AI も読める。Confluence／Notion に置くのは「業務知識・運用手順」のみに絞るのが、検索性と更新性を両立する設計です。
ADR — 設計判断の記録
ADR（Architecture Decision Record＝アーキテクチャ判断記録）は、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 — 入口の道案内
README はリポジトリを開いた人が最初に見る案内板です。多くのチームで README は「プロジェクト名と1行説明だけ」か「全部入りで誰も読まない」の二極化に陥ります。本命は5分で起動できる手順 + 必要最低限の文脈に絞る構成です。
| 含めるべき | 含めるべきでない |
|---|---|
| プロジェクトの目的（1段落） | 詳細な設計説明（→ ADR／docs/） |
| 起動手順（コピペで動く形） | 全機能の使い方 |
| 開発環境の前提（ランタイムの要求バージョン等） | API リファレンス（→ 別ファイル） |
| ライセンス・連絡先 | 個人の TODO メモ |
| 関連リンク（CONTRIBUTING・docs/） | 障害履歴 |
「コピペで起動できる」が最重要。git clone から localhost:3000 まで、コマンドを順に貼るだけで動く状態を README で担保します。コマンドが古い・依存が変わったまま放置された README は、新人を最初の30分で挫折させる装置になります。
docs-as-code — Markdown + Gitに寄せる
docs-as-code は、ドキュメントをコードと同じ仕組み（Markdown + Git + PR レビュー）で管理する考え方です。Confluence や Notion のような GUI 中心ツールから、リポジトリ内 Markdown に寄せる流れが現時点では主流です。
| 観点 | docs-as-code（Markdown + Git） | Confluence／Notion |
|---|---|---|
| バージョン管理 | Git の履歴で完全 | 限定的（編集履歴のみ） |
| レビュー | PR でコードと同じワークフロー | コメント機能のみ |
| 検索性 | grep／IDE で瞬時 | 検索精度に難 |
| AIが読めるか | ◎（標準フォーマット） | △（独自API・スクレイピング困難） |
| 図表 | Mermaid・PlantUML でコード化 | 画像埋め込み（更新が手作業） |
| 学習コスト | Markdown の知識のみ | ツール固有のUI |
Confluence／Notion は業務知識・組織情報には向きますが、コードと密結合のドキュメントを置くと検索性とレビュー性が劣化します。API仕様・設計判断・READMEは全てリポジトリ内Markdownに寄せるのが現代の鉄板です。
ドキュメントを書く段階 — 段階別の実務
「いつドキュメントを書くか」も曖昧にすると形骸化します。書くタイミングと粒度を段階で切るのが実用的で、各段階で何をどこに残すかを決めておきます。
| 段階 | いつ書くか | 何を書くか | どこに置くか |
|---|---|---|---|
| ①設計検討 | 実装前 | 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 で辿った人が即座に文脈を再構築できます。
ドキュメントの鬼門 — 腐ったドキュメントは誤情報
ドキュメントの最大の罠は書いた後に更新されないこと。古い情報が残っているドキュメントは「ドキュメントがない」状態より悪く、読んだ人を間違った方向に誘導するためです。
| 鬼門 | なぜ起きる・なぜダメか |
|---|---|
| README に古いコマンドが残る | 新人が初日に動かず挫折。コマンドは CI で実行可能に |
| Confluence のアーキテクチャ図が3年前 | 「動いているコード」と乖離。画像は腐る |
| API仕様書を Word で配布 | コードと同期せず、半年で誤情報の塊に |
| 全機能の使い方を README に詰め込み | 巨大化して誰も読まない・更新もされない |
| 「設計書は Excel」運用 | 検索不能・差分追跡不能・AI解析不能 |
対策の核はドキュメントをコードと同じ場所に置き、PRで更新を強制する仕組み化です。OpenAPI・TypeDoc などコードから自動生成できる種類はすべて自動化し、人間が手で更新するドキュメントを最小化するのが現代の防衛線です。
古いドキュメントはドキュメントがない状態より悪い。書いた人が更新責任を持たない設計が問題です。
OpenAPI／TypeDoc — コードから自動生成
API 仕様書は手書きすると必ず腐ります。OpenAPI（旧称 Swagger＝REST API の機械可読な仕様フォーマット）や TypeDoc（TypeScript のコメントから自動生成）を使えば、コードと仕様が常に同期します。
| ツール | 対象 | 特徴 |
|---|---|---|
| OpenAPI（YAML／JSON） | REST API | デファクト標準・SwaggerUI で可視化 |
| GraphQL Schema（SDL） | GraphQL | 型がそのまま仕様 |
| gRPC + Protocol Buffers | gRPC | .proto がそのまま仕様 |
| TypeDoc | TypeScript ライブラリ | コメントから HTML 生成 |
| Sphinx + autodoc | Python | docstring から HTML 生成 |
| rustdoc | Rust | 標準で組み込まれている |
コードのコメント・型がそのままドキュメントになる設計が、現代の鉄板です。OpenAPI を使えば、サーバ実装・クライアントSDK・モックサーバ・ドキュメントHTMLまで全て1つの YAML から生成できます。OpenAPI YAMLをGitで管理し、CI で「コードと YAML が同期しているか」を検証する仕組みが、API ドキュメントの劣化を防ぐ最大の防衛線です。
Mermaid／PlantUML — 図表もコードに
図表は腐りやすい代表格です。Lucidchart や draw.io で作った PNG をリポジトリに貼ると、ソースが行方不明になり更新不能になる事故が頻発します。Mermaid や PlantUML はテキストで図を定義する仕組みで、Markdown内に直接書けるため docs-as-code と相性が最高です。
sequenceDiagram
User->>Frontend: ログイン要求
Frontend->>AuthAPI: POST /auth/login
AuthAPI->>DB: ユーザー認証
DB-->>AuthAPI: 認証結果
AuthAPI-->>Frontend: JWT発行GitHub・GitLab・Notion・VS Code が標準で Mermaid をレンダリングします。テキストなので差分が読める・PRで変更レビューできる・AIが理解できるの3点が圧倒的に強い。「図を描く」と「図を更新する」のコスト差が劇的に縮まり、「図が腐らない」仕組みが手に入ります。
ポストモーテム — 障害から学ぶ仕組み
ポストモーテム（Postmortem＝直訳は「死後の検死」、IT業界では障害発生後の振り返り文書）は、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 流の運用です。
ドキュメンテーションのアンチパターン
ドキュメントを書く文化があっても、以下のアンチパターンが混ざると効果が一気に減ります。
| アンチパターン | なぜダメか |
|---|---|
| 全部 Confluence に投げ込む | 検索不能・PR レビューできない・AI が読めない |
| ドキュメントを「責任者」だけが更新 | ボトルネック化・本人が辞めると即陳腐化 |
| 「書く」が評価されず「コードを書く」だけ評価 | 誰も書かない文化が定着 |
| 1ファイルに全機能の使い方を詰め込み | 巨大化して読まれない |
| Slack に重要情報を書いて DM 共有 | 検索不能・新人がアクセスできない |
| ドキュメントを社外秘扱いで部分開示 | 全員が同じ情報を見られないとレビューが回らない |
SlackのDMで共有された設計判断は、組織にとっては存在しないのと同じです。Slack ログは検索できても意図せぬ流れに埋もれて発見不能で、「Slackは議論場、結論はGitに残す」という線引きが必須になります。
AI時代の視点
AI 駆動開発では、ドキュメントの役割が大きく変わります。AIエージェント（Claude Code・Cursor・Windsurf 等）がリポジトリを読んでコードを生成する時代では、AIが読めるドキュメントかどうかが直接生産性に効きます。
| AI時代に有利 | AI時代に不利 |
|---|---|
| Markdown + Git のドキュメント | Confluence・Notion・口伝 |
| ADR で「なぜ」を残す文化 | 「動くコードがドキュメント」主義 |
| OpenAPI／TypeDoc で機械可読な仕様 | Word・Excel での仕様書配布 |
| Mermaid／PlantUML（テキスト図） | PNG／JPG の図（更新不能） |
| README が起動手順を網羅 | README が薄く、口伝に頼る |
AI に「このプロジェクトを理解させる」とき、最初に読ませるのはREADME → ADR → コードの順です。ここに必要情報が網羅されていれば、AI エージェントは数十分で全体像を把握し、的確な変更提案ができます。逆に Confluence にしか情報がないチームは、AIが文脈を持たないまま生成してしまい、的外れな提案を量産します。
AI 時代はMarkdown + Gitに全部寄せるのが圧倒的に有利です。
よくある勘違い①
ドキュメントに関する誤解は、現場で書く人を疲弊させます。
ドキュメントは詳しいほど良い
詳しすぎるドキュメントは誰も読まない。README は5分で起動できる手順、ADR は1ページ以内、PR description は3段落、が現実的な上限。長いドキュメントは更新もされず腐る。
書いた人が責任を持って更新
書いた人が辞めた瞬間に陳腐化します。更新責任は「変更したコードに紐づくドキュメント」を変更PR内で同時更新する文化に乗せるべき。CI で「README に書かれたコマンドが動くか」まで検証するのが本命です。
よくある勘違い②
Confluenceは検索できるから問題ない
Confluenceの検索は実用にならないのが現場の実感です。タイトルしかヒットしない・全文検索が遅い・AIから読めないの3点で、コードと密結合の情報は不適切。Markdown + grep の検索性に勝てません。
ドキュメントを書く時間がない
書かない時間で失う時間の方が長い。新人質問・障害調査・退職者の知識喪失で溶ける時間は、書く時間の数倍〜数十倍になります。
ドキュメントは書く／書かないより、置き場所と更新責任で勝負が決まります。
決めるべきこと — あなたのプロジェクトでの答えは？
以下の項目について、あなたのプロジェクトの答えを1〜2文で言語化してみてください。曖昧なまま着手すると、必ず後から「なぜそう決めたんだっけ」が問われます。
- ドキュメントの置き場所（リポジトリMarkdown／Confluence／Notion）
- ADRの運用（書く対象・テンプレ・置き場所）
- READMEの最低ライン（起動手順がコピペで動くか）
- API仕様の管理方法（OpenAPI／GraphQL SDL／
.proto） - 図表の管理方法（Mermaid／PlantUML／画像）
- PR descriptionのテンプレ
- ポストモーテムの運用（書くタイミング・公開範囲）
- ドキュメント更新責任のルール（変更PRで同時更新）
筆者メモ — 「Confluenceの墓場」が殺した移行プロジェクト
ある中規模 SaaS で、3年分のアーキテクチャ判断・運用手順・障害対応がすべて Confluence に蓄積されていた事例があります。問題は、新人が必要な情報を見つけられないこと。検索しても10年前のドラフト・別チームの古い設計案・コピペで残された重複ページがヒットし、正しい情報を見つけるのに数時間かかる状態が常態化していました。
このチームは段階的に ConfluenceからGitリポジトリ内Markdownへの移行を実施し、最終的に「コードと密結合の情報は全てGitへ・組織情報のみConfluence」に整理。新人のキャッチアップ時間が劇的に短縮されただけでなく、AIエージェントがGitのドキュメントを読んでコードを生成できるようになり、開発速度も向上した──という事例です。ドキュメントの置き場所が、組織の競争力を決める時代になっています。
Confluence は情報の墓場になりやすい。コード密結合の情報は Git へ移します。
最終的な判断の仕方
ドキュメンテーション設計の本質は、「書くこと」ではなく読まれる場所と更新される仕組みを作ることにあります。書くこと自体は誰でもできますが、置き場所を間違えると永久に読まれず、更新責任を曖昧にすると半年で腐る。だから設計の核は、コード密結合の情報は全てGitに寄せ、PRで更新を強制することです。
現時点の鉄板は「README + ADR + OpenAPI + Mermaid を全てリポジトリ内Markdownで管理 + PR description テンプレ + ポストモーテム公開 + Confluence は組織情報のみ」AI 駆動開発では、AI エージェントが読めるかどうかが生産性に直結するため、Markdown + Gitに寄せたチームほどAIの恩恵を受けられる。Confluence・口伝・Slack DM 中心のチームは、AI 時代の競争軸から外れていきます。
選定の優先順位
- ドキュメントの置き場所をGitリポジトリに寄せる — Confluence は組織情報のみ
- ADRでOne-way Doorの判断を必ず残す
- OpenAPI・TypeDoc・Mermaidでコードと仕様を同期
- PR descriptionテンプレで「なぜ・代替案・確認手順」を強制
書いたものが読まれる場所に置く、それが書く以前の最重要設計です。
まとめ
本記事はドキュメンテーションについて、4種類の区別・ADR・README・docs-as-code・OpenAPI・Mermaid・ポストモーテム・AI時代の置き場所まで含めて解説しました。如何だったでしょうか。
ドキュメントはGitリポジトリに寄せ、ADRでOne-way Doorを残し、コードと仕様を自動同期し、PR descriptionで意図を強制する。これが2026年のドキュメンテーション設計の現実解です。
次回はチケット・プロジェクト管理（Issue・カンバン・WIP制限）について解説します。
シリーズ目次に戻る → 『生成AI時代のアーキテクチャ超入門』の歩き方
それでは次の記事も閲覧いただけると幸いです。
📚 シリーズ：生成AI時代のアーキテクチャ超入門（67/89）