AIに複雑なビジネスロジックを解説させ技術ドキュメントへ変換するためのプロンプト集

属人化コードをAIで仕様書化する：一発生成の失敗を防ぐプロンプトチェーン設計と実装ガイド

2026年1月5日約13分で読めます

文字サイズ:

属人化コードをAIで仕様書化する：一発生成の失敗を防ぐプロンプトチェーン設計と実装ガイド

この記事の要点

複雑なビジネスロジックのAIによる解析とドキュメント化
属人化されたレガシーコードの仕様書自動生成
単一プロンプトの限界を超えるプロンプトチェーン設計

はじめに：AIに「コード解説」を丸投げしてはいけない

「このレガシーコード、ドキュメントがないからAIに解説させて仕様書を作ろう」

そう考えてChatGPTやClaudeに数百行のコードを貼り付け、「これを分かりやすく解説して」と指示を出したことはありませんか？そして、返ってきた結果を見てこう思ったはずです。「表面的なコードの翻訳に過ぎない」「肝心のビジネスルールが抜けている」「もっともらしい嘘（ハルシネーション）が混ざっている」と。

AIソリューションエンジニアとして、低スペックな環境下など現場の制約の中で最適解を導き出し、開発から運用までの全体最適を追求する立場から見れば、このアプローチは失敗しやすいと言えます。複雑なビジネスロジックを含んだコードを、文脈（コンテキスト）なしに単一のプロンプトで処理させるのは、新人のエンジニアに仕様書も渡さずに「これ読んどいて」と言うのと同じだからです。

AIによるドキュメント生成を実務レベルで成功させる鍵は、「一発生成」を諦め、処理を適切な粒度に分割してパイプライン化することにあります。これを「プロンプトチェーン」と呼びます。

本記事では、属人化したコードから正確で保守可能な仕様書を生成するための、アーキテクチャ設計と具体的なプロンプト技術を解説します。単なるテキスト生成にとどまらず、Mermaid記法を用いたフロー図の自動生成や、品質を担保するための検証プロセスまで踏み込みます。技術的負債をビジネス価値を生む資産へと変換する、実用的なエンジニアリングアプローチを解説します。

1. 統合の概要：なぜ「一発生成」では失敗するのか

多くのエンジニアが陥る罠、それはLLM（大規模言語モデル）の能力を過信し、複雑なタスクを一度に処理させようとすることです。特に既存コードの仕様書化においては、以下の3つの理由から、単一プロンプトでの生成はほぼ確実に失敗します。

複雑なロジックにおけるコンテキスト欠落の問題

ソースコードには「How（どのように実装されているか）」は書かれていますが、「Why（なぜそのロジックなのか）」や「What（業務的な意味は何か）」は明記されていません。例えば、if (total > 50000 && user.rank == 'A') というコードがあったとき、AIはそれを「合計が5万以上かつランクAの場合」と翻訳することはできます。しかし、それが「大口優良顧客向け特別割引適用条件」であることは、外部の知識（ドメイン知識）がなければ理解できません。

一発生成のアプローチでは、このドメイン知識を注入する隙間がなく、結果として実装の詳細になぞっただけの、ビジネス価値の低いドキュメントが生成されます。

トークン制限と注意機構（Attention）の分散

数千行に及ぶクラスファイルやモジュールを一度に入力すると、LLMの注意機構（Attention Mechanism）が分散します。モデルは入力の「どこに注目すべきか」の重み付けを行いますが、情報量が多すぎると、重要なビジネスロジック（例外処理や境界値条件など）が見落とされ、一般的な定型処理の解説に埋もれてしまうのです。

「抽出」「構造化」「検証」の3段階プロセスの必要性

人間が他人のコードを読んで仕様書を書くプロセスを想像してください。

まずコードを読み解き、何が行われているかメモを取る（抽出）
メモを整理し、章立てや図解を行う（構造化）
書いた内容がコードと矛盾していないか確認する（検証）

これらは全く異なる脳の使い方をします。AIも同様です。これらを1つのプロンプトで同時に行わせようとすると、指示が競合し、どのタスクも中途半端になります。本ガイドでは、この3つの工程を明確に分離し、それぞれの出力を次の入力とするパイプラインを構築します。

2. 統合アーキテクチャとプロンプトチェーン設計

統合アーキテクチャとプロンプトチェーン設計 - Section Image

成功するドキュメント生成システムは、製造業のラインのようなものです。ここでは、実務において推奨される「ドキュメント生成パイプライン」の全体像を設計します。

データフロー：ソースコードからドキュメントまでの変換経路

