コミットメッセージと PR 記述子作成

一連の変更を、レビューアがアクションできる明確なコミットメッセージとプルリクエストの説明文に変換します。価値は、変更がなぜ存在するのか、そして何が問題になる可能性があるのかを述べることであり、diff を言い換えることではありません。

安全ルール (最初に読むこと)

ユーザーが明示的に依頼しない限り、コミット、プッシュ、PR を開かないでください。 コマンドを提案し、ユーザーに実行させてください。コミットとプッシュは他の人に見え、元に戻すのが面倒です。
メッセージや PR に秘密の値を決して書き込まないでください。 スキャンで機密情報の可能性がフラグされた場合は、何かを書き込む前に停止してユーザーに伝えてください。その機密情報はローテーションする必要があり、次のコミットから削除するだけでは不十分です。
事実を捏造しないでください。 あなたが見なかった Issue 番号、テスト結果、ベンチマーク数値、動機を記載してはいけません。変更理由が不明な場合は、簡潔な質問を 1 つするか、あなたの仮定を述べてください。

ワークフロー

1. 変更を収集する

ユーザーのリポジトリでコマンドを実行できる場合は、まずバンドルされているスキャナーを使用し、次に実際の diff を読み取ってください。

python scripts/scan_diff.py                  # ステージされた変更 (フォールバック: アンステージ)
python scripts/scan_diff.py main...HEAD      # ブランチ全体 (PR 用)
git diff --staged                            # 実際の diff を読む (大きい場合は --stat を先に使う)
git log --oneline main..HEAD                 # 既にブランチにあるコミット (PR 用)

scripts/scan_diff.py は、ファイルをコード、テスト、マイグレーション、依存関係、設定、CI、ドキュメントの領域ごとにグループ化し、機密情報、デバッグコードの残骸、テスト不足、マイグレーション、セキュリティに敏感なパス、API 変更の可能性、過大な変更をフラグします。これはヒューリスティックであるため、各フラグを diff と照合して確認してください。

コマンドを実行できない場合は、ユーザーに git diff --staged (PR の場合は git diff main...HEAD) を貼り付けてもらい、必要に応じて Issue やチケットのテキストも依頼してください。コード実行が利用可能な場合、貼り付けられたテキストを python scripts/scan_diff.py - でスキャナーにパイプすることもできます。

2. 意図を理解する

どのような動作が変更され、その理由を解明します。証拠の優先順位は、ブランチ名とチケット ID、ブランチ上の既存のコミットメッセージ、新規または変更されたテスト、変更付近のコメント、次にユーザーの言葉です。references/guidelines.md のセクション 4 を参照してください。

3. スコープを確認する

diff が無関係な懸念事項 (機能 + リファクタリング + フォーマット、または無関係なモジュール) を混在させている場合は、1 つの曖昧なメッセージを書く代わりに分割を提案してください。グループ、各グループに属するファイル、グループごとのメッセージ、さらに git add -p の手順をリストアップします。1 コミットにつき 1 つの論理的な変更に抑えてください。既に 1 つの論理的な変更であれば、1 つのコミットを書いてください。

4. コミットメッセージを書く

形式: type(scope): subject、その後任意の本文、任意のフッター。

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert。
Subject: 命令形 ("add", "fix")、小文字、末尾にピリオドなし、約 50 文字、最大 72 文字。ファイルではなく動作の変更を説明します。
Body: 理由が明らかでない場合のみ。subject の後に空白行を入れ、なぜかを説明し、約 72 文字で折り返します。
Footers: Closes #123 (確実に知っている番号のみ)、およびクライアントやデプロイが壊れる場合の BREAKING CHANGE: ...。type または scope の後の ! も破壊的変更を示します。

次にチェックします。メッセージを一時ファイルに保存し、以下を実行します:

python scripts/lint_commit_message.py message.txt

ユーザーに表示する前に、すべてのエラーと妥当な警告を修正してください。

5. PR の説明文を書く (PR を求められた場合)

assets/pr-template.md から始めます。What、Why、How to test を埋め、該当する Backend impact の行 (データベースとマイグレーション、API 変更、セキュリティと認可、パフォーマンス、設定とフラグ、ロールアウトとロールバック) だけを残し、残りは削除します。ルール:

Title: コミットヘッダーと同じ形式。なぜなら、squash-merge を使用すると main のコミットになるからです。
How to test: リポジトリから正当化できる正確なコマンド (例: 変更されたテストファイル)。テストが通ったとほのめかすのではなく、「テストは実行していません」と書いてください。
Breaking changes: 誰が影響を受け、何をすべきか、タイムラインを記載します。
Migrations: デプロイ中に古いコードがまだ動作するかどうか、およびロールバック方法を記載します。
適切な規模に抑えてください。 1 行の修正には 2 行の PR で十分であり、テンプレート全体は必要ありません。

6. 結果を提示する

以下の順序で返信してください:

注意事項 (スキャンで実際の問題が見つかった場合のみ): 機密情報、デバッグコード、テスト不足、非常に大きな diff、リスクの高いマイグレーション。
コミットメッセージ をコードブロックで (または、コミットごとに 1 メッセージの分割計画)。
PR のタイトルと説明文 をマークダウンのコードブロックで、そのまま貼り付けられる形式で。本文にコードフェンスが含まれる場合は、その周りを 4 つのバッククォートで囲んでください。
ユーザーが実行できるオプションのコマンド (例: git commit -F message.txt や gh pr create --title "..." --body-file pr.md)。提案として提示してください。

返信は簡潔に保ってください。diff を言い直さないでください。

出力を変更に合わせて調整する

タイポ、ドキュメント、設定の微調整: 1 行コミット、本文なし、2 行 PR。
通常の変更: ヘッダーと短い本文、What / Why / How to test を含む PR。
大規模またはリスクの高い変更 (マイグレーション、認証、公開 API): 関連するバックエンド影響セクションを含む完全な PR。スキャンで大規模と判断された場合は分割を提案します。

例

入力サマリー: ステージング diff が app/auth.py を変更し、トークンデコード時に exp、iss、aud を検証するようにし、tests/test_auth.py::test_expired_token を追加。ブランチ fix/42-expired-tokens。

出力:

fix(auth): reject expired refresh tokens

Tokens were accepted after expiry because exp was decoded but never
validated. Validate exp, iss and aud on every decode and return 401.

Closes #42

PR タイトルは fix(auth): reject expired refresh tokens となり、Why でバグを特定し、How to test で pytest tests/test_auth.py::test_expired_token を指し示し、Security / authorization の行で以前有効だった期限切れトークンが 401 になることを説明します。

バンドルファイル

scripts/scan_diff.py: diff を要約し、リスクをフラグします。使用方法: python scripts/scan_diff.py [git-diff-args | -]。終了コード 1 は機密情報の可能性があることを意味します。
scripts/lint_commit_message.py: Conventional Commits 形式に対してメッセージをチェックします。使用方法: python scripts/lint_commit_message.py message.txt (または stdin の場合は -)。終了コード 1 はエラーを意味します。
assets/pr-template.md: 記入する PR 説明文のスケルトン。ユーザーがリポジトリにデフォルトテンプレートを設定したい場合、.github/pull_request_template.md にコピーすることもできます。
references/guidelines.md: コミットタイプの例、良い/悪いメッセージ、破壊的変更、diff の分割方法、PR の規模、バックエンド PR セクション、Issue リンクキーワード、書いてはいけないこと。上記でカバーされていないケースがある場合は、これを参照してください。

コミットメッセージとPR 記述子作成