# 概要设计书自动生成 Agent 实现计划

> 版本: v1.0 | 日期: 2026-07-21 | 状态: 初版
>
> 术语对照：本文件中「書き方ルール」= 设计文档中的「写入规则」，「設計ルール」=「设计规则」，「参考設計文書」=「参考文档」。

---

## 阶段总览

| 阶段 | 名称 | 预计工作量 | 核心产出 |
|------|------|-----------|---------|
| 1 | プロジェクト基盤・共通ツール | 大 | FileReader, CodeParser, ImageAnalyzer + プロジェクト構造 |
| 2 | Parser Agent - Excel解析 | 大 | ExcelParser（Table/FreeText/Formatting） |
| 3 | Parser Agent - Word/PPT解析 + 現行システム探索 | 中 | WordParser, PPTXParser, ExistingSystemExplorer |
| 4 | RAG Infrastructure | 中 | ルールハンドブック構築・検索・バージョン管理 |
| 5 | Impact Agent | 大 | 要素抽出・関連推論・影響調査書生成 |
| 6 | Web UI | 大 | ファイルアップロード・確認画面・生成実行画面 |
| 7 | Writer Agent | 大 | 章構成生成・テンプレート埋め込み・RAG連携 |
| 8 | QA Agent | 中 | フォーマット検証・内容検証・規則遵守検証 |
| 9 | 統合テスト・調整 | 大 | エンドツーエンド試験・エラー処理・性能調整 |
| 10 | 成果物整備 | 中 | README・実験レポート・デモ動画・最終調整 |

> 凡例: 大（3-5日） / 中（1-3日） / 小（0.5-1日）

---

## フェーズ 1: プロジェクト基盤・共通ツール

### 目標
プロジェクト構造の確立、全Agentが依存する共通ツールの実装。

### タスク一覧

| # | タスク | 詳細 |
|---|-------|------|
| 1.1 | プロジェクト構造作成 | `src/` 下のディレクトリ構成、`pyproject.toml`、依存関係定義（詳細: docs/config-design.md の統一構成スキーマ） |
| 1.2 | 共通データモデル定義 | Provenance, CellValue, StructuredSource 等のデータクラス（data_models.py）。設計 §9.4 のモデルは章間で相互参照するため、**ファイル先頭で `from __future__ import annotations` を有効化**し、定義順序に依存しないこと |
| 1.3 | FileReader 実装 | ファイル読み取り統一インターフェース（.xlsx / .docx / .pptx / .java / .xml / .yml） |
| 1.4 | CodeParser 実装（Phase 1） | Java/Spring Boot のディレクトリ走査・Controller/Service/Entity 抽出 |
| 1.5 | ImageAnalyzer 実装 | Vision LLM 接続・画像認識・結果構造化（LLM依存の抽象化） |
| 1.6 | InferenceEngine 実装 | 統一推理引擎：LLMプロバイダー抽象化（DeepSeek/Qwen）、chat/chat_structured、モデル管理、リトライ・タイムアウト・フォールバック、Token管理（詳細: docs/agent-runtime-design.md §2） |
| 1.7 | Prompt テンプレートライブラリ | PromptRegistry 実装（テンプレート登録・バージョン管理） |
| 1.8 | ToolExecutor 実装 | 統一ツール実行器＋ToolCallEvent 打点（詳細: docs/agent-runtime-design.md §5） |
| 1.9 | セッション状態機械実装 | 会话级状态机（8状態）＋状態遷移白名单＋確認イベント永続化（詳細: docs/agent-runtime-design.md §3） |
| 1.10 | MemoryService 実装 | 3層メモリ（長期/作業/短期）＋AgentState 受け渡し（詳細: docs/agent-runtime-design.md §4） |
| 1.11 | 可観測性イベント基盤 | LLMCallEvent / ToolCallEvent イベントストリーム＋SQLite イベント表 |
| 1.12 | AI使用ログ基盤 | `_AI_USAGE_LOG.md` 自動追記機構 |

