signadot-plan

Signadot：プランの作成と実行

プランの概念を説明するためのものではありません。 ユーザーから「プランとは何ですか」「プランはどのように動作しますか」と尋ねられたり、チュートリアルや概要を求められたりした場合は、このスキルを使用しないでください。代わりに、Signadot のドキュメントを案内してください。このスキルは、具体的なプランの作成、実行、反復に使用します。

Signadot のプランは、アクション呼び出しをまとめた不変のコンパイル済み DAG です。各ステップは、組織のカタログから 1 つのアクションを呼び出し、プランのパラメーター、リテラル値、または上流ステップの出力から入力を接続します。スキーマ、利用可能なアクション、アクションの契約は実行時に確認できます。作成を始める前に取得してください。

参考資料一覧

ワークフローが該当するトピックに進んだ場合にのみ、以下の参照資料を読み込んでください。

• references/schema-and-actions.md： プランのスキーマ、アクションカタログ、アクション ID、無効化されたアクション、 アクション本体の契約を確認する方法。
• references/spec-authoring.md：YAML 仕様の構成、参照と値の違い、詳細確認のルール、条件、extraInputs、 extraOutputs、シークレット、一般的なバリデーターエラー。
• references/routing-and-cluster.md： routingContext、ルーティングキーの挿入、カスタムルーティングヘッダー、クエリパラメーターへの フォールバック、spec.cluster。
• references/running-and-debugging.md： 作成／実行コマンド、実行 JSON、ログ、出力アーティファクト、終了コード、 ランナーの失敗とスクリプトの失敗の見分け方。
• references/tagging.md：タグ付けするタイミング、再タグ付けの 安全性、selectionHint。
• references/worked-examples.md：ベースライン トラフィック、サンドボックスにルーティングされたトラフィック、条件付きステップ、 出力を示す小規模なプランのスニペット。

基本ワークフロー

1. 目標と副作用を明確にします。 プランで何を検証または自動化するのか、対象は何か、作成、実行、タグ付けのいずれが想定されているかを確認します。対象、クラスター／ルーティングのコンテキスト、または副作用のリスクが曖昧な場合にのみ質問します。
2. スキーマとカタログを確認します。 作成に取りかかる前に signadot plan schema を取得し、有効なアクションを確認します。 schema-and-actions.md を読みます。
3. 名前だけでなく、契約に基づいてアクションを選択します。 選択したアクションごとに、アクションの本文と ID を取得します。ステップの仕様では、アクション名ではなく action.actionID を使用します。
4. ルーティングとクラスター構成を解決します。 プランの対象がサンドボックス、ルートグループ、ルーティングキー、または分離されたコードに到達させるべき .svc URL の場合は、作成に取りかかる前に routing-and-cluster.md を読みます。
5. YAML 仕様を作成します。 params、steps、output、および必要に応じて cluster／runner を直接構成します。各ステップの action には actionID のみを含めます。サーバーは作成時に、アクション契約の残りの部分をスナップショットします。spec-authoring.md を読みます。
6. 作成前にセルフチェックします。 参照にパス式のみが使われていること、すべての引数がアクションまたは extraInput として宣言されていること、ドリルインのソースにスキーマがあること、条件が解決済みの引数を参照していること、リテラルにシークレットが含まれていないこと、トラフィックを発生させるすべてのステップに適切なルーティングコンテキストがあることを確認します。
7. 作成し、検証エラーを正確に確認します。 signadot plan create -f <spec.yaml> -o json を使用します。サーバーは作成時に検証し、最初の問題で失敗します。広範囲に書き直すのではなく、該当する問題を正確に修正します。
8. 必要に応じて実行し、反復します。 プラン ID またはタグを指定して -o json で実行し、失敗したステップのログまたは出力アーティファクトを明示的に取得してから、修正したパラメーターまたは新しいプラン仕様で再実行します。running-and-debugging.md を読みます。
9. プランを再利用できる場合にのみタグ付けします。 使い捨てのプランには、デフォルトでタグを付けません。タグが必要な場合は、適用前に既存のタグの状態を確認し、プランの作成時に役立つ selectionHint を追加します。tagging.md を読みます。
10. 永続的な識別子と証拠を添えて締めくくります。 作成または実行した内容、対象、使用したパラメーター、確認した出力、および残っているオペレーターの作業を報告します。

ツール連携と CLI の使用

連携された Signadot ツール（MCP サーバー、プラグイン、IDE 拡張機能など）がコントロールプレーンの読み取り（クラスター、サンドボックス、ルートグループ、ワークロード、エンドポイント）を提供する場合は、記憶している値よりもその出力を優先します。それ以外の場合は、同じ情報の読み取りに CLI を使用します。

同じコマンドを明確に扱える連携機能がない限り、プラン固有の操作には Signadot CLI を使用します。

signadot plan schema
signadot plan action list -o json
signadot plan action get <name> -o json
signadot plan create -f <spec.yaml> -o json
signadot plan run <plan-id> --param k=v -o json
signadot plan x logs <exec-id> <step-id>
signadot plan x get-output <exec-id> <name>
signadot plan get <plan-id> -o json
signadot plan tag get <name> -o json
signadot plan tag apply <name> --plan <plan-id>

