review-feedback-schema

Review Feedback Schema

Purpose

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

1. 识别会产生误报的规则
2. 跟踪技能准确度的变化
3. 通过模式分析自动改进技能

Schema

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

字段	类型	描述	示例值
date	ISO date	审查发生的日期	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

Gates（反馈日志行）

追加一行前，按顺序执行。某个门槛未通过时，不要跳到后续门槛。

1. 证据与代码关联

   • 通过条件： file 是存在（或审查时曾存在）的仓库相对路径，且 line 指明你实际查看过的行号，而不只是转述的摘要。

2. 规则来源可追溯

   • 通过条件： rule_source 符合 skill-name[/section]:rule-id 格式（参见规则来源格式）。如果触发规则未知，应尽力填写来源，并在 rationale 中说明缺口，而不是编造规则 ID。

3. 判定有依据

   • 通过条件： 对于 REJECT，rationale 引用可核查的依据（命令及输出、文档 URL 或引用的代码）。对于 ACCEPT，应说明修复内容或指出相应更改。对于 DEFER/ACKNOWLEDGE，应根据判定类型提供跟踪事项、时间线或已记录的意图。

4. 行格式有效

   • 通过条件： 该行有九个以逗号分隔的字段，与表头行相符；含有逗号或换行符的字段必须使用 CSV 引号括起来，以便标准解析器能正确保留列。

Verdict Types

判定	含义	操作
ACCEPT	问题成立，将予以修复	已进行代码更改
REJECT	问题不成立／判断错误	不做更改；可改进技能
DEFER	问题成立，但暂不修复	记录以便后续处理
ACKNOWLEDGE	问题成立，但属于有意设计	说明其有意为之的原因

何时使用各类型

ACCEPT：审查者正确识别了实际问题。

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：审查者判断有误——代码没有问题。

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：问题成立，但超出当前工作的范围。

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：有意为之的设计决策。

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

格式：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

类别	描述	示例
type-safety	类型注解问题	缺少类型、类型不正确、使用 Any
async	Async/await 问题	在异步代码中执行阻塞操作、缺少 await
error-handling	异常处理	裸 except、缺少错误处理
style	代码风格／格式	行长度、命名约定
patterns	设计模式	反模式、误用框架
testing	测试质量	覆盖率不足、测试不稳定
security	安全问题	注入、机密信息泄露

Writing Good Rationales

对于 ACCEPT

说明你修复了什么：

• “将 Exception 改为 (FileNotFoundError, OSError)”
• “修复了使用 model_copy(update={...}) 的问题”
• “移除了未使用的 Any 导入”

对于 REJECT

说明问题为何不成立：

• “ruff check 通过——不存在 E501 违规”（以代码检查工具为准）
• “pydantic-ai 文档明确支持此模式”（框架惯用写法）
• “代码注释中记录了有意采用的优化”（有文档记录的决策）

对于 DEFER

说明何时／为何会处理：

• “已在 issue #123 中跟踪”
• “计划在 Q1 重构”
• “因等待依赖项升级而受阻”

对于 ACKNOWLEDGE

说明为何这是有意为之：

• “根据项目约定，这是性能关键路径（例如 AGENTS.md 或 CLAUDE.md）”
• “出于对旧版 API 的兼容性要求”
• “与上游库的模式一致”

示例日志

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

审查前验证清单

在报告任何问题之前，审查者必须确认：

验证步骤

1. 确认问题确实存在：阅读实际代码，不要根据上下文推断
2. 检查周边代码：问题可能已在其他位置处理（保护条件、前置检查）
3. 追踪状态／变量的使用情况：在声称“未使用”之前，搜索所有引用
4. 验证断言：如果声称“缺少 X”，请确认确实不存在 X
5. 检查框架处理方式：许多框架会自动处理验证／错误
6. 验证对语法的理解：对照当前文档确认（Tailwind v4、TS 5.x 等）

常见误报模式

模式	根本原因	预防措施
“未使用的变量”	变量在其他位置使用	搜索所有引用
“缺少验证”	框架会执行验证	检查 Pydantic/Zod 等
“类型断言”	实际上是类型注解	确认是 as 还是 :
“内存泄漏”	已存在清理逻辑	检查 effect 的返回值
“语法错误”	使用了新版框架	对照当前文档确认
“风格问题”	只是偏好，并非规则	两种写法都有效

误报风险信号

如果你准备指出以下任何问题，请再次核查：

• “这个变量似乎未使用” → 先搜索所有引用
• “缺少错误处理” → 检查父级／框架的处理方式
• “应该使用 X 而不是 Y” → 两者可能都有效
• “这个语法看起来不对” → 对照当前版本的文档确认

完整验证工作流请参阅 review-verification-protocol。

如何将这些反馈用于改进 Skill

1. 按 rule_source 汇总：找出 REJECT 率较高的规则
2. 分析理由：找出拒绝意见中的常见主题
3. 更新 skill：添加例外、说明或验证步骤
4. 跟踪影响：衡量更改是否降低了拒绝率

完整分析工作流请参阅 review-skill-improver skill。

改进信号

模式	Skill 改进
因“代码检查工具通过”而拒绝	指出风格问题前，添加代码检查工具验证步骤
因“文档支持此写法”而拒绝	为有文档记录的框架模式添加例外
因“这是有意为之”而拒绝	指出问题前，添加代码库上下文检查
因“代码路径错误”而拒绝	声称存在遗漏前，添加代码追踪步骤