Docs as Code × AI：AI が扱えるドキュメントを書く技術
最近AIエージェントを利用して開発をしていますが、AIと仕事をしていてあらためて痛感しているのがドキュメントの重要性です。
AI が正しく理解できる記法でドキュメントを作成することは、AI時代の開発において欠かせないスキルになりつつあります。
そこで本記事では、「AI が扱えるドキュメントを書く技術」 をテーマに、Docs as Codeの考え方と、具体的な書き方を紹介します。
この記事は以下のような読者を想定しています。
- AIエージェントを活用し始めた開発者
- ドキュメント管理をExcel/Wordから移行したいチーム
📌 Docs as Code とは
Docs as Code (Documentation as Code) とは、ドキュメントを “コードと同じように” 扱う開発手法です。
Word や Excel といったバイナリ形式ではなく、Markdown / YAML / JSON などのプレーンテキストでドキュメントを作成し、ソースコードと同様に Git でバージョン管理し、レビュー・自動化・CI/CD などの開発プロセスに組み込みドキュメントをコードと同じプロセスで継続的に改善する文化・手法です。
🧩 Docs as Code のメリット
1. バージョン管理（Git）と相性が良い
テキストファイルは Git で扱いやすく、以下のような利点があります。
- 差分（diff）が見やすい
- 複数人での変更履歴が追いやすい
- レビューの負荷が低い
- コンフリクトも解決しやすい
Word や Excel などのバイナリ形式は差分が読めないため、レビューや管理が難しくなりがちです。
2. コードで編集できるため高速
テキストであれば以下が可能です。
- 自動生成
- 一括変換
- CI/CD に組み込み
- 正規表現やスクリプトで変換
「人が読む ＋ 機械が扱う」という両立がしやすい点が大きな強みです。
3. AI フレンドリー
AI にとって テキストは処理しやすいフォーマット です。
- トークン化が容易：テキストはそのままLLMの入力として使える
- コンテキストとして参照可能：リポジトリ内のMarkdownをAIエージェントが仕様書として読み込める
- 構造の推論が可能：見出しや箇条書きからドキュメントの構造を理解できる
テキストベースのドキュメントはAIにとってコードと同じように扱えるため強力なAI連携を可能にします。
AI連携の具体例：
- GitHub Copilot が README.md を読んでコードを提案
- AIエージェントが API仕様（OpenAPI/YAML）を読んでクライアントコードを生成
- Mermaid図から処理フローを理解し、実装を提案
- 実装の内容をドキュメントにフィードバック
AI の力を最大化するにはテキストベースが最適です。
📝 具体的な書き方の紹介
ここからは、Docs as Code で使用されるテキストベースの記法をカテゴリごとに紹介します。
1. マークアップ言語
◆ Markdown
もっとも一般的なマークアップ言語。Qiita でもおなじみ。
例：
# タイトル
## セクション
- 箇条書き
- **強調**
> 引用
特徴：
- 学習コストが低い
- GitHub や Qiita などあらゆる場所で使える
- HTML に変換しやすい
2. UML 図 / フローチャート図
図もテキストベースで記述して、コードのように管理できる記法があります。
◆ Mermaid
GitHub、GitLab、Notion、Obsidian など多くのツールが対応しており、手軽に図が書ける。
例：フローチャート
例：シーケンス図
例：クラス図
特徴：
- シンプルな記述で学習コストが低い
- 環境構築が不要でWebやGitHubで標準でサポートされている
- 自動レイアウト中心、細かい調整がしにくい
- GitHub CopilotがMermaid記法を生成・解釈できるため、図の作成もAI支援が可能
◆ PlantUML
より豊富な図が書ける UML 専用 DSL。PNG/SVG 生成や多種類のダイアグラムに対応。
例：フローチャート
例：シーケンス図
例：クラス図
特徴：
- 多くの UML 図式に対応
- 実行環境が必要だが拡張性が高い
- 学習コストがmermaidと比べてやや高い
| 記法 | 対応図の種類 | 学習コスト | 対応ツール | 環境構築 |
|---|---|---|---|---|
| Mermaid | フローチャート、シーケンス図、ER図、ガントチャートなど | 低 | GitHub, GitLab, Notion, Obsidian, VS Code | 不要（ブラウザ対応） |
| PlantUML | クラス図、シーケンス図、ユースケース図、アクティビティ図など | 中 | VS Code, IntelliJ, Confluence | 必要（Java環境） |
3. 構造化データ
◆ CSV / TSV
データの加工やインポート用途に強い。
CSV 例：
id,name,age
1,John,20
2,Alice,30
◆ Markdown Tables
軽い表を書くときはこれが一番簡単。
| ID | Name | Age |
|----|-------|-----|
| 1 | John | 20 |
| 2 | Alice | 30 |
◆ JSON
構造化データの王道。API、設定ファイル、データ保存などに使われる。
{
"id": 1,
"name": "John",
"tags": ["dev", "backend"]
}
◆ YAML
人間に読みやすく、インフラや設定でよく使われる。
server:
host: localhost
port: 8080
features:
logging: true
cache: false
◆ XML
タグ構造で厳密な記述ができる。一部の業務システムや古めの規格で現役。
<user>
<id>1</id>
<name>John</name>
</user>
| 形式 | 可読性 | ネスト構造 | 主な用途 | 特徴 |
|---|---|---|---|---|
| CSV/TSV | ◎ | ✕ | データ交換、Excel連携 | シンプル、大量データ向き |
| Markdown Tables | ◎ | ✕ | ドキュメント内の表 | 見たままのレイアウト |
| JSON | ○ | ◎ | API、設定ファイル | プログラムとの親和性が高い |
| YAML | ◎ | ◎ | 設定ファイル、インフラ定義 | 人間が読み書きしやすい |
| XML | △ | ◎ | 業務システム、レガシー連携 | 厳密なスキーマ定義が可能 |
✨ まとめ
Docs as Code には、以下のようなメリットがあります。
- AI との相性が非常によい → 解析・生成・校正が得意
- Git で管理しやすい → 差分・履歴・レビューが容易
- 自動化やスクリプト処理がしやすい → CI/CD との連携が可能
Markdown、Mermaid、PlantUML、CSV/JSON/YAML などを目的に応じて使い分けて、AIとコラボレーションしてメンテナンスしていくことで、ドキュメントはより生産的な資産になります。
今後も 「書くことをコード化」 して、情報管理を効率化していきましょう！
🔥 発展編: “Everything as Code × AI” の時代へ
今回は as Code なドキュメントの書き方を紹介しましたが、その他にも as Code な手法はいろいろなシーンで登場します。
◆Infrastructure as Code(IaC)
インフラを手動で管理・デプロイするのではなく、コードで定義・管理する手法です。
サーバーやネットワーク設定などのインフラ構成をコードで定義し、環境構築を自動化することができ、再現性を高め、開発効率が向上します。
代表的なツール
- Terraform
- マルチクラウド対応のデファクトスタンダード
- AWS CloudFormation
- AWS のネイティブ IaC
- Azure Bicep / ARM Templates
- Azure のリソース定義用
- Pulumi
- 一般的なプログラミング言語で IaC が書ける
メリット
- 再現性の向上：同じコードから何度でも同じ環境を作れる
- 自動化：手動操作によるミスを削減
- バージョン管理：Gitで環境の「歴史」が追跡できる
- スケール対応：大量のリソースを一括で作成・変更
◆Pipelines as Code
CI/CD のフローをコードとして記述し、再現性を担保する手法。
代表的なツール
- GitHub Actions（YAML）
- GitLab CI（YAML）
- AWS CodePipeline
- Azure Pipelines
利点
- どのブランチでも同じプロセスでビルド・テストできる
- レビューにより品質が担保される
◆Database as Code / Schema as Code
データベースのスキーマや初期データをコードで管理する手法。
代表的なツール
- Flyway
- Liquibase
◆Configuration as Code(CaC)
アプリや OS、ミドルウェアの設定をコードで管理する手法。
代表的なツール
- Ansible
- Puppet
- Chef
◆Policy as Code
アクセス制御、権限設定、コンプライアンスなどの「ルール」そのものをコード化する手法。
代表的なツール
- OPA（Open Policy Agent）
- Kyverno
- HashiCorp Sentinel
◆Security as Code（SaC）
セキュリティを開発プロセスに組み込み、自動化する手法。
代表的なツール
- Checkov
- Trivy
“as Code” がもたらす共通の価値
✅ 1. 再現性の確保
コードで管理することで、何度実行しても同じ結果が得られるため、人手作業の “手順のブレ” がなくなる。
- 「昨日は動いたのに今日は動かない…」が減る
- 作業ミスや属人化が減る
- 同じ環境を簡単に複製できる（Dev、QA、Prod など）
✅ 2. 変更の可視化（Diff で比較できる）
コードは Git で管理できるため、変更点が一目でわかる。
- 何を、誰が、いつ、どう変更したかが追える
- 変更に対するレビュー（Pull Request）ができる
- 誤操作が減り、透明性が高まる
✅ 3. 自動化による速度向上
コード化 → 自動適用 → 自動検証 の流れを作れるため、
- 新しい環境構築が早い
- 作業時間が大幅に減る
- 一貫した CI/CD のフローを構築できる
✅ 4. バージョン管理による安全性と復元性
「コード＝履歴が残るもの」なので、
- 過去バージョンへロールバックできる
- 不具合が発生したときの原因調査がしやすい
- 複数チームの協業がしやすい
✅ 5. 標準化とガバナンス強化
コードに要件・ルール・設定が明示されるため、
- 組織全体で同じパターンやベストプラクティスを共有できる
- ルールの逸脱（スノーフレーク環境）が減る
- セキュリティとコンプライアンスの維持が簡単になる
🌟 AI 時代における「as Code」のメリット
AI によってコーディングが劇的に高速化されている今、as Code の価値はさらに高まっています。
🧩 メリット 1: AI がコード化を手伝ってくれるため、自動化のハードルが下がる
AI は以下を高速で生成できます：
- IaC 設定ファイル（Terraform、Bicep、CloudFormation など）
- CI/CD パイプライン定義（GitHub Actions, Azure DevOps YAML）
- ポリシーコード（OPA Rego、Azure Policy）
- Dockerfile、k8sマニフェスト など
＝誰でも高度な自動化ができる時代に
🧩 メリット 2: AI の提案や生成物をコードとしてレビューできる
AI が生成した設定は必ず人間がレビューしたいですが、設定が UI 操作だと変更理由がわかりにくい。
コードなら：
- Diff で AI の変更点が明確
- 必要に応じて修正・否決できる
- 自動テストにかけられる
＝AI と人の協調開発がしやすい
🧩 メリット 3: AI 学習データとして扱いやすい
コードは構造化されており、
- 大規模言語モデルが扱いやすい
- パターン化・テンプレ化しやすい
- 過去の変更履歴を元に改善案を生成できる
＝AI に “組織全体のインフラ知識“ を学習させやすい
🧩 メリット 4: 「AI が作ったブラックボックス設定」を防げる
AI に全部丸投げすると、設定の意図や依存関係が追えずブラックボックス化しがち。
コード化しておけば、
- 意図が明示される
- 自動テストと lint がかけられる
- 将来的な人間の理解を保てる
＝ガバナンスを失わない
✨ まとめ
🟦 as Code の共通価値
- 再現性
- 可視化（Diff）
- 自動化
- バージョン管理
- ガバナンス強化
🟩 AI 時代における as Code のメリット
- AI がコード生成を助け、自動化がさらに容易に
- 生成物をコードレビューできるため安全性が高い
- AI の学習データとして有用
- ブラックボックス化を防げる
🌐 “Everything as Code” の時代へ
“as Code” の本質は、人間の知識・手順・意図をコード化し、機械が解釈できる形にすることです。
“as Code” は AI と親和性の高い開発スタイルと言えるでしょう。
その延長線上にあるのが、
Everything as Code（EaC）
というトレンドです。
AIフレンドリーな手法として、as Code は今後増えていくのではないでしょうか。