このアーキテクチャは、Chain of Thought（思考の連鎖）をシステムレベルで実装したものです。以下の3つのステージを経由させます。

Extraction Stage (抽出):
ソースコードを入力とし、実装の詳細を削ぎ落とした「中間表現（Intermediate Representation）」を出力します。ここでは自然言語による箇条書きや、JSON形式でのロジック抽出を行います。
Structuring Stage (構造化):
中間表現を入力とし、ターゲット読者（PM、非エンジニアなど）に合わせたフォーマットへ変換します。ここでMarkdownやMermaid記法の図解を生成します。
Validation Stage (検証):
生成されたドキュメントと元のソースコードを比較し、矛盾や幻覚（ハルシネーション）がないかをチェックします。

役割分担：AIエージェントの定義

各ステージでAIに与える「ペルソナ（役割）」を明確に区別します。

解析エージェント (The Analyst):
- 役割: シニアエンジニア
- 任務: コードを読み、事実のみを抽出する。推測は行わない。
- 出力: ロジックリスト、データフローデータ
執筆エージェント (The Technical Writer):
- 役割: テクニカルライター
- 任務: 解析結果を読みやすく整形し、図解する。
- 出力: 仕様書ドラフト（Markdown + Mermaid）
レビューエージェント (The Auditor):
- 役割: QAエンジニア
- 任務: ドラフトとコードを突き合わせ、誤りを指摘する。
- 出力: 修正指示書または承認サイン

コンテキストウィンドウを考慮した入力データの分割戦略

巨大なモノリシックなコードを扱う場合、ファイル単位ではなく「機能ブロック単位」または「メソッドチェーン単位」で分割してパイプラインに投入します。依存関係のある関数や定数定義は、別途「参照コンテキスト」としてプロンプトのヘッダーに付与する設計にします。

3. 前提条件とコンテキスト準備

プロンプトを投げる前に、AIに「予習」をさせる必要があります。汎用的なLLMを、組織専属のエンジニアに変えるための準備です。

ドメイン知識の注入：用語集とビジネスルールの定義

コード内の変数名 cust_type_flg が「顧客区分フラグ」であることをAIは推測できますが、0: 一般, 1: VIP, 9: ブラックリスト という値の意味までは知り得ません。これらを定義した「ドメイン辞書」を用意します。

最新のAI開発環境（CursorやGitHub Copilotなど）では、プロジェクトルートにコンテキスト定義ファイル（.cursorrulesやCLAUDE.mdなど）を配置することで、この予習を自動化・永続化できます。APIを直接利用する場合は、System Promptに以下の要素を含めてください。

推奨プロンプトパーツ（System Promptに含める）:

# Domain Context
以下の用語定義とビジネスルールを前提として振る舞ってください。
- 用語集:
  - "LTV": Life Time Value。過去3年間の購買実績合計。
  - "仮予約": ステータスコード 10 の状態。
- 定数定義:
  - MAX_RETRY_COUNT = 3
  - TIMEOUT_MS = 5000

参照データの整備：DBスキーマと既存API定義

ビジネスロジックはデータベース操作と密接に関わっています。テーブル定義（DDL）やORMのエンティティ定義をテキスト化し、参照情報として提供することで、AIは「どのデータを操作しているか」を正確に把握できるようになります。

GitHub Copilotを使用している場合は、@workspace コマンドを活用することで、現在開いているファイルだけでなく、プロジェクト全体の定義ファイルや関連ドキュメントをコンテキストとして動的に読み込ませることが可能です。

AIモデルの設定：Temperatureとシステムプロンプトの最適値

Temperature: 0.0 〜 0.2 推奨。ドキュメント生成に創造性は不要です。事実に基づいた決定論的な出力を優先させます。
Model: 複雑な論理推論が必要なため、ChatGPTやClaudeの最新上位モデルが必須です。
- 選定基準: コードの意図を汲み取る「推論能力」と、長いコンテキストを正確に扱える「ウィンドウサイズ」を重視してください。
- 注意点: 軽量モデル（mini版やFlash版など）はコストパフォーマンスに優れますが、複雑なロジックの解釈でハルシネーションや抽出漏れを起こすリスクが高まります。仕様化フェーズでは、コストよりも精度を優先し、その時点で利用可能な最も高性能なモデル（例：推論特化型モデルやハイエンドモデル）を選択することを強くお勧めします。最新情報は各社の公式ドキュメントで確認してください。

4. 実装ステップ1：ロジック抽出プロンプトの構築

