# ユーザー到達状態ゴール

最終更新: 2026-03-01 <!-- G-21〜G-26 を追加・Done に更新（Phase 6 全完了） -->

## ゴール一覧

### Phase 1: 構築（Build） — 既達成

| Goal ID | ユーザーが到達したい状態 | 到達判定（Definition of Done） | 状態 |
| --- | --- | --- | --- |
| G-01 | YAML だけで LangGraph フロー構成を定義できる | ノード・エッジ・条件分岐を含む YAML を Pydantic で検証できる | Done |
| G-02 | YAML 定義と Python 実処理を疎結合に接続できる | Registry でノード名から Python callable を解決し、実行に成功する | Done |
| G-03 | YAML 差し替えで複数ワークフローを低コストに運用できる | Graph 構築コードを追加せずに設定変更だけで別フローを起動できる | Done |
| G-04 | 開発運用で品質ゲートを常時維持できる | CI / pre-commit で format・lint・type・test が一貫して通る | Done |
| G-05 | 非エンジニアが WebUI 上でワークフローを可視化・編集し、迷わず運用できる | Read Only 可視化と編集（prompt/model/エッジ接続）を WebUI で行い、round-trip 後も意味整合を維持しつつ、主要操作の導線と視認性が初見ユーザーにとって自己説明的である | Done |
| G-06 | コーディングエージェントが Yagra ワークフローを正確に生成・検証できる | JSON Schema 公開と validate CLI の JSON 出力により、エージェントがスキーマ準拠の YAML 生成→検証→修正ループを実行できる。加えて、テンプレートライブラリにより典型パターンの生成精度が向上している | Done |
| G-07 | LLM ノードのボイラープレート削減と高度な出力制御ができる | 基本的な LLM 呼び出し、構造化出力（Pydantic）、ストリーミングレスポンスをハンドラーユーティリティで簡潔に実装でき、YAML 定義だけで動作する | Done |
| G-08 | YAML で LLM ノードのデータフロー（入出力キー）を宣言的に制御でき、WebUI から設定できる | `input_keys` を廃止しプロンプト変数を自動検出する仕組みにより YAML 記述量を削減し、`output_key` を WebUI から設定できる。handler タイプ別の責務分離（`llm`: 1 キー出力、`structured_llm`: 複数キー構造化出力、`custom`: 自由制御）が明確になっている | Done |
| G-09 | ワークフロー実行中に人間の確認・承認・修正を挟める | YAML で `interrupt_before` / `interrupt_after` を宣言し、`Yagra.invoke()` → 中断 → `Yagra.resume()` のサイクルで実行を制御できる | Done |
| G-10 | WebUI のグラフ上で各ノードの入力変数と出力変数を一目で把握できる | 各ノードがプロンプトで要求する変数（入力）と `output_key`（出力）がグラフノード上にバッジとして表示され、ON/OFF トグルで表示切り替えができる | Done |
| G-11 | コーディングエージェントが Yagra ワークフローを高精度に自律生成・修正できる | スキーマに意味情報（description/examples）が含まれ、バリデーションが修正提案を返し、ハンドラーパラメータが発見可能で、エージェントが生成→検証→修正ループを人間の介入なしに完結できる。加えて、エージェント統合ガイドにより導入手順が明確化されている | Done |
| G-12 | ワークフロー定義を Git で管理し、CI で自動検証できる | `yagra validate` を GitHub Actions に組み込み、PR ごとにワークフロー変更を自動検証できる。変更差分・実行パスの変化が PR コメントとして可視化され、チームがコードレビューと同じ感覚でワークフローをレビューできる | Done |
| G-13 | 多様なユースケースに対応するテンプレートから素早く開発を開始できる | multi-agent・tool-use・human-review 等の実用テンプレートが揃い、`yagra init --list` でユースケース別に選択できる。各テンプレートには動作可能なサンプルコードが付属し、5 分以内に動作確認できる | Done |

### Phase 2: 実行と計測（Run & Observe) — v1.0 目標

| Goal ID | ユーザーが到達したい状態 | 到達判定（Definition of Done） | 状態 |
| --- | --- | --- | --- |
| G-14 | ワークフロー実行時にノード単位の構造化ログが自動出力される | `Yagra.invoke()` 実行時に、各ノードの実行時間・入出力スナップショット・エラー情報を含む構造化 JSON ログがローカルファイルに出力される。ログ出力は opt-in で有効化でき、既存 API の後方互換を維持する | Done |
| G-15 | LLM 呼び出しのトークン消費とコストを実行ログから把握できる | 組み込み LLM ハンドラー（llm/structured_llm/streaming_llm）がトークン使用量（input/output/total）を実行ログに記録する。複数回実行の集計により、ワークフロー全体のコスト傾向を把握できる | Done |

### Phase 3: 分析と提案（Analyze & Propose） — v1.0 目標

