mcpField
E
execute

execute

github.com/chrislacey89開発465 回インストール今日更新
リポジトリ

execute について

範囲が明確な実装タスクを計画、構築、結果検証、コミットまで進めるパイプラインスキルです。ブランチ分離、タスクコンテキスト、TDD マーカーの確認を設け、監督ありと AFK の実行手順を分けています。

主な機能

  1. 01計画・構築・検証・コミット
  2. 02ブランチとワークツリーの分離確認
  3. 03タスクコンテキストを実行条件に設定
  4. 04監督ありと AFK のモードに対応
  5. 05環境確認と TDD マーカーの適用

活用シーン

  1. 01範囲が定まった Issue の実装
  2. 02十分なコンテキストでの無人実行
  3. 03ホスト提供の分離ワークスペースでの作業
  4. 04コミット前の実際の結果確認

インストール

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

$npx skills add https://github.com/chrislacey89/skills --skill execute

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
mutation-at-consumption.md
next-step-menu.md
restated-claims.md
sidecar.sh
state-backend.md
trivial-task-rule.md

詳細

翻訳後に原文が更新されています。最新の内容は原文をご確認ください。

実行

作業をひとまとまり完了させます。計画し、実装し、実際の成果を検証して、コミットします。

呼び出すタイミング

これは、/prd-to-issues で具体的な作業範囲が作成された後、またはユーザーが明確に範囲を定めた実装タスクをすでに提示している場合に使う、主要なパイプラインスキルです。

作業を実装し、検証して、コミットできる状態なら /execute を使ってください。

実装中にユーザーの積極的な判断、監督、承認が引き続き必要な場合は、HITL の /execute を使ってください。次の作業範囲がすでに GitHub に確実に記録され、作業を妨げる要因がなく、Issue と境界マップ、およびリンクされた調査成果物（アーカイブファイルまたはスパイク Issue）や docs/solutions/ の情報から内容を明確に把握できる場合に限り、AFK の /execute を使ってください。

何も情報を持たない読み手にも内容が伝わること。それが AFK の反復作業です。/prd-to-issues §4 のコンテキスト完全性チェックは、その条件を満たすためのゲートです。このチェックでは、AFK の各作業範囲に ### Context ブロック、または空であることを明示した記述が含まれているかを確認し、Issue の作成前に必須としています。そのようなブロックのない AFK 作業範囲は、この条件を確認したのではなく、満たしていると推測したにすぎません。これは手続きを形式的に済ませる理由ではなく、その作業範囲を HITL で実行するか、/prd-to-issues に差し戻す理由として扱ってください。

必須の Ralph 自動検出ゲートと TDD マーカーゲートについては、以下の Step 0：前提条件 を参照してください。

問題や方向性がまだ定まっていない場合、/shape、/research、/write-a-prd の代わりに使わないでください。実装が完了し、レビューの準備が整った後は、/pre-merge の代わりに使わないでください。

ワークフロー

0. 前提条件

ブランチ分離ゲート。 実装作業に入る前に、以前の作業で使ったままのフィーチャーブランチではなく、このタスク専用に作成されたクリーンなブランチで作業していることを確認してください。

分離がすでに用意されている場合は、手を引く（番号付きルールより先に確認してください）。 環境によっては、/execute の実行前にセッション専用の分離されたワークツリーとブランチが提供されます。Conductor のワークスペース、GitHub Codespaces、devcontainer などのホストでは、それぞれ「1 ワークスペース＝1 ブランチ。ベースから自動フォーク」という形で環境が用意され、セットアップスクリプトも実行済みです。その場合、プロビジョニングはパイプラインの担当ではありません。ここでワークツリーを作成すると、ホストのワークツリー内にさらにワークツリーを作ることになり、タスクではなくワークスペース名が付いたホストのブランチも「古い」ものではありません。環境のシグナルを読み取り、すでにワークツリーを管理している側に任せてください（Norman — パイプラインが常にプロビジョニングすると頭の中で決めつけず、環境が示す情報を読み取ること。Meadows — ストックごとにアクターは 1 つなので、パイプラインは競合する管理者を追加せず、処理を委ねます）。

.claude/settings.json の worktree.provisioning（"host" | "pipeline" | "auto"）からプロビジョニングモードを判定してください。このキーがない場合は、既存の research.storage の前例にならい、デフォルトを "auto" とします。

  • host — 分離はホストが管理します。無条件で手を引いてください。
  • pipeline — パイプラインがプロビジョニングします。このスタンドダウンを省略し、以下の番号付きゲートを実行してください。
  • auto（デフォルト）— 次のシグナルのいずれかが成立したら手を引いてください。
    • ホスト環境変数が、このツリーを示している場合 — 以下のブロックで host_owned=yes が出力されます。これは最も低コストで主要な判定方法です。パイプラインが使える検出手段は Bash のみで、これらの変数はエージェントのシェルから参照できます。ただし、変数が存在するだけでは不十分です。CONDUCTOR_WORKSPACE_PATH は Conductor の配下で起動されたシェルすべてに引き継がれ、別のリポジトリのワークスペースを指す場合があるため、現在のトップレベルパスが含まれている場合に限り判定に使います。（カレントディレクトリ内の .conductor ディレクトリで検出してはいけません。Conductor はこれをワークスペースではなく $CONDUCTOR_ROOT_PATH の下に保持します。）
    • 現在のワーキングツリーがリポジトリのプライマリワーキングツリーでない場合 — git rev-parse --show-toplevel の結果が、git worktree list --porcelain の最初のパスと異なります。
