エージェントループアーキテクト（ループエンジニアリング）

エージェントループアーキテクト（ループエンジニアリング） は何をしますか？

概要

Agent Loop Architectは、クローズドループの反復処理、永続メモリ、状態追跡を通じて複雑なマルチステージエージェントワークフローを調整するための実行標準および設計パターンです。

エージェントの実行を1回限りのプロンプトや線形パイプラインとして扱うのではなく、Agent Loopは、サブエージェントが専門化し、客観的な検証ゲートを通じて作業を検証し、実行を重ねるごとに体系的に学習する反復ライフサイクルを強制します。

ループの2つの黄金律

1. 事前学習なしに実行してはならない: いかなるソリューションを提案または実装する前に、エージェントはLearnフェーズを実行し、メモリ内の既存の肯定的および否定的パターンを参照しなければなりません。
2. 圧縮なしに完了してはならない: コードやコンテンツが書かれた時点でサイクルは終了しません。Compressフェーズが結果をメモリに蒸留し、状態を更新した後にのみ完了します。

flowchart TD
    Start([タスク開始]) --> Learn[1. LEARN: .loop-memory/ を取り込む]
    Learn --> Plan[2. PLAN: ステージ分割 & etapas.json]
    Plan --> Exec[3. EXECUTE: 専門サブエージェントをディスパッチ]
    Exec --> Verify{4. VERIFY: 客観的ゲートを通過?}
    Verify -- No: 回帰/ピボット --> Learn
    Verify -- Yes --> Compress[5. COMPRESS: メモリを蒸留 & 状態を更新]
    Compress --> Done([ループ完了])

---

ループの5フェーズ

各ループサイクルは厳密に5つのフェーズを経て進行します。

フェーズ1: Learn（実行前の取り込み）

• 必須チェック: サブエージェントは以下を読み込む必要があります:
  • .loop-memory/positive-cases/（成功パターン、検証済み修正、高コンバージョンのコピーアングル、最適なプロンプトテンプレート）
  • .loop-memory/negative-cases/（アンチパターン、失敗した仮説、エッジケースの回帰、禁止されたアプローチ）
• 目標: エージェントが以前文書化されたミスを繰り返すのを防ぎ、実証済みのパターンの再利用を強制する。

フェーズ2: Plan & Orchestrate（状態の初期化）

• 目的を個別の順序付けられたステージに分割する。
• etapas.jsonを初期化または更新し、ステージのステータス、割り当てられたサブエージェント、入力、出力、合格基準を記録する。
• ドメイン要件に合わせた専用のサブエージェントロールを割り当てる。

フェーズ3: Execute（専門サブエージェントのディスパッチ）

• ステージの依存関係に基づき、サブエージェントを順次または並行して実行する。
• サブエージェントは分離されたコンテキストで作業し、会話の履歴全体ではなく、簡潔な成果物や差分を受け渡す。

フェーズ4: Verify & Evaluate（客観的合格ゲート）

• 実行出力を明示的かつ自動化または決定論的な基準（例: 単体テスト/結合テストの結果、lint、ファクトチェック引用、トーン準拠）に対して検証する。
• 検証に失敗した場合:
  • その失敗を中間的な否定的パターンとして文書化する。
  • 失敗フィードバックを添えてLearn/Planに戻る。
• 検証に合格した場合:Compressへ進む。

フェーズ5: Compress（実行後のメモリ蒸留）

• 肯定的蒸留: 成功した正確なパターン、テンプレート、プロンプト断片、またはコード修正を抽出し、.loop-memory/positive-cases/CASE-<ID>.mdに書き込む。
• 否定的蒸留: 行き止まり、却下された仮説、回帰を.loop-memory/negative-cases/CASE-<ID>.mdに文書化する。
• 状態の最終化: etapas.jsonを完了タイムスタンプ、最終成果物、実行メトリクスで更新する。

---

ディレクトリ構造とメモリアーキテクチャ

Loopパターンを採用するすべてのプロジェクトは、以下のルートまたはワークスペース構造に準拠する必要があります:

<project-root>/
├── .loop-memory/
│   ├── positive-cases/
│   │   ├── CASE-001-fix-auth-race-condition.md
│   │   └── CASE-002-high-conversion-cold-hook.md
│   └── negative-cases/
│       ├── CASE-001-failed-jwt-in-localstorage.md
│       └── CASE-002-clickbait-hook-bounce.md
├── etapas.json
├── references/
│   └── domain-examples.md
└── SKILL.md