実装ステップ1：ロジック抽出プロンプトの構築 - Section Image

ここからが実装の本番です。まずは「解析エージェント」への指示です。ここでのゴールは、コードから「仕様の種」を取り出すことです。

失敗例：悪いプロンプト

まずは、やってはいけない例を見てみましょう。

Bad Prompt:
「以下のPHPコードを読んで、何をしているか分かりやすく説明してください。重要なロジックは漏らさないでください。」

なぜダメなのか:

「分かりやすく」の基準が曖昧。
出力形式が指定されていないため、AIがダラダラと散文を書く。
実装の詳細（変数への代入など）とビジネスロジックが混ざる。

成功例：構造化された抽出プロンプト

以下は、実務の現場で活用されているテンプレートの例です。「役割」「タスク」「制約」「出力形式」を明確に定義します。

Good Prompt (Extraction):

# Role
あなたは経験豊富なバックエンドエンジニアです。レガシーコードの解析とリバースエンジニアリングを専門としています。

# Task
入力されたソースコードから「ビジネスロジック」と「データ操作」のみを抽出し、構造化データとして出力してください。
コードの行ごとの翻訳は不要です。業務上の意図（What/Why）に焦点を当ててください。

# Constraints
- プログラミング言語特有の構文（forループの書き方など）についての解説は省略すること。
- 変数名はそのまま記載せず、コード内のコメントや文脈から推測される「日本語の論理名」を併記すること。
- 条件分岐はすべてのパターン（else句や例外処理含む）を網羅すること。
- 推測を含む場合は、必ず「(推測)」と注釈をつけること。

# Input Code
{{SOURCE_CODE}}

# Output Format
以下のJSONフォーマットのみを出力してください。Markdownのコードブロックで囲むこと。

{
  "function_name": "関数名",
  "summary": "処理の概要（50文字以内）",
  "inputs": [{"name": "変数名", "description": "意味", "validation": "バリデーションルール"}],
  "logic_flow": [
    {"step": 1, "type": "validation|calculation|db_access|external_api", "description": "処理内容", "business_rule": "関連する業務ルール"}
  ],
  "outputs": [{"description": "戻り値の意味", "condition": "返却条件"}]
}

このプロンプトのポイントは、出力をJSON形式に限定している点です。これにより、次の工程での機械処理が可能になり、AIもフォーマットに従おうとするため論理破綻が起きにくくなります。

5. 実装ステップ2：ドキュメント構造化と図解生成

次に、抽出されたJSONデータを元に、人間が読むためのドキュメントを生成します。ここで「執筆エージェント」が登場します。

ドキュメントの標準化とMermaid図の活用

テキストだけの仕様書は誰も読みません。視覚的なフロー図が必要です。しかし、作図ツールで手書きするのは保守コストの増大を招きます。そこで、Mermaid記法をAIに生成させ、ドキュメント内に「コードとしての図」を埋め込みます。

構造化プロンプトの実例

Good Prompt (Structuring):

# Role
あなたは優秀なテクニカルライターです。エンジニアから渡されたロジック情報（JSON）を元に、プロジェクトマネージャー向けの仕様書を作成します。

# Task
入力されたJSONデータを元に、Markdown形式の仕様書を作成してください。また、処理の流れを可視化するためにMermaid記法のフローチャートを含めてください。

# Constraints
- 専門用語には注釈をつけるか、平易な言葉に言い換えること。
- 「ロジックフロー」セクションには、Mermaid記法で `graph TD` を用いたフロー図を記述すること。
- Mermaidのノード内テキストは日本語を使用し、記号（(), []など）の使用ミスがないように注意すること。
- スタイルは「である」調で統一すること。

# Input Data (JSON)
{{EXTRACTED_JSON}}

# Output Format

## 機能概要
(概要記述)

## 入力データ要件
(表形式で記述)

## 処理フロー図
```mermaid
(Mermaidコード)

詳細ロジック

(ステップ名): (詳細説明)
- 業務ルール: (ルール記述)

出力

(説明)


この段階では、ソースコードを直接見せず、ステップ1で抽出したJSONだけを渡すのがコツです。これにより、実装の詳細に引きずられることなく、純粋なロジックに基づいたドキュメントが生成されます。

## 6. 実装ステップ3：整合性検証（Self-Correction）

最後に、生成されたドキュメントが正しいかを検証します。ここでは「レビューエージェント」に、元のコードと生成されたドキュメントの両方を見せ、矛盾がないかチェックさせます。

### ハルシネーションの検知と修正

AIは時として、コードに存在しない「理想的なエラーハンドリング」を勝手に捏造してドキュメントに書くことがあります。これを防ぐためのプロンプトです。

> Good Prompt (Validation):
```markdown
# Role
あなたは品質管理（QA）エンジニアです。ドキュメントの正確性を検証する責任があります。

