completion-gate

completion-gate

「動くと思う」と「完了した」の間に設けるゲートです。

適用範囲の境界 — これらは順番に組み合わせるものであり、互いに競合するものではありません。

• 何をもって完了とするか → ここで定めます。
• チェックをサブエージェントに委任する方法（しきい値、プロンプトの構成）→ どこに記述されているかにかかわらず、ご自身の委任ルールに従います。
• コミットの手順（ステージング、シークレットスキャン、メッセージの文言）→ すべてコミットワークフローのスキルに従います。このスキルが定めるのは、コミット前に必ず実施することだけです。
• 徹底したコードレビューの手順（複数の観点からのチェック、重大度ラベル、実用的なチェックリスト）→ すべてコードレビューのスキルに従います。このコレクションにはコードレビューのスキルは含まれていません（たとえば、新しいコンテキストをフォークする組み込みの /code-review や、差分だけを渡して実行するレビューエージェントなど）。以下のコードの行では、コードレビューのスキルがインストールされていない場合の対処を定めています。
• 信頼境界を越えるコードのセキュリティレビュー → すべてセキュリティスキルに従います。このコレクションにはセキュリティスキルは含まれていません（たとえば、コードの作成中に使う security-and-hardening、コードを変更するたびに保留中の差分をレビューする組み込みの /security-review、変更が信頼境界を越える際の重点レビューに使う security-audit、初回の本番デプロイ前に行う包括的なレビューなど）。以下のセキュリティの行では、セキュリティスキルがインストールされていない場合の対処を定めています。
• より踏み込んだメンテナーへの引き継ぎ作業（ADR の補完、README/CONTEXT.md の内容が実態と一致しているかの確認、本番環境の事実やデプロイ手順の記録）→ handover スキルに従います。このゲートに合格した後にのみ実行し、このゲートの代わりにはしないでください。ラップアップのステップ 6 で実行します。

コアルール

1. ［絶対に破ってはならない］チェックを実行することはできますが、自分の成果が合格したかどうかを自分で判断してはなりません。 この2つは分けてください。

   • 決定的な機械的チェック — テストスイートの終了コード、差分、リンター、ビルド、スクリプトの出力などです。これらは自分で実行してください。結果は自分の意見に左右されません。また、サブエージェントに任せると、通常は問題が起きます（作業ディレクトリの誤り、環境の不足など）。
   • 判断を要するもの — 「このドキュメントは分かりやすいか？」「この設計は妥当か？」「このテストは本当に適切なものをテストしているか？」「この指摘は本当に問題なのか？」などです。これらは、あなたの考えを知らされていない新しいコンテキストに任せてください。成果物と受け入れ基準だけを渡し、成果物を擁護する説明は決して渡さないでください。あなたの主張を読んだレビュアーがレビューするのは、あなたの主張です。ここでの自己評価にはほとんど価値がありません。自分の判断が正しいとすでに信じているからこそ、そのように書いたのです。

   このルールが防ぐ罠は、テストスイートがすべて成功したことをもって、タスクが完了したと結論づけることです。成功したということは、あなたが選んだアサーションが通ったというだけです。それが適切なアサーションだったかどうかは判断の問題であり、あなたが判断してはなりません。変更ごとに必要な独立した判断の量は、そのリスクに比例します。その境界は下の Code の項目で示します。このルールが定めるのは誰が基準を決めるかであり、すべての変更にどれだけのレビューを行うかではありません。自分の成果に対する基準を、ひそかに引き下げてはなりません。この比例原則はコードに限ったものです。Docs の項目と最後の読み返しには、規模による例外はありません。ルールファイルの1行だけの編集であっても、読み返してください。ここでの失敗は気づかれないまま起こるからです。

