pr-workflow

以下の手順でissueを実行する。$ARGUMENTSにissueファイルのパスを渡す。 前提: AI は実装してコミットし、確認者（issue-verifier）の判定を受け、user に見てもらうものがあるときだけ止まり、指摘をこのセッションで直す。挙動の正しさは確認者が確かめ、user が見るのは使い心地・起票時の合意から外れたこと・エージェントが実行できない確認（rebuild・deploy・実機）である。見るものが無いか user が OK を出したら、Issue を閉じて PR を出すまでが担当。マージは user が i か GitHub で押す。リモートへは自分のブランチを push するだけで、main には push しない。

一度やったことをやり直したら、その場で worktree の外のメモに1行書き留める。 終わってから思い出すと、回数と時間が抜ける。PR 本文への置き方は手順11の3と、末尾の「手戻りの書き方」にある。

1. issueファイルを読む。frontmatter の depends: に挙がった id が worktree の issues/done/ に無ければ、前提の Issue がまだマージされていないので、報告して止まる（i が先に弾くので通常は起きない）
2. git status で、ブランチが claude/{id}-{branch-slug} かつワーキングツリーがクリーンなことを確認する（ブランチとworktreeは i が作成済み）。違えば報告して止まる
3. 対象ファイルを読んで実装
   • Issue の「対象」と「内容」から外れる作業に気づいたら、手を付ける前に AskUserQuestion で「新しい Issue にする / この Issue の中で直す / 見送る」を聞く。黙って直さず、黙って捨てない
   • 「新しい Issue にする」なら、local-issue skill の書式（テンプレート・id の振り方）で status: draft の Issue を書き、本筋に戻る。置き場は worktree ではなく元リポ（main のチェックアウト）の issues/ で、ステージもコミットもしない。main 側の Issue ファイルは untracked のまま i に拾われる前提で、worktree に置くと手順6の対象一致を崩し、worktree の削除で消える。id は書く直前に元リポの issues/（done/ を含む）を見て決める。並行で走る別の Builder と番号がぶつからないようにするため
   • 他の Issue ファイルの status: は変えない。この Issue は手順11で閉じる
   • 画面に出る変更は、画面を先に見せる。 画面を持たない Issue はこの箇条を飛ばす。使い心地で形が変わると、先に書いたテストと台帳が無駄になるため
     1. 画面を動く形まで作る。テスト・台帳はまだ書かない。コミットもしない
     2. 開発サーバーを立て、screen-operator にトップの URL と、Issue の確認に書かれた画面の道順を渡して操作させる。返ってきた「見えたもの」を Issue と突き合わせ、違えば直して流し直す。画面写真を自分で見て、崩れも直す
        • ヘッドレスのブラウザで再現できない操作（画面全体の共有、OS の権限や共有のダイアログ、印刷、通知）は道順に入れない。ブラウザの API を差し替え、渡した引数と失敗の扱いを確かめる道順に書き換える。本物の操作は 3 で user に頼む
        • 見せる状態のデータはここで道順の前に入れておく。user に URL やコマンドで作らせない
     3. crit-live <url> で画面を開いて渡し、使い心地を見てほしいと頼んで止まる。示すのは、変わった画面と何が変わったかだけで、挙動や値の照合は頼まない。2 で確かめてある。2 で道順から外した本物の操作があれば、それだけは試してほしいと添える
        • <url> は未ログインのブラウザで開いて、本番のログイン（Google など）に止まらずに入れるものにする。リポの CLAUDE.md の検証手段に仮のログインがあれば、その仮のログインから始まる URL を渡す
     4. 直しが返ったら直して 3 に戻る。見た目の直し（並べ方・文言・幅・色・余白）なら 2 を流し直さない。出す値・行・ボタンの有無まで変えたら、2 を流し直す。OK が出たら、テスト・台帳を書いて手順4へ進む
4. issueの「確認」項目と、リポ CLAUDE.md の「静的チェック / 検証手段」に従い提出前確認を行う。コードを読んでcaller・importの整合性も確認する。実行系・デプロイ系コマンド（rebuild / deploy / 本番起動）は実行しない
5. issueの保証節がリポの保証台帳 docs/guarantees.md の記載に影響する場合（新保証・変更・廃止）、テストと同じPR内で台帳（保証の文言と対応テストの表）を更新する。台帳の更新漏れは実装未完了として扱う
6. 日本語の .md を書き換えたなら、共通ガイドの「日本語の文書はコミットの前に校正させる」に従って jp-proofreader に校正させる。そのあと git add {変更したファイル} し、bash .claude/skills/pr-workflow/scripts/check-scope.sh {issueファイルのパス} を流して終了コード0を確かめる（ステージ済みの変更が issue の「対象」と一致するかを比べるスクリプトで、保証台帳を更新した場合はそれも対象に含まれていること）。非0なら足りないパスと余計なパスが出るので、実装に戻る
7. コミットする（保証台帳を更新した場合は同じコミットに含める）。メッセージ本文に報告を入れる（手順11で PR 本文の下敷きにする）。一時ファイルは作らず、heredoc で標準入力から渡して1コマンドに収めること:

   git commit -F - <<'EOF'
   {type}: {タイトル}
   
   ## 変更内容
   {issueの内容フィールドを展開}
   
   ## 保証
   {issueの保証節の各項目 → それを固定したテスト（ファイル・テスト名）の対応。テストを伴わない場合は Issue と同じく `なし（理由）` }
   
   ## 静的確認結果
   {確認項目に対する結果。check-scope.sh の結果（終了コード0）を含める}
   
   ## 検証手順
   {Agent側で完結しない確認（実行・デプロイ・目視）を、リポ CLAUDE.md の検証手順の雛形に従って記載。なければ省略}
   EOF