# Task
「元のソースコード」と「生成された仕様書」を比較し、以下の観点でレビューを行ってください。

# Checkpoints
1. 過剰記述: コードに存在しない処理が仕様書に書かれていないか？（ハルシネーションの検知）
2. 欠落: コードにある重要な分岐（特にエラー処理）が仕様書から漏れていないか？
3. 誤解釈: 変数の意味や条件式の解釈に誤りはないか？

# Input
[Source Code]
{{SOURCE_CODE}}

[Generated Document]
{{GENERATED_DOC}}

# Output
問題がない場合は「PASS」とだけ出力してください。
問題がある場合は、以下の形式で指摘してください。

- 指摘箇所: (仕様書の該当セクション)
- コードの記述: (該当する行番号とコード)
- 誤りの内容: (具体的な矛盾点)
- 修正案: (正しい記述の提案)

この検証ステップをパイプラインに組み込むことで、人間がレビューする前の「一次フィルター」として機能し、ドキュメントの信頼性を劇的に向上させます。

7. 運用と保守：ドキュメントの鮮度維持

苦労してドキュメントを作っても、コードが変更された瞬間にそれは「嘘のドキュメント」になります。これを防ぐには、ドキュメント生成を開発プロセス（CI/CD）に組み込む必要があります。

CI/CDパイプラインへの組み込み

GitHub ActionsやGitLab CIを活用し、以下のワークフローを構築することを推奨します。

Trigger: 特定のディレクトリ（例: src/business_logic/）内のファイルに変更があったPull Requestが作成された時。
Action: 変更されたファイルに対して、前述のプロンプトチェーンを実行。
Result: 生成されたドキュメントをPRのコメントとして投稿、またはドキュメントリポジトリへ自動コミット。

近年の開発プラットフォーム（GitHub Enterpriseの最新版など）では、プロジェクト管理機能やAI活用の幅が広がっています。特にGitHub CopilotなどのAIコーディングアシスタントは、現在ではOpenAI、Anthropic、Googleなどが提供する多様なAIモデルから選択して利用できるようになっています。

これにより、ドキュメント生成タスクには「推論能力の高いモデル」を、日常のコード補完には「高速なモデル」を使い分けるといった運用も現実的です。ただし、利用可能なモデルは定期的に更新・廃止されるため（例えば、Claudeの旧バージョンなどが廃止対象となるケースがあります）、CI/CDパイプラインで使用するモデル設定はハードコードせず、環境変数などで柔軟に変更できるようにしておくことが重要です。

差分検知と自動更新フロー

毎回すべてのドキュメントを再生成するのはコスト（API利用料と時間）がかかります。Gitの差分（diff）を利用し、変更があった関数やクラスのみを対象にドキュメントを更新するスクリプトを組むのが現実的です。

また、生成されたドキュメントのヘッダーには必ず「最終更新日」と「元になったコミットハッシュ」を自動挿入させます。これにより、読み手はそのドキュメントが最新のコードと同期しているかを即座に判断できます。

まとめ：技術的負債を「生きた資産」へ

入力データ要件 - Section Image 3

AIによるドキュメント生成は、単なる作業の効率化ではありません。それは、長年ブラックボックス化していたシステムの中に光を当て、チーム全体で仕様を共有・管理できる状態を取り戻すための「資産化プロセス」です。

重要なポイントを振り返ります。

一発生成を避ける: 「抽出」「構造化」「検証」の3ステップに分割する。
構造化データを経由する: JSONという中間表現を用いることで、正確性を担保する。
検証を自動化する: AIに自己レビューさせ、ハルシネーションを防ぐ。
プロセスに組み込む: CI/CDで継続的に更新し、ドキュメントの陳腐化を防ぐ。

プロンプトチェーンの構築は、最初は手間に感じるかもしれません。しかし、一度パイプラインができあがれば、それは眠らず、文句も言わず、常に最新の仕様書を書き続けてくれる強力なパートナーとなります。まずは、開発現場で最も複雑で誰も触りたがらない「あのコード」から、この手法を試してみてください。

属人化コードをAIで仕様書化する：一発生成の失敗を防ぐプロンプトチェーン設計と実装ガイド - Conclusion Image

参考リンク

GitHub Copilot - AI models

コメントは1週間で消えます

コメントを読み込み中...