approval-gate — 承認ゲート Skill

approval-gate — 承認ゲート

方針・原稿・コードを Crit で人に見せ、インラインコメントで承認を受け取ってから先へ進むためのワークフロー。作る前なら実装の前に、書いた後ならコミットや次の作業の前に置く。 Input: 見せたい対象 (UI 配置・設計・方針の 1 案、長文の原稿、または書いたコード) + 決めてほしい論点。 Output: Crit で開いたシート・原稿・差分と、そこに付いたコメント (Claude の [判断] コメントへの返信 + 人が自由に付けたコメント)。

前提は crit。 command -v crit (PowerShell なら Get-Command crit) で確かめる。無ければシートを作らず、Crit の導入を人に案内して止める。

まずここで止まる — このスキルを使わない条件

レビューは確認コストを人に払わせる道具で、シート 1 枚の作成は小規模な実装より重いことがある。 下のどれかに当てはまるなら、シートを作らずに済ませる。 該当したら、その場でその手段に切り替える。

| 状況 | 代わりに使う手段 | |---|---| | Claude にバグや問題点を探してほしい (人が承認するのではなく、Claude が指摘する) | code-review | | 決めてほしいことが 2 問以下、または返答が候補 1 つで完結する (方針・命名・優先度など見た目の差が無いもの) | AskUserQuestion で直接聞く | | 答えが事実で一意に決まる (コードを読めば分かる、実行すれば分かる) | 自分で調べて決める。人に聞かない | | 多数アイテムの一括検収 (100 件の分類結果を承認等) | 別の道具。レビューの対象外 | | 人が既に方針を明示していて、確認は儀式にしかならない | そのまま実装する |

使うのは、現物 (絵・原稿・コード) の上でないと判断できない論点があるときだけ。 UI の配置・画面遷移・レイアウトの A/B のように、文章で説明すると人が想像で補ってしまい、結果として全部「お任せ」に倒れる論点。コードなら、差分の該当行を見ないと裁定できない設計判断。ここがレビューの本領で、それ以外では純粋な損失になる。

最重要禁則

Finish Review で crit が終わる前に先へ進まない — 作る前なら実装を始めない。コードならコミットも次の変更もしない。確認ゲートの意味が消える。待つ間は別作業をする
承認後もコミットは依頼があるまでしない — 承認はコミットの依頼ではない
レビューは現物への訂正であって、質問票ではない — シートに問いや選択肢の一覧を並べない。シートは案の絵・対比表・根拠だけ。問いは [判断] コメントとして絵やコード行の上に置く。UI や画面が対象なら、現物の再現 (スクショ埋め込みか DOM 再現) を必ず載せる
選択肢の対立軸は両方絵にする — A と B の違いが絵で見えない [判断] は出さない。推奨案の挿絵だけ並べて選択肢をコメントの文字 1 行にすると、人は想像で補えずお任せに倒れる。見た目の無い選択肢 (方針・優先度) は除く
事実を人に聞かない — 各 [判断] に file:line か実行結果の引用を添える。人に残すのは決定 (好み・優先度・トレードオフの裁定) だけ
[判断] は 3±1 件、5 件以上投稿しない — 人の判断コストが本体。各件に推奨と「未返信なら推奨で確定」を明記し、返信が無くても進められる形にする
現物と乖離したモックを描かない — 既存画面に加えるなら、現行 UI の忠実な再現が信頼の根
長文の読み物を要約したシートに組み直さない — 訂正対象の本文が人の目から消える。原稿モードで原稿そのものを開く

モード選択

| モード | 対象 | Crit で開くもの | 人がすること | |---|---|---|---| | 標準 (迷ったらこれ) | UI 配置・設計・方針の 1 案 | 書いたシート HTML を crit preview ./review/<topic>-01.html | [判断] コメントに返信 + 気になる箇所にピン留めコメント | | 原稿 | 記事・README・長文レポート | 原稿ファイルをそのまま crit <原稿> | 段落・語句を選んでコメントか suggestion (書き換え案)。[判断] があれば返信 | | コード | 書いたコード (未コミット差分・コミット範囲・PR) | 未コミット差分は crit、範囲は crit --range <base>..<head>、PR は crit --pr <番号>。未追跡の新規ファイルが出ないときは crit <file...> | [判断] に返信 + 気になる行にコメント |

