review-python

后端代码审查

硬性关卡（按顺序）

只有在客观满足每项通过条件后才能继续（避免由 Linter 导致的误报和缺乏依据的问题）：

关卡	通过条件
G1 — Diff 范围	已运行步骤 1 中的命令；已书面列出更改的 .py 路径（列表可以为空——如果为空，请明确说明，不要编造 Python 问题）。
G2 — 手动检查风格和类型之前先运行 Linter	对于 ruff 和 mypy：要么项目中不存在该工具的配置，要么已针对更改的文件运行该工具并记录通过/失败情况（退出代码或清晰的工具输出）。不要手动报告这些工具在已配置时已检查的规则相关问题。
G3 — 协议和基础技能	在步骤 6 开始实质性审查之前，已加载 review-verification-protocol、python-code-review 和 fastapi-code-review 技能。
G4 — 每个问题都有证据	最终列表中出现的每个问题都已满足步骤 7 的检查要求（重新阅读源代码、搜索“unused”的引用、针对“missing”确认框架处理方式、根据当前文档验证语法）。
G5 — 输出约定	问题使用连续编号，每个问题都包含 FILE:LINE，且结论遵循步骤 8（只有严重或主要问题会阻止通过；次要或提示性问题不会）。

参数

• --parallel：如果 Agent 支持子 Agent，则为每个技术领域运行一个专门的子 Agent（否则按顺序进行审查，输出相同）
• 路径：目标目录（默认：当前工作目录）

步骤 1：识别更改的文件

通过条件（G1）： 在步骤 2–3 之前，将命令输出（或等效内容）记录为权威的更改 .py 文件集合。

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

步骤 2：验证 Linter 状态

重要： 在指出任何风格或类型问题之前，先运行项目 Linter。通过条件（G2）： 只有在针对更改的文件运行了每个已配置的 Linter，或记录了跳过原因（缺少配置）后，才能继续步骤 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

规则：

• 如果 Linter 对某条规则检查通过（例如，行长度），请勿手动指出该问题
• Linter 配置是风格规则的权威依据
• 仅指出 Linter 无法检测的问题（语义问题、架构问题）

原因： 对 24 次审查结果的分析显示，出现了 4 次误报（17%）：审查者指出了行长度违规，但 ruff check 确认并不存在此类问题。Linter 的配置反映了项目的既定决策。

步骤 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 步：审查

如果 Agent 支持子 Agent，则针对每个技术领域并行派发一个子 Agent；否则按顺序审查相同的领域，并生成相同的输出。

顺序审查（默认，或子 Agent 不可用时）：

1. 加载适用的技能
2. 优先审查 Python 质量问题
3. 审查 FastAPI 模式
4. 审查检测到的技术领域
5. 汇总发现

并行审查（Agent 支持子 Agent 时使用 --parallel 标志）：

1. 预先检测所有技术
2. 针对每个技术领域派发一个子 Agent
3. 每个子 Agent 加载对应技能并审查其领域
4. 等待所有子 Agent 完成
5. 汇总发现

标记优化或模式问题之前

1. 检查项目约定（例如 AGENTS.md 或 CLAUDE.md），确认是否记录了有意采用的模式
2. 检查问题区域附近的代码注释，查找“intentional”“optimization”或“NOTE:”
3. 追踪代码路径，再判断是否缺少覆盖或处理不一致
4. 考虑框架惯用写法——通常看起来不妥的做法，对该框架而言可能完全正确

**原因：**分析发现，审查者曾将有意采用的优化标记为“错误处理不一致”，也曾将不存在的代码路径标记为“缺少测试覆盖”，导致审查被驳回。

第 7 步：验证发现

**通过（G4）：**只有以下所有条件对某个问题都成立时，才能报告该问题。

报告问题前：

1. 重新阅读实际代码（而不只是差异上下文）
2. 对于“未使用”的判断——是否搜索了所有引用？
3. 对于“缺失”的判断——是否检查了框架或上层代码的处理方式？
4. 对于语法问题——是否对照当前版本的文档进行了验证？
5. 删除任何属于风格偏好而非实际问题的发现

第 8 步：审查收敛

**通过（G5）：**最终 Markdown 符合输出格式模板；判定行仅反映下方范围规则中定义的严重/主要阻碍问题。

单轮审查完整性

你 MUST 在单轮审查中报告所有类别（风格、逻辑、类型、测试、安全、性能）的所有问题。不要把问题留到后续轮次。

提交发现前，先问自己：

• “如果应用了我建议的所有修复，我会在修复后的代码中发现新问题吗？”
• “我是否要求添加新代码（测试、类型、模块），而这些代码本身也需要审查？”

如果任一答案为“是”，请现在就在本次审查中加入预期的后续问题，以便作者一次性处理所有问题。

范围规则

• 仅审查差异中的代码及与之直接相关的现有代码
• 不要要求添加差异之前不存在的新功能、测试基础设施或架构更改
• 如果缺少测试覆盖，将其作为一个 Minor 问题标记（“缺少对 X、Y、Z 的测试覆盖”）——不要指定模拟库、行为提取或依赖注入模式等实现细节，因为这些会引入大量新代码
• 类型规范、文档和命名问题均为 Minor，除非它们影响公共 API 契约
• 不要要求添加新的依赖项（例如 Mox、测试库或代码检查插件）

修复复杂度预算

无论修复规模大小，对现有代码的修复都应按其实际严重性标记。

但是，要求添加差异之前不存在的新代码时，必须归类为 Informational：

• 添加新的依赖项（例如 Mox、代码检查插件）
• 创建全新的模块、文件或测试套件
• 提取新的行为、协议或抽象

这些属于供作者在未来工作中考虑的改进建议，不是审查阻碍问题。

迭代策略

如果这是修复完成后的复审：

• 仅验证之前标记的问题是否已正确解决
• 不要提出与之前问题无关的新发现
• 对尚未修复的 Minor/Nice-to-Have 问题予以接受，不要再次标记
• 复审的目标是验证，而非发现问题

输出格式

## 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
• 按实际严重程度分类
• 修复后运行验证
• 一次性报告所有问题——不要将发现留到后续迭代
• 复审只验证之前的修复——不得发现新问题
• 对新增代码（新模块、依赖项、测试套件）的请求属于信息性事项，不构成阻断
• Verdict 忽略 Minor 和 Informational 项——只有 Critical 和 Major 会阻止审批