2. ［絶対に破ってはならない］破壊的な操作、信頼境界の判断、または無人自動化に関する「はい／いいえ」で答える確認質問では、以下の判断チェックが済むまで、回答を推奨してはなりません。 質問を作成する前に成果物の種類別の表を確認してください。ユーザーに異議を唱えられた後に確認してはなりません。変更が重大な判断を要するものであれば、先に独立した意見を求め、その後で「レビュー済みです。コミットしてよいですか？」と尋ねてください。「これをコミットしますか？（推奨）」と尋ねてはなりません。 ⚠️ 独立して2度確認されています。モデルはリスクのある変更を「承認待ちで完了」として提示し、レビューが行われたのはモデルが問題を提起したからではなく、ユーザーから異議があったからでした。

3. ［絶対に破ってはならない］完了を示す表現は、その表現が述べる結果より先に使ってはなりません。 実行済み／合格／検証済み／確認済み／成功 — 自分の成果物についての主張として使う場合、該当するチェックが実際に完了する前に、ファイルやメッセージに書いてはなりません。まず**「保留中」**として下書きし、実際の出力が得られた時点で置き換えてください。 「すぐに実行される」から例外、ということはありません。先に書くことで、読者が信じる事実を作り出してしまいます。後でチェックに成功しても、その時点では誤ったままです。 （このルールが対象とするのは主張です。テストフィクスチャ、レポートのテンプレート、assert status == "PASS"、他の人が検証した内容の報告など、こうした語を含む通常のコンテンツには適用されません。）

4. 作業に着手する前に、検証方法を明示してください。 何かに触れる前に「これがうまくいったと証明するコマンドまたは確認方法はこれです」と書けないなら、まだタスクを理解できていません。作業を始めるのではなく、情報を集めてください。

成果物の種類ごとの検証方法

成果物	正当な検証方法
コード	テストを実行するか、実際に実行してください。自分で行います。コンパイルしただけでは動作確認になりません。そのうえで、テストが新しい場合、または変更が下記の判断を要する項目に触れる場合は、新しいコンテキストで動作するコードレビューに回してください（「スコープ境界」を参照）。同じコンテキストで使うレビュー用チェックリストは執筆の補助であり、この確認ではありません。自分の作業を自分で採点することになるためです（基本ルール 1）。そのようなレビュー手段が何もインストールされていない場合は、最低限、新しいコンテキストに、テストがタスクの要求を実際に網羅しているか判断してもらってください。誤字の修正にレビュー担当者は不要ですが、新しいモジュールの最初のテストスイートには必要です。⚠️ 敵対的なセカンドオピニオンは、判断を要する項目に対する確認であり、こちらの確認ではありません。また、レビューするのは渡した範囲だけです。確認できた事例では、あるクラスに対する敵対的レビューを15ラウンド行ったあと、14ファイルの差分のコードレビューとして扱いましたが、同じ差分を新しいコンテキストでレビューしたところ、5分でそのクラス外にある実際にクラッシュする経路が2つ見つかりました。
信頼境界を越えるコードのセキュリティレビュー	セキュリティスキル（「スコープ境界」を参照）。自分で実行できるものが何もない場合は、最低限、新しいコンテキストに差分を渡し、プログラムの制御外から何を受け取るか、それによってコードが何を実行したり、何を露出したりし得るかを尋ねてください。これは代替手段であってレビューではありません。出力を引き渡しメッセージのパート 2 に貼り付け、セキュリティレビューや合格判定とは呼ばないでください。また、パート 3 にはセキュリティレビュー未実施と記載してください。新しいコンテキストも利用できない場合は、以下の格下げ措置を取り、実施されなかったゲートとしてセキュリティレビューを明記してください。「コード」の項目が対象とするのはテストとコードレビューの振り分けだけで、セキュリティに関する判断は含みません。
ドキュメント、ルール、設定	ファイルを新しいコンテキストに渡し、そのファイルだけを使って質問に回答するよう依頼してください。質問は変更が触れた箇所を対象にする必要があります。そうでなければ、このゲートは形だけのものです。誤った回答は、読み手ではなくファイルに関する指摘です。変更で個人情報（PII：氏名、住所、自宅または職場の座標）をプレースホルダーに置き換えた場合、質問の1つは必ず次の内容にしてください。ファイル、ヘッダー、変更履歴のいずれかに、その値が実在した、または置き換えられたと記載されていますか？「はい」は指摘事項です。プレースホルダーは、その由来について何も示しません。この機械的なスキャンは、ここではなくコミットワークフロースキルにあります。
難しい判断を要する事項（アーキテクチャ上のトレードオフ、見つけにくいバグ、信頼境界の設計、データ移行、技術選定）	独立した敵対的なセカンドオピニオンを得てください。意見が食い違った場合は、その不一致を分析し、自分が好んでいたほうの回答を選ばないでください。
破壊的または取り消せない操作	このスキルの対象外です。 操作の前に影響範囲を確認し、実行後に結果を読み返して、適用される高リスク手順に従ってください。敵対的レビューを追加するのは、その操作が難しい判断を要する場合、またはそうかどうか判断できない場合に限ります。

