review-python

バックエンドコードレビュー

ハードゲート（順序）

各合格条件が客観的に満たされた場合にのみ次へ進みます（リンターが検出する誤検出や、根拠のない指摘を防ぐためです）。

ゲート	合格条件
G1 — 差分の範囲	ステップ 1 のコマンドが実行され、変更された .py のパスが文書に列挙されています（リストは空でもかまいません。空の場合はその旨を明記し、存在しない Python の指摘を作り上げないでください）。
G2 — 手動でスタイルや型を確認する前にリンターを実行	ruff と mypy について、プロジェクト設定が存在しないか、変更されたファイルに対して実行して合格／不合格を記録しています（終了コードまたは明確なツール出力）。設定されている場合、これらのツールがすでに検査するルールについて、手動でスタイルや型の指摘を追加しないでください。
G3 — プロトコルと基本スキル	実質的なレビューを行うステップ 6 の前に、review-verification-protocol、python-code-review、および fastapi-code-review のスキルが読み込まれています。
G4 — 各問題の根拠	報告する各問題について、最終リストに記載する前にステップ 7 の確認事項が満たされています（ソースを再読し、「未使用」の参照を検索し、「不足」のフレームワークによる処理を確認し、構文を最新のドキュメントで検証します）。
G5 — 出力形式	指摘には連番を付け、各問題に FILE:LINE を記載し、判定はステップ 8 に従っています（Critical／Major のみブロック対象。Minor／Informational はブロックしません）。

引数

• --parallel：エージェントがサブエージェントをサポートしている場合は、技術領域ごとに専門のサブエージェントを実行します（それ以外の場合は、同一の出力で順次レビューします）
• Path：対象ディレクトリ（デフォルト：現在の作業ディレクトリ）

ステップ 1：変更されたファイルを特定する

合格（G1）： ステップ 2〜3 の前に、コマンド出力（または同等の情報）を、変更された .py ファイルの正式な一覧として記録します。

git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '\.py$'

ステップ 2：リンターの状態を確認する

重要：スタイルや型に関する問題を指摘する前に、プロジェクトのリンターを実行してください。合格（G2）： 設定されている各リンターを変更されたファイルに対して実行するか、実行しなかった理由（設定がないこと）を記録してから、ステップ 3 に進んでください。

# Check if ruff config exists and run it
if [ -f "pyproject.toml" ] || [ -f "ruff.toml" ]; then
    ruff check <changed_files>
fi

# Check if mypy config exists and run it
if [ -f "pyproject.toml" ] || [ -f "mypy.ini" ]; then
    mypy <changed_files>
fi

ルール：

• 特定のルール（例：行の長さ）についてリンターが合格した場合、その問題を手動で指摘しないでください
• スタイルルールについては、リンターの設定を正式な基準とします
• リンターでは検出できない問題（意味上の問題、アーキテクチャ上の問題）のみを指摘します

理由： 24 件のレビュー結果の分析では、4 件（17%）の誤検出が確認されました。レビュー担当者が行の長さ違反を指摘したものの、ruff check では問題が存在しないことが確認されていました。リンターの設定には、プロジェクトが意図的に選択した方針が反映されています。

ステップ 3：技術を検出する

# Detect Pydantic-AI
grep -r "pydantic_ai\|@agent\.tool\|RunContext" --include="*.py" -l | head -3

# Detect SQLAlchemy
grep -r "from sqlalchemy\|Session\|relationship" --include="*.py" -l | head -3

# Detect Postgres-specific
grep -r "psycopg\|asyncpg\|JSONB\|GIN" --include="*.py" -l | head -3

# Check for test files
git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E 'test.*\.py$'

ステップ 4：検証プロトコルを読み込む

review-verification-protocol のスキルを読み込み、レビュー全体を通してそのチェックリストを念頭に置いてください。

ステップ 5：スキルを読み込む

対象領域をレビューする前に、該当するスキルごとに SKILL.md を読み込んでください。

必ず読み込む：

• python-code-review
• fastapi-code-review

検出結果に応じて読み込む：

条件	スキル
テストファイルが変更された	pytest-code-review
Pydantic-AI が検出された	pydantic-ai-common-pitfalls
SQLAlchemy が検出された	sqlalchemy-code-review
Postgres が検出された	postgres-code-review

ステップ 6：レビュー

エージェントがサブエージェントに対応している場合は、技術領域ごとにサブエージェントを 1 つずつ並列で起動します。対応していない場合は、同じ領域を順番に確認し、同一の出力を作成します。

逐次実行（デフォルト、またはサブエージェントを利用できない場合）：

1. 適用可能なスキルを読み込みます
2. まず Python の品質に関する問題を確認します
3. FastAPI のパターンを確認します
4. 検出された技術領域を確認します
5. 指摘事項を統合します

並列実行（エージェントがサブエージェントに対応している場合の --parallel フラグ）：

1. すべての技術を事前に検出します
2. 技術領域ごとにサブエージェントを 1 つずつ起動します
3. 各サブエージェントがスキルを読み込み、担当領域を確認します
4. すべてのサブエージェントの完了を待ちます
5. 指摘事項を統合します

最適化やパターンに関する問題を指摘する前に

