PR tidy (PR 整理ツール)
ブランチをプルリクエストにする前の一貫性スイープです。差分が変更した箇所と、差分によって同時に変更されるべきだった箇所を確認します。
ブランチ自身の変更にのみ対応してください。差分が誤りを引き起こさない限り、リポジトリ内の他の未着手の債務には触れないでください。
0. スコープ
-
まずリポジトリの指示書を読んでください:
AGENTS.md、CLAUDE.md、CONTRIBUTING*、README*、およびそれらが参照するすべてのドキュメント。 -
ベースと差分を見つけてください:
base=$(git merge-base origin/main HEAD) # またはリポジトリのデフォルトブランチ git log --oneline "$base"..HEAD git diff --stat "$base"...HEAD git diff --name-only "$base"...HEAD -
ワーキングツリーを確認してください(
git status)。未コミットの変更は維持します。あなたが行う編集がそれらと重なる場合は、停止して確認してください。 -
デフォルトブランチ上にあり、比較するものがない場合は、その旨を伝えて停止してください。
1. 差分の分類
変更を次のように分類します:
- 新規: ファイル、コマンド、関数、オプション、フラグ、設定キー、環境変数、スクリプト、スキル。
- 変更: 振る舞い、デフォルト値、API、シグネチャ、ルール、およびデザイン:何か異なることを述べるようになったガイドや仕様。
- 削除または名称変更: 削除、名称変更、移動、または置き換えられたもの。
- インフラ: ビルド、CI、テスト、ツール。
そこから サーフェス(読み手や他のファイルが参照できるすべての名前、パス、フラグ、オプション、用語、ルール)をリストアップしてください。デザイン変更の場合は、名前だけでなく古いアイデアのキーフレーズもリストアップしてください(削除された「レベルごとのチェック」が「各レベル下のチェック」としてまだ説明されている可能性があります)。
2. 古くなった参照
削除、名称変更、または再設計されたすべての項目について、変更されたファイルだけでなくリポジトリ全体を検索してください:
git grep -n -w "古い名前" # 名前、パス、フラグ
git grep -n -i "古いデザインのフレーズ"
コード、コメント、テスト、ドキュメント、README、例、ノートブック、テンプレート、スキルファイル、図(Mermaid および ASCII)、そして設定を確認してください。すべてのヒットは、更新されるか、理由とともにフラグ付けされます。
次に、新しい項目または変更された各項目に対して カバレッジマップ を作成してください:どこにドキュメントがありますか?
カバレッジマップ:
項目 参照先 ハウツー 例 説明
--new-flag README - - -
check_levels.py scripts/ - - -
カバレッジがない項目はギャップとして報告してください。依頼されていないのに新しいドキュメントページ全体を書かないでください。
3. 新しい振る舞いに対するテストとドキュメント
新しいまたは変更された各振る舞いに対して:
- テスト がそれを実行し、それを所有するレイヤーで実行し、変更された障害パスもテストします。リポジトリの既存のテストパターンと、リグレッションを捕捉できる最も狭いテストを優先してください。
- ドキュメント は、古い振る舞いが説明されていた場所(リファレンス、例、古い方法を教えていたガイド)で、それを説明します。
- テスト欠落は、具体的にどのような障害を捕捉するかを明示できる場合にのみ報告してください。推測や未着手のカバレッジ債務には触れないでください。
4. チェッカーは明確に失敗する
新しいまたは変更された各チェッカー、リンター、バリデーター、チェックスクリプトに対して:
- 組み込まれていること。 リポジトリが使用するすべてのエントリポイントを見つけてください:
.pre-commit-config.yaml、.github/workflows/*、Makefile、justfile、noxfile.py、tox.ini、pyproject.tomlまたはpackage.jsonのスクリプト、および他のチェックを呼び出すバリデーター。チェッカーが少なくとも1つから呼び出されていることを確認してください。呼び出されていない場合は、同じ仲間と同じ方法で組み込むか、フラグを立ててください。 - 不正な入力で失敗すること。 故意に壊れた入力で実行してください。終了コードは0以外である必要があります。
- 空の入力でも失敗すること。 空または欠落した入力(ファイルなし、マッチなし、解析対象なし)で実行してください。終了コードは0以外であるか、何もチェックしていないことを明確に示し、決して黙って合格してはいけません。
- 2と3をカバーするテストがあること。
後でこの状態を維持するために、references/test_checkers_wired.py のような配線テストを追加してください。
5. 数値、バージョン、例
差分が触れたファイルまたはそれらを説明するドキュメント内の、すべての数値、バージョン、日付、URL、引用、コマンド、コード例をリストアップしてください。それぞれについて:
- ソースを明示すること: それを生成するコードまたはコマンド、設定値、データセット、または正確なバージョン(arXiv
v3、DOI)の論文。 - 再確認すること: コマンドを再実行するか、ソースを再読してください。修正するか、確認できない場合はフラグを立ててください。
- 条件を一緒に保持すること: 数値が成立するデータセット、設定、マシン、または時間(「N ポイント」ではなく「マシン M 上で T 時間での N ポイント」)。
- 外部ソースはバージョンに固定すること。
- 今後も変化し続ける数値は、手入力よりもコードから生成する(例えば
cogを使用し、cog --checkでチェックする)方がよいので、提案してください。
6. 個人情報と認証情報
ブランチが追加するすべてのもの、および追加されようとしている追跡されていないファイルを、マシンから出る前にチェックしてください。これはブロッキングです:先に進んでも以下の項目は「修正」されません。
git diff "$base"...HEAD # ブランチ上でコミット済み
git diff; git diff --cached # まだコミットされていない
git status --short # 追加される可能性のある追跡されていないファイル
次のものを探してください:
- 認証情報: API キー、トークン、パスワード、パスワードを含む接続文字列、秘密鍵(
-----BEGIN … PRIVATE KEY-----)、クラウドおよび CI のシークレット、セッションクッキー。 - それらを保持するファイル:
.env*、*.pem、*.key、id_rsa*、credentials*、secrets*、*.p12、サービスアカウント JSON、トークン付きの.npmrcや.pypirc、ローカル設定ファイル。 - 個人情報: メールアドレス、電話番号、自宅または住所、例やテストデータ内の実名、アカウント番号や ID 番号、他の人を特定するデータ。
- マシンの詳細: 絶対ホームパス(
/Users/<名前>、/home/<名前>、C:\Users\<名前>)、内部ホスト名、プライベート IP アドレス、ログやノートブック出力内のユーザー名。 - 隠れた場所: ノートブックの出力とメタデータ、ログ、スクリーンショット、フィクスチャ、生成レポート、コミットメッセージ、そしてブランチの最終状態だけでなく全履歴。
リポジトリにスキャナーがあれば実行してください(gitleaks、detect-secrets、pre-commit run --all-files)。また、自分でも差分を読んでください。スキャナーは個人データを見逃すことがあります。
何か見つけた場合:
- レポートやコミットメッセージに値を決して繰り返さないでください。 ファイル、行、および種類(
AWS キー、メールアドレス)を指定してください。 - まだコミットされていない場合: 削除し、無視されるファイルまたは環境変数に移動し、パターンを
.gitignoreに追加してください(ファイルの場合)。 - ブランチ上で既にコミットされている場合: 停止してユーザーに伝えてください。一度コミットされた認証情報は、履歴を書き換えた後でも失効させて置き換える必要があります。なぜなら、既にコピーされている可能性があるからです。ユーザーなしで共有履歴を書き換えないでください。
- ユーザーが意図的に配置した個人情報(ライセンス内の自分の公開名など)は、削除せずに確認してください。
7. 修正またはフラグ
ファイル自身の言葉遣い、構造、用語法で最小限に編集してください。編集する前にファイルを完全に読んでください。
確認なしで修正:
- 差分から直接導き出せる事実上の訂正;
- 古くなった名前、パス、カウント、バージョン、相互参照;
- 既存のテーブルやリストへの新しい項目の追加;
- 同種のパターンが示されている場所へのチェッカーの組み込み。
フラグ、または変更前に確認:
- ナラティブ、デザイン、ポリシーのテキスト、およびブランチの明らかな意図と矛盾するもの;
- 削除や大規模な書き直し;
- セキュリティ上重要な変更;
CHANGELOGエントリとバージョンアップ;- 他の人やチームが所有するファイル;
- 設計上の決定が必要な新しいテスト。
絶対に行わないこと: 既存のチェンジログエントリを書き換えたり再生成したり、バージョンを黙って上げたり、生成されたファイルを手動編集したり(そのジェネレータを使用してください)、シークレットや実際の認証情報を貼り付けたりしないでください。
8. 証拠付きで検証する
このセッションからの新しい証拠なしに主張をしないでください。最後の関連する編集の後:
- 主張を証明するコマンドを指定してください。
- それを完全に実行してください。
- 出力全体と終了コードを読んでください。
- その証拠とともに結果を述べるか、実際の状態を述べてください。
リポジトリが既に持っているもの(テスト、リンター、pre-commit run --all-files、ドキュメントビルド、リンクチェック)を実行してください。インストールされていないツールやダウンしているサービスは 検証ギャップ として報告され、決して合格にはなりません。「おそらく合格する」やエージェントの「完了」は証拠ではありません。
9. レポート
スコープ: <base>..HEAD, N ファイル, M コミット
ブロッキング
- path:line — 認証情報または個人情報の種類(値は非表示)、および必要な対応
変更済み
- path:line — 何が変更されたか、およびなぜ差分がそれを必要としたか
フラグ済み(未修正)
- path:line — 問題、修正されなかった理由、提案される修正
カバレッジギャップ
- item — ドキュメント化またはテストされるべき場所
検証済み
- `command` → 結果(終了コード)
未検証
- 何か、およびその理由(ツール欠落、外部サービス、判断が必要)
機械的なレイヤー
セクション2〜6のほとんどは判断が必要ですが、一部はすべてのコミットで実行できます。まだ導入していないリポジトリには、references/pre-commit-config.yaml のスターター設定を提供してください:ファイル衛生、ruff、codespell、秘密鍵とシークレットの検出(gitleaks)、およびプッシュ時の pytest と diff-cover。lychee リンクチェックとパスゲートされた CI は、コミットフックよりもワークフローに適しています。
クレジット
MIT ライセンスのスキルから、変更を加えて翻案:Jakub Merta による docs-sync と review-test-coverage(jMerta/codex-skills)。Garry Tan による document-release の差分分類、カバレッジマップ、修正またはフラグのルール(garrytan/gstack)。Jesse Vincent による verification-before-completion の証拠ルール(obra/superpowers)。Anthropic の pr-review-toolkit エージェントからのアイデア(テキストではなく)(anthropics/claude-plugins-official)。ライセンス:THIRD_PARTY_NOTICES.md。