| Goal ID | ユーザーが到達したい状態 | 到達判定（Definition of Done） | 状態 |
| --- | --- | --- | --- |
| G-16 | コーディングエージェントが実行ログを MCP 経由で取得・分析できる | MCP サーバーに実行ログ取得ツールが追加され、エージェントが直接ログデータを読み取り、ノード別の成功率・レイテンシ・トークン効率を分析できる | Done |
| G-17 | 複数回の実行結果を集約し、品質傾向を把握できる | 実行ログの集約機能により、ノード別の成功率・平均レイテンシ・トークン消費の傾向をサマリとして構造化 JSON で出力できる。コーディングエージェントが MCP 経由でサマリを取得し、分析・改善提案に活用できる | Done |

### Phase 4: 承認と最適化（Approve & Update） — v1.0 目標

| Goal ID | ユーザーが到達したい状態 | 到達判定（Definition of Done） | 状態 |
| --- | --- | --- | --- |
| G-18 | エージェントの改善提案に基づき YAML を安全に更新できる | エージェントが分析結果に基づいて YAML 修正を提案し、ユーザーの承認後に変更が適用される。変更は Git diff として追跡可能で、`yagra validate` による自動検証を経て品質が担保される | Done |
| G-19 | Build→Observe→Analyze→Update の最適化サイクルを手元環境で完結できる | 上記 G-14〜G-18 の全工程がローカル完結（外部 SaaS 不要）で動作し、コーディングエージェントとの対話によって反復的にワークフローが改善される。サイクル 1 周を 30 分以内に完了できる | Done |

### Phase 5: 回帰検証（Regression Test） — v1.1 目標

| Goal ID | ユーザーが到達したい状態 | 到達判定（Definition of Done） | 状態 |
| --- | --- | --- | --- |
| G-20 | ワークフロー変更後にゴールデンケースベースの回帰検証ができる | 既存トレースからゴールデンケースを保存し、ワークフロー YAML 変更後に `yagra golden test` で実行パス・ノード入出力の回帰を検証できる。LLM ノードは `node_id` 単位のモック解決で決定論的にテストされ、API 呼び出しが不要である。コーディングエージェントが MCP 経由で `run_golden_tests` を実行し、`propose_update → run_golden_tests → apply_update` のサイクルを回せる | Done |

### Phase 6: 弾性制御と型安全（Resilience & Type Safety）

| Goal ID | ユーザーが到達したい状態 | 到達判定（Definition of Done） | 状態 |
| --- | --- | --- | --- |
| G-21 | バリデーションの is_valid 判定が warning/info に影響されない | `is_valid` が error severity のみをチェックし、warning/info が追加されても既存ワークフローの valid 判定に影響しない | Done |
| G-22 | プロンプト変数と state_schema の型整合性を検証できる | `prompt_state_validator` で warning レベルの変数存在確認・output_key 宣言確認がバリデーションパイプラインに統合されている | Done |
| G-23 | ノードレベルの retry / fallback / timeout を YAML で宣言的に設定できる | `RetrySpec` モデルでノード単位の retry/timeout/fallback を YAML 宣言し、`state_graph_builder` が実行時ラッパーを自動適用する。スキーマバリデーションで fallback 参照を検証する | Done |
| G-24 | Studio UI から retry / fallback / timeout を編集できる | ノードプロパティパネルに Resilience Settings セクションがあり、retry/timeout/fallback を GUI で編集して YAML に反映できる | Done |
| G-25 | Studio UI でリアルタイムバリデーションが動作する | フォーム変更時に 400ms デバウンスで自動バリデーションが実行され、severity バッジとキャンバスノードのエラー/警告ハイライトで結果が表示される | Done |
| G-26 | プロンプトバージョニングでバージョン整合性を検証できる | `_meta.version` メタデータと `@version` サフィックスでバージョンピニングでき、不一致を warning/info で検出する。`yagra prompt info` CLI で確認可能 | Done |

## 運用ルール

- アクティブなゴールは 3〜5 個に絞る。
- 各ゴールは必ず「ユーザーが到達したい状態」で書く。
- 各ゴールに `到達判定（Definition of Done）` を 1 つ以上持たせる。

補足:
- G-01〜G-13 は Phase 1（Declarative LangGraph Builder）として全て完了済み。詳細は各 Goal の実装項目（milestones.md）を参照。
- G-14/G-15 は PR #21 で実装完了。G-16/G-17 は PR #22 で実装完了。G-18/G-19 は Phase 4 で実装完了。v1.0 目標の全ゴールが達成された。
- G-20 は Phase 5（回帰検証）として M-49〜M-52 に分割。全マイルストーン完了。M-49（ドメインモデル）、M-50（テストランナー）、M-51（CLI）、M-52（MCP ツール）。
- G-21〜G-26 は Phase 6（弾性制御と型安全）として M-53〜M-58 に分割。全マイルストーン完了。
- G-14/G-15（Run & Observe）は完了。G-16/G-17（Analyze & Propose）はログ出力に依存する。G-18/G-19（Approve & Update）は分析機能に依存する。分析・提案の生成はコーディングエージェントに委ね、Yagra はデータ収集と構造化出力に徹する。
