Zenn
📝

コードと設計書の乖離はAIで埋められるのか？ “生きた設計書”を作るアプローチ

に公開
AI
Git
document
設計
開発プロセス
idea

1. AI開発時代でも消えない普遍的な悩み

私たちはいま、生成AIを日常的に使う「AI開発時代」に生きています。

コード補完やテスト自動化、レビュー支援まで、AIは多くの場面でエンジニアを助けてくれるようになりました。

それでもなお、開発現場では耳にする言葉があります。

「その設計書、古いですよ」。

リリースされた瞬間から、設計書はコードの進化から取り残されていきます。
機能改善やリファクタリング、緊急のバグ修正。こうした 「最新の設計意図」 は、コードレビューのコメントや Pull Request（PR）のやり取りの中にこそ熱をもって存在しているはずです。

しかし、その情報が設計書に戻ることはほとんどありません。
結果として設計書は信頼を失い、“読む価値のないもの”へと形骸化してしまいます。

やがて「結局コードを読め」という文化が根付き、ドキュメントと実装の溝は深まっていく──。

AI開発時代になり、コード生成・修正の速度は飛躍的に向上しました。しかし皮肉なことに、この高速化により設計書との乖離は従来以上に加速しているように感じています。

2. 課題整理

ではなぜ、設計書を最新に保てないのでしょうか。
その背景には、個人の怠慢ではなく開発プロセスに根ざした構造的な問題が潜んでいるように思えます。

  1. 更新コストの高さ
    設計変更のたびに文章や図を修正するのは大きな負担です。

  2. 差分の追従が困難
    コードと設計の影響範囲を人力で追い続けるのは難しいのが現実です。

  3. “意図”の蒸発
    「なぜこの設計にしたのか」という背景はチャットやPRに散らばり、時間とともに失われてしまいます。

こうした問題は単にドキュメントが古びる以上の影響を生みます。
属人化、レビューの手戻り、新人オンボーディングの非効率…。
どれもチームの開発力を削ぐ要因になっているのではないでしょうか。

3. AIでの解決アプローチ

この課題にどう向き合えばよいのでしょうか。
ここで考えてみたいのが、「設計ドキュメントを自動再生産する」アプローチです。

これは単にコードから設計書をリバース生成するのとは違います。
PRやレビューコメントに込められた“設計意図”をAIが翻訳し、設計書に反映することを目指す点に特徴があります。

(1) コード差分から設計意図を抽出

PR がマージされるとき、AIが差分とコメントを解析し「なぜ、どう変わったのか」を要約できるとしたらどうでしょう。

例：「従来の同期処理による性能問題を解決するため、通知機能を非同期キューイング方式（SQS）に変更しました。」

もしAIが設計判断の背景まで言語化してくれるなら、それを設計書に取り込む価値があるはずです。

(2) 設計書へのマッピング

次のステップは、その要約を既存の設計書にマッピングすることです。
「第3章『アーキテクチャ概要』に追記が必要」といった更新候補が自動で示されれば、設計書を常に最新に近づけることができます。

設計図を PlantUML や Mermaid で管理していれば、図の更新をAIに任せられる可能性も広がります。

(3) Docs-as-Codeとの統合：AIを「レビュー可能な提案者」として扱う

ここで最も重要なのは、AIを「全自動の書き換えツール」ではなく**「レビュー可能な提案者」**として扱う点です。

もしAIがドキュメントを直接書き換えてしまったらどうなるでしょう。その変更は誰の承認も得ていない「ブラックボックス」な更新となり、「いつの間にか変わっていた」「この記述は本当に正しいのか？」という新たな不信感を生む原因になりかねません。それでは本末転倒です。

そこで鍵となるのが、Docs-as-Code と Pull Request (PR) を組み合わせるアプローチです。

Docs-as-Code とは
設計書や仕様書などのドキュメントを、ソースコードと同じようにテキストファイル（Markdownなど）で記述し、Gitなどのバージョン管理システムで管理する手法のこと。コードレビューやCI/CDといったソフトウェア開発のプラクティスをドキュメントにも適用できるのが大きな利点です。

この考え方に基づき、AIはドキュメントの「更新案」をPRとして作成する役割を担います。

この仕組みのメリットは明確です。

  • 透明性と合意形成: AIによる提案はPRとして可視化され、コードレビューと同じようにチームで議論できます。マージするという行為は、その設計変更に対する 「チームの公式な承認」 を意味します。
  • 品質の担保: 人間がレビューすることで、AIの誤解や不適切な表現を防ぎ、ドキュメントの品質を担保します。
  • 履歴の追跡可能性: 「なぜこの設計書が更新されたのか」が、関連するコードのPRと紐づいた形でGitの履歴に残り、後から誰でも追跡できます。

