# プロダクトビジョン

最終更新: 2026-02-20 <!-- Phase 3 の方針を修正：分析・提案はエージェントに委ねる -->

## 1. Vision Statement

Yagra は、AIコーディングエージェントを"専属のチューナー"に変える、
LLM ネイティブなエージェント開発・最適化ライブラリである。

重厚な UI や独自ホストの分析基盤を持たず、
**「開発者の IDE（手元環境）で完結する AgentOps」** を実現するための極めて軽量な OSS ライブラリとして、
YAML 宣言型ワークフロー定義 × LangGraph 実行基盤 × AI フレンドリーな観測・最適化サイクルを提供する。

**差別化ポジション**：
Langfuse・Datadog 等の「人間がダッシュボードのグラフを見て分析する重厚な SaaS」は目指さない。
Yagra は「AI が AI を評価・改善する（LLM-as-a-Judge や自己改善ループ）」ための
データ収集と橋渡し（MCP 連携）に特化した、**圧倒的に AI フレンドリーな OSS ライブラリ**である。

## 2. 対象ユーザー

- LangGraph を使う LLM アプリケーション開発者（コアターゲット）
- コーディングエージェント（Claude Code, Cursor, Copilot 等）を活用して Vibe Coding でワークフローを構築・最適化する開発者
- プロンプトやフロー改善に関わる PM / ドメインエキスパート
- ワークフロー改善に参加する非エンジニア（業務担当者・オペレーター）
- 承認・レビューフローを AI ワークフローに組み込みたいエンタープライズ開発者
- GitHub Actions / CI パイプラインでワークフロー品質を担保したい DevOps エンジニア

## 3. 解決する課題

- プロンプトエンジニアリングやエージェントのチューニングが「職人芸」になりがちで、特定のコアメンバーに負荷が集中する（属人化・時間的コストの増大）。
- LangGraph のフロー構造やプロンプト設定が Python コードと密結合し、改善のたびに実装コストが高い。
- ワークフロー実行時の詳細なログ（各ステップの実行時間、トークン消費、入出力データ、エラー等）が構造化された形で出力されず、コーディングエージェントが分析・改善提案を行えない。
- 既存の観測ツール（Langfuse, Datadog 等）は人間向けのダッシュボードを前提としており、AI エージェントが直接読み取り・解析するための標準フォーマットを提供していない。
- LangFlow・Flowise 等の GUI ツールは Git 管理・CI 統合・差分レビューができず、チーム開発・本番運用での品質担保が困難。

## 4. 提供価値 — 開発・最適化サイクル

UI をポチポチ操作するのではなく、人間とコーディングエージェントの「対話（Vibe Coding）」によって以下のサイクルを回す。

### Phase 1: 構築（Build）

ユーザーが普段使っているコーディングエージェント（Cursor, Copilot, Claude Code 等）に「こういう CS エージェントを作って」と指示。
エージェントが MCP 経由で、Yagra 仕様の YAML ワークフロー定義を生成・構築する。

- **Schema-Driven**: Pydantic スキーマで YAML 記述ミスを早期検知する。
- **Registry Pattern**: YAML 上の文字列定義と Python 関数を疎結合に接続する。
- **Zero-Boilerplate**: グラフ構築コードを毎回書かず、YAML 差し替えで異なるワークフローを実行できる。
- **AI-Ready Schema**: JSON Schema + 意味情報 + 修正提案により、エージェントが自律的に生成→検証→修正ループを回せる。
- **Template Library**: 典型パターンのテンプレートでエージェントおよび開発者の立ち上がり速度を向上させる。

### Phase 2: 実行と計測（Run & Observe）

ユーザーがワークフローを実行する。
Yagra ライブラリは、各ステップの実行時間、トークン消費、入出力データ、エラーなどの詳細なログを、
**「LLM（コーディングエージェント）が最も読み取りやすく、解析しやすい標準フォーマット」** でローカルに出力する。

- **Structured Execution Log**: ノード単位の実行時間・トークン消費・入出力スナップショット・エラー情報を構造化 JSON で出力する。
- **AI-Friendly Format**: 人間向けダッシュボードではなく、コーディングエージェントが直接パースし分析できるフォーマットに特化する。
- **Local-First**: 外部サービスへの送信なし。ログはローカルファイルに出力し、Git 管理・IDE 内参照で完結する。
- **Multi-Run Aggregation**: 複数回の実行結果を集約し、傾向分析の基盤を提供する。

### Phase 3: 分析と提案（Analyze & Propose）

出力されたログをコーディングエージェントに読み込ませる。
エージェントがログを分析し、「ステップ B のプロンプトの指示が曖昧でエラー率が高いです。このように修正・分岐させませんか？」とユーザーに改善案をフィードバックする。
Yagra はデータ収集と構造化出力に徹し、分析・提案の生成はコーディングエージェントに委ねる。

- **MCP Analysis Tools**: MCP サーバー経由でエージェントが実行ログを取得・集約サマリを参照できるツールを提供する。
- **Quality Metrics**: ノード別の成功率・レイテンシ分布・トークン効率などの品質指標を集約し、エージェントが分析しやすい構造化 JSON で出力する。

