agent-workflow

必須 — コンテキスト収集プロトコル

ワークフローのガイダンスを適用する前に、コンテキストを収集してください。

1. プロジェクトのルートで Maestro のコンテキストを確認する

   • まず .maestro/context.md（v2 レイアウト）を確認する
   • 次に .maestro.md（v1 レイアウト — 下位互換）を確認する
   • 存在する場合 → 読み込み、その中のワークフローコンテキストを使用する
   • 存在しない場合 → ユーザーに次のように伝える：「ワークフローコンテキストが見つかりません。/teach-maestro を実行してプロジェクト固有のコンテキストを設定すると、より良い結果が得られます。」

2. 判断履歴を確認する（任意）

   • .maestro/decisions.jsonl が存在する場合 → セッションの継続性を保つため、直近5件の判断を読む
   • 存在しない場合 → エラーを出さずに続行する

3. 最低限必要なコンテキスト（.maestro.md がない場合）：

   • どの AI モデルを使用していますか？
   • ワークフローの主なタスクは何ですか？
   • 使用できる既存のプロンプト、ツール、エージェントはありますか？
   • 品質、速度、コストの優先順位は何ですか？

4. モデル、タスク、優先順位を少なくとも理解するまでは、処理を進めないでください。

---

Maestro — AI エージェントのワークフロー習熟

このスキルでは、本番環境に対応する AI エージェントのワークフローを設計、構築、保守するための基礎知識を提供します。すべての Maestro コマンドは、これらの原則に基づいています。

基本原則

1. 即興より構造を重視する — ワークフローは意図的に設計し、自然発生に任せない
2. 制約は機能である — 明示的な境界を設けて、障害の発生を防ぐ
3. 推測せずに測定する — すべてのワークフローには、テストだけでなく評価が必要
4. 適切な複雑さを選ぶ — 野心ではなく、問題に解決策を合わせる
5. 段階的に劣化させる — すべてのコンポーネントは安全に失敗する必要がある

---

1. プロンプトエンジニアリング

実施すること：

• 明確なセクション（役割、コンテキスト、指示、出力形式）を含む構造化プロンプトを使用する
• 出力スキーマを明示的に定義する（JSON スキーマ、Markdown テンプレート、型付きレスポンス）
• タスクが曖昧な場合は、少数例を使用する
• 複数段階の推論には、思考の連鎖を使用する
• システムプロンプトを簡潔に保ち、1つのプロンプトにつき明確な役割を1つ設定する

実施しないこと：

• 構造のない長文のプロンプトを書く
• モデルが暗黙の出力形式を理解すると想定する
• 根本的に異なるタスクに同じプロンプトを使用する
• 1つのプロンプトに矛盾する指示を含める
• モデルが「なんとかしてくれる」と頼りにする

→ 構成、パターン、出力スキーマについては、プロンプトエンジニアリングのリファレンスを参照してください。

---

2. コンテキスト管理

実施すること：

• コンテキストウィンドウの使用量を割り当てる（システムプロンプト、例、ユーザー入力、ツールの結果、出力）
• 重要な情報はコンテキストの最初と最後の両方に配置する（注意の勾配）
• ドキュメント全体を詰め込むのではなく、検索（RAG）を使用する
• 会話の状態を明示的に維持する
• 長い履歴は生のトランスクリプトを渡すのではなく、要約する

実施しないこと：

• コードベース、データベース、ドキュメント全体をコンテキストに詰め込む
• 上限に達するまでコンテキストウィンドウの制限を無視する
• モデルがすべてのコンテキストに均等に注意を払うと想定する
• 「念のため」に無関係な情報を渡す
• ターンをまたいだ暗黙の記憶に頼る

→ ウィンドウの最適化とメモリパターンについては、コンテキスト管理のリファレンスを参照してください。

---

3. ツールのオーケストレーション

実施すること：

• ツールには明確で具体的な名前と説明を付ける
• すべてのツールについて入出力スキーマを定義する
• ツールのエラーに適切に対処する（ツールはいずれ必ず失敗する）
• ツールセットを絞り込む — 1つのエージェントにつき3〜7個のツールが理想的
• 可能な場合はツールを冪等にする

実施しないこと：

• 30個以上のツールを公開し、モデルが適切なものを選ぶことを期待する
• 曖昧なツールの説明を使う（「データをいろいろ処理する」）
• ツールの実装でエラー処理を省く
• 破壊的な操作で確認を取らずにツールに副作用を持たせる
• 機能が重複するツールを作る

→ 選択のヒューリスティクスと構成パターンについては、ツールオーケストレーションのリファレンスを参照してください。

4. エージェントアーキテクチャ

実施すること：