原稿モードとコードモードはシートを作らない。直すのが agent でも人でも同じで、人が書き換えたいなら Crit の suggestion で受け取る。

コードモードの [判断] は判断の要る行にだけ付ける。説明・実況・自明な変更へのコメントは付けない。全変更行に付けない。不確かな理解は断定せず「確認: 〜という理解で合っているか」の形で聞いてよい。

[判断] コメントの書式

1 コメント = 1 判断。人がコメントと、そのピンが刺さった絵やコード行だけで即答できる形にする。

[判断] <問い 1 行>
A: <案> — 利点: <1 行> / 代償: <1 行>
B: <案> — 利点: <1 行> / 代償: <1 行>
推奨: A (<理由 1 行>)
根拠: <file:line か実行結果>
未返信なら A で確定

非推奨の選択肢にも利点を書く。 代償しか無い選択肢は実質 1 択で、ゲートとして機能しない。利点が書けないなら [判断] ごと落として推奨で進める
判断に要る数値はコメント内に再掲する。シートへ戻って探させない
刺さる場所に付ける。標準モードは selector でシート内の論点要素 (#p1, #p2, …) にピン留めし、route は /preview-content。原稿モードとコードモードは file + line (+ 語句に絞るなら quote)。行番号はディスク上のファイルの 1 始まり (diff の行番号ではない)
コードモードで根拠がその行自体なら、根拠: は呼び出し元や実行結果など行の外の事実を書く (無ければ 根拠: この行 でよい)
行や要素に紐づかない全体方針は scope: "review" に 1 つだけ。冒頭で「判断 N 件、最重要は <場所>」と一言添えてよい

JSON 例 (標準モード):

[
  {"scope": "review", "body": "判断 3 件。最重要は ① (保存ボタンの位置)。他は推奨どおりで可。"},
  {"selector": "#p1", "route": "/preview-content", "body": "[判断] 保存ボタンをどこに置くか\nA: ヘッダ右 — 利点: 常に見える / 代償: 誤タップが増える\nB: フォーム末尾 — 利点: 入力後の流れに沿う / 代償: 長いフォームで隠れる\n推奨: A (フォームの平均高さ 2.3 画面)\n根拠: src/Form.tsx:88\n未返信なら A で確定"}
]

assets のパス

以下の手順で <skill dir> と書いた箇所は、この SKILL.md が置かれているディレクトリを指す。plugin として入れた場合は ${CLAUDE_PLUGIN_ROOT}/skills/approval-gate/、skill ディレクトリを配置した場合は ~/.claude/skills/approval-gate/。分からなければ、この SKILL.md 自身のパスから求める。

手順

不使用条件と crit の確認 — 冒頭の表に当てはまらないことを確かめる。当てはまるならその手段へ切り替える。crit が無ければ導入を案内して止める
現物把握 — 既存 UI ならスクショかコードから忠実に再現する。ゼロからの構想なら図解でよい。原稿モードは原稿ファイルを用意する。コードモードは git status / git diff (範囲・PR ならその差分) を読み、人の判断で結果が変わる行だけを拾う
モード選択 — 上の表で決める
シートを書く (標準モードのみ) — assets/sheet-template.html を references/sheet-spec.md の規約で埋め、./review/<topic>-01.html に保存する。骨格は動かさない。論点ごとに、その絵を包む要素へ id="p1", id="p2", … を振り、赤の ①②③ を打つ。動く論点 (操作感・頻度) があれば、モックを ./review/mock/ に置き、シートの冒頭に file:// リンクのボタンを置く
[判断] を 3±1 件に絞り、JSON を書く — 上の書式で scratchpad に Write する。原稿モード・コードモードで決めてほしい論点が無ければ 0 件でよい (人は自由にコメントする)
機械検査 (標準モードのみ) — python3 "<skill dir>/assets/check-sheet.py" ./review/<topic>-01.html --comments <json> を実行する。TODO の残り、相対 URL、[判断] の selector がシートに無い (ピンが刺さらない)、推奨・既定の書き忘れなど、無言で壊れる不備を検出する
試問 (preflight) — references/preflight.md の 5 問を、Agent ツールで立てた文脈ゼロの subagent に出す。渡すのはシートのパス、コメント JSON のパス、読者宣言 1 行だけ。model=sonnet を指定する。同期で結果を待つ (background にしない)。結果を受け取るまで応答を終えない。 落ちた件は絵を加える / 落とす / 言い換える。計 2 巡で打ち切る。原稿モード・コードモードは [判断] コメントだけが対象で、0 件なら省く
起動 — モードの表のコマンドを run_in_background: true で実行する (ブラウザが開き、Finish Review までブロックする)。stdout の Started crit daemon at http://localhost:<port> (session <id>) から URL と session id を得る
[判断] を投稿する — crit comment --session <id> --json --file <json> --author 'Claude Code' で一括投稿する
待つ — 「Crit を開いています: <URL>。[判断] コメントに返信し、ほかに気になる箇所があればそこへコメントして Finish Review を押してください。返信しなかった判断は推奨で進めます」と伝えて応答を終える。Finish Review 前に crit comments を読まない
反映 — バックグラウンドの crit が終わったら stdout の指示に従ってコメントを読む (補助に crit comments --session <id> --json)。quote があればその文言に絞って直す。返信の無い [判断] は推奨で確定。各コメントに crit comment --reply-to <id> --author 'Claude Code' '<何をしたか 1 行>' で返し、--resolve は付けない。コメントゼロで Finish なら全件推奨で承認
再往復 — 設計が変わる指摘なら、標準モードは <topic>-02.html を作って crit preview し直す (捨てた案は取り消し線で残す)。原稿モード・コードモードは直してから stdout が示す次ラウンドのコマンドを再実行する (Crit が差分を見せる)。コードの修正が軽微なら再提示せず報告だけでよい
証跡 — シート HTML は消さずに残す (git 管理下ならシートの commit を推奨)。「なぜこの設計か」の答えになる。反映後の原稿・コードの commit は人に確認してから (シートの commit とは別扱い)

Gotchas

HTML preview では file:line でコメントできない — selector (+ route: "/preview-content") で DOM にピン留めする。手順 6 の --comments が selector とシートの id の対応を検査する
複数セッションが有効だと headless コマンドが拒否される — crit status --json で id を確認し --session <id> を付ける
複数行の body は必ず --file で渡す — シェルの生 JSON は改行で壊れる
crit の起動は 1 回 — 追加ラウンドは stdout の指示コマンドを再実行する
人が別のデバイスで開くとき — crit スキルの --public-url 手順に従う。認証無しでネットワークに出すことになるので、先に人へ確認する
Windows の file:// URL はスラッシュ 3 本 — file:///C:/path/to/mock.html。パスに空白があれば %20 に置換する
試問の Agent を background で立てない — 結果が返る前に応答を終えると、人に見せる前の検査が抜けたまま進む
シートに問いを並べない — 問いを記憶したまま説明を読ませる形になり、[判断] コメントとも二重になる。論点の場所は ①②③ の印だけで示す

Additional resources

references/sheet-spec.md — 標準モードのシートの規約 (骨格・7 色・論点の印・文章の規律・CSS スケルトン)。シートを書く前に Read
references/preflight.md — 試問 5 問、Agent ツールの prompt 雛形、打ち切り規則、落ちた件の直し方
assets/sheet-template.html — 標準モードの雛形。TODO を埋めて使う
assets/check-sheet.py — シートと [判断] JSON の機械検査 (python3 標準ライブラリのみ)。手順 6 で実行

Agent Skills: approval-gate — 承認ゲート

Install this agent skill to your local

Skill Files