### 検収基準
- FileReader が .xlsx / .docx / .pptx を読み取り UnifiedDocument を返せる
- CodeParser が Java Spring Boot プロジェクトの Controller/Service/Entity を抽出できる
- ImageAnalyzer が Vision LLM を呼び出し画像説明を返せる
- InferenceEngine がモデル切替・構造化出力・リトライ/フォールバックを正しく動作させる
- セッション状態機械が 8 状態の合法/非法遷移を正しく判定し、確認イベントを永続化する
- 単体テストが通る

---

## フェーズ 2: Parser Agent - Excel解析

### 目標
要件定義Excelを解析し、StructuredSource に変換する。

### タスク一覧

| # | タスク | 詳細 |
|---|-------|------|
| 2.1 | ExcelParser 基本構造 | Sheet 読み取り・セル値取得・データ型変換 |
| 2.2 | SheetDetector 実装 | Sheet 名 + 表頭からのタイプ自動判定（FUNCTION/SCREEN/REPORT/DATABASE/INTERFACE/BATCH/MASTER/GENERIC） |
| 2.3 | Sheet性質判定 | テーブル型/自由記述型/混合型 の自動判別 |
| 2.4 | TableExtractor（構造化テーブル型） | 行列解析・ヘッダー行検出・データ行抽出 |
| 2.5 | MergeHandler 実装 | 結合セルの検出・下行填充（forward_fill） |
| 2.6 | FreeTextParser（自由記述型） | 全セルテキスト結合 → LLMに渡して構造化 |
| 2.7 | FormattingDetector 実装 | 取消線検出・非表示行/列検出・コメント抽出 |
| 2.8 | ProvenanceAnnotator | 全セルに source_uri を付与 |
| 2.9 | ExcelParser 統合テスト | 各種Excelパターンに対するテスト（テーブル型/自由記述型/混合型/取消線あり/結合セルあり） |

### 検収基準
- 3種類のExcelパターン（テーブル型/自由記述型/混合型）を正しく解析できる
- 結合セルの下行填充が正しい
- 取消線行が検出・除外マークできる
- 各セルに source_uri が付与されている
- 単体テストカバレッジ > 80%

---

## フェーズ 3: Parser Agent - Word/PPT解析 + 現行システム探索

### 目標
Wordテンプレート・ルール文書・PPTルール文書・現行システムの解析。

### タスク一覧

| # | タスク | 詳細 |
|---|-------|------|
| 3.1 | WordTemplateParser 実装 | 章構成（Heading階層）抽出、占位符（{{section:xxx}}）検出、スタイル抽出 |
| 3.2 | RuleDocParser（Word） 実装 | ルール文書のMarkdown化、ルール分類（書き方ルール / 設計ルール） |
| 3.3 | PPTXParser 実装 | PPTからのテキスト抽出、スライド構成の保持 |
| 3.4 | ExistingSystemExplorer - コード探索 | CodeParser を利用して現行コードから Controller/Entity/API 抽出 |
| 3.5 | ExistingSystemExplorer - 設計書探索 | 既存Word/Excel設計書の解析 → 現行構成データ生成 |
| 3.6 | SourceAggregator 実装 | 全パーサーの出力を統一的 StructuredSource にまとめる |
| 3.7 | Parser Agent 統合テスト | 全入力パターンに対する統合テスト |

### 検収基準
- Wordテンプレートの章構成が正しく抽出できる
- ルール文書がMarkdown化され「写入规则」「设计规则」に分類される
- PPTからテキストが抽出できる
- 現行システムのコードと設計書から構成データが生成できる
- 統合テストが通る

---

## フェーズ 4: RAG Infrastructure

### 目標
ルール文書からルールハンドブックを構築・検索・バージョン管理する仕組み。

### タスク一覧

