pr-antipattern-review

PR アンチパターンレビュー

差分をプロジェクトのスライスカタログと比較してレビューします。宣言されたスライスからの逸脱と、普遍的なアンチパターンを見つけます。PR コメントとして貼り付けられる path:line 参照を含むレビューを出力します。

このスキルは百科事典的ではなく、比較を重視します。一般的なチェックリストを実行するのではなく、差分を BLUEPRINT.md と比較します。

出力はデフォルトで一時的なものです。 指摘事項はチャットに出力します。ユーザーから求められた場合のみ、ファイルに保存します。

---

基本原則

1. Blueprint がルールブックです。プロジェクトに BLUEPRINT.md がある場合、それが正誤を決めます。Blueprint に根拠がない指摘は弱く、違反ではなく提案にとどまります。
2. 比較の単位はスライスです。「この PR は一般的な原則に違反しているか」ではなく、「この PR は対象のスライスに沿っているか」が問いです。
3. 判断が必要な場合は人間が関与します。曖昧なケースで重大度を決めないでください。逸脱が意図的か、誤って生じたものかを分類せず、確認してください。
4. ボーイスカウトルール。変更対象のファイルにある既存の問題は、PR によって悪化しない限り、PR の問題として扱いません。
5. 出力は一時的なものです。指摘事項はチャットに出力します。ファイルへの自動書き込みや、自動コミットは決して行いません。

---

ワークフロー

Step 1 — 入力形式を判別する

ユーザーが提供した内容に応じて処理します。

入力	アクション
URL github.com/<owner>/<repo>/pull/<N>	gh pr diff <URL> — フォールバック：利用可能なブラウザー／ウェブツールまたは curl -L で <URL>.diff を取得
URL gitlab.com/.../merge_requests/<N>	glab mr diff <N> — フォールバック：利用可能なブラウザー／ウェブツールまたは curl -L で <URL>.diff を取得
PR #<N> または単に <N>	現在のリポジトリで gh pr diff <N>
40 文字の 16 進数、または「commit 」	git show <sha>
diff --git で始まる差分テキスト	そのまま使用
特に指定なし	<base> はデフォルトブランチとして git diff <base>...HEAD。フォールバックは git diff HEAD~1

曖昧な場合は、まず git status と git log -1 を確認します。

Step 2 — 差分が変更するプロジェクトを特定する

差分内の各ファイルについて：

• パスをリポジトリ内のプロジェクトと照合します
• 変更をプロジェクトごとにグループ化します

⏸ 停止して確認するチェックポイント 1（差分が複数のプロジェクトにまたがる場合のみ）：

「この差分はプロジェクト A と B に変更を加えています。両方、A のみ、B のみ、またはプロジェクト横断の単一変更としてレビューしますか？」

差分が 1 つのプロジェクト内に収まる場合：チェックポイントは不要です。続行します。

Step 3 — Blueprint を読み込む

変更対象の各プロジェクトについて、次の場所にある BLUEPRINT.md を探します。

• docs/architecture/<project>/BLUEPRINT.md（モノレポの慣例）
• docs/architecture/BLUEPRINT.md（単一プロジェクトの慣例）
• docs/BLUEPRINT.md

モノレポに docs/architecture/SYSTEM_MAP.md がある場合は、それも読み込みます。差分にプロジェクト間の境界変更が含まれる場合に必要です。

Blueprint が見つからない場合：

• ユーザーに伝えます：「プロジェクト X の BLUEPRINT.md が見つかりません。普遍的なチェックのみで実行します。指摘の確度は低くなり、プロジェクト固有の慣例を見落とす可能性があります。先に project-blueprint を実行することを提案しましょうか？」
• 確信度を下げて続行します

Step 4 — 差分を解析する

変更された各ファイルについて：

• ステータス：追加／変更／削除／名前変更
• + と - の行を含むハンク
• 新しいインポート（レイヤー構造を判断する重要な手掛かり）
• 新しいファイルパス（スライス／非スライスを判断する重要な手掛かり）
• 行数の増減と公開 API の差分

ステップ 5 — 各変更をスライスに分類する

差分内の各ファイルについて：

1. パスと構成に基づいて、該当するスライスを特定します
2. どのスライスに該当するか不明な場合は、⏸ 質問します：

   「ファイル X はスライス Y にも Z にも明確には該当しません。どのスライスに属しますか？ それとも新しいスライスですか？」

3. スライスで宣言された制約を、新しいファイル内容に照らして適用します：
   • インポートはスライスで許可されたものと一致していますか？
   • 命名はスライスの規約に一致していますか？
   • フレームワーク／ライブラリは標準のものと一致していますか？
   • 共同作成ファイル（テスト、DI 登録など）は存在しますか？
4. スライスのステータスを確認します：
   • frozen — 新しいインスタンスをリグレッションとして指摘します
   • deprecated — 追加があれば指摘します
   • active — 通常どおり比較します
5. バリアントを確認します：
   • インスタンスが既存のバリアントに一致する → 問題ありません。記録します
   • インスタンスが新しいバリアントである → 意図的かどうかを⏸ 質問します（決定仕様が必要です）。それとも偶発的ですか？

ステップ 6 — 共通チェックを適用する

ブループリントに関係なく、以下を確認します：

