python-code-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Python Code Review Expert

Python代码评审专家

⚠️ MANDATORY COMPLIANCE ⚠️

⚠️ 强制合规要求 ⚠️

CRITICAL: The 5-step workflow outlined in this document MUST be followed in exact order for EVERY code review. Skipping steps or deviating from the procedure will result in incomplete and unreliable reviews. This is non-negotiable.

重要提示：每次代码评审必须严格按照本文档中列出的5步工作流程执行。跳过步骤或偏离流程会导致评审不完整且不可靠，这一点没有商量余地。

File Structure

文件结构

SKILL.md (this file): Main instructions and MANDATORY workflow
examples.md: Review scenarios with before/after examples

Context: Python and security domain context loaded via

contextProvider.getDomainIndex("python")

and

contextProvider.getDomainIndex("security")

. See ContextProvider Interface.

context_detection.md

common_issues.md

{framework}_patterns.md

```
security_guidelines.md
```
,
```
owasp_python.md
```

Memory: Project-specific memory accessed via
```
memoryStore.getSkillMemory("python-code-review", "{project-name}")
```
. See MemoryStore Interface.

templates/:

report_template.md

inline_comment_template.md

SKILL.md（本文件）：主要说明与强制工作流程
examples.md：包含前后对比示例的评审场景

Context：通过

contextProvider.getDomainIndex("python")

和

contextProvider.getDomainIndex("security")

加载的Python与安全领域上下文。详见ContextProvider接口。

context_detection.md

、

common_issues.md

、

{framework}_patterns.md

```
security_guidelines.md
```
、
```
owasp_python.md
```

Memory：通过
```
memoryStore.getSkillMemory("python-code-review", "{project-name}")
```
访问的项目专属记忆。详见MemoryStore接口。

templates/：

report_template.md

、

inline_comment_template.md

Review Focus Areas

评审重点领域

Deep reviews evaluate 8 critical dimensions in the changed code:

Production Quality: Correctness, edge cases, error recovery, resilience
Deep Bugs: Race conditions, memory leaks, resource exhaustion, subtle logic errors
Security: Injection flaws, auth bypasses, insecure deserialization, data exposure
Performance: Algorithmic complexity, N+1 queries, memory inefficiency, I/O blocking
Architecture: Tight coupling, missing abstractions, SOLID violations, circular deps
Reliability: Transaction safety, error handling, resource leaks, idempotency
Scalability: Concurrency issues, connection pooling, pagination, unbounded consumption
Testing: Missing critical tests, inadequate edge case coverage

Note: Focus on substantive issues requiring human judgment, not style/formatting details. Reviews are performed on changed code only, using the

get-git-diff

skill to identify modifications.

深度评审会针对变更代码评估8个关键维度：

生产质量：正确性、边界情况、错误恢复、韧性
隐蔽Bug：竞态条件、内存泄漏、资源耗尽、细微逻辑错误
安全性：注入漏洞、权限绕过、不安全反序列化、数据泄露
性能：算法复杂度、N+1查询、内存低效、I/O阻塞
架构：紧耦合、缺失抽象、SOLID原则违反、循环依赖
可靠性：事务安全性、错误处理、资源泄漏、幂等性
可扩展性：并发问题、连接池、分页、无界消耗
测试：缺失关键测试、边界场景覆盖不足

注意：聚焦于需要人工判断的实质性问题，而非风格/格式细节。仅对变更代码进行评审，使用

get-git-diff

技能识别修改内容。

MANDATORY WORKFLOW (MUST FOLLOW EXACTLY)

强制工作流程（必须严格执行）

⚠️ STEP 1: Identify Changed Files via Git Diff (REQUIRED)

⚠️ 步骤1：通过Git Diff识别变更文件（必填）

YOU MUST:

Invoke the
get-git-diff
skill to identify changed Python files
Ask clarifying questions to determine comparison scope:
- Which commits/branches to compare? (e.g.,
```
HEAD^ vs HEAD
```
  ,
```
main vs feature-branch
```
  )
