open-pr

プロセス

1. 状態を確認する

作業ツリー、現在のブランチ、そのブランチにオープン中の PR がすでにあるかを確認します。ブランチを作成するか、PR を作成するか、既存のものをそのまま更新するかを決めるのは、この 3 つの情報です。

PR がすでにあり、ユーザーからの依頼ではなく後続作業が入ったためにこの作業を行う場合、新しいコミットによってタイトルや本文が古くなったときに限り更新します。つまり、変更の範囲、アプローチ、背景について、以前の説明では伝わらなくなった場合です。

未コミットの変更も作業の一部です。どの状態でも、本文を作成する前に /commit に従ってコミットします。作業がデフォルトブランチではないブランチにコミットされ、ベースブランチと PR の有無がわかったら完了です。

2. ブランチを確認する

ブランチ全体を確認します。git diff <base>...HEAD と git log <base>..HEAD を使い、何が、なぜ変更され、ユーザーから見て何が変わるのかを把握します。ブランチ上のすべてのコミットを理解できたら完了です。

3. 作成する

まず /humanize を読み込みます。タイトル、説明、コメントのすべての文言に従ってください。

直前に確認したブランチの内容をもとに、PR が新規か既存かにかかわらず、以下の形式に従ってタイトルと説明を新たに作成します。リポジトリに PR テンプレート（例：.github/pull_request_template.md）がある場合は、その構成を優先し、ここに記載された各セクションの指針をテンプレートのセクションに適用します。

既存の PR を更新する場合は、ユーザーが書いた内容を残します。Evidence の内容と To-do 項目（チェックボックスの状態も含む）を引き継ぎ、新しい内容があれば統合してください。

インラインコメントの案もここで作成します。説明と同じブランチの読み取りに基づいて作成します。

次の 2 つの質問は、該当する場合に限り、1 回の AskUserQuestion 呼び出しでユーザーに尋ねます。

• Evidence — Overview にユーザーから見える変更が記載されていて、セッションにキャプチャがない場合：今すぐキャプチャするか、ユーザー指定のファイルを使うか、スキップするかを尋ねます。
• Annotation — コメント案がある場合：PR と一緒に投稿するか、差分にはコメントを残さないかを尋ねます。コメントの内容も伝えてください。

--capture と --annotate が指定されていれば、これら 2 つの項目は事前に決定されているため、質問は不要です。それぞれの --no- 形式も同様に、反対の選択を確定します。フラグは質問を省略するだけで、判断そのものを省略するものではありません。キャプチャに値するものがない場合、またはコメントを付けるべき箇所がない場合は、どちらも作成しません。

PR が作成される前にキャプチャを行い、PR を完成した状態にします。キャプチャに失敗しても、そのまま作業を続けます。いずれの場合も、キャプチャのために起動したブラウザーセッションやアプリのプロセスは終了してください。

タイトルと、該当するすべてのセクションの案ができ、Evidence があればディスク上に保存され、投稿するコメントがあればその内容を把握できたら完了です。

4. 作成または更新する

ブランチをプッシュしてから、PR を作成するか既存の PR を編集し、/attach-media に従って Evidence を添付します。把握している作業がレビューを妨げる場合は PR をドラフトにし、それ以外はレビュー可能な状態にします。本当に判断がつかない場合に限り、質問してください。PR が存在し、その URL を報告できたら完了です。

5. 差分にコメントする

作成したコメントがあれば、1 回にまとめてレビューを投稿します。gh pr review はインラインコメントに対応していないため、event: COMMENT と {path, line, side, body} の配列 comments[] を指定して、gh api repos/<owner>/<repo>/pulls/<number>/reviews を実行します。PR の更新時は、すでに投稿されている内容を確認し（gh api repos/<owner>/<repo>/pulls/<number>/comments）、まだコメントがない行にだけ投稿します。作成したすべてのコメントを投稿したら完了です。

タイトルの形式

<type>(<scope>): <subject>。scope は省略可能です。

• 最新のコミットではなく、ブランチ全体の主な変更を示します。
• 変更内容は subject の動詞で表現します。update session handling ではなく、expire sessions after 30 days のようにします。
• subject は平文とし、末尾にピリオドを付けません。

説明のテンプレート

1–2 sentence summary: what the PR does and why.

A reference to the issue(s) this PR closes (`Closes <id>`).

## Overview

Strictly user-facing: what someone using the app sees or experiences differently. Refactors, component restructuring, and other implementation details belong in Changes. For purely internal PRs, keep it brief ("No user-facing changes."). If there's more than one user-facing theme, add a `###` subheading per theme with short prose under each.

## Changes

Open with the **shape** of the change as a whole — the one view a reviewer reads before the diff. Then a `###` subheading per unit of work with short prose under each, carrying the _why_ the Overview leaves implicit; a one-theme PR is a single paragraph.

Reference a commit by its bare short SHA, which GitHub autolinks.

## Evidence

Captures a reviewer can look at, each referenced inline beneath the prose that says what it proves.

## To-do

What a human must do to land or operate this change: run a migration, set an env var, flip a flag, merge a dependent PR first. Short checkbox bullets (`- [ ]`). Work this PR defers or leaves out of scope belongs in the issue tracker; generic local-testing steps don't belong at all.

Closes の行、Evidence、To-do は、記載する内容がある場合に限り含めます。

説明は、最後に記載するセクションで終わります。謝辞のフッター、生成ツールに関する行、作成セッションへのリンクは含めません。

図

図を使えば、文章で段落をかけて説明する内容をひと目で伝えられます。制御フローが変わる場合、ステートマシンが導入される場合、2つを超えるモジュール間でデータが移動する場合、複数のサービスにまたがる一連の処理を実行する場合、またはファイル構成が広範囲に再編される場合に使ってください。単一ファイルの変更なら文章で説明します。

• Mermaid。フェンス付きの mermaid ブロックを使います。フロー、状態、シーケンスの図に適しています。GitHub では本文内にレンダリングされます。/artifact-diagramming に従って描画し、実際の状態名、実際の名称、実際の分岐条件を使い、矢印には移動する内容をラベル付けしてください。
• フェンス付きテキスト。役割を示すファイルツリーや広範なリファクタリングの構造、実行時の順序を示す呼び出しツリー、UI 構造を示すコンポーネントツリー、分岐が重要で構文は重要でないロジックを示す擬似コードに使います。

インラインコメント

差分を見ても答えが分からず、レビュー担当者がその行で立ち止まったときに疑問を持つような箇所にコメントを付けます。たとえば、二次ループを安全にする上限値、フラグが切り替わるまで実行されない分岐、原因が別のリポジトリにある回避策などです。