review-feedback-schema

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Review Feedback Schema

评审反馈Schema

Purpose

用途

Structured format for logging code review outcomes. This data enables:

Identifying rules that produce false positives
Tracking skill accuracy over time
Automated skill improvement via pattern analysis

用于记录代码评审结果的结构化格式。这些数据可用于：

识别产生误报的规则
随时间跟踪技能准确性
通过模式分析实现技能的自动改进

Schema

csv

date,file,line,rule_source,category,severity,issue,verdict,rationale

Field	Type	Description	Example Values
`date`	ISO date	When review occurred	`2025-12-23`
`file`	path	Relative file path	`amelia/agents/developer.py`
`line`	string	Line number(s)	`128` , `190-191`
`rule_source`	string	Skill and rule that triggered issue	`python-code-review/common-mistakes:unused-variables` , `pydantic-ai-common-pitfalls:tool-decorator`
`category`	enum	Issue taxonomy	`type-safety` , `async` , `error-handling` , `style` , `patterns` , `testing` , `security`
`severity`	enum	As flagged by reviewer	`critical` , `major` , `minor`
`issue`	string	Brief description	`Return type list[Any] loses type safety`
`verdict`	enum	Human decision	`ACCEPT` , `REJECT` , `DEFER` , `ACKNOWLEDGE`
`rationale`	string	Why verdict was chosen	`pydantic-ai docs explicitly support this pattern`

csv

date,file,line,rule_source,category,severity,issue,verdict,rationale

字段	类型	描述	示例值
`date`	ISO日期	评审发生时间	`2025-12-23`
`file`	路径	相对文件路径	`amelia/agents/developer.py`
`line`	字符串	行号	`128` , `190-191`
`rule_source`	字符串	触发问题的技能和规则	`python-code-review/common-mistakes:unused-variables` , `pydantic-ai-common-pitfalls:tool-decorator`
`category`	枚举	问题分类	`type-safety` , `async` , `error-handling` , `style` , `patterns` , `testing` , `security`
`severity`	枚举	评审标记的严重程度	`critical` , `major` , `minor`
`issue`	字符串	问题简要描述	`Return type list[Any] loses type safety`
`verdict`	枚举	人工决策结果	`ACCEPT` , `REJECT` , `DEFER` , `ACKNOWLEDGE`
`rationale`	字符串	决策理由	`pydantic-ai docs explicitly support this pattern`

Verdict Types

评审结论类型

Verdict	Meaning	Action
`ACCEPT`	Issue is valid, will fix	Code change made
`REJECT`	Issue is invalid/wrong	No change; may improve skill
`DEFER`	Valid but not fixing now	Tracked for later
`ACKNOWLEDGE`	Valid but intentional	Document why it's intentional

结论	含义	操作
`ACCEPT`	问题有效，将修复	进行代码变更
`REJECT`	问题无效/错误	不做变更；可能需要优化技能
`DEFER`	问题有效，但暂不修复	跟踪留待后续处理
`ACKNOWLEDGE`	问题有效，但为有意设计	记录设计意图

When to Use Each

各结论适用场景

ACCEPT: The reviewer correctly identified a real issue.

csv

2025-12-27,amelia/agents/developer.py,128,python-code-review:type-safety,type-safety,major,Return type list[Any] loses type safety,ACCEPT,Changed to list[AgentMessage]

REJECT: The reviewer was wrong - the code is correct.

csv

2025-12-23,amelia/drivers/api/openai.py,102,python-code-review:line-length,style,minor,Line too long (104 > 100),REJECT,ruff check passes - no E501 violation exists

DEFER: Valid issue but out of scope for current work.

csv

2025-12-22,api/handlers.py,45,fastapi-code-review:error-handling,error-handling,minor,Missing specific exception type,DEFER,Refactoring planned for Q1

ACKNOWLEDGE: Intentional design decision.

csv

2025-12-21,core/cache.py,89,python-code-review:optimization,patterns,minor,Using dict instead of dataclass,ACKNOWLEDGE,Performance-critical path - intentional

ACCEPT：评审者正确识别出真实问题。

csv

2025-12-27,amelia/agents/developer.py,128,python-code-review:type-safety,type-safety,major,Return type list[Any] loses type safety,ACCEPT,Changed to list[AgentMessage]

REJECT：评审者判断错误 - 代码本身正确。

csv

2025-12-23,amelia/drivers/api/openai.py,102,python-code-review:line-length,style,minor,Line too long (104 > 100),REJECT,ruff check passes - no E501 violation exists

DEFER：问题有效，但超出当前工作范围。

csv

2025-12-22,api/handlers.py,45,fastapi-code-review:error-handling,error-handling,minor,Missing specific exception type,DEFER,Refactoring planned for Q1

ACKNOWLEDGE：为有意的设计决策。

csv

2025-12-21,core/cache.py,89,python-code-review:optimization,patterns,minor,Using dict instead of dataclass,ACKNOWLEDGE,Performance-critical path - intentional

Rule Source Format

规则来源格式

Format:

skill-name/section:rule-id

skill-name:rule-id

Examples:

python-code-review/common-mistakes:unused-variables