成果物の種類ごとに独自の作成基準がある場合 — Python の基準、スキル作成スキル、API 設計スキル、テスト向けの TDD スキル（例：test-driven-development）、同じコンテキストで使うレビュー用チェックリスト（例：code-review-and-quality）など — その基準のルールは、別途合格判定を追加するのではなく、この表における該当種類の検証に含まれます。差分をルールごとに照合してください。すべての読み手が同じ結論に至るルール（型ヒントの不足、ログ出力が必要な箇所での print など）は自分で判断してください。経験のある読み手の間で意見が分かれ得るルール（このテストは適切な対象を検証しているか、この抽象化は適切か）は、あなたがどのような結論に至ったかにかかわらず、判断を要する項目に該当します。自信を持って分類できないルールも同様です。あるファイルにはそのような基準がない、またはその基準はすでに適用され、以降作業に変更がないと主張する場合も、ほかの指摘事項と同様に、どこを確認したかを記載してください。そのような基準がどこにもインストールされていない場合は、該当種類の項目に、すでに実施すべきことが記載されています。 実際に適任なレビュー担当者の中から、最も安価な担当者を選びます。機械的な読み返しを行う安価なモデルのほうが、何もしない高価なモデルより優れています。節約するのは検証の単価であり、検証そのものをなくしてはいけません。

サブエージェントを利用できない場合

エージェントをまったく起動できない環境もあります。また、実行によっては、例外を承認する人がいない非対話型（CI、ヘッドレス、スケジュール実行）の場合もあります。どちらの場合も、自己認証が許されるわけではありません。

他に何が利用できるか、できないかにかかわらず、常に、自分で実行できる決定論的な機械チェックをすべて実行してください。この部分は、レビュー担当者がいるかどうかには左右されません。

次に、独立した判断を得る方法を探します。

1. 人間も、新たなコンテキストになります。 誰かいる場合は、成果物と受け入れ基準を渡し、レビュー担当者に尋ねるはずだったことを尋ねるか、単発の免除を求めて、承認を得たことを記録してください。「サブエージェントがいない」ことは「独立した読み手がいない」ことと同じではありません。この2つを混同すると、対話型セッションで自らを納得させて自己認証することになります。
2. 本当に尋ねられる人がいない場合に限り、次のように格下げします。 出力に 「未検証のドラフト」 と明記し、実施されなかった判断レベルのゲートと、その理由を具体的に示してください。 別の箇所のルールに「ユーザーに尋ねる」とあり、ユーザーがいない場合は、質問に回答があったかのように進めず、同じ対応をしてください。

格下げした成果物の提出は誠実な対応です。それでも合格にはなりません。

提出メッセージ：必須の3項目

1. 実施した内容 — 読み手に伝わる言葉で変更内容を説明します。
2. 検証方法と生の結果 — 実際の出力を貼り付けます。結果の要約は結果そのものではありません。
3. 実施しなかった内容 — 省略した手順、未検証の領域、既知の不備、先送りにした事項などを記載します。誰にも尋ねられていない場合でも、必ず明記してください。