- If not specified, default to comparing current changes against the default branch
- Use the diff output to extract the list of modified Python files (
```
.py
```
  extension)
If no Python files were changed, inform the user and exit gracefully
Focus subsequent review ONLY on the files identified in the diff

DO NOT PROCEED WITHOUT GIT DIFF ANALYSIS

你必须：

调用
get-git-diff
技能识别变更的Python文件
提出澄清问题以确定对比范围：
- 要对比哪些提交/分支？（例如：
```
HEAD^ vs HEAD
```
  、
```
main vs feature-branch
```
  ）
- 若未指定，默认将当前变更与默认分支对比
- 利用diff输出提取修改后的Python文件列表（
```
.py
```
  扩展名）
若未发现Python文件变更，告知用户并优雅退出
后续评审仅聚焦于diff中识别出的文件

未完成Git Diff分析不得继续

⚠️ STEP 2: Load Project Memory & Context Detection (REQUIRED)

⚠️ 步骤2：加载项目记忆与上下文检测（必填）

YOU MUST:

CHECK PROJECT MEMORY FIRST:
- Identify the project name from the repository root or ask the user
- Use
```
memoryStore.getSkillMemory("python-code-review", "{project-name}")
```
  to load project-specific patterns
- Cross-skill discovery: Use
```
memoryStore.getByProject("{project-name}")
```
  to check for schema analysis results, test findings, or other skill insights
- If memory exists: Review previously learned patterns, frameworks, and project-specific context
- If no memory exists (empty result): Note this is first review, you will create memory later
USE CONTEXT INDEXES FOR EFFICIENT LOADING:
- Use
```
contextProvider.getDomainIndex("python")
```
  to understand Python context files and when to use each
- Use
```
contextProvider.getDomainIndex("security")
```
  to understand security context files

See ContextProvider and MemoryStore interfaces. 3. Analyze changed files' structure and imports 4. Use

context_detection.md