pydantic-ai-common-pitfalls:tool-decorator

fastapi-code-review:dependency-injection

```
pytest-code-review:fixture-scope
```

Use the skill folder name and identify the specific rule or section that triggered the issue.

格式：

skill-name/section:rule-id

或

skill-name:rule-id

示例：

python-code-review/common-mistakes:unused-variables

pydantic-ai-common-pitfalls:tool-decorator

fastapi-code-review:dependency-injection

```
pytest-code-review:fixture-scope
```

使用技能文件夹名称，并指明触发问题的具体规则或章节。

Category Taxonomy

问题分类体系

Category	Description	Examples
`type-safety`	Type annotation issues	Missing types, incorrect types, `Any` usage
`async`	Async/await issues	Blocking in async, missing await
`error-handling`	Exception handling	Bare except, missing error handling
`style`	Code style/formatting	Line length, naming conventions
`patterns`	Design patterns	Anti-patterns, framework misuse
`testing`	Test quality	Missing coverage, flaky tests
`security`	Security issues	Injection, secrets exposure

分类	描述	示例
`type-safety`	类型注解问题	缺失类型、类型错误、 `Any` 类型使用
`async`	异步/等待问题	异步代码中的阻塞操作、缺失await
`error-handling`	异常处理问题	裸except、缺失错误处理
`style`	代码风格/格式问题	行长度、命名规范
`patterns`	设计模式问题	反模式、框架误用
`testing`	测试质量问题	缺失测试覆盖、不稳定测试
`security`	安全问题	注入攻击、密钥泄露

Writing Good Rationales

撰写优质决策理由

For ACCEPT

针对ACCEPT

Explain what you fixed:

"Changed Exception to (FileNotFoundError, OSError)"
"Fixed using model_copy(update={...})"
"Removed unused Any import"

说明修复内容：

"Changed Exception to (FileNotFoundError, OSError)"
"Fixed using model_copy(update={...})"
"Removed unused Any import"

For REJECT

针对REJECT

Explain why the issue is invalid:

"ruff check passes - no E501 violation exists" (linter authoritative)
"pydantic-ai docs explicitly support this pattern" (framework idiom)
"Intentional optimization documented in code comment" (documented decision)

说明问题无效的原因：

"ruff check passes - no E501 violation exists"（以代码检查工具结果为准）
"pydantic-ai docs explicitly support this pattern"（符合框架惯用写法）
"Intentional optimization documented in code comment"（已有文档记录的决策）

For DEFER

针对DEFER

Explain when/why it will be addressed:

"Tracked in issue #123"
"Refactoring planned for Q1"
"Blocked on dependency upgrade"

说明后续处理的时间/原因：

"Tracked in issue #123"
"Refactoring planned for Q1"
"Blocked on dependency upgrade"

For ACKNOWLEDGE

针对ACKNOWLEDGE

Explain why it's intentional:

"Performance-critical path per CLAUDE.md"
"Legacy API compatibility requirement"
"Matches upstream library pattern"

说明设计意图：

"Performance-critical path per CLAUDE.md"
"Legacy API compatibility requirement"
"Matches upstream library pattern"

Example Log

示例日志

csv

date,file,line,rule_source,category,severity,issue,verdict,rationale
2025-12-20,tests/integration/test_cli_flows.py,407,pytest-code-review:parametrization,testing,minor,Unused extra_args parameter in parametrization,ACCEPT,Fixed - removed dead parameter
2025-12-20,tests/integration/test_cli_flows.py,237-242,pytest-code-review:coverage,testing,major,Missing review --local in git repo error test,REJECT,Not applicable - review uses different error path
2025-12-21,amelia/server/orchestrator/service.py,1702,python-code-review:immutability,patterns,critical,Direct mutation of frozen ExecutionState,ACCEPT,Fixed using model_copy(update={...})
2025-12-23,amelia/drivers/api/tools.py,48-53,pydantic-ai-common-pitfalls:tool-decorator,patterns,major,Misleading RunContext pattern - should use decorators,REJECT,pydantic-ai docs explicitly support passing raw functions with RunContext to Agent(tools=[])
2025-12-23,amelia/drivers/api/openai.py,102,python-code-review:line-length,style,minor,Line too long (104 > 100),REJECT,ruff check passes - no E501 violation exists
2025-12-27,amelia/core/orchestrator.py,190-191,python-code-review:exception-handling,error-handling,major,Generic exception handling in get_code_changes_for_review,ACCEPT,Changed Exception to (FileNotFoundError OSError)
2025-12-27,amelia/agents/developer.py,128,python-code-review:type-safety,type-safety,major,Return type list[Any] loses type safety,ACCEPT,Changed to list[AgentMessage] and removed unused Any import

csv