メモリーケーススキーマ（.loop-memory/*/CASE-*.md）

各ケースファイルは、この標準化されたマークダウンテンプレートに従う必要があります:

# ケース: [短い説明的タイトル]
- **日付:** YYYY-MM-DD
- **ドメイン:** [エンジニアリング | コピーライティング | セールス | リサーチ]
- **タイプ:** [ポジティブ | ネガティブ]
- **トリガー/コンテキスト:** [正確な状況、エラーメッセージ、またはプロンプトの目標]

## パターン/テクニック
[何がうまくいったか、またはなぜ失敗したかの詳細な説明]

## 具体的な成果物/コードスニペット/プロンプト
```[言語]
[具体的なスニペット、テンプレート、または差分をここに貼り付ける]

教訓とヒューリスティック

• Do: [将来のエージェントのための実践可能なルール]
• Don't: [避けるべきこと]

### `etapas.json` スキーマ

`etapas.json`ファイルは、現在のライフサイクルの進行状況を追跡します:

```json
{
  "project": "agent-loop-project",
  "loop_version": "2.0.0",
  "updated_at": "2026-11-06T21:00:00Z",
  "current_stage": "fix",
  "stages": [
    {
      "id": "reproduce",
      "role": "QA Reproducer Subagent",
      "status": "completed",
      "input": "Bug report #402",
      "output": "tests/repro_spec.ts",
      "memory_consulted": ["CASE-001-fix-auth-race-condition.md"]
    },
    {
      "id": "fix",
      "role": "Core Fix Engineer Subagent",
      "status": "in_progress",
      "input": "tests/repro_spec.ts",
      "output": null,
      "memory_consulted": []
    }
  ],
  "metrics": {
    "total_cycles": 1,
    "positive_patterns_harvested": 0,
    "negative_patterns_avoided": 1
  }
}

---

統合ドメインアーキタイプ

Agent Loop Architectには、実戦で検証済みの4つのドメインパイプラインが含まれています。各アーキタイプの完全なステップバイステップの手順とプロンプトについては、domain-examples.mdを参照してください。

1. バグ修正とエンジニアリング

• パイプライン: 再現 -> 根本原因 -> 修正 -> テスト -> 文書化
• 学習チェック: 関連サブシステムの以前の修正を取り込み、過去の回帰を回避する。
• 検証ゲート: 再現テストがREDからGREENに変わること。コロラテラルテストの破壊がないこと。
• 圧縮: 根本原因の説明と最小限の修正差分を.loop-memory/positive-cases/に保存する。

2. コンテンツとコピーライティング

• パイプライン: オーディエンスとアングル調査 -> フックとナラティブ草案 -> 批評とトーンの洗練 -> 校正とファクトチェック -> 配信パッケージング
• 学習チェック: トップパフォーマンスのフックと禁止されているバズワード/クリシェを読む。
• 検証ゲート: 目標読解レベル、ブランドボイスの評価スコア $>$= 8.5/10、検証済みの事実主張。
• 圧縮: 高パフォーマンスのアングルとフックの公式をメモリに収穫する。

3. セールスアウトリーチ

• パイプライン: ICP分析 -> 価値仮説 -> パーソナライズされたシーケンス -> 反論対応 -> ディスパッチ準備
• 学習チェック: 価値提案、反論パターン、無効な仮定に対する応答率を照会する。
• 検証ゲート: 具体性チェックリスト（汎用的な差し込み行なし）、スパムガイドラインへの準拠。
• 圧縮: パーソナライゼーションフックの成功例を保存し、応答率の低いアングルを否定的ケースに記録する。

4. リサーチ、財務・法務分析

• パイプライン: 発見とソース取り込み -> ファクトチェックとリスクマトリックス -> 定量/法務統合 -> シナリオストレステスト -> エグゼクティブブリーフィング
• 学習チェック: 過去の事例、過去の分析見落とし、データ妥当性基準を取り込む。
• 検証ゲート: 100%の引用元追跡。ストレスシナリオに対してテストされたリスクマトリックス。
• 圧縮: 統合テンプレート、ソース信頼性評価、リスクアセスメントのヒューリスティックを保存する。

---

サブエージェントディスパッチガイドライン

ループ内でサブエージェントをディスパッチする際のガイドライン:

1. ロールの具体性: 汎用エージェントにプロンプトを与えてはいけません。プロンプトの先頭にドメインロールの指示を付けてください（例: あなたはQA Reproducer Subagentです...）。
2. メモリインジェクション: サブエージェントの初期プロンプトには、常に関連する.loop-memory/ケースのパスまたは要約を提供してください。
3. 離散的なハンドオフ: サブエージェントは、会話履歴ではなく、明示的なファイル（例: 再現スクリプト、ドラフトファイル、評価ルーブリック）を介して通信する必要があります。
4. 自律的ステップゲート: サブエージェントは、検証可能な証拠（ログ、テスト出力、検証スコア）なしにetapas.jsonのステータスを"completed"に進めることは許可されません。

---

よくある間違いとアンチパターン

アンチパターン	ループを破る理由	正しい実践
Learnフェーズのスキップ	エージェントが既知のバグを再発明したり、却下されたコピーアングルを使用したりする。	すべてのプロンプトのステップ0として.loop-memory/の読み込みを強制する。
Compressフェーズの省略	セッションコンテキストがリセットされるとすぐに教訓が失われる。	成功/失敗のケースをファイルに蒸留せずにタスクを完了させてはならない。
モノリシックなエージェント実行	単一のエージェントが計画、コーディング、検証、文書化を同時に行おうとして混乱する。	個別のステージごとに専門化されたサブエージェントをディスパッチする。
ソフトな検証（「よさそう」）	幻覚が本番環境に紛れ込む。	決定論的ゲートを使用する: テストスイート、linter出力、ファクト引用。
無制限のリトライループ	エージェントが修正不可能な欠陥に対して無限にループする。	ループのリトライを3回に制限し、その後人間によるエスカレーションゲートをトリガーする。