| # | タスク | 詳細 |
|---|-------|------|
| 4.1 | ルール文書のインデックス化 | 分類済みルールの分割（Word/Excel/PPT フォーマット適応）→ Embedding → ベクトルストア構築（詳細: docs/rag-layer-design.md §3, §4） |
| 4.2 | StorageAdapter 実装 | VectorStoreAdapter 抽象＋ChromaAdapter＋MockAdapter（詳細: docs/rag-layer-design.md §9） |
| 4.3 | ハイブリッド検索API | ベクトル（bge-small-zh-v1.5）＋BM25 双チャネル＋RRF 融合の実装（詳細: docs/rag-layer-design.md §6） |
| 4.4 | ルールハンドブックのバージョン管理 | ドキュメント級インクリメンタル更新（hash比較）＋manifest＋セッションロックバージョン（詳細: docs/rag-layer-design.md §5） |
| 4.5 | ルール衝突検出・ユーザー確認 | ConflictDetector＋ユーザー確認フロー＋意思決定記録（詳細: docs/rag-layer-design.md §7） |
| 4.6 | 「ルールを更新」UI連携 | Web UI からの更新トリガー → 再インデックス化 |
| 4.7 | 設計ルールの Impact Agent 連携 | 設計ルールを Impact Agent の関連推論に渡す仕組み |

### 検収基準
- 書き方ルールを章単位で検索できる（例：「機能一覧のルール」で検索→該当ルール返却）
- ハイブリッド検索（ベクトル+BM25+RRF）が正しく融合結果を返す
- ルールハンドブックのバージョン管理が正しく動作する（ドキュメント級インクリメンタル更新含む）
- ルール更新→再インデックス化のフローが通る
- ルール衝突が検出され、ユーザー確認フローが動作する

---

## フェーズ 5: Impact Agent

### 目標
StructuredSource から影響調査書を生成する。

### タスク一覧

| # | タスク | 詳細 |
|---|-------|------|
| 5.1 | Step 0: 変更箇所特定 | 新規/追加/変更/削除の自動識別（追加改修シナリオ） |
| 5.2 | Step 1: 要素抽出（LLM呼出） | StructuredSource → 構成要素抽出のプロンプト設計・実装 |
| 5.3 | Step 2: コメント分析 | コメントのLLM分析・分類・重要度判定（先分析、不明なら質問） |
| 5.4 | Step 3: 関連推論（LLM呼出） | 要素間関連推論のプロンプト設計・証拠抽出・置信度判定 |
| 5.5 | クロスチェック・矛盾検出 | 複数証拠による置信度補正・循環参照検出・孤立要素検出 |
| 5.6 | Step 4: 影響マトリックス構築 | Relations → 双方向マトリックス変換 |
| 5.7 | Step 5: 影響調査書出力 | 中間成果物（JSON）の構造定義と出力 |
| 5.8 | 品質指標計算 | provenance_chain, coverage_markers, orphan_warnings, risk_flags |
| 5.9 | Impact Agent 統合テスト | 新規開発・追加改修・自由記述型Excel の各シナリオテスト |

### 検収基準
- 新規開発シナリオで正しい要素抽出と関連推論ができる
- 追加改修シナリオで変更箇所特定と影響分析ができる
- 影響調査書が設計通りの構造で出力される
- 矛盾検出・孤立要素警告が機能する
- 各関連に証拠（evidence）と置信度が付与されている

---

## フェーズ 6: Web UI

### 目標
ユーザーとの対話インターフェース。

### 画面構成

```
Web UI
├── ファイルアップロード画面
│   ├── 要件定義Excel (必須)
│   ├── 设计书模板 (必須)
│   ├── 规则文档 (任意, 複数)
│   ├── 現行システムファイル (任意)
│   └── アップロード進捗表示
│
├── Probe 確認画面
│   ├── Sheet タイプ判定結果 (修正可能)
│   ├── テンプレート章構成プレビュー
│   ├── 現行システム探索結果 (あれば)
│   └── [確認して次へ]
│
├── Impact 確認画面
│   ├── 要素一覧 (展開/折畳み)
│   ├── 関連一覧（逐条修正可能）
│   │   ├── 追加/削除/種類変更/証拠修正
│   │   ├── 確信度フィルタリング
│   │   └── 修正履歴表示
│   ├── 不確かさ一覧（ユーザー回答入力）
│   ├── 品質指標（孤立要素・リスク警告）
│   └── [確認完了 → Writerへ進む]
│
├── 生成実行画面
│   ├── 生成進捗表示（何章目を生成中…）
│   ├── エラー発生時の選択肢（リトライ/続行/中断）
│   └── 完了通知
│
├── 結果プレビュー画面
│   ├── 生成設計書のプレビュー
│   ├── ダウンロード（Word形式）
│   └── ルールハンドブック管理（更新ボタン）
│
├── ルール管理画面
│   ├── 現在のルールハンドブックバージョン表示
│   ├── 「ルールを更新」ボタン
│   └── バージョン履歴
│
└── 共通: エラーダイアログ / 進行状態表示 / ヘルプ
```

