mcpField
M
merge-readiness

merge-readiness

github.com/yeachan-heoテスト・品質40.4k99 回インストール1 日前に更新
リポジトリ

merge-readiness について

タスク完了後に変更内容を説明し、マージ承認前に目的やトレードオフ、リスクへの理解を人に問うスキルです。証拠を記録して回答を採点しますが、承認やマージは行いません。

主な機能

  1. 01変更説明とクイズを生成
  2. 02ローカル差分と成果物の証拠を収集
  3. 03質問を一問ずつ提示
  4. 04基準に照らして回答を採点
  5. 05合格・保留・ブロックを報告
  6. 06マージ承認は人に委ねる

活用シーン

  1. 01マージ承認前にチームの理解を確認
  2. 02証拠と未実施の検証を記録
  3. 03高リスク変更への理解を評価

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/yeachan-heo/oh-my-claudecode --skill merge-readiness

インストール後、Claude Code で/merge-readinessを入力して読み込まれたか確認します。

詳細

マージ準備状況チェックは、タスク完了後に説明可能性を確認するゲートです。実装、テスト、QA、レビューの証跡がそろった後、変更内容を人が理解できる形で説明し、続いて、変更が存在する理由、何が変わったのか、どのようなトレードオフがあったのか、どのようなリスクを検討したのか、チームが変更をどう理解すべきかを人が説明できるか確認するため、対象を絞った質問をします。

<Use_When>

  • タスク、PR、または変更一式が機能的に完了しており、マージ準備が整ったと判断する前に、人が変更を理解しているか最終確認が必要な場合
  • テスト、QA、コードレビュー、セキュリティレビューなどの検証がすでに実施されている場合、または不足している証跡を明示的に記録する必要がある場合
  • AI に変更内容を説明させた後、人がその内容を説明できるか確認したい場合
  • マージ承認を求める前に、チームが変更を信頼し、理解できる理由を示す、永続的なセッション監査記録が必要な場合 </Use_When>

<Do_Not_Use_When>

  • 実装前で要件がまだ不明確な場合は、/deep-interview を使用してください
  • 実装が完了していない場合は、/ralph、/team、または /autopilot を使用してください
  • テストや QA が未実施で、このコマンドで代用することを期待している場合
  • コードレビューでの指摘事項が必要な場合は、/review または該当するレビューワークフローを使用してください </Do_Not_Use_When>

<Why_This_Exists> 実際の成果は、動作するコードだけではありません。チームは、変更が存在する理由、何が変わったのか、意図的に何を行わなかったのか、どのリスクを検討したのか、将来の保守担当者が変更について何を理解しておくべきかを把握する必要があります。このワークフローでは、マージ承認を求める前に、そうした理解を明確にします。このゲートを通過しても、変更が承認またはマージされたことにはなりません。人が変更内容を説明できることを示すだけです。 </Why_This_Exists>

<Depth_Profiles>

  • Quick（--quick）：小規模／局所的な変更。正答率のしきい値 >= 0.70。MCQ は最大 3 問。必須の観点：理由／変更／リスク
  • Standard（--standard、デフォルト）：通常の機能追加／バグ修正。正答率のしきい値 >= 0.80。MCQ は最大 5 問。必須の観点：理由／変更／トレードオフ／リスク／チーム
  • Deep（--deep）：リスクの高い変更、アーキテクチャの変更、セキュリティ関連の変更、または複数モジュールにまたがる変更。正答率のしきい値 >= 0.90。MCQ は最大 8 問（5 つすべての観点で重複を考慮）

フラグが指定されていない場合は、Standard を使用してください。しきい値とラウンド数の正式な定義は src/hooks/merge-readiness/mcq.ts にあり、このファイルと常に一致させる必要があります。 </Depth_Profiles>

<Execution_Policy>

  • これはタスク完了後に実行するコマンドです。このモードではコードを実装しないでください。
  • ローカルで確認できる事実を人に尋ねる前に、リポジトリと成果物の証拠を収集してください。
  • 説明ドキュメントと MCQ は 1 回の AI ステップで生成し、その後、MCQ を 1 ラウンドにつき 1 問ずつ提示してください。
  • 実行時処理（TS フックコード）が基盤となり、検証、セッションの正規状態、客観的な MCQ 採点、レポートのレンダリングを担います。AI は、AskUserQuestion を介したコンテンツ生成と MCQ の提示を担います。
  • AskUserQuestion を使い、deep-interview 形式で MCQ を 1 ラウンドにつき 1 問ずつ提示してください。各回答は実行時処理に記録し、客観的に採点します。
  • 実装の細かな知識ではなく、説明可能性について質問してください。
  • 行番号、変数名、非公開ヘルパー名、偶発的な実装詳細を人に暗記させる質問は、絶対にしないでください。
  • スコアは客観的な正答率（正解数／回答数）であり、キーワードに基づく推測ではありません。
  • 必須 MCQ にすべて回答した後も正答率がしきい値を下回る場合は、結果を paused とし、マージ準備が整ったとは主張しないでください。
  • 重要な証拠（差分／変更を示す情報）が不足している場合は、結果を blocked としてください。
  • このゲートへの合格は、マージの承認、テストやレビューやセキュリティレビューの代替、リスクの受容、またはメンテナー承認の回避を意味しません。
  • 再開時の安全性を確保するため、状態は .omc/state/merge-readiness-state.json（セッションごとの状態は .omc/state/sessions/<sessionId>/）に保存してください。このファイルを直接書き込まないでください。
  • v1 は助言を行うものであり、ゲートロジック（checkMergeReadiness）は Stop フックに接続されていないため、有効なゲートがセッションをブロックすることはありません。Git のマージを実行または承認するものではありません。 </Execution_Policy>