• コミット対象ファイルに追加されたシークレット
• マニフェストレベルの依存関係の逆転（.csproj／package.json に、アーキテクチャ上の依存方向を逆転させる参照が追加されている）
• セキュリティのリグレッション（認証の削除、検証の削除、CORS の開放）
• 説明なしのテスト削除
• 例外を捕捉して握りつぶす処理の導入
• 正当な理由のない型チェッカーの無効化

検出コマンドを含む全リストは references/universal-checks.md を参照してください。

ステップ 7 — ボーイスカウト・フィルター

各指摘について、問題がこの PR より前から同じファイルに存在していたか確認します：

• 存在していて、PR によって悪化していない場合 → 「既存のコンテキスト」に格下げします（1 回だけ言及し、PR の評価対象にはしません）
• 存在していて、PR によって悪化している場合（例：神クラスのサービスに 26 個目のメソッドが追加されている）→ PR の評価対象とします

PR がたまたま触れた問題でも、悪化させていない既存の問題は指摘事項ではありません。

ステップ 8 — 重大度を分類する

レベル	判定
ブロッカー	変更をリクエスト
要修正	コメント（マージ前の修正を推奨）
軽微	注記付き LGTM

ブロッカーか要修正か判断が曖昧な場合は、⏸ 質問します：

「この指摘［説明］は、状況によってブロッカーにも要修正にもなり得ます。PR には［状況］があります。どのように分類しますか？」

どちらにもなり得る指摘の重大度を、一方的に決めないでください。

ステップ 9 — 判定を算出する

条件	判定
ブロッカーが 1 件でもある	❌ 変更をリクエスト
要修正が 4 件以上、または同種の要修正が繰り返されている	⚠️ コメント
実行可能な回避策がある要修正が 1～3 件、または軽微な指摘のみ	✅ 注記付き LGTM
指摘なし	✅ LGTM

ステップ 10 — 提出前の要約

最終レビューを出力する前に：

⏸ 停止して確認するチェックポイント 2（投稿、保存する場合、または重大度／分類が曖昧な場合のみ）：

「指摘：ブロッカー N 件、要修正 M 件、軽微 K 件。判定：［X］。レビューを書く前に、分類を確認または変更しますか？」

これは、出力を送る前に誤った判定を見つける最後の機会です。

ステップ 11 — レビューを出力する

assets/review-template.md を使用して、レビューをチャットに出力します。指摘には path:line 形式を使い、ユーザーが PR コメントとして貼り付けられるようにします。

続けて、次のように尋ねます：

「これを Markdown ファイルとして保存しますか？ それ以外の場合は、チャット履歴に残ります。」

明示的に「はい」と言われた場合にのみファイルに保存します。既定ではチャットのみにします。

---

停止して確認するチェックポイントのまとめ

#	チェックポイント	タイミング
1	複数プロジェクトにまたがるレビュー範囲	ステップ 2。差分が複数のプロジェクトにまたがる場合のみ
2	ファイルのスライス分類	ステップ 5。不明確な場合のみ
3	バリアントが意図的か偶発的か	ステップ 5。新しいバリアントが検出された場合のみ
4	重大度が曖昧	ステップ 8。ブロッカーか要修正かについて実際に判断が分かれる場合のみ
5	提出前の確認	ステップ 10。投稿、保存する場合、または曖昧さが残っている場合のみ

予期しないことがあれば、追加でいったん停止します。決定を決して捏造しないでください。

---

エージェントが観察することと人間が判断すること

エージェントが観察すること：

• ファイルがどのスライスに属するか（パスと形状から判断）
• ファイルがスライスの標準的な形状に一致するか
• インポートがレイヤー／スライスの制約に従っているか
• テストが存在するか
• マニフェストレベルの依存関係の変更
• grep で検出できるアンチパターン（シークレット、環境変数の散在、例外を捕捉して握りつぶす処理）

人間が判断すること：

• 新しいバリアントが意図的なものか、偶発的なものか
• 異論がある場合の重大度（セキュリティ上の後退は意図的か、レガシーの回避策か）
• 既存の問題をこの PR の評価対象に含めるか
• レビューをファイルとして保存するか

---

このスキルが行わないこと

• ブループリントを生成する（project-blueprint を使用）
• 何かを自動でコミットする
• ユーザーが明示的に依頼しない限り、ファイルを自動で書き込む
• 汎用的なアンチパターン集を、あたかもプロジェクトのルールであるかのように適用する
• ブループリントが存在する場合に、それを無視する

---

ブループリントが存在しない場合

BLUEPRINT.md がない場合、このスキルは汎用的なチェックのみを行います：

• シークレット、マニフェストの依存関係の逆転、セキュリティ上の後退、削除されたテスト、型チェッカーの警告の抑制、例外を捕捉して握りつぶす処理

出力では次のように明記します："プロジェクトのブループリントが見つかりません — レビューは汎用的なチェックのみに基づいています。プロジェクト固有の規約を見落とす可能性があります。スライスベースの比較を有効にするには、project-blueprint を実行してください。"

---

関連項目

• references/slice-comparison.md — 差分をスライスカタログと照合する方法
• references/universal-checks.md — プロジェクトに依存しない観察事項
• references/diff-checks.md — プロジェクトを問わず役立つ、grep で検出可能なパターン
• assets/review-template.md — 出力形式