### タスク一覧

| # | タスク | 詳細 |
|---|-------|------|
| 6.1 | フロントエンドプロジェクト設定 | React + TypeScript + ルーティング |
| 6.2 | ファイルアップロード画面 | ドラッグ&ドロップ・複数ファイル対応・進捗表示 |
| 6.3 | Probe 確認画面 | Sheet タイプ確認・修正・テンプレートプレビュー |
| 6.4 | Impact 確認画面 | 要素一覧・関連一覧（逐条修正UI）・不確かさ入力・品質指標表示 |
| 6.5 | 生成実行画面 | 進捗表示・エラー対話・途中再開 |
| 6.6 | 結果プレビュー画面 | Wordプレビュー・ダウンロード |
| 6.7 | ルール管理画面 | バージョン表示・更新トリガー・履歴 |
| 6.8 | バックエンドAPI実装 | Orchestrator + REST API（FastAPI）＋WebSocket イベント（詳細: docs/api-design.md の端点リスト・状態遷移・TaskQueue 抽象） |
| 6.9 | Web UI 統合テスト | 全画面遷移テスト・エラーシナリオテスト |

### 検収基準
- 全画面遷移が正常動作
- ファイルアップロードからダウンロードまでエンドツーエンドで動作
- 異常系（ファイル不正・LLM失敗）でエラーダイアログが表示されユーザー選択可能
- 影響調査の逐条修正が反映される

---

## フェーズ 7: Writer Agent

### 目標
影響調査書 + StructuredSource + RAGルール から設計書を生成する。

### タスク一覧

| # | タスク | 詳細 |
|---|-------|------|
| 7.1 | 章構成管理 | テンプレートから抽出した章構成の管理と生成順序制御 |
| 7.2 | ルール検索連携 | 各章生成時に RAG から関連ルールを取得 |
| 7.3 | 設計ルール連携 | Impact Agent から設計ルールの制約を受けて生成 |
| 7.4 | データ抽出 | StructuredSource から当該章に必要なデータを抽出 |
| 7.5 | 関連情報連携 | ImpactReport から当該要素の関連関係を抽出 |
| 7.6 | プロンプト設計（章ごと） | 各章（機能一覧/画面一覧/DB設計/…）の生成プロンプト設計 |
| 7.7 | テンプレート注入 | docxtpl による Word テンプレート充填 |
| 7.8 | 記入規則プロンプト設計 | 書き方ルールをプロンプトに組み込む戦略 |
| 7.9 | Writer Agent 統合テスト | 全章生成テスト・ルール遵守テスト |

### 検収基準
- テンプレートの各章に正しい内容が注入される
- 書き方ルールに沿った生成がされる
- 設計ルールの制約が反映される
- 生成内容に source_uri の Provenance が付与されている
- ルール遵守の単体テストが通る

---

## フェーズ 8: QA Agent

### 目標
生成された設計書の品質を検証する。

### タスク一覧

| # | タスク | 詳細 |
|---|-------|------|
| 8.1 | フォーマット検証 | テンプレートとのスタイル一致性チェック（フォント・サイズ・色・表書式）＝10項目中 #1 |
| 8.2 | 内容検証 | 要件定義のデータが正しく反映されているか（LLM検証）＝10項目中 #2,#3,#4 |
| 8.3 | ルール遵守検証 | RAG から取得したルールと生成内容の一致性チェック＝10項目中 #5,#6,#7,#9 |
| 8.4 | 可追溯性検証 | 各生成内容に source_uri が付与されているか＝10項目中 #8 |
| 8.5 | 章構成完整性検証 | テンプレート章構造との対比（欠章検出）＝10項目中 #10 |
| 8.6 | QAレポート出力＋Writerフィードバック | 検証結果レポート生成＋エラー章のみ Writer へフィードバック（再生成ループ）|
| 8.7 | QA Agent 統合テスト | 各種不備パターンの検出テスト |