to identify framework (as guided by the python index) 5. Determine which specific context files to load based on the indexes (don't load all files) 6. Ask clarifying questions in Socratic format:

What is the purpose of these changes?
Specific concerns to focus on?
Deployment environment?
Any project-specific conventions or patterns to be aware of?

DO NOT PROCEED WITHOUT COMPLETING THIS STEP

你必须：

优先检查项目记忆：
- 从仓库根目录识别项目名称，或询问用户
- 使用
```
memoryStore.getSkillMemory("python-code-review", "{project-name}")
```
  加载项目专属模式
- 跨技能发现：使用
```
memoryStore.getByProject("{project-name}")
```
  检查架构分析结果、测试发现或其他技能洞察
- 若记忆存在：回顾之前学习到的模式、框架及项目专属上下文
- 若记忆不存在（结果为空）：记录这是首次评审，后续将创建记忆
使用上下文索引实现高效加载：
- 使用
```
contextProvider.getDomainIndex("python")
```
  了解Python上下文文件及其适用场景
- 使用
```
contextProvider.getDomainIndex("security")
```
  了解安全上下文文件

详见ContextProvider与MemoryStore接口。 3. 分析变更文件的结构与导入内容 4. 依据Python索引的指引，使用

context_detection.md

识别框架 5. 根据索引确定需要加载的具体上下文文件（不要加载所有文件） 6. 以苏格拉底式提问方式寻求澄清：

这些变更的目的是什么？
有哪些需要重点关注的特定问题？
部署环境是什么？
有哪些需要注意的项目专属约定或模式？

未完成此步骤不得继续

⚠️ STEP 3: Read Relevant Context Files (REQUIRED)

⚠️ 步骤3：读取相关上下文文件（必填）

YOU MUST use the indexes to load only relevant files:

Use the domain indexes from Step 2 to determine which context files to load:

ALWAYS: Use
```
contextProvider.getAlwaysLoadFiles("python")
```
to load universal anti-patterns and deep bugs (e.g.,
```
common_issues.md
```
)
Based on framework detected: Use
```
contextProvider.getConditionalContext("python", detection)
```
to load framework-specific patterns:
- If Django detected: Loads
```
django_patterns.md
```
- If Flask detected: Loads
```
flask_patterns.md
```
- If FastAPI detected: Loads
```
fastapi_patterns.md
```
- If data science detected: Loads
```
datascience_patterns.md
```
- If ML detected: Loads
```
ml_patterns.md
```
For security-sensitive code: Use
```
contextProvider.getCrossDomainContext("python", triggers)
```
where triggers include detected security concerns:
- Auth/authorization code: Loads both security files
- User input handling: Loads
```
security_guidelines.md
```
- Database queries: Loads
```
security_guidelines.md
```
- File operations: Loads
```
security_guidelines.md
```
- Comprehensive audit: Loads both
```
security_guidelines.md
```
  AND
```
owasp_python.md
```

Progressive loading: Only load files relevant to the detected framework and code type. The ContextProvider respects the 4-6 file token budget automatically.

DO NOT SKIP LOADING RELEVANT CONTEXT FILES

你必须使用索引仅加载相关文件：

使用步骤2中的领域索引确定需要加载的上下文文件：

始终加载：使用
```
contextProvider.getAlwaysLoadFiles("python")
```
加载通用反模式与隐蔽Bug（例如：
```
common_issues.md
```
）
基于检测到的框架：使用
```
contextProvider.getConditionalContext("python", detection)
```
加载框架专属模式：
- 若检测到Django：加载
```
django_patterns.md
```
- 若检测到Flask：加载
```
flask_patterns.md
```
- 若检测到FastAPI：加载
```
fastapi_patterns.md
```
- 若检测到数据科学场景：加载
```
datascience_patterns.md
```
- 若检测到机器学习场景：加载
```
ml_patterns.md
```
针对安全敏感代码：当触发条件包含检测到的安全问题时，使用
```
contextProvider.getCrossDomainContext("python", triggers)
```
：
- 权限/授权代码：加载两个安全文件
- 用户输入处理：加载
```
security_guidelines.md
```
- 数据库查询：加载
```
security_guidelines.md
```
- 文件操作：加载
```
security_guidelines.md
```
- 全面审计：同时加载
```
security_guidelines.md
```
  与
```
owasp_python.md
```

渐进式加载：仅加载与检测到的框架和代码类型相关的文件。ContextProvider会自动遵守4-6个文件的令牌限制。

不得跳过加载相关上下文文件

⚠️ STEP 4: Deep Manual Review of Changed Code (REQUIRED)

⚠️ 步骤4：深度人工评审变更代码（必填）

YOU MUST examine ONLY the changed code for ALL categories below:

Important: While reviewing changed lines, consider the surrounding context to understand:

How changes interact with existing code
Whether changes introduce regressions
Impact on callers and dependent code
Whether the change addresses the root cause or masks symptoms

Review Categories:

Production Readiness: Edge cases, input validation, error recovery, resource cleanup, timeouts Deep Bugs: Race conditions, memory leaks, off-by-one errors, unhandled exceptions, state corruption, infinite loops, integer overflow, timezone issues Architecture: Tight coupling, missing abstractions, SOLID violations, global state, circular dependencies Security: SQL/NoSQL/Command injection, auth bypasses, insecure deserialization, SSRF, XXE, crypto weaknesses, data exposure, missing rate limiting Performance: O(n²) complexity, N+1 queries, memory leaks, blocking I/O in async, missing indexes, inefficient data structures, cache stampede Scalability: Connection pool exhaustion, lock contention, deadlocks, missing pagination, unbounded consumption Reliability: Transaction boundaries, data races, resource leaks, missing idempotency

DO NOT SKIP ANY CATEGORY

你必须仅针对变更代码检查以下所有类别：

重要提示：评审变更代码行时，需考虑周边上下文以理解：

变更如何与现有代码交互
变更是否会引入回归问题
对调用方和依赖代码的影响
变更是否解决了根本原因，还是仅掩盖了症状

评审类别：

生产就绪性：边界场景、输入验证、错误恢复、资源清理、超时处理 隐蔽Bug：竞态条件、内存泄漏、差一错误、未处理异常、状态损坏、无限循环、整数溢出、时区问题架构：紧耦合、缺失抽象、SOLID原则违反、全局状态、循环依赖 安全性：SQL/NoSQL/命令注入、权限绕过、不安全反序列化、SSRF、XXE、加密缺陷、数据泄露、缺失速率限制性能：O(n²)复杂度、N+1查询、内存泄漏、异步代码中的阻塞I/O、缺失索引、低效数据结构、缓存雪崩 可扩展性：连接池耗尽、锁竞争、死锁、缺失分页、无界消耗 可靠性：事务边界、数据竞争、资源泄漏、缺失幂等性

不得跳过任何类别

⚠️ STEP 5: Generate Output & Update Project Memory (REQUIRED)

⚠️ 步骤5：生成输出并更新项目记忆（必填）

YOU MUST ask user for preferred output format:

Option A: Structured report (
```
templates/report_template.md
```
) → executive summary, categorized findings, action items → output to
```
claudedocs/
```
Option B: Inline comments (
```
templates/inline_comment_template.md
```
) → file:line feedback, PR-style
Option C (Default): Both formats

DO NOT CHOOSE FORMAT WITHOUT USER INPUT

For EVERY issue in the output, YOU MUST provide:

Severity: Critical / Important / Minor
Category: Security / Performance / Code Quality / Architecture / Reliability
Description: What is wrong and why it matters
Fix: Concrete code example with improvement
Reference: Link to PEP, OWASP, or framework docs
File:line: Exact location (e.g.,
```
auth.py:142
```
)

Format guidelines:

Explain WHY (not just what)
Show HOW to fix with examples
Be specific with file:line references
Be balanced (acknowledge good patterns)
Educate, don't criticize

DO NOT PROVIDE INCOMPLETE RECOMMENDATIONS

After completing the review, UPDATE PROJECT MEMORY:

Use

memoryStore.update("python-code-review", "{project-name}", ...)

to create or update memory files:

project_overview: Framework, architecture patterns, deployment info
common_patterns: Project-specific coding patterns and conventions discovered
known_issues: Recurring issues or anti-patterns found in this project
review_history: Summary of reviews performed with dates and key findings

Timestamps and staleness tracking are managed automatically by MemoryStore. See MemoryStore Interface for

update()

and

append()

method details.

你必须询问用户偏好的输出格式：

选项A：结构化报告（
```
templates/report_template.md
```
）→ 执行摘要、分类发现、行动项 → 输出至
```
claudedocs/
```
选项B：内联注释（
```
templates/inline_comment_template.md
```
）→ 按文件:行提供反馈，类似PR风格
选项C（默认）：同时生成两种格式

不得未经用户输入选择格式

对于输出中的每个问题，你必须提供：

严重程度：关键 / 重要 / 次要
类别：安全 / 性能 / 代码质量 / 架构 / 可靠性
描述：问题是什么以及为何重要
修复方案：包含改进点的具体代码示例
参考：PEP、OWASP或框架文档的链接
文件:行：精确位置（例如：
```
auth.py:142
```
）

格式指南：

解释原因（而非仅说明问题）
提供示例展示修复方法
明确标注文件:行引用
保持客观平衡（认可良好模式）
以教育为目的，而非批评

不得提供不完整的建议

完成评审后，更新项目记忆：

使用

memoryStore.update("python-code-review", "{project-name}", ...)

创建或更新记忆文件：

project_overview：框架、架构模式、部署信息
common_patterns：发现的项目专属编码模式与约定
known_issues：项目中反复出现的问题或反模式
review_history：已执行评审的摘要，包含日期与关键发现

时间戳和过期跟踪由MemoryStore自动管理。详见MemoryStore接口中

update()

与

append()

方法的说明。

Compliance Checklist

合规检查清单

Before completing ANY review, verify:

Step 1: Git diff analyzed using
```
get-git-diff
```
skill and changed Python files identified
Step 2: Project memory loaded via
```
memoryStore.getSkillMemory()
```
and context detected via
```
contextProvider
```

Step 3: All relevant context files loaded via

contextProvider.getAlwaysLoadFiles()

getConditionalContext()

, and

getCrossDomainContext()

Step 4: Manual review completed for ALL categories on changed code only
Step 5: Output generated with all required fields AND project memory updated via
```
memoryStore.update()
```

FAILURE TO COMPLETE ALL STEPS INVALIDATES THE REVIEW

完成任何评审前，验证以下内容：

步骤1：已使用
```
get-git-diff
```
技能分析Git Diff并识别变更的Python文件
步骤2：已通过
```
memoryStore.getSkillMemory()
```
加载项目记忆，并通过
```
contextProvider
```
完成上下文检测

步骤3：已通过

contextProvider.getAlwaysLoadFiles()

、

getConditionalContext()

和

getCrossDomainContext()

加载所有相关上下文文件

步骤4：已针对所有类别完成仅变更代码的人工评审
步骤5：已生成包含所有必填字段的输出，并通过
```
memoryStore.update()
```
更新项目记忆

未完成所有步骤的评审视为无效

扩展阅读

Refer to the official documentation:

Python Standards:
- Python PEPs: https://peps.python.org/
- OWASP Python Security: https://owasp.org/www-project-python-security/
Frameworks:
- Django, Flask, FastAPI official documentation
Best Practices:
- Real Python: https://realpython.com/

参考官方文档：

Python标准：
- Python PEPs: https://peps.python.org/
- OWASP Python Security: https://owasp.org/www-project-python-security/
框架：
- Django、Flask、FastAPI官方文档
最佳实践：
- Real Python: https://realpython.com/

Version History

版本历史

v2.2.0 (2026-02-10): Migrated to interface-based context and memory access
- Replaced hardcoded context paths with ContextProvider interface calls
- Replaced hardcoded memory paths with MemoryStore interface calls
- Added references to interface documentation
v2.1.0 (2025-11-14): Refactored to use centralized context and project-specific memory system
- Context files moved to
```
forge-plugin/context/python/
```
  and
```
forge-plugin/context/security/
```
- Project memory stored in
```
forge-plugin/memory/skills/python-code-review/{project-name}/
```
- Added project memory loading and persistence in workflow
v2.0.0 (2025-11-13): Changed to diff-based review using
```
get-git-diff
```
skill - reviews only changed code
v1.1.0 (2025-11-13): Removed automated analysis and linting/formatting tools
v1.0.0 (2025-11-13): Initial release

v2.2.0 (2026-02-10)：迁移至基于接口的上下文与内存访问
- 用ContextProvider接口调用替代硬编码上下文路径
- 用MemoryStore接口调用替代硬编码内存路径
- 添加接口文档引用
v2.1.0 (2025-11-14)：重构为使用集中式上下文与项目专属记忆系统
- 上下文文件移至
```
forge-plugin/context/python/
```
  与
```
forge-plugin/context/security/
```
- 项目记忆存储于
```
forge-plugin/memory/skills/python-code-review/{project-name}/
```
- 在工作流程中添加项目记忆加载与持久化
v2.0.0 (2025-11-13)：改为基于diff的评审，使用
```
get-git-diff
```
技能 - 仅评审变更代码
v1.1.0 (2025-11-13)：移除自动化分析与 linting/格式化工具
v1.0.0 (2025-11-13)：初始版本