副作用に関するポリシー

操作	デフォルトの動作
スキーマ、アクション、クラスター、タグ、プラン、実行、ログ、出力の読み取り	自律的に実行します
依頼されたタスク用の、タグなしプランの作成	仕様と対象が明確であれば、自律的に実行します
開発／テスト用サンドボックスまたは明示的に指定された非本番環境を対象とする、新規作成プランの実行	パラメーターとクラスター／ルーティングの対象が明確であれば、自律的に実行します
本番環境、顧客が利用する共有対象、または曖昧な対象に対するプランの実行	事前に確認します
ユーザーが依頼した新しいタグの適用	重要な参照先がすでに設定されていないことを確認してから実行します
既存タグの参照先の変更	plan tag get で確認します。ユーザーがそのタグの変更を明示的に依頼している場合を除き、上書き前に確認します
仕様またはチャットの要約へのシークレット値の記載	決して行いません。プランのパラメーターと --param-secret を使用します

重要なルール

• スキーマを優先します。 このスキルが signadot plan schema と矛盾する場合は、スキーマに従ってください。
• アクションは組織のスコープに属します。 status.enabled == true でフィルタリングしてください。無効なアクションは、作成したプランから参照できません。
• プランは不変です。 後からアクションを更新しても、既存のプランには影響しません。アクションの更新を反映するには、新しい仕様を作成し、新しいプランを作成してください。
• ステップの順序は依存関係によって決まります。 配列の順序は実行順序ではありません。参照が DAG を示します。
• 参照はパスであり、式ではありません。 params.<name> または steps.<id>.outputs.<name> を使い、必要に応じて階層をたどります。演算子、条件分岐、文字列の連結、変換には、構成用アクションを使用してください。
• 階層をたどるにはスキーマが必要です。 元のパラメーターまたは出力でスキーマが宣言されており、実行時の値が JSON である必要があります。
• ルーティングには 2 つの要素があります。 routingContext は SIGNADOT_ROUTING_KEY などの環境変数を設定しますが、送信リクエストでは、受け付けられるヘッダーまたはクエリパラメーターにルーティングキーを引き続き挿入する必要があります。
• spec.cluster は routingContext ではありません。 クラスターはランナーの実行場所を決定し、ルーティングコンテキストはステップがトラフィックをどのように振り分けるかを決定します。
• タグ付けは任意です。 タグは再利用可能なプランを参照するための安定したポインターであり、すべてのドラフトに対するデフォルトの命名方法ではありません。
• 実行は少なくとも 1 回行われます。 再試行や再実行の際に、ステップが複数回実行されることがあります。アクションのコードはべき等にしてください。また、厳密に 1 回だけ実行されることを前提としたプランは作成しないでください。

クイックリファレンス

読み取りには -o json を使用します。CLI は JSON を整形して出力するため、フィルタリングする場合にのみ jq にパイプしてください。書き込み（plan create）には YAML ファイルを使用します。

目的	方法
アクションを一覧する	signadot plan action list -o json | jq '.[] | {name, description: .status.description, enabled: .status.enabled}'
1 つのアクション本文を読む	signadot plan action get <name> -o json | jq -r .spec.body
アクション ID を取得する	signadot plan action get <name> -o json | jq -r .id
プランのスキーマを取得する	signadot plan schema
スキーマの主要フィールドを確認する	signadot plan schema | jq '.properties.params, .properties.output, .properties.steps.items'
プランを作成する	signadot plan create -f plan.yaml -o json
ID で実行する	signadot plan run <plan-id> --param k=v -o json
タグで実行する	signadot plan run --tag <name> --param k=v -o json
ステップのログを取得する	signadot plan x logs <exec-id> <step-id>
プランの出力を取得する	signadot plan x get-output <exec-id> <name>
ステップの出力を取得する	signadot plan x get-output <exec-id> <step>/<name>
すべての出力を一括取得する	signadot plan x get-output <exec-id> --all --dir ./outputs/
プランの詳細を取得する	signadot plan get <plan-id> -o json
タグを確認する	signadot plan tag get <name> -o json
プランにタグを付ける	signadot plan tag apply <name> --plan <plan-id>

最終レポート

タスクに該当する項目を記載してください。

• プラン ID、実行 ID、作成または更新した場合はタグ名。
• クラスター、サンドボックス、ルートグループ、ルーティングキー、またはベースライン実行／クラスター非依存の実行であることを明記します。
• 使用したパラメーター。シークレット値は伏せ、安全な場合に限りシークレット参照名を記載します。
• 選択したアクション名と ID。特に、近い代替案を使用した場合は明記します。
• 確認した出力と、最終的な合否の判定。
• 未解決の失敗ステップのエラー、ログの場所、またはアーティファクトのコマンド。
• 残された副作用：タグのないプラン、付け替えられたタグ名、生成された YAML ファイル、またはオペレーターによる追加対応。