review-python

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Backend Code Review

后端代码评审

Arguments

参数

```
--parallel
```
: Spawn specialized subagents per technology area
Path: Target directory (default: current working directory)

```
--parallel
```
: 按技术领域生成专门的子Agent
Path: 目标目录（默认：当前工作目录）

Step 1: Identify Changed Files

步骤1：识别变更文件

bash

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

bash

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

Step 2: Verify Linter Status

步骤2：验证代码检查工具（Linter）状态

CRITICAL: Run project linters BEFORE flagging any style or type issues.

bash

undefined

重要提示：在标记任何风格或类型问题之前，请先运行项目的代码检查工具。

bash

undefined

Check if ruff config exists and run it

检查是否存在ruff配置并运行

if [ -f "pyproject.toml" ] || [ -f "ruff.toml" ]; then ruff check <changed_files> fi

Check if mypy config exists and run it

检查是否存在mypy配置并运行

if [ -f "pyproject.toml" ] || [ -f "mypy.ini" ]; then mypy <changed_files> fi


**Rules:**
- If a linter passes for a specific rule (e.g., line length), DO NOT flag that issue manually
- Linter configuration is authoritative for style rules
- Only flag issues that linters cannot detect (semantic issues, architectural problems)

**Why:** Analysis of 24 review outcomes showed 4 false positives (17%) where reviewers flagged line-length violations that `ruff check` confirmed don't exist. The linter's configuration reflects intentional project decisions.

if [ -f "pyproject.toml" ] || [ -f "mypy.ini" ]; then mypy <changed_files> fi


**规则**:
- 如果某个规则（例如行长度）通过了代码检查工具的验证，请勿手动标记该问题
- 代码检查工具的配置是风格规则的权威依据
- 仅标记代码检查工具无法检测到的问题（语义问题、架构问题）

**原因**：对24次评审结果的分析显示，有4次误报（占比17%），评审人员标记了行长度违规，但`ruff check`确认这些违规并不存在。代码检查工具的配置反映了项目的有意决策。

Step 3: Detect Technologies

步骤3：检测技术栈

bash

undefined

bash

undefined

Detect Pydantic-AI

检测Pydantic-AI

grep -r "pydantic_ai|@agent.tool|RunContext" --include="*.py" -l | head -3

Detect SQLAlchemy

检测SQLAlchemy

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

Detect Postgres-specific

检测Postgres相关内容

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$'

undefined

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

undefined

Step 4: Load Verification Protocol

步骤4：加载验证协议

Load

beagle-python:review-verification-protocol

skill and keep its checklist in mind throughout the review.

加载

beagle-python:review-verification-protocol

技能，并在整个评审过程中牢记其检查清单。

Step 5: Load Skills

步骤5：加载技能

Use the

Skill

