mutation-gate について
mutation-gate は、外部への書き込み前に明示的な承認を得て、実行結果を報告するスキルです。実行前に、各操作の対象、正確なコマンド、プレビュー、前提条件、失敗時の処理、復旧計画を提示します。
主な機能
- 01予定する書き込みと正確な対象を列挙
- 02コマンド、ペイロードのプレビュー、前提条件を提示
- 03失敗時の処理と復旧計画を必須化
- 04提示した操作一式について承認を取得
- 05各操作の結果を順番に報告
活用シーン
- 01送信前のプルリクエストや Jira 変更の確認
- 02リポジトリやサービスへの一括更新の計画
- 03完了、失敗、スキップした書き込みの追跡
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/mutation-gateを入力して読み込まれたか確認します。
同梱ファイルagents/openai.yamlscripts/scan_credentials.py
詳細
RHDH 書き込みゲート
外部への書き込みとは、セッションを閉じるだけではユーザーが取り消せない操作です。たとえば、プッシュしたコミット、作成したプルリクエスト、Jira のステータス遷移、投稿したメッセージ、他の人のリポジトリで変更したファイルなどです。
読み取りは書き込みではありません。取得、トリアージ、分析、報告の依頼は読み取りの意図を示すものであり、何も承認するものではありません。
ゲート
1. 操作を明示します。 実行する操作をすべて、実行する順に列挙します。それぞれについて、次の情報を示します。
| 項目 | 内容 |
|---|---|
| 対象 | 変更する具体的な対象：owner/repo#412、RHIDP-1234、ブランチ名、チャンネル |
| コマンド | 実行するコマンドまたはリクエストそのもの。言い換えではありません |
| プレビュー | 反映される本文、ラベル、フィールド値、差分 |
| 前提条件 | すでに満たされている必要がある条件。実行の直前に確認し、満たされていなければ一連の処理を中止します |
| 失敗時の対応 | この操作が失敗した場合、後続の操作をどうするか |
| 復旧方法 | この操作の実行後に、取り消す方法または影響を封じ込める方法 |
会話内に表として表示します。承認はユーザーがすでにいる場所で行われるため、計画はファイルではなくユーザーに提示します。
復旧方法は必須であり、失敗時の対応とは異なります。 失敗時の対応では、まだ実行されていない操作をどうするかを示します。復旧方法では、すでに実行された操作をどうするかを示します。承認を求める前に記載してください。取り消し方を説明できない操作は、ユーザーが内容を知らずに承認することになります。本当に取り消せない場合は、その旨を明記してください。投稿したメッセージ、起動したパイプライン、公開したパッケージなどの場合は、「取り消し不可。メッセージは残ります」のように書きます。記載しないのは不可です。
会話履歴では読み切れないほど計画が大きい場合（複数のリポジトリにまたがるバージョン更新や、数十個のファイルに及ぶカタログ変更など）は、/handoff の規則に従ってオペレーティングシステムの一時ディレクトリに書き込み、絶対パスを表示します。ユーザーのチェックアウトには書き込まないでください。コミットに含まれるおそれがあります。
2. 明示した操作一式について承認を得ます。 ユーザーが承認するのは、提示された内容です。公開するという以前の意図があっても、正確な対象とペイロードが示されていない操作は承認されません。承認後に計画が変わった場合（対象の変更、操作の追加、本文の編集など）、それは新しい計画であり、改めて承認が必要です。
3. 実行し、すべての操作を報告します。 計画した順に、各操作について完了、失敗、スキップのいずれかを報告します。先行する操作の失敗により実行されなかった操作は、省略せずスキップとして報告します。書き込みの失敗は必ず報告し、内容を変えて密かに再試行してはいけません。
認証情報をプレビューに含めない
プレビューには実行されるコマンドを表示するため、貼り付けられたトークン、環境から展開されたトークン、ツールから返されたトークンが含まれる可能性があります。表示する前にスキャンしてください。
uv run scripts/scan_credentials.py <plan.json> --json
uv run scripts/scan_credentials.py --text "<a single command or body>"
認証情報のようなフィールドや値（認証ヘッダー、PEM 秘密鍵、ghp_、glpat-、xox、sk-、AKIA トークン、または任意の階層でシークレットを示す名前のフィールド）を見つけると、ゼロ以外の終了コードを返し、該当するパスを示します。報告するのはフィールドであり、シークレットそのものではありません。
計画に認証情報が含まれているのは、コマンドの組み立て方に問題があるということです。伏せ字にして続行してはいけません。実行時に認証済みツールからシークレットが供給されるように、構成を修正してください。
誰が実行するか
対象を担当するスキルが操作を実行します。Jira への書き込みが必要な呼び出し元は /rhdh-jira-update を呼び出します。Forge への書き込みが必要な呼び出し元は、コマンドを組み立てて自ら実行します。/rhdh-forge は Forge のペイロードを構築しますが、実行はしません。コマンドの構築方法を知っているモジュールが実行できないようにすることで、この分離によりゲートを確実に適用できます。
完了
ユーザーが承認したすべての操作に結果があり、結果が計画した順に並び、それぞれの対象が明記されていれば完了です。報告に含まれていない操作や、変更対象を示さずに報告された操作がある場合、ゲートは完了していません。