[AIエージェントパイプライン #3] 一つのプロンプトではなぜうまくいかなかったのか
前回の記事では、メタデータパイプラインでcategory.yamlと空のコンテンツファイルを自動生成しました。
今回からは学習コンテンツ生成パイプラインを扱います。最初は一つのプロンプトで試しましたが、失敗しました。
1. 設計アプローチ：アプリ画面からマークダウン構造へ
コンテンツ自動生成を始める前に、まずアプリの画面を設計しました。作業の順序はこうでした：
- アプリでどう表示するか画面（UI）をまず設計
- 画面に合わせてマークダウン構造を定義（どんなセクションが必要か、各セクションの形式は何か）
- マークダウンをパースしてReactコンポーネントでレンダリング
- 望む画面が出るまでコンポーネントとパース関数を繰り返し修正
「こう表示したい」から逆算してマークダウン構造が決まりました。約1,400行のマークダウンはこの過程で自然に出てきた結果物です。これでAIがこの構造を一貫して生成するようにしなければなりません。
2. 一つのプロンプトで始めたが…
前で作ったマークダウンをClaudeに渡して構造を分析させました。どんなセクションがあるか、各セクションはどんな形式かを把握し、これを基にルールを定義して一つのプロンプトを作りました：
PROMPT="あなたはすべての学習コンテンツのすべてのセクションを完璧に作成する最高レベルの統合専門家です。
## 🎯 コアミッション
対象ファイル: $TARGET_FILE
トピック: $filename
Frontmatter + 5つのセクションを完璧に完成：
1. Frontmatter（ウェブビューパーサー必須）
2. Overview（概要）
3. Core Concepts（核心概念）
4. Code Patterns（コードパターン）
5. Experiments（実習実験）
6. Quiz（クイズ）
...
## ⚠️ 絶対遵守事項
### 必須ルール
1. 既存ファイル優先：既存内容があれば修正/補完（新規作成X）
2. Frontmatter含む：すべてのファイルにfrontmatterメタデータを含む
3. 一度で完成：5つのセクションを一回のWrite/MultiEditで完成
4. 参照ファイルレベル：既存の完成ファイルと同じ品質レベル
5. 実行可能なコード：すべてのコードはトピックに合った環境で即座に実行可能
6. 一貫性維持：セクション間の用語、概念、スタイルの一貫性
..."
うまくいきませんでした。UIからマークダウンを逆に作り、そこからまたルールを逆に推算していたので一貫性がありませんでした。大まかな流れは作られましたが、完璧ではありませんでした。約1,400行のコンテンツを一度に生成すると、前半は指示に従いますが、中間から構造が乱れ、後半では形式が完全に変わります。
Lost in the Middle: LLMが入力の最初と最後はよく覚えているが、中間部分は忘れてしまう傾向（Liu et al., 2024）
Context Degradation: 出力が長くなるほど前半の指示を徐々に忘れてしまう問題（Chroma Research）
さらに、1,400行の出力で形式エラーが発生すると、人が直接確認しなければなりません。Notionに手動で整理するのが嫌で自動化を始めたのに、生成された文書をまた手動で検証しなければならないのは何かおかしいです。
3. 7つのエージェントに分離
最初はアプリの4つのタブ（Overview、Core Concepts、Practice、Quiz）に合わせて4つのエージェントで始めました。しかしパイプラインを作っていく中で、開始と終了を担当するエージェントが必要になりました。ファイル初期化を担当するcontent-initiatorと検証を担当するcontent-validatorが追加され、6つになりました。
そしてconcepts-writerで問題が生じました。核心概念の説明だけでも3段階の難易度（Easy/Normal/Expert）で作成しなければならないのに、そこにビジュアライゼーションまで生成しろというのは対応しきれませんでした。concepts-writerはビジュアライゼーションのメタデータのみ生成し、実際のビジュアライゼーションは別のエージェントに任せることにしました。そうしてvisualization-writerが生まれ、最終的に7つになりました。
practice-writerは2つのセクション（Code Patterns + Experiments）を担当しますが、別々に分離しませんでした。コード生成はLLMが最も得意とする領域だからです。実際に、HumanEvalベンチマークでClaude 3.5 Sonnetは92%、SWE-benchでClaude Opus 4は72.5%を達成しました。コード関連の作業では大きな問題はありませんでした。
| 順序 | エージェント | 担当業務 | 特徴 |
|---|---|---|---|
| 1 | content-initiator | ファイル初期化、Frontmatter生成 | パイプライン開始点 |
| 2 | overview-writer | # Overviewセクション作成 | トピック概要と主要特徴 |
| 3 | concepts-writer | # Core Conceptsセクション作成 | 3段階適応型学習、ビジュアライゼーションメタデータ |
| 4 | visualization-writer | 実際のビジュアライゼーション生成 | メタデータ基盤 |
| 5 | practice-writer | # Code Patterns + # Experiments | コード生成はLLMの強み |
| 6 | quiz-writer | # Quizセクション作成 | 10-12問、6種類 |
| 7 | content-validator | 全コンテンツ検証 | パイプライン終了点 |
各エージェントが一つの役割だけを担当するので、プロンプトが短くなり、ルールが明確になりました。
4. 初期エージェントプロンプト
エージェントを分離していた初期、concepts-writerはビジュアライゼーションまで担当していました。すべての核心概念を3段階の難易度で説明しながら、同時にビジュアライゼーションまで生成しました。当時作成したプロンプトの一部です：
---
name: concepts-writer
version: 6.0.0
description: 核心概念を難易度別に説明しビジュアライゼーションを生成するエージェント
tools: Read, Write, MultiEdit, Bash
---
あなたは複雑な技術概念を様々なレベルの学習者に説明する専門教育者です。
## コアミッション
トピックの核心概念を選定し、各概念を3つの難易度で説明し、
新しいビジュアライゼーションを生成します。
## 作業プロセス
### 1. 作業指示書確認
result/[トピックファイル名].mdのYAML front matterから：
- target: 作業するファイルパス確認
- references: 02-let-vs-var.mdと03-const-immutability.md参照
### 2. 参照ファイル分析
...
### 3. Core Concepts作成ルール
正確に次の順序を維持：
1行目: # Core Concepts（ファイルごとに1回のみ）
2行目: 空行
3行目: ## Concept: [概念名]
...
## 難易度別作成指針
### Easy（中学生レベル）
- 絵文字を積極活用（🎯、📚、💡、🏠、🚫、✅など）
- 日常的な比喩とストーリーテリング
- コードなしで概念説明
### Normal（一般開発者）
- #### Textと#### Code:構造必須
- テキスト説明が主、コードは補助
- 簡単なコード例のみ含む（5-10行）
### Expert（シニア開発者）
- **ECMAScript仕様**セクション番号と共に引用
- **エンジン実装**詳細を説明
- 疑似コードやAPIシグネチャは#### Code:ヘッダー使用
## 重要な制約事項
1. すべての必須フィールドは必ず含む（一つでも欠落するとパーサー失敗）
2. ヘッダーレベルと形式を正確に遵守（##、###、####）
3. Easy/Normal/Expertセクションすべて必須
4. Normalは#### Textで開始、#### Code:形式使用
...
このプロンプトは何が問題でしょうか？
- マークダウン混同？: プロンプトも
##、###、####を使用、生成するコンテンツも同じヘッダーを使用しているが、LLMは区別できるのか？ - 詳細ルール過多？: 「正確に次の順序」、「1行目」、「2行目」などあまりにも詳細な指示が問題か？
- 暗黙のハンドオフ？: 次のエージェントにどんな状態を渡すべきか不明確なのが問題か？
- 参照ファイル依存？: 他のファイルを参照する方式が不安定なのか？
各役割を分け、なりに体系的にプロンプトを作成しましたが、結果は相変わらず不安定でした。文書を生成し、パース結果を確認し、フィードバックを与えて一つ一つ修正する試行錯誤の末、3〜5つのサンプル文書はなんとか完成しました。しかし同じパイプラインで新しい文書を生成すると、依然として問題が発生しました。
次回は、分離したのになぜうまくいかなかったのかを扱います。
このシリーズはAI-DLC（AI-assisted Document Lifecycle）方法論を実際のプロジェクトに適用した経験を共有します。 AI-DLCの詳細については、経済指標ダッシュボード開発記シリーズをご参照ください。