tool to load each applicable skill (e.g.,

Skill(skill: "beagle-python:python-code-review")

Always load:

```
beagle-python:python-code-review
```
```
beagle-python:fastapi-code-review
```

Conditionally load based on detection:

Condition	Skill
Test files changed	`beagle-python:pytest-code-review`
Pydantic-AI detected	`beagle-ai:pydantic-ai-common-pitfalls`
SQLAlchemy detected	`beagle-python:sqlalchemy-code-review`
Postgres detected	`beagle-python:postgres-code-review`

使用

Skill

工具加载每个适用的技能（例如：

Skill(skill: "beagle-python:python-code-review")

）。

必须加载:

```
beagle-python:python-code-review
```
```
beagle-python:fastapi-code-review
```

根据检测结果条件加载:

条件	技能
测试文件发生变更	`beagle-python:pytest-code-review`
检测到Pydantic-AI	`beagle-ai:pydantic-ai-common-pitfalls`
检测到SQLAlchemy	`beagle-python:sqlalchemy-code-review`
检测到Postgres	`beagle-python:postgres-code-review`

Step 6: Review

步骤6：评审

Sequential (default):

Load applicable skills
Review Python quality issues first
Review FastAPI patterns
Review detected technology areas
Consolidate findings

Parallel (--parallel flag):

Detect all technologies upfront
Spawn one subagent per technology area with
```
Task
```
tool
Each agent loads its skill and reviews its domain
Wait for all agents
Consolidate findings

顺序评审（默认）:

加载适用的技能
首先评审Python质量问题
评审FastAPI模式
评审检测到的技术领域
整理发现的问题

并行评审（--parallel 参数）:

预先检测所有技术栈
使用
```
Task
```
工具为每个技术领域生成一个子Agent
每个Agent加载对应的技能并评审其领域的代码
等待所有Agent完成
整理发现的问题

Before Flagging Optimization or Pattern Issues

在标记优化或模式问题之前

Check CLAUDE.md for documented intentional patterns
Check code comments around the flagged area for "intentional", "optimization", or "NOTE:"
Trace the code path before claiming missing coverage or inconsistent handling
Consider framework idioms - what looks wrong generically may be correct for the framework

Why: Analysis showed rejections where reviewers flagged "inconsistent error handling" that was intentional optimization, and "missing test coverage" for code paths that don't exist.

查看CLAUDE.md，确认是否有文档记录的有意采用的模式
查看标记区域附近的代码注释，寻找包含"intentional"、"optimization"或"NOTE:"的内容
追踪代码路径，再声称存在覆盖缺失或处理不一致的问题
考虑框架惯用写法 - 从通用角度看似乎有问题的写法，可能在该框架下是正确的

原因：分析显示，部分评审意见被驳回，原因是评审人员标记了"不一致的错误处理"，但实际上这是有意的优化；还有标记了"缺失测试覆盖"的代码路径实际上并不存在。

Step 7: Verify Findings

步骤7：验证发现的问题

Before reporting any issue:

Re-read the actual code (not just diff context)
For "unused" claims - did you search all references?
For "missing" claims - did you check framework/parent handling?
For syntax issues - did you verify against current version docs?
Remove any findings that are style preferences, not actual issues

在报告任何问题之前：

重新阅读实际代码（而不仅仅是差异上下文）
对于"未使用"的声明 - 你是否搜索了所有引用？
对于"缺失"的声明 - 你是否检查了框架/父级的处理逻辑？
对于语法问题 - 你是否对照当前版本的文档进行了验证？
删除所有属于风格偏好而非实际问题的发现

Step 8: Review Convergence

步骤8：评审收敛

Single-Pass Completeness

单次评审完整性

You MUST report ALL issues across ALL categories (style, logic, types, tests, security, performance) in a single review pass. Do not hold back issues for later rounds.

Before submitting findings, ask yourself:

"If all my recommended fixes are applied, will I find NEW issues in the fixed code?"
"Am I requesting new code (tests, types, modules) that will itself need review?"

If yes to either: include those anticipated downstream issues NOW, in this review, so the author can address everything at once.

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

提交发现的问题之前，请自问：

"如果我推荐的所有修复都已应用，我会在修复后的代码中发现新问题吗？"
"我是否要求添加新代码（测试、类型、模块），而这些代码本身也需要评审？"

如果其中任何一个问题的答案是肯定的：请立即在本次评审中包含这些预期的后续问题，以便作者可以一次性解决所有问题。

Scope Rules

范围规则

Review ONLY the code in the diff and directly related existing code
Do NOT request new features, test infrastructure, or architectural changes that didn't exist before the diff
If test coverage is missing, flag it as ONE Minor issue ("Missing test coverage for X, Y, Z") — do NOT specify implementation details like mock libraries, behaviour extraction, or dependency injection patterns that would introduce substantial new code
Typespecs, documentation, and naming issues are Minor unless they affect public API contracts
Do NOT request adding new dependencies (e.g. Mox, testing libraries, linter plugins)

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

Fix Complexity Budget

修复复杂度预算

Fixes to existing code should be flagged at their real severity regardless of size.

However, requests for net-new code that didn't exist before the diff must be classified as Informational:

Adding a new dependency (e.g. Mox, a linter plugin)
Creating entirely new modules, files, or test suites
Extracting new behaviours, protocols, or abstractions

These are improvement suggestions for the author to consider in future work, not review blockers.

现有代码的修复应根据其实际严重程度进行标记，无论修复规模大小。

然而，对于差异之前不存在的全新代码的请求必须归类为信息性建议：

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

这些是供作者在未来工作中考虑的改进建议，而非评审阻塞项。

Iteration Policy

迭代策略

If this is a re-review after fixes were applied:

ONLY verify that previously flagged issues were addressed correctly
Do NOT introduce new findings unrelated to the previous review's issues
Accept Minor/Nice-to-Have issues that weren't fixed — do not re-flag them
The goal of re-review is VERIFICATION, not discovery

如果这是修复后的重新评审：

仅验证之前标记的问题是否已正确解决
不得引入与之前评审问题无关的新发现
接受未修复的次要/锦上添花的问题——不得重新标记
重新评审的目标是验证，而非发现新问题

Output Format

输出格式

markdown

undefined

markdown

undefined

Review Summary

评审摘要

[1-2 sentence overview of findings]

[1-2句话概述发现的问题]

Issues

问题

Critical (Blocking)

严重（阻塞）

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

[文件:行号] 问题标题
- 问题：错误内容描述
- 原因：该问题的影响（bug、类型安全、安全）
- 修复：具体的推荐修复方案

Major (Should Fix)

主要（应修复）

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

[文件:行号] 问题标题
- 问题：...
- 原因：...
- 修复：...

Minor (Nice to Have)

次要（锦上添花）

N. [FILE:LINE] ISSUE_TITLE

Issue: ...
Why: ...
Fix: ...

N. [文件:行号] 问题标题

问题：...
原因：...
修复：...

Informational (For Awareness)

信息性（供参考）

N. [FILE:LINE] SUGGESTION_TITLE

Suggestion: ...
Rationale: ...

N. [文件:行号] 建议标题

建议：...
理由：...

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]

undefined

可通过：是 | 否 | 需修复1-N（仅严重/主要问题；次要问题可接受）理由：[1-2句话]

undefined

Post-Fix Verification

修复后验证

After fixes are applied, run:

bash

ruff check .
mypy .
pytest

All checks must pass before approval.

修复完成后，运行：

bash

ruff check .
mypy .
pytest

所有检查必须通过才能批准。

Rules

规则

Load skills BEFORE reviewing (not after)
Number every issue sequentially (1, 2, 3...)
Include FILE:LINE for each issue
Separate Issue/Why/Fix clearly
Categorize by actual severity
Run verification after fixes
Report ALL issues in a single pass — do not hold back findings for later iterations
Re-reviews verify previous fixes ONLY — no new discovery
Requests for net-new code (new modules, dependencies, test suites) are Informational, not blocking
The Verdict ignores Minor and Informational items — only Critical and Major block approval

评审前先加载技能（而非之后）
为每个问题按顺序编号（1、2、3...）
每个问题都要包含文件:行号
清晰区分问题/原因/修复
根据实际严重程度分类
修复后运行验证
单次评审报告所有问题——不得将发现留到后续迭代
重新评审仅验证之前的修复——不进行新的发现
对全新代码（新模块、依赖、测试套件）的请求属于信息性建议，而非阻塞项
结论忽略次要和信息性项目——仅严重和主要问题会阻塞批准