date,file,line,rule_source,category,severity,issue,verdict,rationale
2025-12-20,tests/integration/test_cli_flows.py,407,pytest-code-review:parametrization,testing,minor,Unused extra_args parameter in parametrization,ACCEPT,Fixed - removed dead parameter
2025-12-20,tests/integration/test_cli_flows.py,237-242,pytest-code-review:coverage,testing,major,Missing review --local in git repo error test,REJECT,Not applicable - review uses different error path
2025-12-21,amelia/server/orchestrator/service.py,1702,python-code-review:immutability,patterns,critical,Direct mutation of frozen ExecutionState,ACCEPT,Fixed using model_copy(update={...})
2025-12-23,amelia/drivers/api/tools.py,48-53,pydantic-ai-common-pitfalls:tool-decorator,patterns,major,Misleading RunContext pattern - should use decorators,REJECT,pydantic-ai docs explicitly support passing raw functions with RunContext to Agent(tools=[])
2025-12-23,amelia/drivers/api/openai.py,102,python-code-review:line-length,style,minor,Line too long (104 > 100),REJECT,ruff check passes - no E501 violation exists
2025-12-27,amelia/core/orchestrator.py,190-191,python-code-review:exception-handling,error-handling,major,Generic exception handling in get_code_changes_for_review,ACCEPT,Changed Exception to (FileNotFoundError OSError)
2025-12-27,amelia/agents/developer.py,128,python-code-review:type-safety,type-safety,major,Return type list[Any] loses type safety,ACCEPT,Changed to list[AgentMessage] and removed unused Any import

Pre-Review Verification Checklist

评审前验证清单

Before reporting ANY finding, reviewers MUST verify:

在报告任何问题之前，评审者必须完成以下验证：

Verification Steps

验证步骤

Confirm the issue exists: Read the actual code, don't infer from context
Check surrounding code: The issue may be handled elsewhere (guards, earlier checks)
Trace state/variable usage: Search for all references before claiming "unused"
Verify assertions: If claiming "X is missing", confirm X isn't present
Check framework handling: Many frameworks handle validation/errors automatically
Validate syntax understanding: Verify against current docs (Tailwind v4, TS 5.x, etc.)

确认问题真实存在：查看实际代码，不要仅凭上下文推断
检查周边代码：问题可能在其他地方已处理（如防护逻辑、前置检查）
跟踪状态/变量使用：在声称“未使用”之前，搜索所有引用
验证断言：如果声称“缺失X”，确认X确实不存在
检查框架处理逻辑：许多框架会自动处理验证/错误
验证语法理解：对照当前版本文档验证（如Tailwind v4、TS 5.x等）

Common False Positive Patterns

常见误报模式

Pattern	Root Cause	Prevention
"Unused variable"	Variable used elsewhere	Search all references
"Missing validation"	Framework validates	Check Pydantic/Zod/etc.
"Type assertion"	Actually annotation	Confirm `as` vs `:`
"Memory leak"	Cleanup exists	Check effect returns
"Wrong syntax"	New framework version	Verify against current docs
"Style issue"	Preference not rule	Both approaches valid

模式	根本原因	预防措施
"未使用变量"	变量在其他地方被使用	搜索所有引用
"缺失验证"	框架已自动验证	检查Pydantic/Zod等工具
"类型断言"	实际是类型注解	确认使用 `as` 还是 `:`
"内存泄漏"	已存在清理逻辑	检查effect返回值
"语法错误"	框架版本更新	对照当前版本文档验证
"风格问题"	只是偏好而非规则	两种写法均有效

Signals of False Positive Risk

误报风险信号

If you're about to flag any of these, double-check:

"This variable appears unused" → Search for ALL references first
"Missing error handling" → Check parent/framework handling
"Should use X instead of Y" → Both may be valid
"This syntax looks wrong" → Verify against current version docs

Reference: review-verification-protocol for full verification workflow.

如果要标记以下内容，请务必再次检查：

"该变量似乎未使用" → 先搜索所有引用
"缺失错误处理" → 检查父级/框架的处理逻辑
"应使用X而非Y" → 两种写法可能均有效
"该语法看起来错误" → 对照当前版本文档验证

参考：review-verification-protocol 获取完整验证流程。

How This Feeds Into Skill Improvement

如何助力技能改进

Aggregate by rule_source: Identify which rules have high REJECT rates
Analyze rationales: Find common themes in rejections
Update skills: Add exceptions, clarifications, or verification steps
Track impact: Measure if changes reduce rejection rate

See

review-skill-improver

skill for the full analysis workflow.

按rule_source聚合数据：识别误报率高的规则
分析决策理由：找出拒绝的常见主题
更新技能：添加例外情况、说明或验证步骤
跟踪影响：衡量变更是否降低误报率

查看

review-skill-improver

技能获取完整分析流程。

Improvement Signals

改进信号

Pattern	Skill Improvement
"linter passes" rejections	Add linter verification step before flagging style issues
"docs support this" rejections	Add exception for documented framework patterns
"intentional" rejections	Add codebase context check before flagging
"wrong code path" rejections	Add code tracing step before claiming gaps

模式	技能改进方向
"代码检查工具通过"类拒绝	在标记风格问题之前，添加代码检查工具验证步骤
"文档支持该写法"类拒绝	为框架文档明确支持的模式添加例外
"有意设计"类拒绝	在标记前添加代码库上下文检查
"代码路径错误"类拒绝	在声称存在漏洞之前，添加代码跟踪步骤