8. 確認者（issue-verifier）に確かめさせる。渡すのは Issue ファイルのパスと worktree のパスだけで、何をどう作ったか・どこを見ればよいかは書かない。画面に出る Issue は、立てた画面のトップの URL も渡す。「否」があれば手順3に戻って直し、手順4〜7をやり直して確認者の判定を受け直す。「否」が無くなったら手順9へ進む

9. 承認を求める項目を並べ、あれば push・PR 作成はせずに止まる。項目は次の3つで、該当が無ければ「なし」と書く

   1. 確認者の判定。 手順8の判定の表をそのまま示す。「判定できない」があれば、何が足りないかを添える
   2. **起票時の合意から外れたこと。**保証節に無い保証の追加・変更、確認の項目の読み替え、対象 に無いファイルへの波及、確認者が挙げた範囲の外と目的に届かない点。根拠を添えて採るか（目的に届かない点は足すか）を聞く
   3. 人が見るもの。 Issue の 人が見るもの のうち、エージェントが実行できない確認（rebuild・deploy・実機）。手順3で使い心地の OK を受けたあとに画面を変えたなら、変えた画面と変えたこと。rebuild・deploy・本番起動は user が行う

   3つとも「なし」で、確認者の判定がすべて「合」なら、止まらずに手順11へ進む。 挙動の照合は user に頼まない。確認者が確かめてある。止まるときは以下を出力する: ✅ Committed on {branch}: {type}: {タイトル} Files: {git diff --name-only main...HEAD。差分は貼らない} Verifier: {項目1} Scope: {項目2} Verify: {項目3}

   差分を見たいと言われたときだけ、crit で見せる。worktree で crit stop（--all は付けない）を実行して、前に開いたこのブランチのレビューを止めてから、crit --base-branch main を run_in_background: true で起動し、URL（http://localhost:<port>）を載せて「ブラウザでレビューし、終わったら Finish Review を押してください」と添える。user が Finish Review を押すまでブロックし、先にレビューファイルを読んだり、user に何かを入力させたりしない。完了したら stdout の指示に従い、指摘は手順10で直す。指摘の無い Finish Review は差分を見終えた合図であって、PR を出す明示ではない

10. 直しを頼まれたら、Issue の範囲内なら追加コミットで直す（手順3のスコープ外の扱いは同じ）。画面の直しは手順3の「画面を先に見せる」の 4 と同じく扱う。直した範囲について手順4の確認をやり直し、手順8の確認者の判定を受け直して、手順9に戻る。直しで新しい Issue は起こさない 確認者の判定のあとに直したとき（「否」の直し、user の指摘の直し）は、新しい確認者を立てず、同じ確認者を SendMessage で再開する。渡すのは前回の判定のあとに足したコミットの範囲（<前回の判定の HEAD>..HEAD）だけで、何を直したかは書かない。セッションが変わって再開できないとき、または直しが Issue の対象の半分以上に触れたときは、新しい確認者で最初から確かめる
11. 手順9で止まらなかったとき、または止まったあとに user が PR を出すよう明示したら、次の順で進める。止まったまま明示が無ければ進めない
    1. Issue ファイルを同じ階層の done/ へ git mv し、frontmatter の status: open を status: close に変える。chore(issues): close {id} でコミットする
    2. git push -u origin {branch}
    3. PR を出す（base は main、題は手順7の実装のコミットの題）。本文はそのコミットの本文を下敷きにし、手順10の直しを反映した最終の状態に書き直す。最後に受けた確認者の判定の表を ## 確認者の判定 として載せ、その下に書き留めた手戻りを ## 手戻り として置く（書き方は「手戻りの書き方」）
    4. done/ のファイルの先頭に次の記録を足し、chore(issues): record PR for {id} でコミットして push する

       ## PR記録: {PR の題}
       issue: {id} ({ファイル名})
       PR: {PR の URL}
       
       {PR 本文}
       
       ---
       

    5. 以下を出力して終える。マージは user が i か GitHub で押す。user に頼まれたときだけ squash でマージする ✅ PR: {PR の URL} Next: このセッションを閉じる → i でマージ（worktree は閉じたときに、ブランチはマージで消える）

手戻りの書き方

手戻りの多くは、手順・道具・ガード・Issue の切り方のどこかが欠けて起きる。PR 本文に残せば、同じ欠けが別の PR でも起きたときに気づける。 節が無い PR と手戻りが無かった PR を見分けるため、無ければ なし と書く。

書くもの:

• 確認者の「否」と、それを直したやり直し
• 確認や CI が落ちて直したもの
• Issue の本文が足りずに止まったもの、user に聞き直したもの
• フックや deny が正しい操作まで止め、回り道したもの。止めて正しかったものは書かない
• Issue に書かれていない波及を手で直したもの

書かないもの: user の使い心地の直し（動くものを見てから決める、予定したやり直し）、main の取り込み、その場で1分もかからずに直した打ち間違い。

1つの原因を表の1行にし、同じ原因から続いたやり直しは1行にまとめて回数を「失ったもの」に書く。

## 手戻り

| 何が起きたか | 失ったもの | 原因の分類 | 仕組みで防げたか |
|---|---|---|---|
| <見えた事実と、分かった原因> | <やり直した回数>。<おおよその時間> | <分類> | 防げた：<どのファイルのどこに何があれば> / 防げない |

防げたと書いた行は「実装者の不注意」にしない。何が欠けていたかに応じて、ほかの4つのどれかにする。