フェーズ 0：証拠の取り込み

  1. {{ARGUMENTS}}、深度プロファイル、ソースモード（--from-diff|--from-artifacts）を解析し、タスク用スラッグを導出します。--from-pr はサポートされていません。このワークフローではローカルの証拠のみを使用します。
  2. 利用可能な証拠を収集します（ランタイムはファイル名のヒューリスティックでアーティファクトを検出します。ファイルの内容は解析されません）。
    • ローカルの Git 差分とコミット範囲
    • 変更されたファイル
    • テスト／QA／検証アーティファクト（ファイル名が test|spec|qa|verify|validation に一致）
    • レビュー／リスク／セキュリティ／準備状況／判定アーティファクト（ファイル名が review|risk|security|readiness|verdict に一致）
    • .omc/plans/、.omc/specs/、.omc/interviews/、.omc/artifacts/、.omc/logs/、および関連するモード状態アーティファクト（実際の実行を記録した、.omc/state/ 内の正規の {mode}-state.json ファイル）
  3. 不足している証拠を明示的に記録します。説明が適切でも、不足している証拠を隠してはいけません。

フェーズ 1：初期化

変更概要を指定して merge_readiness_start ツールを呼び出し、状態を初期化します（ランタイムが --quick／--deep プロファイルを解析します（どちらのフラグもない場合、--standard がデフォルトです。解析対象のトークンではありません））。状態の形式：

{
  "active": true,
  "current_phase": "merge-readiness",
  "phase": "content",
  "profile": "standard",
  "threshold": 0.80,
  "max_rounds": 5,
  "required_dimensions": ["why", "change", "tradeoff", "risk", "team"],
  "questions": [],
  "answers": [],
  "awaiting_content": true,
  "readiness_score": 0,
  "result": "pending"
}

AI が生成したドキュメントと MCQ を merge_readiness_set_content で送信するまで、awaiting_content は true です。

フェーズ 2：説明ドキュメントと MCQ の生成（AI によるコンテンツ作成ステップ）

実際の差分と証拠に基づいて（テンプレートは使用せず）、以下を生成します。

  1. 5 セクションの説明：理由、変更内容、トレードオフ、検討したリスク、チームの理解度。
  2. MCQ のセット（正解の選択肢は各 1 つ。correctOptionId と任意の rationale を含めます）。
    • プロファイルで定められた最大ラウンド数まで（quick 3／standard 5／deep 8）
    • 必須の各観点に分散
    • 実装の細部ではなく、この変更そのものへの理解度を確認

merge_readiness_set_content を使って送信します（merge_readiness_start による有効なゲートが必要です。有効なゲートがない場合はエラーになります）。状態 JSON の書き込みや、内部ランタイム関数の呼び出しは行わないでください。無効なコンテンツは、修正可能な検証エラーとともに拒否されます。検証済みのコンテンツは、正式なセッション状態に保存されます。

merge_readiness_report を使うと、5 つのセクション、証拠、クイズの進捗、準備状況、マージ境界が状態から直接表示されます。このツールは読み取り専用で、ファイルを作成しません。解答と根拠は回答が完了するまで非表示です。キャンセルまたはオーバーライドした場合も、回答済みの質問のみが表示されます。

マージ境界には、次の文言を含める必要があります。「合格は、人間が変更を説明できることを意味します。マージの承認、テストやレビューの代替、リスクの受け入れを意味するものではありません。」

メンテナーによるオーバーライド権限

/merge-readiness --override <reason> が受け付けられるのは、MCP サーバーのランチャーが OMC_MERGE_READINESS_AUTHENTICATED_PRINCIPAL に認証済みプリンシパルを設定し、そのプリンシパルがカンマ区切りの OMC_MERGE_READINESS_MAINTAINERS 許可リストに完全一致で含まれている場合のみです。呼び出し元が指定する session_id は状態レコードの選択にのみ使用され、オーバーライド権限としては扱われず、override_owner にも記録されません。

フェーズ 3：人間によるクイズのループ（MCQ、1ラウンドにつき1問、深掘り面接形式）