つまり、AIはチームメイトの一員として設計書の更新案をPRで提出し、人間がそれをレビューして承認する。この仕組みによって、設計書はコードと同じ厳格な品質管理のライフサイクルに乗り、信頼性を保ちながら進化していくのです。

4. 実現イメージ（フロー）

この仕組みを CI/CD に組み込むと、次のような流れが考えられます。

  1. トリガー: フィーチャーブランチが main にマージされる
  2. 情報収集: CI/CDが PR の差分とコメントを取得する
  3. AI解析: 設計意図の要約と更新案を生成する
  4. PR作成: Docsリポジトリに自動でPRを送信する
  5. レビュー: 人間が内容を確認して承認 → 設計書が更新される

これは現実的に導入を検討できるフローではないでしょうか。

5. 期待できる効果

もしこのアプローチを取り入れられたら、次のような効果が期待できます。

  • 設計書がコードと共に進化し続ける
  • 新メンバーが「設計の物語」を追体験できる
  • 設計意図が形式知化され、属人化を防げる
  • レビューや設計判断の背景が体系的に残る資産になる

6. 乗り越えるべき課題と注意点

もちろん、このアプローチは万能薬ではありません。実現に向けては、いくつかの技術的な課題と、それを乗り越えるための運用上の原則を理解しておく必要があります。

技術的な課題

  • 自然言語処理の限界: 開発者のPRコメントは往々にして簡潔で文脈に依存するため、AIが設計意図を正確に読み取れない可能性があります。
  • 設計判断の複雑性: 重要な設計決定は、明文化されない暗黙知や組織的な制約に基づくことも多く、PRの情報だけでは不十分な場合があります。
  • 誤検知のリスク: 些細なリファクタリングを重要な設計変更と誤認し、不要な更新を提案してしまう可能性もあります。

守るべき運用原則

  • AIによる誤解を許容する: 上記の課題から、AIが意図と異なる要約をする可能性は常にあります。提案はあくまで「下書き」と捉えるべきです。
  • 情報の冗長化を避ける: 軽微な修正まで記録するとノイズが増える恐れがあるため、重要な変更のみを対象とするフィルタリングが有効です。
  • 人間のレビューを必須とする: 最終的な品質を担保するのは人間です。「AIと人の協働」という前提は揺らぎません。

これらの課題はありますが、完璧を求めるのではなく 「現状よりも設計書を生きた状態に近づける」 ことを目標とすれば、十分に検討に値するアプローチだと考えています。

7. 実現に向けた第一歩：AIプロンプトのテンプレート

この記事で提案したアイデアを、どのように実現するのか。ここでは、その心臓部となるAIの思考を再現するための、具体的なプロンプトテンプレートを共有します。

CI/CDパイプライン（例: GitHub Actions）から、大規模言語モデル（LLM）のAPIを呼び出す際に、このテンプレートを利用することを想定しています。

このプロンプトが実現すること

このプロンプトは、AIに以下の3つのタスクを段階的に実行させ、Pull Requestの情報から 設計書の更新差分（Markdown Diff） を生成させることを目的とします。

  1. 設計意図の抽出: PRのコード差分と議論から「なぜこの変更が行われたのか」を読み解く。
  2. 設計書へのマッピング: 抽出した意図を、既存の設計書のどの部分に反映すべきか特定する。
  3. 更新差分の生成: 人間がレビューしやすいように、具体的な更新案を差分形式で出力する。

プロンプトを利用するための準備

このプロンプトを機能させるには、CI/CDスクリプトが以下の情報を収集し、プロンプト内の {} で示されたプレースホルダーに埋め込む必要があります。

  • {PR_TITLE}: プルリクエストのタイトル
  • {PR_BODY}: プルリクエストの本文（説明文）
  • {REVIEW_COMMENTS}: プルリクエストで行われた主要なレビューコメントのやり取り
  • {CODE_DIFF}: 主要なコードの差分 (git diff の出力)
  • {EXISTING_DOCS_TOC}: 既存の設計書の目次
  • {EXISTING_DOCS_SECTION_CONTENT}: 更新対象となりそうな設計書の章・節の現在の内容

プロンプトサンプル

# Role
あなたは、経験豊富なソフトウェアアーキテクトであり、ドキュメントの達人です。開発チームのメンバーが作成したPull Requestの内容を深く理解し、その変更が持つ「設計上の意図」を読み解き、既存の設計書を常に最新の状態に保つ役割を担っています。

# Goal
提供されたPull Requestの情報から、設計上の重要な変更点を特定し、関連する設計書セクションの更新案をMarkdownの差分形式で生成してください。重要なのは、単なるコードの変更内容（What）ではなく、その背景にある設計思想やアーキテクチャ上の決定（Why）を反映させることです。

# Input Data