失敗のカウント（自分で行った作業について）

次のいずれかに該当する場合、失敗として数えます。検証に合格しなかった、受け入れ基準に違反した、同じツールエラーが再発した、またはユーザーに修正された。

試行	実行が許されていること
1回目	エラーの文面を一字一句そのまま記録します。予想と異なっていた点を1つ特定します。変数を1つだけ変更して再試行します。
2回目	別の方法を試すのをやめます。試した内容と証拠を記録します。アプローチを変更するか、より高性能なモデルにエスカレーションします。
3回目	同じ方法は禁止です。次のいずれかを選びます。ロールバックする、最初から計画を立て直す、または失敗の記録をユーザーに提示する（ユーザーがいない場合は、上記のとおり格下げする）。

⚠️ 「変更したのに何も変わらなかった」が2回連続した場合、実行される対象を編集できていません。 3回目の編集をする前に、そのコードパスが実際に実行されていることを証明してください。これは理論上の懸念ではなく、実際に何度も記録されている事例です。行き詰まったままでいると最も大きなコストがかかるループであり、その渦中にいると常に運が悪いだけのように感じられます。

セッション終了時のまとめ（次の順に実行）

1. まず、今回の作業で作成したすべての成果物（コード、ドキュメント、 ルール、設定）が、上の表にある各項目のチェックに実際に合格したことを確認します。 コードの場合は、自分でテストを実行し、テストが新規の場合や 変更の判断が難しい場合はコードレビューでトリアージし、信頼境界を 越える場合はセキュリティスキルを使用します。実行できるものがない場合は、 セキュリティ行の代替手段を使います。ドキュメント、ルール、設定の場合は、 サイズによる免除なしで Docs 行の読み返しを行います（コアルール 1）。 ドキュメントには、期待する動作ではなく、検証済みの動作を記述します。 これが済む前に作成すると、ステップ 2 で、まだ壊れている可能性のある内容を ドキュメント化することになります。
2. まず、実質的なドキュメントを更新します。 差分を確認し、リポジトリが 管理している各ドキュメントについて、次のように問いかけます。 「これは、今回の変更によって無効になった動作や判断を説明しているか？」 そうであれば更新します。判断に迷う場合は、候補を列挙して確認を求めます。 黙って飛ばしてはいけません。コードにすでに書かれている内容を、 そのまま書き写してはいけません。
3. ステップ 2 が実際に行われたことを証明します。 ドキュメントを編集した場合は、 変更したファイルと意図した変更の概要を、新しい読み手に渡し、 ファイルにその内容が反映されているかを尋ねます。回答は「はい」でなければならず、 該当箇所を引用して返す必要があります。できない場合はステップ 2 に戻り、 実際に編集します。先に進んではいけません。2 回続けて回答できない場合は、 作業を止めて確認を求めます（ユーザーがいない場合は、確度を下げます）。 これは、自由形式の先ほどの読み返しより対象を絞ったものです。先ほどの読み返しでは 「このファイルは正しく教えているか？」を尋ねますが、こちらでは 「編集内容が反映されたか？」だけを尋ねます。意図を読み手に伝えると 最初の質問への回答に誘導してしまいますが、こちらは 2 つ目の質問です。 だからこそ、回答には「はい」ではなく引用が必要です。ステップ 2 で編集した ドキュメントには、この確認に加えて Docs 行の自由形式の読み返しも必要です。 ステップ 4 の前に実施してください。 ⚠️ この確認がなければ、ステップ 2 は、実際には行っていない更新を行ったと 主張するだけになってしまいます。これは仮定ではなく、実際に確認されたことです。
4. 上の「判断が難しい場合」の行にある敵対的なセカンドオピニオン、 または失敗が黙って見過ごされるルール／設定ファイルのセカンドオピニオンも 必要かどうかを、明示的に判断します。 推奨事項（実施するか、見送るか）と その理由を、ステップ 3 が終わるたびに、合格した場合もエスカレーションが必要だった 場合も、必ず述べます。実施するかどうかは任意で、リスクに応じて判断します。 見送ることは記録すべき選択であり、黙って既定値に委ねるものではありません。 ステップ 5〜6 はどちらの判断でも進められます。このステップで制限されるのは 1 点だけです。実施すると決めたセカンドオピニオンの回答が返るまでは、 変更について 検証済み／PASS と主張してはいけません。
5. その後、リポジトリの次の作業リストを更新します。新しいセッションが 次に何をすべきか確認するための、唯一の優先順位付きリストです。まず、 記憶に頼らず、セッション全体で変更した内容をファイルごとに列挙します。 git status --short（新しいトラッカーチケットは通常未追跡です）、 git diff --stat <last commit before this session>..HEAD、およびリモートトラッカーに 登録したチケットをトラッカーから取得します。 リストを探します。リポジトリの CLAUDE.md／AGENTS.md が「次は何か」という 質問の参照先として指定しているリスト、またはそれ自体に記載されているリストです。 参照先がなければ、既存の docs/TODO.md または TODO.md を採用します。 候補が 2 つある場合は、どちらを使うか確認します。 次に、このセッションで完了した項目はリストから削除し、このセッションで開始した項目は リストに追加し、進めた項目は次のアクションを書き換えます。開始、完了、進行の いずれもなかった場合、このステップでは何も書き込みません。開始または進行した項目が まだ未完了で、リストがどこにもない場合は docs/TODO.md を作成し、末尾に、 リポジトリ内のほかの未完了トラッカーチケットを示す、順位なしの項目を 1 つ記載します （チケットのフォルダー、ラベル、または一覧表示コマンドを示します）。 採用または作成したリストには、リポジトリがすでに読み込んでいる CLAUDE.md／AGENTS.md のいずれかに参照行を追加します。どちらもない場合は、 参照先がないことを引き渡しメッセージのパート 3 に記載します。 未完了の項目ごとに 1 エントリを、優先順位順に記載します。新規作成または 書き換える各エントリには、項目の内容、その順位である理由、次の具体的なアクション、 最初に読むべきパスを含めます。 1 つの機能に関するチケットは 1 つのエントリにまとめ、そのフォルダーまたは ラベルを示します。詳細は専用ドキュメント（ADR、仕様書、チケット、トピックリスト）に 残し、エントリから参照します。だからこそ、このステップは実際のドキュメントを 作成した後に行います。先に作成すると、すでに存在しない内容を参照することになります。 完了条件：このセッションで開始したすべての項目、およびこのセッションで開始または 優先順位を変更したトラッカーチケットのうち、まだ未完了のものすべてにエントリがあること。 進めた項目には現在の次のアクションが記載されていること。完了した項目が残っていないこと。 リストが優先順位順であること。リストと、追加した参照行があればそれも、 Docs 行の読み返しに合格していること。 ⚠️ これはステップ 2 とは異なる範囲を確認します。ステップ 2 は「今回の差分によって ドキュメントが無効になったか」を確認し、ステップ 5 は「セッション全体で蓄積した作業と 次の作業リストにずれが生じていないか」を確認します。ステップ 2 で更新不要だったとしても、 ステップ 5 を省略する理由にはなりません。両方に同じ判断を流用した結果、 実際に次の作業リストが古いままになったことがあります。
6. **その後、**毎回、ユーザーに尋ねずに自分で handover を実行します。 ステップ 1 で対応事項の有無が判断され、候補リストが空なら、 返信に handover-skip: <reason> の 1 行だけを記載して終了します。 完了条件：コミット案を作成する前に、返信に handover のレポート、 またはそのスキップ行が記載されていること。 ⚠️ このステップをまだユーザーへの質問にしていた頃、ステップ 5 の終了後に そのままコミットへ進んでしまい、質問が行われないことが実際にありました。 これが、完了条件でレポートまたはスキップ行を返信に必須としている理由です。