1. プロジェクトの規約（例：AGENTS.md や CLAUDE.md）を確認し、意図的なパターンが記載されていないか調べます
2. 該当箇所周辺のコードコメントを確認し、「intentional」、「optimization」、「NOTE:」がないか調べます
3. 指摘するコードパスを追跡してから、カバレッジの欠如や一貫性のない処理を主張します
4. フレームワークの慣例を考慮します。一般的には誤りに見えるものでも、そのフレームワークでは適切な場合があります

理由： 分析の結果、レビュー担当者が最適化を意図した「一貫性のないエラー処理」や、存在しないコードパスに対する「テストカバレッジの不足」を指摘し、却下されたケースが確認されています。

ステップ 7：指摘事項の検証

合格（G4）： 以下の項目がすべて該当するまで、その問題を含むコードをリリースしてはいけません。

問題を報告する前に：

1. 実際のコードを読み直します（差分の周辺だけではなく）
2. 「未使用」と主張する場合、すべての参照箇所を検索しましたか？
3. 「欠落」と主張する場合、フレームワークや親側で処理されていないか確認しましたか？
4. 構文上の問題の場合、現行バージョンのドキュメントで確認しましたか？
5. 実際の問題ではなく、スタイル上の好みにすぎない指摘は削除します

ステップ 8：レビューの収束

合格（G5）： 最終的な Markdown が出力形式テンプレートに一致しており、判定行には以下のスコープルールに従って重大または深刻なブロッカーのみが反映されています。

1 回のレビューですべてを網羅

すべてのカテゴリ（スタイル、ロジック、型、テスト、セキュリティ、パフォーマンス）にわたる問題を、1 回のレビューですべて報告する必要があります。 後のラウンドに問題を持ち越してはいけません。

指摘事項を提出する前に、次の点を自問してください。

• 「提案した修正をすべて適用した場合、修正済みのコードに新たな問題が見つかるでしょうか？」
• 「新たなコード（テスト、型、モジュール）を求めており、そのコード自体もレビューが必要になるでしょうか？」

どちらかの答えが「はい」の場合は、作成者が一度にすべて対応できるよう、予測される後続の問題も今回のレビューに含めてください。

スコープルール

• 差分内のコードと、直接関連する既存コードのみをレビューします
• 差分以前には存在しなかった新機能、テストインフラストラクチャ、アーキテクチャの変更を要求してはいけません
• テストカバレッジが不足している場合は、「X、Y、Z のテストカバレッジが不足しています」という 1 つの軽微な問題として指摘します。大幅な新規コードにつながるモックライブラリ、動作の抽出、依存性注入のパターンなど、実装の詳細を指定してはいけません
• Typespec、ドキュメント、命名に関する問題は、公開 API の契約に影響する場合を除き、軽微な問題です
• 新しい依存関係（例：Mox、テストライブラリ、リンタープラグイン）の追加を要求してはいけません

修正規模の上限

既存コードへの修正は、規模にかかわらず実際の深刻度に基づいて指摘します。

ただし、差分以前には存在しなかった新規コードの追加を求める場合は、情報提供として分類する必要があります。

• 新しい依存関係（例：Mox、リンタープラグイン）の追加
• 新しいモジュール、ファイル、テストスイートの新規作成
• 新たな動作、プロトコル、抽象化の抽出

これらは作成者が今後検討するための改善案であり、レビューをブロックするものではありません。

イテレーション方針

修正適用後の再レビューの場合：

• 以前に指摘した問題が正しく修正されたかどうかのみを確認します
• 以前のレビューの問題と無関係な新たな指摘を追加してはいけません
• 修正されていない軽微な問題や、あると望ましい問題は許容し、再度指摘してはいけません
• 再レビューの目的は新たな問題の発見ではなく、修正の検証です

出力形式

## Review Summary

[1-2 sentence overview of findings]

## Issues

### Critical (Blocking)

1. [FILE:LINE] ISSUE_TITLE
   - Issue: Description of what's wrong
   - Why: Why this matters (bug, type safety, security)
   - Fix: Specific recommended fix

### Major (Should Fix)

2. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Minor (Nice to Have)

N. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Informational (For Awareness)

N. [FILE:LINE] SUGGESTION_TITLE
   - Suggestion: ...
   - Rationale: ...

## Good Patterns

- [FILE:LINE] Pattern description (preserve this)

## Verdict

Ready: Yes | No | With fixes 1-N (Critical/Major only; Minor items are acceptable)
Rationale: [1-2 sentences]

修正後の検証

修正を適用した後、次を実行します。

ruff check .
mypy .
pytest

承認前に、すべてのチェックに合格する必要があります。

ルール

• レビュー前にスキルを読み込みます（レビュー後ではありません）
• 各問題に連番を付けます（1、2、3...）
• 各問題に FILE:LINE を含めます
• Issue／Why／Fix を明確に分けます
• 実際の重大度に応じて分類します
• 修正後に検証を実行します
• すべての問題を1回で報告します。後のイテレーションに指摘を持ち越してはいけません
• 再レビューでは、以前の修正のみを確認します。新たな問題を発見してはいけません
• 新しいコード（新規モジュール、依存関係、テストスイート）の追加リクエストは、ブロッキングではなく情報提供として扱います
• 判定では軽微および情報提供の項目を考慮しません。承認を妨げるのは重大および主要な項目のみです