# host-signal: does a host env var describe THIS tree, not just this shell?
host_owned=no
top=$(cd "$(git rev-parse --show-toplevel)" && pwd -P)
if [ -n "${CONDUCTOR_WORKSPACE_PATH:-}" ]; then
  ws=$(cd "$CONDUCTOR_WORKSPACE_PATH" 2>/dev/null && pwd -P) || ws=
  if [ -n "$ws" ]; then
    case "$top/" in "$ws"/*) host_owned=yes ;; esac
  fi
fi
if [ -n "${CODESPACES:-}" ] || [ -n "${REMOTE_CONTAINERS:-}" ]; then host_owned=yes; fi
echo "host_owned=$host_owned"

CODESPACES と REMOTE_CONTAINERS には比較対象となるパスがなく、存在の有無を確認するために読み取ります。これらはコンテナー単位の変数であり、これらを認識するシェルは、それらが示すリポジトリがあるコンテナー内で動作しています。同じブロックが /closeout、/lfg、/init-pipeline にもバイト単位で同一の内容で記載されており、パック自身のリポジトリにある scripts/test-host-signal-containment.sh によって固定されています。

スタンドダウンする場合：worktree の作成と EnterWorktree はスキップし、現在のブランチでそのまま作業してください。 以下の番号付きルールはすでに満たされています。特に、ルール 3 は適用されません（ホストが用意したブランチはベースブランチでもタスク名のブランチでもありませんが、古いブランチではありません。worktree をネストしたり、作業を中止したりしないでください）。ホストによって Git で無視される設定ファイルと依存関係がすでに用意されているため、「Worktree setup checklist」の大部分は参考情報にすぎません。コマンドが失敗した場合は .env.local／依存関係を軽く確認しますが、再度セットアップしないでください。例外は git フックの項目で、これは引き続き適用されます。 ホストが用意するのは 追跡対象の ファイルと依存関係です。git フックは worktree ごとに存在する、追跡されない .git/hooks にあるため、ホストが用意したワークスペースには通常ありません。スタンドダウンする場合も、この項目を確認してください。その後、issue の形状を判定するゲートに進みます。

このスタンドダウンは、/closeout のティアダウン確認とは意図的に 非対称 です。受け入れ側で確認するのは 「すでに分離されていますか？」 だけなので、一般的な検出（toplevel ≠ primary）と環境変数のヒントのどちらでも判断できます。一方、払い出し側で確認する 「ティアダウンの責任者は誰ですか？」 という問いは、より厳密であり、一般的なヒューリスティックだけには頼れません。パイプラインが作成した worktree も toplevel ≠ primary を満たすためです。/closeout では、明示的な設定またはホストの環境変数のみを基準にします。

  1. 現在のブランチを確認します：git branch --show-current
  2. 現在のブランチがベースブランチ（例：main、prod、master）の場合、このタスク用の新しいフィーチャーブランチを作成します。
  3. 現在のブランチが別のフィーチャーブランチ（ベースブランチでも、このタスク用の名前のブランチでもない）の場合、前の作業で使った古いブランチです。ここで新しい作業をコミットしないでください。例外： 現在のブランチが、このタスクの Consumes from #N 宣言に記載された兄弟スライスのブランチである場合、積み重ねた PR 用にそこから分岐する意図があります。そのまま進めてください。例外（ホストが用意した場合）： 上記のスタンドダウン確認が適用された場合、このブランチはホストが用意した分離済みのワークスペースブランチです。古いブランチではないため、そのまま作業してください。

分離されたブランチを作成するには、次のいずれかの方法を優先順に使用します。

  • Worktrunk（wt が使用可能な場合）：wt switch --create <branch-name> — 適切なベースから新しい worktree とブランチを作成して切り替え、ファイルシステムを完全に分離します。使い方は /worktrunk スキルを参照してください。
  • 通常の git：git checkout <base> && git checkout -b <branch-name> — 現在の作業ディレクトリに、適切なベースから新しいブランチを作成します。

適切なベースは、デフォルトではリポジトリ自体のベースブランチです。リポジトリの宣言内容を使用してください（git symbolic-ref refs/remotes/origin/HEAD --short | sed 's@^origin/@@'）。main と決めつけないでください。スライスが、インポートするシンボルを生成する未マージの Consumes from #N 依存関係を持つ場合は、兄弟スライスのブランチから分岐してください。そうすることで、積み重ねた PR はその兄弟の PR を対象にできます（Hammant の Trunk-Based Development 第 13 章：1 つのストーリーに複数の PR。兄弟の PR は 2 日以内にリポジトリのベースブランチへマージする必要があります）。

タスクに基づいてブランチ名を決めます。例：issue-5-landing-page、landing-page、または issue のスラッグ。以前の作業で使ったブランチ名を再利用しないでください。 作業ツリーをセッションとして開きます（作業ツリーを作成した場合）。 作業ツリーを作成することと、その中でセッションを実行することは別です。wt switch --create は各コマンドの実行後にシェルの cwd をプロジェクトルートに戻すため、さらに手順を踏まないと、セッションは元のチェックアウトに紐づいたままとなり、報告される cwd は実際の作業場所と異なります。作業ツリーを作成したら、ハーネスの EnterWorktree ツールを使って中に入り、セッションの作業ディレクトリが実際に作業ツリーになるようにします。

  • EnterWorktree { path: <absolute-worktree-path> } を呼び出します。このリポジトリの git worktree list にパスがすでに表示されている必要があります（直前に作成したため、表示されているはずです）。これにより、セッションが作業ツリーに切り替わった状態が維持されます。
  • 作成手順は上記のとおりにしてください。wt switch --create／git worktree add は、.env.local と依存関係を用意する worktrunk の pre-start フックを実行します。EnterWorktree は cwd を切り替えるだけで、これらのフックは実行しません。まず作成して環境変数と依存関係を用意し、その後で中に入ります。
  • これにより、知識を頭の中ではなく、実際の環境に反映できます。cwd が編集やコミットの場所を正しく示し（監視しているオペレーターも確認できます）、コマンドごとに cd を付け忘れることもありません。接頭辞の付け忘れによって誤ったツリーに書き込むミスをなくせます。
  • Plain git オプション（git checkout -b、作業ツリーなし）では、現在のチェックアウトにブランチが作成されます。入る作業ツリーはないため、EnterWorktree を省略して、そのまま作業してください。

AFK／ヘッドレス環境での代替手順。 EnterWorktree を使用できない場合（ヘッドレス実行、AFK Ralph、cron）は、cwd の接頭辞を付ける方法に切り替えます。シェルの cwd は Bash コマンドの実行ごとにプロジェクトルートへ戻るため、このセッションのすべての Bash 呼び出しの先頭に cd <absolute-worktree-path> && を付けてください。この方法を使うのは、ハーネスのツールを本当に使用できない場合だけです。ネイティブの仕組みがない環境向けに残されている、従来の回避策です。

この作業ツリーの削除は、パイプライン末尾の /closeout が担当します。PR のマージ後、/closeout はシェルをベースチェックアウトに戻し、作業ツリーを削除して、マージ済みのブランチを整理します。/execute は作業ツリーのライフサイクルにおける流入側で、/closeout は流出側です。以下の手順 6 のクリーンアップでは .tdd-* マーカーだけを削除します。作業ツリーは意図的に削除しません。

作業ツリーを作成したら、セットアップします。 新しい作業ツリーには追跡対象のファイルは引き継がれますが、Git の無視対象ファイル（.env.local、作業ツリーごとの依存関係、ビルドキャッシュ）は引き継がれません。方法は 2 つあります。

推奨 — worktrunk フックで一度だけ設定する（プロジェクト内の .config/wt.toml）：

[pre-start]
copy = "wt step copy-ignored"
install = "pnpm install"

pre-start フックはブロッキング処理です。完了するまで作業ツリーは準備完了として報告されません。.env.local や node_modules を必要とする後続コマンドがフックと競合しないよう、両方に post-start ではなく pre-start を使用してください。詳しい設定方法は /worktrunk を参照してください。設定はプロジェクトごとに一度だけです。

代替 — 通常の git worktree add を使った手動セットアップ（worktrunk なし）：

  • cp <source-repo>/.env.local <worktree>/.env.local を実行します（プロジェクトで使われている、その他の Git 無視対象の設定ファイルもコピーします）。
  • 作業ツリー内で、プロジェクトのインストールコマンド（pnpm install、npm ci、pip install -r requirements.txt など）を実行します。

作業ツリーのセットアップチェックリスト（DO-CONFIRM — 各手順を実行し、次に進む前に確認してください）。 作業ツリーの作成方法にかかわらず適用されます。

  • Git で無視される設定ファイルがコピーされている — .env.local（およびその他の .env.*、*.local、プロジェクト固有の無視対象設定ファイル）が作業ツリーに存在する
  • 依存関係がインストールされている — インストールコマンド（pnpm install、npm ci など）が作業ツリー内でエラーなく実行されている
  • セッションが作業ツリー内にある — EnterWorktree { path } で移動しているため、pwd がプロジェクトのルートではなく作業ツリーのパスを返す。AFK／ヘッドレスのフォールバック時に限り、この項目は、すべての Bash 呼び出しに cd <absolute-worktree-path> && のプレフィックスが適用されていることを意味する
  • $CLAUDE_PROJECT_DIR のスコープが正しい — プロジェクトのスクリプトでこの環境変数を参照している場合、プライマリリポジトリではなく作業ツリーのパスに解決されることを確認する
  • ローカル Git フックがインストールされ、その管理ツールが PATH にある — ls "$(git rev-parse --git-dir)/hooks/" | grep -v '\.sample$' で何かが表示され、リポジトリが宣言している管理ツール（lefthook、husky、pre-commit など）が解決される。フックは .git/hooks にあり、作業ツリーごとに管理され、追跡対象外のため、新しい作業ツリーにはフックが一切引き継がれない。しかも最悪の形で、失敗がひそかに起こる。すべてのコミットが成功し、コミット時にリポジトリが保証すると記載している内容が一切実行されない。管理ツールがなければ、インストールする（lefthook install）か、Step 6 のレビューメモに、このブランチではローカルゲートが無効だったと記録する。これにより、ローカルで問題なく実行できたことをマージゲートの結果だと誤解されずに済む
  • 分類マーカーが存在しない — .claude/.tdd-active、.claude/.tdd-skipped、.claude/.lfg-active が作業ツリーに存在しない（クリーンな状態。Step 3 でいずれかを作成する）
  • レビュー後のロックフラグが存在しない — .claude/.review-stamped と .claude/.fix-findings-active が存在しない。どちらも前のブランチのレビューに属する。/pre-merge の Phase 4 が前者を書き込み、/fix-findings が後者を書き込み、そのブランチの最後に /closeout と /fix-findings がそれぞれ削除する。.review-stamped が残っていると、この作業に対するすべての実装書き込みが開始前に拒否される。一方、.fix-findings-active が残っていると、作業全体を通してロックが保持される。こちらは気づかれにくい。見つかったものはどちらも削除する。レビューが行われていないブランチの開始時点なので、どちらもこのブランチを示すものではない

Issue 形状の検出ゲート。 タスクが GitHub issue の場合、未分解の PRD ではなく、スライス（実装可能な状態）であることを確認する。gh issue view <n> --comments を実行し、^Decomposed into: #\d+ に一致するコメントがあるか確認する。

  • そのようなコメントがある場合：続行する。PRD は分解済みで、作業者はその子スライスのいずれかに取り組むものと想定される（また、PRD ではなく該当するスライスの番号が渡されているはずである）。
  • そのようなコメントがなく、かつ issue の本文に shaped-pitch マーカー（Appetite、Rabbit Holes、No-gos、User Stories、Implementation Decisions という名前のセクション）が含まれている場合：停止する。これは未分解の PRD である。/prd-to-issues <this-issue-number> を実行して実装可能なスライスを作成し、その後、子スライスの issue のいずれかを対象に /execute を再開する。
  • Decomposed into: コメントが複数ある場合は、最も新しいものを読む。どれを有効とするかを確実に一つにするのは /prd-to-issues の役割である。

GitHub issue に関連しない単発タスクでは、このゲートをスキップする。

ブロックされたスライスのゲート。 引き続き issue を確認し、実装に着手できる状態か確かめる。変更直後は古い値が返る可能性のある集計件数ではなく、依存関係そのものを読む。

gh issue view <n> --json blockedBy \
  --jq '{open_blockers: [.blockedBy.nodes[] | select(.state == "OPEN") | {number, title}],
         ever_wired: .blockedBy.totalCount}'

open_blockers が空なら着手可能なので、続行する。未解決のブロッカーが一つでもあれば停止する。ブロッカーとなっている issue をユーザーに示し、先にブロッカーへ取り組むか、依存関係が古い、またはこのスライスには関係ないとして上書きするか、ユーザーに判断してもらう。実装を始めてから途中で不足に気づくことがないようにする。 空のリストを信頼する前に、ever_wired を確認してください。 空になる理由は2つあります。このスライスに未解決のブロッカーが本当に存在しない場合と、リポジトリが /prd-to-issues §7 のエッジ接続より前のもので、エッジがまったくない場合です。totalCount はすべての状態のブロッカーを数えるため、この2つを見分けられます。ever_wired > 0 は、このスライスには以前エッジが設定されていて、ブロッカーがその後すべて解決したことを意味するため、空のリストは正しい結果です。ever_wired == 0 は、エッジが一度も書き込まれておらず、空のリストは何の証拠にもならないことを意味します。issue の本文に文章形式の Blocked by #N という行がある場合は、その記述を信頼し、ブロッカーの状態を手動で確認してください。

ここでの state は GraphQL の enum です。REST エンドポイントの小文字の open ではなく、大文字の OPEN です。

GitHub issue に紐づかない単発タスクでは、このゲートをスキップしてください。

Ralph 自動検出ゲート。 次の3つの条件をすべて確認してください。

  • タスクが GitHub issue に由来する（単発の口頭依頼ではない）
  • issue のスコープが複数スライスにわたる（PRD、大規模な一括処理、または複数のユーザーストーリー）
  • リポジトリのルートに ralph-once.sh または ralph.sh が存在しない

3つすべてに該当する場合は、今すぐ /setup-ralph-loop を実行してください。Ralph のセットアップが完了するか、条件に該当しないことが確認されるまで、Step 1 に進まないでください。

パイプラインフックのゲート。 フックファイルが存在することと、フックがレビュー後の編集ロックを備えていることは同じではありません。このゲートではその両方を確認します。レビュー後の編集ロックが導入される前に /init-pipeline を実行したプロジェクトでは、.claude/.review-stamped を読み取らないフックが使われています。そのため、ロックは機能せず、.claude/.fix-findings-active を保持している /fix-findings の修正担当者も、結局拒否されます。分類の条項によるもので、メッセージには /tdd と記される一方、修正担当者が実行中のルートには触れられません。どちらも黙って失敗するため、存在だけを確認しても不十分です。機能しないロックは、外から見るとレビュー後に誰もブランチを編集していない場合とまったく同じに見えます。

HOOK="${CLAUDE_PROJECT_DIR:-$(git rev-parse --show-toplevel)}/.claude/hooks/enforce-classification.sh"
# Every path the hook's own clause 1 tests. A path missing from this list is a
# boundary this gate cannot see, so an install predating it reports current
# forever. scripts/test-lfg-marker.sh section 7 pins this list against that
# clause; add a path here in the commit that adds it there, or the suite fails.
GATE_TERMS=".claude/.review-stamped .claude/.tdd-active .claude/.tdd-skipped .claude/.lfg-active"
if [ ! -f "$HOOK" ]; then
  echo "hooks-absent"
else
  missing=""
  for term in $GATE_TERMS; do
    grep -qF -- "$term" "$HOOK" || missing="$missing $term"
  done
  if [ -n "$missing" ]; then
    echo "hooks-stale"
    echo "missing:$missing" >&2
  else
    echo "hooks-lock-present"
  fi
fi

hooks-absent と hooks-stale はどちらも、今すぐ /init-pipeline を実行することを意味します。実行結果が報告されるまで Step 1 に進まないでください。前者は、強制用フックがないプロジェクトにそれらを用意します。後者は、既存のインストールに § 2 のフック本体を再配置し、§ 6 の .gitignore への追記も再実行します。既存のインストールでは、ロック用の2つのフラグに対してこの処理が行われていませんでした。これを行わないと、どちらのファイルも追跡対象外ファイルとして残り、コミットされる可能性があります。その結果、そのリポジトリの今後すべてのブランチでロックが解除されたまま、またはロックされたままになります。/init-pipeline § 2 では、既存の IMPL_PATTERNS 行を再配置時に引き継ぐため、アップグレードによってプロジェクトがカスタマイズしたトリガー対象がリセットされることはありません。サイドカーは /init-pipeline § 8 で扱われ、作成するかどうかはそこでのゲートが判断します。hooks-lock-present の場合は先に進みます。

このゲートで確認できないこと。3つ目の判定結果が、実際には行っていない主張を示すように読まれてしまうため、説明します。 ゲートはフック自身の条項1がテストするすべてのパスを検索し、各パスについて1つのバージョン境界を認識して、インストールがそのどちら側にあるかを報告します。この判定が正しいのは一方向だけです。フックにこれらの語句が1つでも欠けていれば、そのフックが導入前のものだと確実にわかるため、hooks-stale が出た場合の判定は正しいです。しかし、プロジェクトをアップグレードすると、これらの語句はその後も残り続けます。そのため、パスを追加せずに /init-pipeline § 2 のフック本体が後から変更されても（順序の変更、拒否メッセージの書き換え、条項のロジックの修正など）、hooks-lock-present と報告され、このゲートでは変更が配布されません。したがって3つ目の判定名は、このチェックでは確認できない最新性ではなく、見つかった語句を示しています。 GATE_TERMS はその主張全体であり、scripts/test-lfg-marker.sh のセクション 7 でフックの条項 1 に照らして検証しているため、フックにマーカーを追加してこのリストに追加しなかった場合、追加したコミットでテストスイートが失敗します。これにより、この段落で以前に文章として述べていたルール、つまり 境界には独自の用語を設け、それを導入するコミットで追加する が置き換えられます。chrislacey89/skills#370 はそのルールを読んだにもかかわらず従わず、配布用の用語を設定せずに .claude/.lfg-active を追加したため、それ以前にインストールされたすべてのプロジェクトで機能しないままになりました（chrislacey89/skills#385）。新しいパスを伴わない配布境界には、依然として仕組みがなく、独自の配布方法が必要です。

TDD 分類ゲート。 ステップ 3 では、コードを書く前に作業を分類する必要があります。/tdd を読み込むと、ハーネスの前処理によって .claude/.tdd-active が自動的に作成されます（LLM に依存しません）。ビジュアルフロントエンドでは .claude/.tdd-skipped が作成され、/lfg では .claude/.lfg-active が作成されます。PreToolUse フックは、これらのマーカーのいずれかが存在しない限り、すべての .ts ファイルへの書き込みをブロックします。ステップ 6 では、コミット後にこれらのマーカーをすべて削除します。

自明なタスクの例外。 実施中の機能開発に関係しない、単一コミットで完了するクリーンアップでは、.claude/.tdd-skipped を直接作成して分類を省略できます。すべて満たす必要のある 4 つの条件と、いずれかを満たさない場合の対応は、references/trivial-task-rule.md に一度だけ記載されています。

前提の検証ゲート。 タスクが「Assumptions from Parent PRD」セクションを含む GitHub イシューの場合、作業を進める前に 60 秒かけて、記載された各前提を現在の状況と照らし合わせて確認してください。それぞれについて、次を確認します。

  • 外部サービスは、想定される API と料金プランで引き続き利用できますか？
  • 現在判明している情報を踏まえても、親 PRD のアプローチは有効ですか？
  • このスライスが依存するパッケージは、互換性のあるバージョンと エントリーポイント を引き続き備えていますか？ 複数ランタイムに対応するパッケージでサブパスを変更すること（例：pkg → pkg/http、または pkg/<sub> → pkg/<other-sub>）は、型だけの差分を装ったランタイムに影響する変更です。無条件に許容される型同等の編集ではなく、前提の変化として扱ってください。

すべての前提が引き続き有効であれば、ステップ 1 に進んでください。いずれかの前提に変更があれば、作業を止めてユーザーに伝えてください。このスライスは実行前に、対象を絞った /research とミニ PRD のサイクルが必要です。実装中にパッチで対処してはいけません。古い前提のまま進み、実行中に回避策を試みないでください。

「Assumptions from Parent PRD」セクションのない単発タスクでは、このゲートを完全に省略してください。

未検証の実現可能性チェック（参考）。 タスクの調査成果物（アーカイブファイルまたはスパイクイシュー）に Uncertain または Speculative の前提が残っており、その妥当性を 10 行程度の使い捨てコードで簡単に確認できる場合は（ライブラリが実際にこの機能を公開しているか、ストリーミング経路が部分タグを出力するか、必要な場所でこの形式がレンダリングされるかなど）、メイン実装の前に /prototype FEASIBILITY を提案してください。XP の slack の原則に従い、これは参考情報であり、作業をブロックするものではありません。ユーザーには作業を進めて実装中に答えを見つけたい理由があるかもしれません。ただし、コストの非対称性は明らかです（XP の Defect Cost Increase）。この時点でのスパイクには数分しかかかりませんが、同じ前提が実装中に判明すれば、方向転換に数時間かかります。未検証の前提を明示し、ユーザーに判断を委ねてください。調査成果物のない単発タスク、またはすべての前提に Verified / Refuted が付いている場合は、このチェックを省略してください。

Consumes 検証ゲート。 イシューに基づくスライス作業の場合に限ります。タスクが /prd-to-issues によって作成された GitHub イシューに由来し、その ## Boundary Map / ### Consumes セクションが、すでにクローズ済みの上流スライスを参照している場合は、60 秒かけて、記載されたシンボルがそれぞれ現在のツリー内の指定パスに存在することを確認してください。これにより、実装開始前に上流の境界マップのずれを検出できます。

Consumes の各項目について：

  1. ファイルパスが指定されている場合は、そのファイルが存在することを確認します。
  2. 関数、型、またはエクスポートされたシンボルが指定されている場合は、エクスポートを grep で検索します。
  3. 形状（例：「Effect Layer」「Zod スキーマ」「React コンポーネント」「Context プロバイダー」）が指定されている場合は、名前だけでなく、形状が一致することを確認します。純粋なヘルパー関数は「Effect Layer」の主張を満たしません。プレーンなオブジェクトは「Zod スキーマ」の主張を満たしません。
  4. Consumes エントリーで兄弟スライスの型付きシンボルが指定されている場合（/prd-to-issues の Boundary Map ガイダンスに従う）、コンシューマーのコードが形状を再宣言するのではなく、import type（またはその言語での同等の方法）を使ってプロデューサーから入力型を導出していることを確認します。プロデューサーとたまたま一致するローカルでの再宣言は DRY 違反であり、プロデューサーの変更に伴って気付かないうちにずれます。型付きインポートを使えば、この種のずれが構造的に起こり得なくなります。

Consumes のシンボルが欠落しているか、形状が間違っている場合は、停止します。上流の境界マップは古くなっています。次のいずれかを選択します。

  1. このスライスのスコープを拡大して不足分を補います。最初のコミットのメッセージと PR の説明にスコープ拡大を記載し、今後のスライスが古い記述を信頼しないよう、上流のクローズ済みイシューに事後修正コメントを投稿します。
  2. /correct-course を使って差し戻し、上流の境界マップを更新して、影響を受けるスライスの形状を整え直します。
  3. 不足している作業のために新しいスライスを作成し、このスライスをその作業が完了するまでブロックします。

不足分を黙って取り込んではいけません。次のスライスに手掛かりを残してください。

単発のタスク、まだ計画中の兄弟スライス、上流の Consumes エントリーがないイシューでは、このゲートを省略します。

このゲートの対象は、リポジトリー内のシンボル（パス、エクスポート、形状）です。外部から解決可能な宣言（パッケージ名、公開 API シンボル、ピン留めされたバージョン）を調査スナップショットと照合するミラーチェックは、/pre-merge の Boundary Map Contracts ディメンションにある「Spec-reality check」で実行します。Step 0 はスライス開始時点のレジストリーを確認し、/pre-merge はマージ時点のレジストリーを確認します。どちらのタイミングも意図的なものです。このゲートを広げて、レビュー時のチェックを重複させないでください。

1. タスクを理解する

参照されている計画、PRD、または GitHub イシューを読みます。コードベースを調べ、関連するファイル、パターン、慣例を把握します。タスクが曖昧な場合は、作業を進める前にスコープをユーザーに確認します。

イシューのコメントスレッドを読む（イシューに基づく作業のみ）。 タスクが GitHub イシューの場合は、実装前にコメントスレッドを読みます。本文だけで終わらせないでください。Step 0 のイシュー形状検出ゲートで gh issue view <n> --comments をすでに実行しているため、コメントスレッドはコンテキストに含まれています。再取得せず、それを利用してください。コメントにはパイプラインの継続状態が記録されています。前回の反復からの引き継ぎメモ（完了したこと、残っていること、前のコンテキストウィンドウで発生した正確なエラー出力）、進捗がなかった内容を明記した停滞時の停止メモ、上流の境界マップがずれた際にこのイシューに投稿された事後修正コメント、イシュー作成後に追加された明示的な人間によるスコープ変更などです。AFK Ralph のループでは、これは作業の根幹に関わります。反復 N+1 は、反復 N がスレッドに記した内容を引き継ぐように設計されているため、スレッドを読み飛ばすと、前の反復ですでに説明された作業を改めて導き出したり、繰り返したりすることになります。

優先順位のルール。 イシュー本文が継続的に有効な契約です。コメントは本文を補足するものであり、暗黙のうちに上書きするものではありません。コメントが権威ある追加情報となるのは、（a）パイプラインが作成した継続または修正コメント、または（b）人間による明示的なスコープ変更の場合に限ります。自由形式の議論はコンテキストであり、上書きではありません。コメントがスコープについて本文と矛盾しているように見え、それがパイプラインによる明確な修正コメントでも人間によるスコープ変更でもない場合は、そのコメントに従わず、矛盾があることをユーザーに伝えてください。 破棄ルール。 コメントを分類するだけでは不十分です。本文が扱っていないスレッドの部分をどうするか決めてください。このルールは、このスライスの PR が issue をクローズする場合（Closes #N）に適用されます。本文はこのパイプラインの基準です。受け入れ条件は本文に記載され、/prd-to-issues は本文を分解し、Closes #N は本文の条件に基づいてクローズします。コメントに残された機能は、これらの仕組みのいずれにも含まれないため、クローズと同時に気づかれないまま破棄されます。そして、issue は問題なくクローズされ、PR も問題なくマージされるため、この損失を示すシグナルは発生しません。

判断基準は単一のテストであり、「アイデアが優れているか」ではありません。 その機能を使う側を特定できますか？ その機能を利用する issue、スライス、PRD、またはリリース済みコードを示せるなら、対象になります。示せない場合、たとえば設計上の思いつき、「あったほうがいいかもしれない」という案、利用者が特定されていない、作者が考えを述べただけのアプローチなどは、対象にならず、昇格させてはいけません。昇格させるとスコープを作り出し、依存関係をでっち上げることになります。迷った場合は、対象になりません。

対象になるコメントについては、スライスを完了する前にユーザーに提示し、次の 2 つの処理方法を提案してください。

  1. 本文に昇格させる — 本当に同じ接点に関する内容であり、追加作業を受け入れられる場合は、この issue の受け入れ条件に追加し、このスライスで実装します。
  2. 独自の issue を作成する — 別の場所で行うべき実作業の場合は、特定した利用者を示す Blocks #N リンクを付けます。

どちらの方法でも、クローズ後も機能に担当者が残ります。気づかれないまま取り込んだり、独断でスコープを広げたり、見つけたというだけで実装したりしてはいけません。選択するのはユーザーです。AFK 実行では尋ねるユーザーがいないため、Blocks #N リンクを付けてフォローアップ issue を作成することを既定の対応としてください。本文への昇格は、承認なしにスライスの範囲を広げることになります。

GitHub issue に紐づかない単発タスクでは、この読み取りと破棄ルールを省略してください（Step 0 で使用するのと同じスコープガードです）。

まずサイドカーを解決してください。 調査アーカイブとプロジェクトの教訓は、このスキルに同梱されたリゾルバー references/sidecar.sh を、インストール先の絶対パスで使って確認します。サイドカーパスを自分で計算してはいけません。

SC="<this skill's directory>/references/sidecar.sh"
bash "$SC" resolve

終了コード 0 なら続行します。AFK イテレーションで終了コード 1 が返された場合は、停止してください。リゾルバーの標準エラーを出力されたとおりに表示します。SIDECAR MISS の場合、これは init コマンドです。サイドカーの作成は人間が行う作業であり、コンテキストの半分しか読み取っていないイテレーションが完了したように見えてしまうため、人間に判断を委ねてください。HITL 実行の場合は、同じ行をユーザーに提示し、読み取り専用で続行します。以下のソリューション検索は docs/solutions/ にフォールバックし、PRD に記載された調査パスは記載どおりに確認します。

この機能の調査成果物を読み取ってください。 PRD の「Research Reference」セクションに、その保存場所が記載されています。場所はプロジェクトの research.storage モードに応じて、次の 2 つのいずれかです。

  1. スパイク issue モード — PRD は research ラベル付きのクローズ済み GitHub issue を参照します（Refs #<spike-issue-number>）。次のように読み取ってください。

    gh issue view <spike-issue-number>

    新規クローン、CI サンドボックス、復旧したノートパソコン、コントリビューターの環境など、どのマシンでも動作します。

  2. アーカイブモード（既定）— PRD は調査エントリーの絶対パスを参照します。読み取る前に、次のように確認してください。

    SC="<this skill's directory>/references/sidecar.sh"
bash "$SC" require "<path the PRD cites>" --from "PRD #<n>"

    見つからない場合、リゾルバーは MISSING: <path> (referenced by PRD #<n>) と表示して終了コード 1 を返します。通常は、調査を作成したマシンとは別のマシンであることが原因です。AFK イテレーションでは停止してください。HITL 実行では、この行をユーザーに提示し、/research を再実行するか、コンテキストが欠落していることを明示的に承知したうえで続行するかを選んでもらいます。

一部の古い PRD は、リポジトリのルートまたは plans/ にある research.md を参照している場合があります。存在する場合は読み取ってください。場所にかかわらず、調査成果物にはアプローチの検討に役立てるべき、キャッシュ済みの技術調査が含まれています。すでに決定済みの内容を再調査してはいけません。 以下の grep を実行する前に、スライスの ### Context ブロックを読んでください（Issue に基づく作業のみ）。 スライスの Issue の ## Boundary Map に ### Context サブセクションがある場合は、まずそのアンカー、注意点、調査へのポインターを確認してください。/prd-to-issues は、このセッションでそれらを再度導き出す必要がないように、このブロックを作成しました。アンカーには、参照または手本にする既存ファイルが示され、調査へのポインターからは、親 PRD をたどって該当箇所を探すことなく、成果物に直接アクセスできます。これは任意ではありません。ブロックが作成されているのに優先して読まれないのは、単なる余計な手間ではありません。読者が読み飛ばすようになるセクションとなり、その周囲の Boundary Map に負担をかけることになります。

これらは事実ではなく、ポインターとして扱ってください。アンカーは分解時に作成されており、その後、兄弟 Issue がマージされている可能性があります。下記の優先順位ルールに従い、矛盾がある場合はコードと調査成果物を優先してください。アンカーが古い場合は、ブロックを読み飛ばすのではなく、その Issue のファイルを修正してください。

実装を始める前に、関連する過去の解決策について docs/solutions/ とサイドカーを確認してください。このブロックでは、サイドカーの solutions/ ディレクトリとプロジェクトの solutions.in_tree_path（none の場合はスキップ）を検索します。サイドカーがない場合は、docs/solutions/ のみを検索します。検索するキーワードを KW に設定してください。

SC="<this skill's directory>/references/sidecar.sh"
KW="relevant-keyword"
SIDE="$(bash "$SC" path solutions 2>/dev/null)" || SIDE=""
ITP="$(bash "$SC" config get solutions.in_tree_path 2>/dev/null)" || ITP=""
[ -n "$SIDE" ] || ITP="docs/solutions"          # SIDECAR MISS: fall back to the default store
for DIR in "$SIDE" "${ITP:-docs/solutions}"; do
  case "$DIR" in ""|none) continue ;; esac
  [ -d "$DIR" ] && grep -rl -- "$KW" "$DIR"
done
true

両方の場所で見つかった項目を列挙してください。一方がもう一方に優先することはありません。docs/solutions 以外の in_tree_path にある項目は、そのリポジトリ固有の慣例に従ったものです。通常のドキュメントとして読んでください。読んだ項目に別のパス（Related: ポインター、調査項目、ドシエなど）が記載されている場合は、それを参照する前に SC="<this skill's directory>/references/sidecar.sh"; bash "$SC" require "<cited path>" --from "<the citing entry's file path>" で確認してください（新しいシェルには SC がありません）。参照元から推測したパスではなく、出力されたパスを開いてください。MISSING: が表示された場合、AFK イテレーションでは作業を中断し、HITL 実行ではユーザーに報告してください。

この問題領域に関する過去の解決策がある場合は、その教訓を取り入れ、記録された落とし穴を避けてください。

成果物の優先順位： 調査成果物と解決策の項目で指針が矛盾する場合は、現行のインストール済みバージョンで検証されている調査成果物に従ってください。保存場所によって信頼度は変わりません。スパイク Issue とアーカイブ項目は同等の権威を持ちます。矛盾が重大で判断に迷う場合は、作業を進める前にユーザーに報告してください。解決策の項目は必要なものだけ読み込んでください。まず関連するキーワードを grep し、一致したファイルのみを読んでください。

2. 実装を計画する（任意）

タスクの計画がまだ作成されていない場合は、作成してください。GitHub Issue に境界マップ（Produces/Consumes セクション）が含まれている場合は、それを使って、実装またはコードで利用するインターフェースを把握してください。

スタック固有のリファレンス

実装を始める前に、プロジェクトのスタックを確認し、関連するベストプラクティスを読み込んでください。

  • Next.js／React プロジェクト：package.json に next または react が含まれている場合は、コードを書く前に以下のスキルを読み込んでください。
    • /vercel-react-best-practices — パフォーマンスの最適化と React Server Component に関するガイダンス
    • /vercel-composition-patterns — prop の乱立を避け、拡張性の高いコンポーネント合成パターン
    • /next-best-practices — ファイル規約、データパターン、メタデータ、エラー処理
    • /next-cache-components — キャッシュコンポーネント、use cache、cacheLife、cacheTag
3. 実装

停止 — コードを書く前に分類してください：

  • バックエンドコード → 今すぐ /tdd を実行します（.claude/.tdd-active を作成）
  • 動作に関わるフロントエンド（reducer、状態マシン、バリデーション、アクセシビリティ、インタラクションのリグレッション）→ 今すぐ /tdd を実行します（.claude/.tdd-active を作成）
  • フロントエンドのビジュアル／レイアウト／スタイリング／コピー → 次を実行します：mkdir -p .claude && touch .claude/.tdd-skipped

PreToolUse フックは、これらのマーカーのいずれかが存在しない限り、すべての .ts ファイルへの書き込みをブロックします。作業を分類するまでは、実装コードを書かないでください。

/tdd が利用できない場合は、次の最低限の手順に従ってください：

  1. 最小の垂直スライスの動作を対象に、失敗するテストを1つ書きます
  2. テストを実行し、失敗すること（レッド）を確認します
  3. テストを通すために必要な最小限のコードを書きます（グリーン）
  4. 次の動作スライスについて、手順1から繰り返します
  5. 必要に応じて、テストをグリーンに保ちながらリファクタリングします

テストをすべて先に書かないでください。1つ書いて、それを通してから、次に進んでください。

[TypeScript プロジェクト] ライブラリコールバックの戻り値。 論理単位が、ライブラリからアプリケーションに提供を求められるコールバック（エージェントフック、ミドルウェア、プロキシ、ツールハンドラー、render props、ライフサイクルメソッド）を実装する場合は、satisfies LibraryReturnType、新しいオブジェクトリテラル、または派生型（ReturnType<typeof …>）を使って、返す値をライブラリが宣言する戻り値の型に合わせてください。型付きのローカル変数を返してはいけません。TypeScript の余分なプロパティチェックは、型付きの値を返す場合には実行されないため、ライブラリのシグネチャで宣言されていないフィールドが、実行時に黙って破棄されます。根拠の全容については /tdd のリファクタリング手順を参照してください。調査成果物（アーカイブファイルまたはスパイクの課題）に Library Callback Contracts のスナップショット（/research フェーズ1.25）が含まれている場合は、採用されたフィールドの一覧を固定された参照元として使用してください。

インシデントではなく、コードにコメントを書いてください。 ここで書くコメントには、現在の理由、つまりこのコードが何をするのか、なぜこの形になっているのかを記します。ここに至ったインシデントについては、代わりにコミットメッセージと PR 本文に記してください。以前の動作はどうだったのか、どの先行する試みを置き換えるのか、途中で何を退けたのか、という点です。単位をコミットする前に、追加したコメントを読み返し、コードではなく履歴を説明する文があれば移動してください。コメントはこのファイルを次に編集する人に向けて書き、差分をレビューする人に向けて書かないでください。 レビューで出そうな異論に答える文、たとえば、なぜアダプターではなくこれなのか、実際に出荷されるコンポーネントはこちらなのか、並行する経路は意図的なのか、といった内容は、レビュー担当者に向けたものであり、他のレビュー向け説明とともに PR 本文に記すべきです。その見分け方は強調表現です。大文字の REAL、SAME、DELIBERATE は、ファイルの次の編集者ではない相手に反論するコメントです。同じことは一度だけ述べてください。ファイル内ですでに述べられている文や、その隣にある宣言ですでに述べられている文を繰り返すコメントは、削除するほうの文です。

論理単位ごとにコミットする

すべての変更を1つのコミットにまとめないでください。自己完結した進捗の単位ごとにコミットしてください。論理単位とは、コードベースが動作する状態を保てる最小の変更です。つまり、型チェックとテストが通り、未接続の箇所が残っていない状態です。例：

  • 1回のレッド・グリーン・リファクタリングによるTDDサイクル（1つの動作に対するテストと実装）
  • テストを含む新しいモジュール、型、またはスキーマ
  • 接続に関する変更（ルートの登録、依存性の注入、設定）
  • 動作を変えずに構造を改善するリファクタリング
  • マイグレーションファイルまたはシードファイル
  • ファイル単位で作業すると途中で型チェックが失敗する、複数ファイルにまたがる型またはインターフェースのリファクタリング。その波及範囲全体を1つの論理単位とします

各論理単位の完了後：

  1. pnpm run typecheck と pnpm run test（またはプロジェクトで同等のコマンド）を実行します。失敗があれば、コミットする前に修正してください。
  2. その単位に属するファイルだけをステージします。無関係な変更はステージしないでください。
  3. 「WIP」や「progress」ではなく、その単位で何を達成したかが分かるメッセージでコミットします。その単位で以前の動作を修正する場合は、上の段落でこの箇所を参照するよう案内されているインシデントの経緯を、コミットメッセージだけでなくPR本文にも記載してください。スカッシュマージでは、これらの単位ごとのメッセージが1つにまとめられます。また、/closeout ではスカッシュが一般的な方法として扱われるため、コミットメッセージだけでは後から参照できる記録として残りません。数か月後に git blame を実行する読者にそのまま伝わるのは、PR本文です。

単位がテストとその実装の両方に及ぶ場合は、同じコミットに含めてください。その単位をきっかけにリファクタリングを行ったものの、概念的に別の作業である場合は、リファクタリングを別途コミットしてください。

4. 検証

「すべての手順が完了した」は検証ではありません。実際の結果を確認してください。

この時点で、各論理単位はすでに型チェックとテストに合格した状態でコミットされています。ステップ4では、全体を通した検証を行います。個々の単位が通ることだけでなく、機能全体がエンドツーエンドで動作することを確認してください。

フィードバックループを最後にもう一度すべて実行します。

pnpm run typecheck
pnpm run test

問題があれば修正してください。修正が必要な場合は、別のコミットとしてコミットしてください（例：「XとYの統合を修正」）。

その後、検証の段階的な手順を適用し、実行可能な範囲で最も強力な段階まで進めてください。

Tier 1: 静的検証
  • 存在すべきファイルが実際に存在する
  • エクスポートが存在する（宣言されているだけでなく、実際にエクスポートされている）
  • モジュール間のインポートが正しく接続されている（解決できないパスからインポートしていない）
  • 実装に実質的な内容がある（スタブではなく、console.log のプレースホルダーでもなく、実際のコードが必要な箇所に TODO コメントが置かれているだけでもない）

削除の完全性（このスライスの差分でモジュールが削除または名前変更されている場合）。 パイプラインのどこにも書き込まれないセクション見出しではなく、すでに確認した差分からトリガーを判断してください。

BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD --short 2>/dev/null | sed 's@^origin/@@')
if [ -z "$BASE_BRANCH" ]; then
  for candidate in main master prod develop trunk; do
    if git rev-parse --verify "$candidate" >/dev/null 2>&1; then BASE_BRANCH=$candidate; break; fi
  done
fi
# A name is not a ref. $BASE_BRANCH names the branch (for `--base`, `git switch`);
# $BASE_REF points at it, and is the only thing safe as a range endpoint.
if git rev-parse --verify "origin/$BASE_BRANCH" >/dev/null 2>&1; then
  BASE_REF="origin/$BASE_BRANCH"
else
  BASE_REF="$BASE_BRANCH"
  echo "note: origin/$BASE_BRANCH does not resolve — measuring against the local branch, which may be stale" >&2
fi
git diff --diff-filter=DR --name-status "$BASE_REF...HEAD"

注意点： $BASE_REF の鮮度は最後に git fetch した時点に限られます。また、三角形のフォークの場合（またはリモート名が origin ではない場合）、origin/$BASE_BRANCH が存在しないか、上流ではなく自分のフォークを追跡していることがあります。その場合、else ブランチはローカルブランチにフォールバックしますが、これはこのガードで避けようとしている古い参照の動作です。誤った可能性の高い答えが何のシグナルもなく返されることが、この不具合が5か月間残った原因だったため、黙ってフォールバックするのではなく、stderr にその旨を出力します。件数がおかしい場合は、git fetch を実行して再試行するか、BASE_REF を手動で設定してください。

削除されたパスは D<TAB><path>、名前変更されたパスは R<score><TAB><old><TAB><new> として出力されます。出力が少しでもあればこの段階を実行し、出力が空ならスキップします。終了ステータスではなく出力で判定してください。コマンドはどちらの場合も 0 で終了します。スライス本文内の ### Deletes セクションは、確認すべき対象を示す任意のヒントであり、トリガーではありません。

削除または名前変更された各モジュールについて、外部の利用側サーフェスを列挙します。つまり、そのモジュールのエクスポートに加えて、利用側が出力するよう指示されていたシンボル名です。一般的なサーフェスは次のとおりです。

  • モジュールが読み取っていた DOM のデータ属性（data-*）
  • モジュールが適用または検索していた CSS クラス名とセレクター
  • グローバルイベント名またはカスタムイベント名（addEventListener('foo-bar')、dispatchEvent(new CustomEvent('foo-bar'))）
  • window、localStorage、または sessionStorage のキー
  • モジュールが所有していたルート名、設定キー、またはフィーチャーフラグ名

削除前のモジュール本体からサーフェスを推測します（git show <base>:<path> を使うか、スライス本文に Deletes のヒントがある場合はその記述を使います）。マージ後のツリーで、プロジェクトが使用するすべてのソーステキストファイル種別を対象に、各サーフェスを grep してください。固定の拡張子リストに限定しないでください。関連するサーフェスは技術スタックによって異なります（インポートなら .py／.rb／.go／.rs、テンプレートなら .vue／.svelte／.astro／.tsx、スタイルなら .css／.scss／.sass／.less／.styl、設定なら .yml／.toml／.json、配布されるドキュメントなら .md／.mdx）。合格には一致が 0 件である必要があります。一致が 1 件以上ある場合は、モジュールを復元するか、利用側を移行するか、意図的に機能しない状態として宣言し、クリーンアップを後続のスライスで追跡してください。インポートだけを利用側とみなすのは、最も限定的な定義です。サーフェスはそれより広い可能性があります。

上流の形状を確認するスイープ。 上記の利用側サーフェスのスイープ後、このスライスで共有モジュール上の変更対象となったエクスポートをそれぞれ列挙します（コンテキストフィールド、ビルダーの戻り値フィールド、インターフェースまたは型のメンバー、スキーマフィールド、エクスポートされたマップまたはレコードのエントリー）。削除後のツリーで、それぞれのエクスポートについて自己参照以外の読み取りを grep します。合格には一致が 0 件である必要があります。一致が 1 件以上ある場合は、その読み取りが現在も有効で意図的なものか確認します。一致が 0 件の場合は、同じ PR でそのエクスポートを削除してください。従来の利用側を削除した時点で移行期間は終了しており、読み取られていないエクスポートを残すと、インポート契約が広がり、将来のクリーンアップが目立たない削除ではなく破壊的変更になってしまいます。デッドエクスポートを検出するリンター（knip、ts-prune、TypeScript の noUnusedLocals）で多くの形状をカバーできますが、エクスポートされたコンテキスト、インターフェース、スキーマのフィールドは対象外です。これらは型そのものから読み取られるため、ツールには使用中に見えるからです。そのため、対象を絞った削除後の grep はリンターではできない役割を果たします。

ティア 2：コマンドの検証
  • テストが成功する（単に「テスト失敗なし」ではなく、テストが実際に存在し、実行されたことを確認する）
  • テストの実時間が予期せず増加していない。以前は高速だったテストで突然数秒増加した場合、特に retry、sleep、backoff、interval のコードを追加した後であれば、注入可能にせずリアルタイムプリミティブが導入されたことを示しています。/tdd § Timing-coupled primitives を参照してください。testTimeout を引き上げるのではなく、注入によって修正してください。
  • ビルドが成功する
  • リントに問題がない
  • 差分に記載されているコマンド（機能が公開する CLI、または読者がコピーして実行することを想定したコマンドブロック）は、記憶を頼りに書いただけでなく、実際に実行されている
ティア 2.5：ランタイム起動の検証

スライスがスキーマ、マイグレーション、環境設定、サーバー初期化、または新しいルートに関わる場合は必須です。アプリケーションの起動に変更がない既存モジュールの純粋なロジック変更の場合に限り、省略できます。

  • データベースの準備ができている：未適用のマイグレーションまたは db:push を実行します。テストが成功したというだけで、開発用データベースに最新のスキーマがあると想定してはいけません（テストでは独自のマイグレーションを実行するインメモリデータベースがよく使われます）。
  • 開発サーバーがコールドスタート時にエラーなく起動する：pnpm run dev（または同等のコマンド）で起動し、ビルドするだけでなく応答することを確認します。
  • 新規または変更したルートが 500 エラーなしで読み込まれる：curl -s -o /dev/null -w '%{http_code}' http://localhost:<port>/ が 200 を返すことを確認します。
  • 必要な環境変数が存在し、有効である（.env.local または同等のファイルを確認します）。
  • 起動中、サーバーコンソールの出力に未処理のエラーがない

外部サービスの不足などで開発サーバーを起動できない場合は、省略したチェック項目とその理由を、ステップ 5 のチェックリストとステップ 6 のレビュー記録の両方に記載してください。チェックリストはユーザーに、レビュー記録はレビュアーに届きます。チェックリストにだけ記載すると、それが表示されない実行では情報がそこで途切れます。AFK 実行はすべてこれに該当します。また、検証の省略がレビューから見えなくなることこそ、このティアが解消するための問題です。

ティア 2.6：ドライラン以外の経路の健全性チェック（CLI とオーケストレーションのスライスのみ）

スライスで、ドライランまたはプレビュー機能を備えた CLI、スケジュール済みジョブ、cron ワーカー、またはオーケストレーションのエントリポイントを提供する場合は必須です。

ドライランが成功しても、通常実行の成功を意味するわけではありません。ドライランではストレージや副作用が発生する前に処理が短絡することがあり、本番経路に接続されたプレースホルダー関数が見過ごされる可能性があります。

本番コード経路のデフォルトとして接続されている各関数（レイヤー構築、DI コンテナ、設定オブジェクト、CLI フラグハンドラー）について、次を確認します。

  1. 関数にプレースホルダー、スタブ、TODO、または後続対応であることを示す名前、説明、コメントがあるか。
  2. ある場合、（a）ドライラン以外のモードで例外をスローするフェイルファストチェックによって保護されているか、または（b）ドライランのコード経路にのみバインドされているか。

フェイルファストガードなしで、ドライラン以外の経路のデフォルトとしてプレースホルダーが接続されている場合は、ただちに指摘してください。対応方法は次のとおりです。

  • ランタイムガードを追加する：if (!process.env.ALLOW_PLACEHOLDER) throw new Error(...) または同等の処理
  • スタブは dryRun === true の場合にのみバインドし、ドライラン以外の経路には実際の実装を必須とする
  • 実際の実装が用意されるまでスライスを保留する（範囲は大きくなりますが、サイレントに劣化する期間を完全に解消できます）

これはサイレント劣化のチェックです。オペレーターが --dry-run なしで実行した場合、出力は実際のデータになるでしょうか。それとも、プレースホルダーデータが本番経路に流れるでしょうか。

ティア 2.7：本番ランタイムとの同等性（deploy-runtime ≠ test-runtime の場合のみ）

条件付きです。決して普遍的なものではありません。以下のいずれかに該当する場合にのみ、この段階を実施し、それ以外の場合は完全に省略します。テストがデプロイ先と同じランタイムで実行されるスライス（Node から Node、Node から Vercel への作業の大半）では、この段階は適用されません。

  • スライスのデプロイ先ランタイムがテストランタイムと異なる場合 — 例：workerd と miniflare/Node、実際のブラウザーと jsdom、エッジ／Lambda ランタイムとローカル開発サーバー。
  • パスがデプロイ時に解決される公開済みまたは静的アセットをスライスが配信する場合 — 絶対パスの <link>／<script>／<img> 参照、公開／コピー手順、CDN またはワーカーの公開ルート。
  • テストランタイムでは適用されない制限がプラットフォームにある場合 — 暗号化の反復回数上限、リクエスト／レスポンスサイズ、CPU／時間の予算、バンドルサイズ、またはテストランタイムには存在するが本番環境にはない API。

この段階が必要な理由、そして検査レイヤーではなくフィードバックループである理由。 テストが成功しても、保証されるのは テスト がモデル化する環境での動作であり、コードの デプロイ先 での動作ではありません。テストランタイムがデプロイ先ランタイムより寛容な場合や、実際の成果物との境界がモックで置き換えられている場合、「テストが通る」ことは「本番環境で動作する」証拠にはなりません。これは開発環境と本番環境の同等性のギャップです（Twelve-Factor Factor X：ツール の観点から開発環境と本番環境のギャップを小さく保つ）。また、Continuous Delivery が本番環境に近い環境でのスモークテストによって解消する、自動フィードバックループの欠如でもあります。ここでの目的は儀式を増やすことではありません。「誰かがデプロイされたものを実行し、動作した」という手順を 構造化 し、セーフティネットを個人の注意深さではなくパイプラインに担わせることです。

テストビルドではなく、実際の成果物に対して実行します。

  • リリース済み の成果物を、デプロイ先のランタイム内またはそれに対してビルドして実行します — wrangler dev／本番ランタイムを使用するプラットフォームのエミュレーター、プレビューデプロイ、または実際の配信方法で配信する本番ビルドなどです。pnpm run dev を実行するだけでは不十分です。
  • 失敗が起きる境界を通る経路を、エンドツーエンドで検証します。ログインを送信する、公開済みページをブラウザーで読み込み、リンク先のサブリソース（/_astro/*、/assets/*、フォント、ファビコン）がそれぞれ 200 を返すことを確認する、テストでモックしたプラットフォーム API を呼び出す、といった検証です。HTML が 200 を返しても、サブリソースが 404 なら不十分です。
  • テストランタイムが本番環境より寛容だったためにテストが通った場合（適用されていない制限や、本番環境にはない API がある場合）は、成功ではなく 盲目的な テストとして扱います。本番環境の制限をアサーションに明示し、実際のランタイムで再検証してください。

より根本的な修正は通常 /tdd の上流にあります。テストを成功させるためにモックする必要があった境界（プラットフォームの暗号化 API、ファイルシステム、デプロイ時のコピー処理）は、まさに GOOS が モックすべきでない とする境界です。所有していない外部型を薄いアダプターでラップし、そのアダプターを統合テストします。この段階は同等性のギャップを検出し、自分たちが所有するアダプターと忠実なテストランタイムによって、再発を防ぎます。

レビュー頻度に関する注記。 相互に収束する根拠（Continuous Delivery の本番環境に近い環境でのスモークテスト、Twelve-Factor Factor X、Release It! の「Design for Deployment」、GOOS のウォーキングスケルトン）に加え、きっかけとなったインシデントが 1 件あったため追加されました（下流の Cloudflare Workers リポジトリでの audit-publish スライス、2026-06-25 — どちらもテストスイートでは成功しましたが、workerd／デプロイ済みランタイムでのみ失敗しました）。妥当な数のスライスを確認した結果、他に問題のなかった差分の 10% 未満でしかこの段階が必要にならない場合は、儀式として残すのではなく、助言扱いに格下げするか削除してください。

ティア 3：動作の検証
  • API エンドポイントが期待どおりのレスポンスを返すことを確認します（curl または httpie を使用して検証します）
  • ブラウザーフローがエンドツーエンドで動作することを確認します（該当する場合、および検証可能な場合）
  • 入力からストレージ、出力までデータが正しく流れることを確認します
ティア 4：人による検証
  • 自分ではどうしても確認できない場合に限り、ユーザーに尋ねます
  • 確認してほしい内容を具体的に伝えます：「2 つ目のブラウザータブでレッスン 3 を開いたとき、プレゼンスインジケーターに自分の名前が表示されるか確認してもらえますか？」
  • ティア 1〜3 の代わりに、人による検証を決して使わないでください

検証で不備が見つかった場合は、修正して、その修正自体を独立したコミットとしてコミットします。以前のコミットを修正しないでください。履歴には、何を実装し、何を修正したかが残るようにします。

集合に関する主張の範囲を確認します。 集合全体に言及する文を書く前に、その集合、集合を導き出した列挙方法、および対象外のメンバーを明記します。見つかったメンバーすべてで同じ表現または同種のファイルが使われている場合、列挙が早すぎる段階で終わっています。references/restated-claims.md を参照してください。

その後、消費時点で変更を加えます（この作業範囲で、ある性質が成り立つと主張するテストを出荷する場合のみ）。 そのようなテストを出荷しない場合はスキップしてください。文章、設定、スタイルの作業には、適用する対象がありません。段階そのもの、成功結果の 2 つの解釈、および変更内容は合成せずコーパスから選ぶというルールは、references/mutation-at-consumption.md に一度だけ記載されています。

バグ修正の検証（機能追加ではなく修正の場合）

この作業単位でバグを修正する場合は、コミット前に以下の追加確認を行います。

  1. 修正を分類します：これは欠陥（問題の原因となったコードの誤り）を取り除く是正ですか、それとも欠陥が残ったまま失敗を抑える回避策ですか？ 回避策を現実的な選択として採用する場合は、コミットメッセージにその旨を記載し、課題を未解決のままにするか、是正のためのフォローアップを作成します。
  2. 構造的に同じ箇所を検索します：欠陥の原因となったパターンをコードベース全体で検索します。他の箇所にも見つかった場合は、すべてのインスタンスを修正するか、それらの課題を登録します。1 か所で欠陥を修正しても、ほかの 3 か所に残っていれば、75％は未修正です。
  3. 2 つの条件で確認します：（a）破損した状態が発生しなくなったこと、（b）元の失敗が発生しなくなったことの両方を確認します。失敗だけが抑えられ、根本的な状態が誤ったままなら、それは是正ではなく回避策です。
5. 手動検証チェックリスト

/pre-merge に引き渡す前に、作業の準備が整っていることをユーザーが確認できるよう、検証チェックリストを提示します。

準備： 実装した内容を要約し、作成したコミットと変更した主要なファイルを列挙します。作業が受け入れ条件のある GitHub の課題に起因する場合は、ユーザーが別途参照しなくて済むよう、その条件をチェックリストに含めます。

次のチェックリストを提示します。

動作の確認
  • ブラウザー、ターミナル、API で手動操作したとき、機能が期待どおりに動作する
  • エッジケースやエラー状態で正しく動作する
  • 隣接する機能にリグレッションがない
コード品質
  • 差分を確認済みで、デバッグコード、console.logs、コメントアウトされたブロックが残っていない
  • マージ前に解決すべき TODO が残っていない
  • 設定値や環境変数にすべき値がハードコードされていない
受け入れ基準

タスクが受け入れ基準のある GitHub の issue または PRD に由来する場合は、それらを確認し、各基準について具体的な検証手順を作成してください。各手順では、単に基準を言い換えるのではなく、ユーザーが何をすればよいか、何を期待できるかを正確に示してください。

スライス issue に親 PRD を参照する User Stories Addressed セクションがある場合は、そのスライスが対象としている親 PRD のユーザーストーリーを確認してください（/prd-to-issues のステップ 5 で作成された）派生マトリックスの項目は、ここで検証対象として示されます。対応付けられた各コミットメントについて、ユーザーが確認できる具体的な手順が必要です。スライス内の対応付けられていないコミットメントは、このチェックリストの対象外です。これらは他のスライス、またはマージ後の /pre-merge の照合に属します。

例 — AC に「ユーザーがメールでパスワードをリセットできる」とある場合：

  • /login に移動 →「Forgot password」をクリック → テスト用メールアドレスを入力 → リセットメールが届いたことを確認 → リンクを開く → 新しいパスワードを設定 → 新しいパスワードでログイン

生成した手順の後には、必ず次の項目を含めてください。

  • スコープが依頼内容と一致している — 依頼されていない追加がなく、抜けている項目もない（これは作業中のセルフチェックです。/pre-merge の Surgical Scope は、マージされた差分を対象に実行する差分時のチェックです）

検証済みのステータスを issue に書き戻します（強制措置）。 スライス issue の ## Acceptance Criteria チェックリストは、/prd-to-issues が作成した「このスライスをマージする前に満たすべき条件」の永続的な契約です。基準が検証済みと確認されるたびに（ステップ 4 の検証、またはユーザーによる確認によって）、そのチェックを issue に記録してください。これにより、誰もチャットログを読むことなく、トラッカーに実際の状況が反映されます。これは別途「忘れずに実行する」手順ではありません。すでに行った検証に伴って実施されるため、新たな判断は必要ありません。

安全に編集してください — 実際に検証したチェックボックス行だけを切り替え、本文を再生成しないでください。gh issue edit --body* は本文全体を置き換えます。そのため、現在の本文を読み込み、確認済みの - [ ] 行だけを - [x] に変更し、--body-file を使って書き戻してください。

BODY_FILE=$(mktemp)  # unique per run — two parallel worktrees / Ralph iterations must not share a temp path

# Guard the read half. A 5xx makes `gh` fail, and the edit below would then
# replace the whole issue body with whatever this file happens to hold.
if ! gh issue view <slice-issue-number> --json body -q .body > "$BODY_FILE"; then
  echo "writeback aborted: issue body fetch failed" >&2; rm -f "$BODY_FILE"; exit 1
fi
[ -s "$BODY_FILE" ] || { echo "writeback aborted: issue body came back empty" >&2; rm -f "$BODY_FILE"; exit 1; }
ORIG_BYTES=$(wc -c < "$BODY_FILE")

# In "$BODY_FILE", change ONLY the verified criterion lines under
# "## Acceptance Criteria" from "- [ ]" to "- [x]". Leave every other line untouched.

# Guard the write half. Flipping "- [ ]" to "- [x]" preserves length exactly,
# so the edited body is never shorter. Shorter means the edit dropped content.
[ "$(wc -c < "$BODY_FILE")" -ge "$ORIG_BYTES" ] || { echo "writeback aborted: edited body is shorter than the body read" >&2; rm -f "$BODY_FILE"; exit 1; }

gh issue edit <slice-issue-number> --body-file "$BODY_FILE"
rm -f "$BODY_FILE"

実際に検証していないチェックボックスは切り替えず、確認した基準以外の行には触れないでください。不注意な編集は issue の内容を壊すおそれがあります。これらのチェックボックスを書き込むのは /execute だけです。/pre-merge は読み取りますが書き込まないため、互いに矛盾するもう一人の編集者はいません。

ガードは必須であり、ステップ 6 の AFK 書き戻しでも同じガードを再利用します。 これは、負荷時に 5xx を返す API に対する読み取り・変更・書き込み操作であり、gh issue edit --body* は本文全体を置き換えます。そのため、ここで取得に失敗すると、単にスタンプが失われるのではなく、/prd-to-issues が作成し、/pre-merge のフェーズ 4 が照合する受け入れ基準が失われます。/pre-merge のスタンプにも、同じ理由で同じ 2 つのガードが適用されます。取得は1 回だけ再試行してください。2 回目も中断された場合は、チェックボックスを未チェックのままにし、書き込まずにその旨を伝えてください。

PR レビューの準備完了
  • すぐに PR を作成してアーキテクチャレビューを実施しますか（そのまま /pre-merge に進みますか）？

ユーザーがレビューして確認するまで待ちます。修正が必要な項目を指摘された場合は、対応して修正をコミットし、チェックリストを再提示します。ユーザーの確認後にのみ、ステップ 6 に進みます。

レビュー前の任意の理解確認。 このブランチをマージする人が作成者ではない場合や、承認前にコミットごとの内容を把握したい場合は、/pre-merge の前に /walk-commits を利用できます。コミットごとに、意図、最もリスクの高い行、意図的な特異点、設計上あえて含めていないもの、コミットごとの承認を確認する対話型のウォークスルーです。これは任意で、自動的に実行されることはありません。選択肢として提示し、自動実行しないでください。

「PR レビューの準備完了」項目によって引き継ぎがどう進むか： ユーザーがこの最後の項目を確認すると、ステップ 6 でクリーンアップを実施し、その後（タスクが PRD の課題から始まった場合は）課題番号を指定して /pre-merge を自動的に呼び出します。ユーザーが動作、コード品質、受け入れ基準の項目は確認したものの、追加作業とまとめる、外部からの入力を待つ、またはブランチをそのまま保持するために PR レビュー項目には「いいえ」と回答した場合、ステップ 6 でクリーンアップを行い、/execute は正常に終了します。準備ができたら、ユーザーが手動で /pre-merge を実行します。

6. クリーンアップと引き継ぎ

この時点で、コミットはすべて完了しているはずです。このステップでは、実装後のクリーンアップと /pre-merge への移行を行います。分類マーカーのみを削除します。意図的にワークツリーやブランチは削除しません。パイプライン末尾で PR がマージされた後にワークツリーとブランチを削除するのは、/closeout の役割です。ここでワークツリーを削除すると、レビューとマージの前にブランチが失われてしまいます。

分類マーカーを削除します。

rm -f "$CLAUDE_PROJECT_DIR/.claude/.tdd-active" "$CLAUDE_PROJECT_DIR/.claude/.tdd-skipped" "$CLAUDE_PROJECT_DIR/.claude/.lfg-active"

AFK 実行では、検証済みの受け入れ基準も書き戻します。 AFK Ralph の反復ではステップ 5 のユーザーチェックリストを省略するため、そこに伴う書き戻しも実行されません。AFK の反復を終了する前に、ステップ 4 で検証した受け入れ基準をスライス課題に書き戻します。ステップ 5 で説明したものと同じ gh issue edit --body-file による切り替えを使い、2 つのガードも必ず適用します。取得処理の終了ステータスを確認し、編集後の本文が読み取った本文より短くなっていたら書き込みを拒否します。書き込みを見守る人がいないのが AFK モードなので、ガードが最も必要なのもこのモードです。ひと目で読み取れる状態が最も重要なのも AFK モードです。検証済みの作業があるのに課題のチェックがすべて外れたままになることこそ、ここで解消する問題です。

レビュー用メモは PR 本文に記載します。 /execute が完了する時点では、どの検証レベルを実施または省略したかとその理由、ステップ 0 の Consumes ゲートで取り込んだスコープ、変化した前提、実装のうち最も薄い部分など、成果物に記録されない情報が残っています。作成者による準備は欠陥密度の低さと最も強く相関し（Cohen）、構造化された読解計画は不具合の検出率を測定可能なほど高めます（Dunsmore）。ただし、レビュー担当者にそれが届く場合に限ります。ステップ 5 のチェックリストに残しただけでは、情報はユーザーに届いてそこで止まります。AFK の実行ではチェックリスト自体が提示されないため、誰にも届きません。

代わりに、PR 本文に ## Review Notes ブロックとして記載し、レビュー担当者に渡します。GitHub 標準の形式なので、新しいセッションでも保持され、ファイルシステムに新しい状態を追加する必要もありません。/execute がメモをまとめ、/pre-merge が記載します。作成者モードとループモードの両方の引き継ぎで、このブロックを /pre-merge に渡します。/pre-merge はフェーズ 2 で、PR テンプレートの他の内容とともに本文に出力します。PR の作成を担うのは /pre-merge です。直後のステップが本文を開いて記載する内容を渡すためだけに、/execute が PR 本文への書き込みを始めるべきではありません。 ノートは信頼するものではなく、検証できるものでなければなりません。 レビュアーがこの変更について把握する情報はすべて、差分とこれらのノートから得られます。そしてノートを書いたのは、レビュー対象の作業を行ったエージェントです。新しいコンテキストによって正当化からの独立性は得られますが、虚偽の報告に対しては何の対策にもなりません（Leveson：どの制御システムも、測定チャネルの性能を超えることはありません）。どの検証コマンドを実行し、その終了ステータスがどうだったかを、レビュアーが再実行できる形式で記録してください。レビュアーが信じるしかない結論を決して断言してはいけません。「Tier 2.5 検証済み」はまさに、検証できない主張です。

## Review Notes



**Verification commands run**

| Command | Exit | Tier |
|---|---|---|
| `pnpm run typecheck` | 0 | 2 |
| `pnpm run test` | 0 | 2 |
| `curl -s -o /dev/null -w '%{http_code}' localhost:3000/reports` → `200` | 0 | 2.5 |
| `shellcheck --version` → `0.9.0` (matches `.shellcheck-version`); `shellcheck scripts/*.sh` | 0 | 2 |

**Name the version whenever the repo pins the tool, and say whether local gates ran.** A bare "lint clean" is a claim about *whichever* binary happened to be on `PATH`, and linters disagree across releases in both directions — so the reviewer cannot tell whether it describes the merge gate or a different instrument. Two lines close it: give the version beside any pinned tool's row, and state once whether the repo's own pre-commit/pre-push hooks were active for this branch. A branch whose hooks never ran is not disqualified; it is *differently evidenced*, and the reviewer needs to know which they are reading.

**Verification skipped, and why**
- Tier 2.7 — not applicable: test runtime and deploy runtime are both Node 22.
- Tier 2.5 dev-server boot — skipped, no Postgres available in this environment.

**Scope absorbed under the Consumes gate**
- #41 declared `ReportSchema` as a Zod schema; the tree had a plain object. Added the schema here; correction comment filed on #41.

**Assumptions that shifted**
- None.

**Known-weak spots**
- The retry path in `lib/fetch.ts` is covered only for the 2-attempt case.

/pre-merge を自動実行します。 モードは Step 5 の結果によって決まります。

  • Step 5 を実行し、ユーザーが「Ready for PR Review」と確認した → ここで author-mode の /pre-merge を実行し、レビュー用ノートと、タスクが PRD イシューから始まった場合はそのイシュー番号を渡します。これにより、ユーザーに再度確認することなく、スライスの系譜を収集し、境界マップの契約を検証できます。
  • AFK Ralph の反復（ユーザーに尋ねる相手がいないため、構造上 Step 5 を実行できない） → 手動実行に委ねて終了するのではなく、/pre-merge の loop-mode に入ります。これにより、AFK の境界が「コードが存在する」から「コードがレビューされ、すべての指摘に担当者が割り当てられている」に移ります。loop-mode は PR 上の永続的な台帳に指摘を記録し、コミットも判断も行いません。そのため、オペレーターが朝に引き継ぐのは、ひそかに一晩中編集されたブランチではなく、レビュー済みのブランチとトリアージ済みの一覧です。
  • ユーザーが PR レビュー項目に「no」と回答した、または軽微なタスクの例外により Step 5 がスキップされた → /execute はここで終了し、準備ができたらユーザーが手動で /pre-merge を実行します。

手動で終了する場合の次のステップメニュー。 /pre-merge を自動実行せずに /execute が停止する場合（ユーザーが PR レビュー項目に「no」と回答した場合、またはさらに作業をまとめて行う場合）は、空のテキストボックスだけを表示してはいけません。次のステップを単一の AskUserQuestion（references/next-step-menu.md を参照）で提示し、推奨する手順を最初に置き、各選択肢にはスキル名だけでなく、その結果を記載します。→ 今すぐ /pre-merge（推奨 — PR を作成してレビューする）、作業をさらにまとめる — PR を作成せずに終了する、先に /walk-commits（ブランチの各コミットを順に確認する）。パイプラインの次のステップに加え、今回の実行内容に基づくフォローアップを 1～3 件含めます。たとえば「実行中のアプリで受け入れ条件 N を検証する」「最もリスクの高い変更の差分を表示する」などです。/walk-commits のコミットごとの詳細確認にならってください。プラットフォームの自由記述式「Other」オプションが代替手段になるため、追加しないでください。このメニューは、Step 5 ですでに PR レビューが確認されている場合（自動実行で対応します）や、AFK Ralph の反復時（尋ねるユーザーがいない場合）には適用されません。

ランタイムの引き継ぎ行を出力します。 /pre-merge を自動実行する場合も、ユーザーが後で手動実行するために終了する場合も、新しいセッションをコピー＆ペーストで開始できるよう、この行を出力してください。

**Next session:** /pre-merge
**Input:** the verified commits on branch <branch-name>

<branch-name> は、コミットが存在する実際のブランチ名（git branch --show-current）に置き換えてください。

このコンテキストウィンドウ内でタスクを完了できない場合は、GitHub イシューにコメントを残してください。内容は以下のとおりです。

  • 実施したこと
  • 残っていること
  • 次の反復で注意すべき点や難しい部分
  • ビルドの失敗、テストの失敗、予期しない API の動作など、エラーが原因で失敗した場合は、エラー出力を正確に記載してください。要約ではなく、実際のエラーが次の反復に役立ちます。

エラーから、調査資料または PRD のアプローチが間違っている可能性が示唆される場合は、コメントでその旨を伝えてください。これは同じアプローチを繰り返すのではなく、手順を巻き戻すべきだという合図です。

AFK の進捗と停滞の検出。 Ralph のもとで実行する場合、進捗とは活動ではなく、認識状態の前進です。次のいずれかが未解決から解決済みに移行した場合に限り、反復は進捗として数えます。

  • アクティブなスライスの未達成の受け入れ条件
  • 失敗していたチェック（型チェック、テスト、または検証ゲート）が合格する
  • 調査資料または PRD に記載された、名前のある未知の事項や行き詰まりが解消される このような移行を伴わないコード変更は、停滞を示す点です。危険信号：同じスライスが複数回のイテレーションにわたってアクティブなままである、テストは依然として失敗しているものの「失敗の仕方が変わっただけ」である、表面的なコードの書き換えを伴って同じエラークラスが繰り返し発生する、受け入れチェック項目やゲートが一つも進んでいない。

停滞時の停止ルール。 同じスライスで2回連続してイテレーションを行い、停滞を示す点が続いた場合は停止し、上記の失敗繰り返し時のコメントと同じ形式で、何が進まなかったのかを明記したイシューコメントを残してください。3回目のイテレーションは開始しないでください。ヒステリシス：少なくとも上記の移行が1つ発生する回復イテレーションが1回あれば、停滞カウンターをリセットします。このルールは既存の失敗繰り返しルールを補完するものであり、置き換えるものではありません。

これは AFK Ralph のイテレーションにのみ適用されます。HITL の /execute 実行はユーザーの判断に従って進められるため、このヒューリスティックは必要ありません。

引き継ぎ

  • 想定される入力： 安全に実装できるだけの範囲が明確な、具体的なタスク、イシュー、またはスライス。AFK で実行する場合は、永続的な上流成果物も含みます
  • 生成するもの： 検証済みのコード変更を論理単位ごとに分割したコミット（論理単位ごとに1つ）、および次のレビュアーまたはイテレーションに引き継ぐ実装コンテキスト
  • 呼び出す場合があるもの： バックエンド作業や、動作を重視するフロントエンドのロジックには /tdd を、プロジェクトの技術スタックに必要な場合はスタック固有のリファレンススキルを呼び出します
  • 自動的に呼び出すもの： 強制フックが不足している場合、またはインストール済みのフックが Step 0 の GATE_TERMS にある語句のいずれか（ロックのスタンプフラグまたは分類マーカー）より古い場合に /init-pipeline を呼び出します。Step 0 の hooks-absent と hooks-stale の判定はいずれもここに進みます。タスクが複数スライスにわたる GitHub イシューに由来し、リポジトリに Ralph スクリプトがない場合は /setup-ralph-loop を呼び出します。また、Step 6 の最後に /pre-merge を呼び出します。author-mode では Step 5 が実行され、ユーザーが「Ready for PR Review」のチェック項目を確認した場合、loop-mode では AFK Ralph のイテレーションで呼び出します
  • デフォルトで次に実行するもの： /pre-merge。HITL モードでは、Step 5 の後にユーザーが確認すると author-mode で自動的に呼び出されます。AFK Ralph のイテレーションでは、loop-mode に自動的に移行します。PR レビューの項目に「いいえ」と回答した場合、または簡単なタスクの例外によって Step 5 が省略された場合は、ユーザーが手動で呼び出します

コメント

Markdown 対応