## 1. Pull Request Information
- PR Title: {PR_TITLE}
- PR Body:
"""
{PR_BODY}
"""
- Review Comments:
"""
{REVIEW_COMMENTS}
"""
- Code Diff:
"""
{CODE_DIFF}
"""

## 2. Existing Design Document Information
- Table of Contents (目次):
"""
{EXISTING_DOCS_TOC}
"""
- Content of Potentially Relevant Section(s) (更新対象となりそうな章・節の現在の内容):
"""
{EXISTING_DOCS_SECTION_CONTENT}
"""

# Instructions
以下のステップに従って、思考し、最終的なアウトプットを生成してください。

### Step 1: Analyze Design Intent (設計意図の分析)
まず、提供されたPR情報を総合的に分析し、この変更がもたらす最も重要な「設計上の意図」を1〜2文で要約してください。
- この変更は、どのような課題を解決しようとしているか？
- 新しい技術やアーキテクチャパターンが導入されたか？
- ユーザー体験やシステムの非機能要件にどのような影響があるか？

### Step 2: Identify Target Section (更新対象セクションの特定)
Step 1で分析した設計意図を反映させるのに最も適切と思われる設計書の章・節を、提供された目次から1つ特定してください。

### Step 3: Generate Update Suggestion (更新提案の生成)
特定したセクションの既存の内容を踏まえ、Step 1の設計意図を反映させるための具体的な追記・修正案を文章で作成してください。既存の文章のトーン＆マナーに合わせてください。

### Step 4: Generate Markdown Diff (Markdown差分の生成)
Step 3で作成した更新提案を、人間がレビューしやすいようにMarkdownの差分（diff）形式で出力してください。
- 追記する行は `+ ` から始めてください。
- 削除する行は `- ` から始めてください。
- 変更がないコンテキスト行も数行含めてください。
- もし、更新が不要だと判断した場合は、その理由を明確に述べてください。

# Output Format
以下のJSON形式で、思考プロセスと最終的な成果物を出力してください。

```json
{
  "analysis": {
    "design_intent_summary": "（ここにStep 1で要約した設計意図を記述）",
    "target_section": "（ここにStep 2で特定した章・節の名前を記述）",
    "update_suggestion_text": "（ここにStep 3で作成した更新提案の文章を記述）"
  },
  "markdown_diff": "```diff\n（ここにStep 4で生成したMarkdown差分を記述）\n```",
  "reason_if_no_update": "（更新が不要な場合に理由を記述。更新がある場合はnull）"
}
```

実現に向けたヒントと注意点

  • コンテキストウィンドウ: CODE_DIFF や設計書の全文は長大になる可能性があります。長文コンテキストに対応したモデルを選ぶか、関連性の高い部分だけを抽出する前処理が重要になります。
  • プロンプトのチューニング: これは汎用的なテンプレートです。あなたのチームの設計書のフォーマットやPRの文化に合わせて、「Instructions」などをカスタマイズすることで、出力精度はさらに向上するはずです。
  • RAGの活用: より高度なシステムを目指すなら、Vector Databaseなどで設計書全体を検索可能にし、AIが更新対象をより賢く見つけ出すRAG (Retrieval-Augmented Generation) の導入が非常に有効です。

8. まとめ：設計と実装の健全なサイクルを回すために

設計書の形骸化は、AI開発時代になっても残り続ける課題です。
しかし、AIを「設計意図の翻訳者」として活用し、Docs-as-Codeの仕組みに組み込むことで、設計書をコードと同じように進化させることができるかもしれません。

これは設計書を「死んだ成果物」から「生きた知識資産」へと変えるための一つのアプローチです。

日本の開発現場では「設計書を書いてから実装する」という流れが長らく基本でした。今回の提案はそれを否定するものではなく、むしろその伝統的なプロセスをさらに強化します。

「設計→実装」の過程で発生した細かな仕様変更や、実装してみて初めてわかった技術的制約といった “現場の発見”を、即座にPRとして設計書にフィードバックする ループを構築できるのです。これにより、設計と実装の乖離を早期に検知・修正できるだけでなく、初期設計そのものが実装を通じてより洗練され、進化していくことになります。

これは、「設計→実装」という一方通行の流れを、「設計 ⇆ 実装」という双方向の健全なサイクルに変える試みです。AIと共に、設計書を生きた存在として育てていく。そんな新しい開発文化を検討してみる価値があるのではないでしょうか。

この記事で提案した内容は、まだアイデア段階の取り組みかもしれません。しかし、設計書の形骸化という根深い課題に対して、「AIと人間の協働」という新しい角度からアプローチする価値はあるはずです。小さなプロトタイプから検証を始めるなど、あなたのチームでの取り組みの出発点として、この記事が何かのきっかけになれば幸いです。

Discussion