### Phase 4: 承認と最適化（Approve & Update）

ユーザーが「うん、それいいね。採用」と承認する。
コーディングエージェントが再び YAML を修正し、ワークフローが最適化される。

- **Git-Native**: ワークフロー変更は YAML ファイルの差分として Git で管理・レビューできる。
- **CI Integration**: `yagra validate` を GitHub Actions に組み込み、PR ごとにワークフロー変更を自動検証できる。
- **Safe Iteration**: 変更履歴・ロールバック・diff プレビューにより安全に反復改善できる。

### 基盤機能（継続改善）

- **Workflow Studio WebUI**: フロー構造の可視化・編集を WebUI で提供し、非エンジニアも参加できる開発体験を維持する。ただし、新たな分析専用ダッシュボードは開発しない。
- **Human-in-the-Loop**: YAML 宣言だけでワークフロー中断・再開ポイントを定義でき、人間のレビュー・承認を実行フローに組み込める。
- **Data Flow Visibility**: グラフ上の各ノードの入出力変数をバッジで可視化し、データフローを視覚的に追跡できる。

## 5. 成功状態

### Phase 1 既達成（v0.6.x）

- 開発チームが Python コード変更なしで、YAML 更新のみでフロー構成変更を反映できる。
- 主要な設定ミスを実行前に検出できる。
- 非エンジニアが WebUI 上でフローを理解・編集・運用できる。
- コーディングエージェントが JSON Schema を参照して有効なワークフロー YAML を生成し、自律的に検証・修正ループを回せる。
- MCP サーバー経由でエージェントが CLI を介さず直接 Yagra 機能を呼び出せる。
- HITL・Git+CI 統合・テンプレートライブラリが整備されている。

### v1.0 目標

- ワークフロー実行時に、ノード単位の実行時間・トークン消費・入出力・エラー情報が構造化ログとして自動出力される。
- コーディングエージェントが実行ログを読み取り、ボトルネック・エラーパターン・コスト効率を分析し、改善提案をユーザーにフィードバックできる。
- ユーザーがエージェントの改善提案を承認すると、エージェントが YAML を修正し、Build → Run & Observe → Analyze & Propose → Approve & Update の最適化サイクルが手元環境で完結する。
- 上記サイクルの全工程がローカル完結（外部 SaaS 不要）で、Git + CI と自然に統合できる。

## 6. やること / やらないこと

### やること
- 「AI が AI を評価・改善する」ためのデータ収集と橋渡し（MCP 連携）に特化する。
- コーディングエージェントが直接読み取り・解析できる AI フレンドリーなログフォーマットを策定・実装する。
- LangGraph ベースのワークフロー実行基盤を引き続き強化する。
- 既存 WebUI（Workflow Studio）の継続改善。

### やらないこと
- Langfuse・Datadog のような人間がダッシュボードで分析するための重厚な SaaS。
- 新たな分析専用 UI / ダッシュボード画面の開発。
- ホスティングコストを伴うクラウドサービス。
- LangGraph 以外の実行基盤への主軸変更（当面）。

## 7. 将来展望

- プロンプト自動最適化（DSPy, Agent Lightning 等）との統合。Yagra の `prompt_ref` によるプロンプト分離構造は、外部オプティマイザーとの統合に適した設計である。
- 「AI がワークフローを生成し、AI がプロンプトを最適化し、人間がレビュー・承認する」サイクルを YAML + Git ベースで実現する。
- 実行ログの分析から自動的に A/B テスト候補を生成し、最適なワークフロー構成を提案する機能。
- VS Code Extension による YAML エディタ統合（スキーマバリデーション・プレビュー・テンプレート挿入）。
- GitHub Actions 公式アクション（`yagra-ai/validate-action`）の提供。
- **エージェントによるエージェントの自律生成**：コーディングエージェントが自身のタスクを分析し、より効率的・効果的に遂行するために Yagra YAML でサブエージェント（ワークフロー）を動的に生成・実行・改善するサイクル。エージェントが「道具を使う」のではなく「道具を生み出す」存在になることで、複雑なタスクを自律的にさばく未来を目指す。

## 8. Vision の再設定ルール

- Build → Run & Observe → Analyze & Propose → Approve & Update の最適化サイクルが実用水準で回らない場合は、ログフォーマットまたは MCP ツール設計を見直す。
- コーディングエージェントが実行ログを分析しても有用な改善提案を生成できない場合は、ログの粒度・構造・メタデータを再設計する。
- LangGraph 以外の実行基盤への主軸変更を判断した時点で見直す。
- 既存 WebUI の改善が利用者の体験向上に寄与しない場合は、WebUI の方針を再評価する。
- 競合ツールが「AI フレンドリーなローカル完結 AgentOps」の軸でキャッチアップしてきた場合は、差別化軸を再評価する。

## 9. 関連ドキュメント

- ユーザー到達状態ゴール: `docs/product/goals.md`
- 到達ステップと実装項目: `docs/product/milestones.md`