各 MCQ を1ラウンドにつき1問ずつ、選択肢の ID とテキストを選択肢として AskUserQuestion で提示し、その後 merge_readiness_record_answer ツールで人間の選択を記録します（questionId + optionId）。ランタイムが客観的に採点し、次の質問に進むか、ゲートを確定します（pass / paused / blocked）。

合格する前に、以下の各観点を網羅します（quick では why/change/risk のみ）。

  1. why - この変更に取り組む価値があった理由
  2. change - 変更された動作、ワークフロー、インターフェース、または保守モデル
  3. tradeoff - 選択、先送り、または却下した内容とその理由
  4. risk - 検討したリスクと、引き続き残るリスク
  5. team - チームがこの変更をどのように理解し、保守すべきか

禁止する質問の種類：

  • 関数名の雑学
  • 行番号の雑学
  • 変数名の暗記
  • 非公開ヘルパーの暗記
  • 回答が変更の説明に役立たない質問

フェーズ 4：準備状況の採点（ランタイムが担当、客観的）

ランタイムが以下を計算します。

  • readiness_score = 正答率 = （正解数）/（回答済みの問題数）。範囲は [0, 1]
  • 観点ごとの網羅状況 = 必須の各観点について、少なくとも1問の MCQ に回答済みかどうか

ゲートの結果：

  • pass：必須の MCQ にすべて回答済みで、正答率がしきい値以上、かつ必須の観点を網羅
  • paused：必須の MCQ にすべて回答済みだが、正答率がしきい値を下回る（または必須の観点が未網羅）
  • blocked：最低限の証拠がない（差分／変更を示す情報がない）

しきい値：quick 0.70 / standard 0.80 / deep 0.90。

フェーズ 5：結果の確定

以下のフィールドをターミナルセッションの状態に保存し、merge_readiness_report で確認します。

  • 最終的な準備状況スコア
  • 観点ごとの内訳
  • 人間の回答
  • AI による評価
  • 結果
  • ブロックまたは一時停止の理由となった不足項目
  • 次のステップ

フェーズ 6：引き継ぎ

pass の場合：

  • 変更を人間によるマージ承認に進められることを伝えます。
  • マージは行いません。

paused の場合：

  • 説明が不足している観点を伝えます。
  • レポートを読み直すか修正し、/merge-readiness を再実行するよう勧めます。

blocked の場合：

  • 再実行する前に作成が必要な証拠を伝えます。

<Tool_Usage>

  • 人間に背景を尋ねる前に、リポジトリ内検索とローカルの成果物を使って証拠を収集します。
  • 利用可能な場合は、構造化されたユーザー質問を使用します。
  • merge_readiness_start でゲートを初期化し、merge_readiness_set_content でレポートと MCQ を送信し、merge_readiness_record_answer で各選択を記録し、merge_readiness_report で現在の監査記録を表示します。状態の読み取り／ステータス確認／クリアは .omc/state/merge-readiness-state.json に対してのみ使用します。クイズの内容を送信するために汎用の状態書き込みを使用してはいけません。state_clear はマージ準備状況のキャンセル処理を行い、終了状態を保持します。同時進行中のクイズをキャンセルしないよう、現在の session_id を渡します。 </Tool_Usage>

<Escalation_And_Stop_Conditions>

  • ユーザーが停止／キャンセル／中断を指示した場合 -> 終了状態 cancelled を保存して停止します。
  • 差分または変更の証拠がない場合 -> blocked。
  • 必須の観点を人間が説明できない場合 -> paused。
  • 準備状況のしきい値に達し、必須のゲート条件を満たした場合 -> pass。 </Escalation_And_Stop_Conditions>

<Final_Checklist>

  • 証拠の収集を完了
  • 不足している証拠を記録
  • 説明文書（5 セクション）と MCQ を merge_readiness_set_content で送信
  • AskUserQuestion で MCQ を1ラウンドにつき1問ずつ提示
  • AskUserQuestion のマーク済み出力から各回答を対応付け（客観的な採点）
  • 実装の雑学を問う質問を回避
  • 正答率をランタイムが計算
  • 結果が pass、paused、blocked、overridden、または cancelled
  • マージの境界を明確化
  • 直接の実装やマージを実行していない </Final_Checklist>
## 推奨されるデリバリーパイプライン 
/deep-interview
  -> /omc-plan or /ralplan
  -> /ralph, /team, or /autopilot
  -> /ultraqa and review
  -> /merge-readiness
  -> human merge approval

Autopilot Bridge

設定されている場合、Autopilot は QA／検証後にこのワークフローを呼び出すことがあります。

{
  "autopilot": {
    "mergeReadiness": true
  }
}

autopilot.understandingGate は、autopilot.mergeReadiness との互換性を保つための非推奨エイリアスです。

タスク：{{ARGUMENTS}}

コメント

Markdown 対応