> 詳細: docs/design.md §7（QA 10項目チェックリスト・二重検証方針・フィードバックループ）

### 検収基準
- フォーマット不備（フォント違い・サイズ違い）を検出できる
- 要件定義にない内容を hallucination として検出できる
- ルール違反を検出できる
- 検証レポートが正しく出力される
- エラー章のみ Writer へフィードバックされ再生成される

---

## フェーズ 9: 統合テスト・調整

### 目標
全 Agent の連携動作確認、エラーシナリオの網羅、性能調整。

### タスク一覧

| # | タスク | 詳細 |
|---|-------|------|
| 9.1 | エンドツーエンドテスト | ファイルアップロード→設計書ダウンロード の全フローテスト（サンプルデータ: docs/sample-spec.md に基づく `samples/` の 7 ファイル） |
| 9.2 | 異常系テスト | ファイル不正・LLM失敗・ネットワーク切断・途中中断→再開 |
| 9.3 | 性能テスト | 大規模Excel（1000行以上）・多数ルール文書・大規模現行コード |
| 9.4 | プロンプト調整 | 各種シナリオでプロンプトの精度検証・改善 |
| 9.5 | エラーメッセージ調整 | 全エラーケースのメッセージ確認・ユーザーフレンドリーな表現 |

### 検収基準
- 3つの実サンプルデータ（新規/追加改修/自由記述型）で正常動作
- 異常系シナリオで正しいエラー処理とユーザー選択肢表示
- 10MB以上のExcelでも性能問題なく動作

---

## フェーズ 10: 成果物整備

### 目標
大会提出用成果物の完成。

### タスク一覧

| # | タスク | 詳細 |
|---|-------|------|
| 10.1 | README 作成 | インストール手順・実行方法・環境要件・API Key設定・依存関係 |
| 10.2 | 実験レポート | テストケース一覧・実行結果・成功率・エラー率・改善点 |
| 10.3 | AI使用ログ整理 | 全開発過程の AI 使用ログ確認、范式步骤の最終調整 |
| 10.4 | デモ動画作成 | 動作デモ（15分以内）・正常フロー + 例外処理 |
| 10.5 | 最終動作確認 | クリーン環境でのインストール→動作→アンインストール確認 |

### 検収基準
- README 通りに進めてクリーンインストール・動作可能
- 実験レポートに全テスト結果と評価データが記載されている
- AI使用ログが全過程をカバーしている
- デモ動画が正常フローと例外処理を含む

---

## 依存関係グラフ

```
Phase 1 (基盤: 共通ツール + 运行时层)
    │  FileReader/CodeParser/ImageAnalyzer
    │  InferenceEngine / ToolExecutor / 状态機械 / MemoryService / 可観測性
    ▼
Phase 2 (Excel解析) ──────────────────┐
    │                                    │
    ▼                                    │
Phase 3 (Word/PPT/現行探索)             │
    │                                    │
    ├────────────────────────────────────┘
    │                                    │
Phase 4 (RAG) ────────────────────────┤
    │                                    │
    ▼                                    │
Phase 5 (Impact Agent) ────────────────┤
    │                                    │
    ▼                                    │
Phase 6 (Web UI) ←─────────────────────┘
    │
    ▼
Phase 7 (Writer Agent) ─── Phase 8 (QA Agent)
    │
    ▼
Phase 9 (統合テスト)
    │
    ▼
Phase 10 (成果物整備)
```

## リスクと注意点

| リスク | 影響 | 対策 |
|-------|------|------|
| LLM のプロンプト結果が不安定 | 各Agentの出力品質に直結 | プロンプトは早期にプロトタイプ作成、大量テスト |
| ルール文書のバリエーションが未知 | RAGの精度に影響 | 複数パターンのルール文書で早期テスト |
| 現行システムのコード解析が不完全 | 追加改修シナリオの品質低下 | 設計書ベースの現行把握で補完、コード解析は段階的 |
| Web UI の開発工数が大きい | 全体スケジュールに影響 | バックエンド先行開発、UIは後追いでOK |
| 大会期限（11月） | 時間制約 | MVP（最小機能）を早期確立し、段階的に拡張 |