mcpField
W
writing-pr

writing-pr

github.com/tester-army開発12.1k273 回インストール今日更新
リポジトリ

writing-pr について

プルリクエストのタイトルと本文を作成するためのガイドです。変更の結果を先に示し、図やコード、検証結果でレビューを支援します。

主な機能

  1. 01Conventional Commits形式のタイトル
  2. 02変更結果を示すタイトル
  3. 03変更点と理由を箇条書きで記述
  4. 04図・コード・画面証拠の使い方
  5. 05必須の検証情報

活用シーン

  1. 01レビューしやすいプルリクエストの作成
  2. 02フローや状態変更を図で説明
  3. 03修正前後の証拠を提示
  4. 04リポジトリ要件に沿った検証欄の作成

インストール

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

$npx skills add https://github.com/tester-army/e2e --skill writing-pr

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

詳細

PR のタイトルと本文の書き方

レビュアーはざっと目を通します。変更の全体像を最初の画面に示し、詳細は図やコードで伝えましょう。

タイトル

  • git log に合わせて Conventional Commits を使います： fix(playwright): provision the browser in a runner-side prepare hook。 PR は番号を付けて squash merge されるため、タイトルがコミットになります。
  • 仕様や API の破壊的変更には、コミットと同様に ! を付けます（feat(config)!: ...）。
  • 作業内容ではなく、変更による成果を示します。「agent-device の変更」ではなく、「appPath オプションでインストールできるようにする」とします。

本文

長文は避けます。変更内容とその理由を箇条書きで簡潔に示し、根拠を添えます。

  • 本文を書く場合は箇条書きにします。1 つの項目につき、事実は 1 つにします。
  • フローや状態が関係する内容には、mermaid 図を使います。ランナーのフェーズ、エンジンのフック、リプレイ経路、変更前後のアーキテクチャなどが該当します。
  • コードサンプルには、新しい API、テストファイルでの使用例、または重要な内部コードを示します。言語タグ付きのフェンスコードブロックを使います。
  • コードの言い換えではなく、コード参照（packages/e2e/src/run/execute.ts:42、GitHub のパーマリンク）を使います。
  • 直接的または間接的なビジュアルの変更（CLI の出力、レポーターの出力、ドキュメントのページなど）には、アップロードした画像または動画を添えた変更前後の表を使います。
  • ベンチマークには変更前後の表を使います。ベースラインは対象ブランチ、比較対象は PR です。
  • 仕様を変更する場合は、レビュー担当者がまとめて確認できるよう、章、スキーマ、suiteVersion の更新を 1 つの箇条書きにまとめます。
  • PR で Issue を解決する場合は、Fixes #123 を記載した ## Issue セクションを設けます。コミュニティからの fix、chore、test、perf、ci、build、revert の PR では必須です（CONTRIBUTING.md、Pull requests）。
  • すべての PR に ## Verified セクションが必要です：
    • 1 行目には、Ran it locally: yes または Ran it locally: no - <why> と記載します（ドキュメントの誤字、CI でのみ実行するもの、手元にないデバイスなど）。
    • yes の場合は、verify の対象範囲、実行したコマンド、確認できたこと、動作を示す CLI 出力、スクリーンショット、または動画を記載します。
    • yes の fix PR では、| main | this branch | の表で、バグと修正を並べて示します。
    • メディアをアップロードするには、gh 2.99+ の --attach を使います。本文では画像を Markdown（![after](./after.png)）で参照し、各ファイルを --attach で指定します。gh がアップロードして、パスを書き換えます。本文に動画のパスを書かないでください。添付した動画は末尾に追加され、プレーヤーとして表示されます。

省くもの

  • 「lint/tests を実行しました」というリスト。CI が報告するため、## Verified には CI で確認できないことを記載します。
  • 中間の履歴。「6k 行を 1k 行に squash した」「2 回リファクタリングした」「途中で名前を変更した」といった内容は、最終的な成果には残りません。最終的な squash merge コミットだけが存在するため、コメントするのもその内容だけです。
  • 差分を 1 行ずつ言い換えた説明。
  • 求められていないチェックリスト、署名、埋め草。

テンプレート

ビジュアルの変更前後：

| Before | After |
| --- | --- |
| ![before](url) | ![after](url) |

修正の検証（ローカル画像パスは --attach でアップロード済みアセットに変換されます）：

## Verified

Ran it locally: yes
- testbed, `e2e run tests/scroll.e2e.ts --video`: the new test fails on main
  and passes here

| main | this branch |
| --- | --- |
| ![bug](./main.png) | ![fixed](./branch.png) |

gh pr edit <pr> --body-file body.md --attach ./main.png --attach ./branch.png --attach ./video.webm

ベンチマーク：

| Scenario | main | this PR | delta |
| --- | --- | --- | --- |
| testbed default suite | 41s | 23s | -44% |

フロー：

```mermaid
flowchart LR
  A[collect] --> B[schedule]
  B --> C{cache hit?}
  C -- yes --> D[replay]
  C -- no --> E[act]
```

大規模な変更

本当に画期的な変更、難易度やリスクが高い変更、または対象範囲が広い変更では、本文を技術ブログ記事のように書きます。背景、問題、アプローチ、コードサンプル、図、変更前後の比較、画像を含めます。ストーリー仕立てでもかまいません。上記のルールは引き続き適用されます。実行結果は ## Verified の根拠としてのみ記載し、中間の履歴は含めません。

文体

投稿前に、最終テキストに unslop のチェックを実施します。 PR で見られる特有の表現に注意します：

  • 「This PR introduces...」、「comprehensive」、「robust」、「seamless」、「ensures」、「leverages」、「enhances」。
  • 行の内容を繰り返す太字ラベルの箇条書き（**Performance:** Performance...）。
  • ダッシュ。読点、コロン、または文の区切りを使います。
  • 3 つがちょうどよさそうだという理由で、項目を 3 つに水増しした箇条書き。
  • そのまま別のリポジトリの PR に貼り付けられるような概要。

コメント

Markdown 対応