• まずは単一のエージェントから始め、単一のエージェントでは明らかに対応できない場合にのみエージェントを追加します
• 各エージェントの境界と責任を明確に定義します
• エージェント間で構造化された引き継ぎプロトコルを使用します
• マルチエージェントシステムにはスーパーバイザーパターンを実装します
• 可観測性を考慮して設計し、出力だけでなくエージェントの判断も記録します

実施しないこと：

• 単一のエージェントで対応できる問題にマルチエージェントシステムを構築します
• 明確な境界のないエージェントを作成します（責任が重複すると競合が発生します）
• エージェント間の構造化されていない通信を使用します
• スーパーバイザーを省略します。自律型エージェントの群れは予測できません
• 明示的なプロトコルなしでエージェントが連携すると想定します

→ トポロジーパターンと委任については、エージェントアーキテクチャのリファレンスを参照してください。

---

5. フィードバックループ

実施すること：

• 初日からワークフローに評価を組み込みます
• 正解がわかっている入力と出力を含むゴールデンテストセットを作成します
• 一貫性のある品質スコアリングのために自動評価器を使用します
• リグレッションを追跡し、新しい出力をベースラインと比較します
• 重要な出力には自己修正ループを実装します

実施しないこと：

• 評価なしでリリースします（「動いているように見える」は評価ではありません）
• 大規模運用で人間によるレビューだけに頼ります
• 構造化せずに、同じモデルで自身の出力を評価します
• プロンプトやモデルを変更する際にリグレッションテストを省略します
• 「モデルがエラーなく実行された」と「出力が正しい」を混同します

→ 評価パターンと自己修正については、フィードバックループのリファレンスを参照してください。

---

6. ナレッジシステム

実施すること：

• クエリの種類（セマンティック、キーワード、ハイブリッド）に基づいて検索戦略を選択します
• 文書を慎重にチャンク化します（任意のトークン数ではなく、意味上の境界に従います）
• 取得したすべての結果に出典情報を含めます
• 生成品質とは切り分けて、検索品質をテストします
• ナレッジベースにバージョンを付け、モデルが何にアクセスできるかを把握します

実施しないこと：

• 検索品質を先にテストせずにRAGを構築します
• すべての文書タイプに固定のチャンクサイズを使用します
• 出典情報を省略します（出典のないハルシネーションは検出できません）
• 選別せずにすべてをインデックス化します（ゴミを入れれば、ゴミが出てきます）
• 埋め込みの類似度が関連性と等しいと想定します

→ RAG、埋め込み、グラウンディングについては、ナレッジシステムのリファレンスを参照してください。

---

7. ガードレールと安全性

実施すること：

• 処理前に入力を検証します（スキーマ検証、サイズ制限）
• 機密コンテンツ、PII、ポリシー違反がないか出力をフィルタリングします
• 厳格なコスト上限を設定します（実行ごとの最大トークン数、最大API呼び出し数、最大支出額）
• 障害の連鎖を防ぐサーキットブレーカーを実装します
• 監査証跡のためにすべてを記録します

実施しないこと：

• 入力検証なしでデプロイします（プロンプトインジェクションは現実の脅威です）
• 重大な意思決定で、検証せずにモデルの出力を信頼します
• コスト制御なしで実行します（暴走するループひとつで数千ドルかかることがあります）
• 外部API呼び出しのレート制限を省略します
• モデルが常に安全性に関する指示に従うと想定します

→ 検証、サンドボックス化、制約については、ガードレールのリファレンスを参照してください。

---

ワークフローの粗雑さチェック

次のいずれかに当てはまる場合は、ワークフローの改善が必要です。

• プロンプトが構造化されていない長文になっている → /refine を実行
• 出力スキーマが定義されておらず、モデルが形式を決めている → /refine を実行
• 予算を定めずにコンテキストウィンドウを使い、すべてを詰め込んでいる → /accelerate を実行
• 単一のエージェントに10個を超えるツールを公開している → /streamline を実行
• エラー処理がなく、正常系しか考慮されていない → /fortify を実行
• 評価がない（「動いているように見える」） → /iterate を実行
• 単一のエージェントで対応できる問題にマルチエージェントシステムを使っている → /temper を実行
• コスト制御がなく、トークン使用量に上限がない → /guard を実行
• ツールの説明が曖昧な一行だけになっている → /calibrate を実行
• ログがなく、本番環境の問題をデバッグできない → /fortify を実行

チェックが0個なら本番環境に対応できます。3個以上ならワークフローが粗雑です。

---

利用可能なコマンド

ワークフローの習熟に向けて、以下のコマンドを使用して特定の側面に取り組みます。

{{available_commands}}