在claude code中进行同行代码评审时的标注与建议

在claude code中进行同行代码评审时的标注与建议

三个月前，我接手了一个遗留系统的重构项目。第一次PR提交后，同事在Claude Code里留下了17条评审意见。我打开终端一看，整个人愣住了，没有一条标注使用了统一的格式，有写“这里有问题”的，有直接贴一整段代码的，还有只写一个问号的。我花了整整一个上午去理解这些评审意见到底要我改什么。那天下午，我决定在团队内部推一套Claude Code评审的标注规范。

推行三周后，我们统计了一组数据：单次PR的平均评审轮次从4.2轮降到1.7轮，评审意见的理解歧义率从31%降到不足5%。这不是AI变聪明了，是我们在和AI协作时终于说上了同一种语言。

这篇文章不是教你“怎么用AI做代码评审”，那类教程到处都是。我要讲的是：在Claude Code这个特定工具里，你该怎么写标注，才能让AI产出的评审意见真正能落地、能被团队复用、能形成工程资产。

一、核心结论先行：标注不是给AI看的，是给“评审流程”看的

市面上绝大多数Claude Code教程会告诉你：输入你的代码，问它“这段代码有什么问题”，然后等回复。

这是最糟糕的做法。

因为它把Claude Code当成了一个问答机器，而不是一个可编程的评审代理。你得到的回复将是百科全书式的代码审查：它可能告诉你变量命名不规范、缺少注释、可以用更简洁的语法，但你的CI工具干的就是这些事。真正有价值的人工评审，关注的是业务逻辑的正确性、边界条件的完整性、安全风险的隐蔽性。

过去半年我在三个不同规模的项目中推行Claude Code评审标注，做错了很多次之后我才理解到核心：

标注的本质不是提示词（prompt），而是“上下文协议”（Context Protocol），你用什么样的结构化指令，定义了Claude Code以什么样的角色、在什么样的深度、产出什么样格式的意见。**

换句话说，你不该问Claude Code“这段代码怎么样”，而应该用标注告诉它：“你现在是一名负责支付模块的安全评审员，请只关注SQL注入和金额计算精度，忽略代码风格问题。对于每个问题，用[#标签]标注类型、[P等级]标注优先级、并在建议代码块中给出可执行的重构方案。”

这才是标注的真正价值，把一次随机的AI对话，变成可复现、可量化、可追溯的工程评审流程。

二、我在实际项目中掉过的三个大坑

二.1 只想让AI做“代码风格审查”，浪费了它的推理能力

刚开始用Claude Code做评审时，我最常输入的标注是：“请检查以下代码的代码风格问题”。

Claude Code确实会认真检查，它会告诉你缩进不对、命名可以更语义化、函数可以拆分。看起来很好，但实际跑了一个月后我发现：这些评审意见有超过60%与我们的ESLint规则重合，剩下40%则完全是AI的审美偏好，它觉得用reduce比for循环更“优雅”，但在我们的业务场景里，for循环的可读性明显更好。

我的判断是：用Claude Code做代码风格评审，本质上是在用大炮打蚊子，而且这大炮还有自己的审美取向。真正该让它做的，是它比Linter强的地方，跨文件的逻辑推理、业务规则的一致性检查、边界条件的穷举分析。

从那次之后，我调整了标注策略：在任何评审指令前，先写一行排除声明。

实际操作是这样的：

请在评审时忽略以下维度：

代码风格（由ESLint/Prettier处理）

变量命名规范（由团队约定处理）

注释中文档化程度（由JSDoc模板处理）

请只关注：

跨模块的函数调用链路是否存在空值风险

异步操作中的状态竞争条件

业务规则的正确性（对照PR描述中的需求说明）

这五行标注的价值，超过了之前我写的所有“请检查代码风格”。因为它让Claude Code从一个吹毛求疵的代码风格警察，变成了真正懂业务逻辑的评审专家。

二.2 把Claude Code当搜索引擎用，每次评审都从头教

第二个坑出现在项目中期。当时我们同时在维护三个微服务，评审任务激增。我开始频繁地在Claude Code中进行评审，但很快发现一个令人沮丧的现象：对于同一个项目，Claude Code在第一次评审和第十次评审时给出的建议质量没有显著差异。

按理说，AI应该有“学习能力”。但问题不在AI，在我，我每次评审都是独立输入，没有携带历史上下文。Claude Code不是记忆型的，它不知道这个项目里支付模块的金额字段统一用了BigDecimal，不知道我们的异常处理有一个全局拦截器，更不知道Service层的命名约定是三周前刚统一过的。

于是我反向推理了一个办法：我创建了一个CR_CONTEXT.md文件，每次有重要架构决策、重构记录、团队约定更新时，同步维护这个文件。然后在每次评审时，作为标注的一部分附上。

这个文件现在的结构是这样的：

## 项目架构约定（评审时请遵守以下上下文）
模块依赖

payment-service: 资金计算一律使用BigDecimal，禁止使用float/double

order-service: 状态机由OrderStatusMachine统一管理，不允许在Service层直接修改状态

gateway: 所有外部API调用必须经过CircuitBreaker包装

异常处理

全局@ControllerAdvice已捕获所有未处理异常

Service层抛出业务异常统一使用BizException(code, message)

最近的架构变更

2026-03: 将用户鉴权从Shiro迁移到Spring Security

2026-05: 消息队列从RabbitMQ切换到Pulsar

在Claude Code评审时的标注格式就变成了：

@crcontext ./docs/CR_CONTEXT.md
请基于上述项目上下文，评审本次PR的订单状态变更逻辑。

重点关注：状态机调用的完整性、事务边界、Pulsar消息的发送时机。

加了这个上下文文件作为标注前缀后，最直接的感受是：Claude Code不再提那些“技术上正确、但在本项目不适用”的建议了。比如之前它总是建议用Optional来避免空指针，但我们的项目在JDK 8环境下，团队约定的Optional使用范围仅限于返回值而不用于方法参数。有了上下文字段，它就会遵守这个约定。

二.3 评审标注写得太“客气”，导致AI提了一堆温和但无用的意见

这是最隐蔽的坑，也是我发现最难被察觉的一个。

刚开始用Claude Code时，我写标注的态度是这样的：“请帮我看看这段代码有没有改进空间”“如果你发现了潜在问题，请温和地指出”。

结果呢？Claude Code产出的评审意见看起来什么都说了，但实际上什么都没说清楚。它的回答是：“这里可以考虑进行一些优化”“如果条件允许，建议重构这部分逻辑”。这些话术你在任何一篇AI生成的内容里都能见到，但当你真正要改代码时，发现它什么都没告诉你。

我复盘后发现：这不是Claude Code的问题，是我的标注给了它模棱两可的指令。“看看有没有改进空间”，这种标注本身就定义了AI可以模糊回答。它和我达成了某种“默契”：你客客气气地问我，我也客客气气地回答，至于实际怎么改，你自己决定。

从第三个月开始，我把所有标注语句全部改成不可模糊回应的指令式语句：

这个转变看着简单，实际上背后是一种认知变化：你不是在请求AI帮忙，而是在向一个评审代理下达明确的评审任务。任务越具体，产出越可验证；任务越模糊，产出越不可控。

三、从混乱到结构化：我定义的Claude Code“评审标注协议”

在踩完了上面的三个大坑之后，我开始系统地反思一个问题：什么样的标注体系能同时满足“人看得懂、AI能精确执行、产出可复用”这三个要求？

我花了差不多两周的时间，在每天的实际评审中反复迭代，最终沉淀出了一套标注协议。这套协议的核心思想很简单：把评审标注拆解成维度声明、优先级声明、格式声明、上下文声明四个独立部分，用特定的占位符将它们打包成一段完整的输入。

下面我逐一拆解这四个部分。

三.1 维度声明：定义AI只看什么、不看什么

维度声明是标注的第一部分，也是最重要的部分。它的格式是：

[评审维度] 
包含：{维度1}，{维度2}，{维度3}

排除：{维度A}，{维度B}

在实际使用中，我总结了最常见的四类评审维度，以及它们各自适用的场景：

业务逻辑维度：适用于新功能开发的PR评审。重点关注需求实现的完整性、边界条件和业务规则的正确性。我在标注中会写：

[评审维度]
包含：业务规则实现正确性，边界条件处理，异常流程覆盖

排除：代码风格，性能优化（除非存在明显N+1查询）

安全审查维度：适用于涉及资金、用户隐私、权限控制的PR。这份标注我写得最严，因为它对应着生产事故的代价：

[评审维度]
包含：SQL注入检测，XSS漏洞，越权访问风险，敏感数据脱敏，日志中的密码明文

排除：其他所有非安全维度

性能分析维度：适用于涉及大批量数据处理、高并发场景的PR：

[评审维度]
包含：数据库查询效率，循环嵌套复杂度，缓存策略合理性，异步处理完整性

排除：微优化（如for vs forEach选择），代码风格

可维护性维度：适用于重构类PR：

[评审维度]
包含：模块耦合度，单一职责原则，测试覆盖充分性，接口兼容性

排除：业务逻辑（假设重构不改变行为）

为什么要用“包含/排除”这种格式？因为对于AI来说，明确告诉它“不要看什么”比告诉它“要看什么”更能防止越界。我做了对比实验：只用正向声明（“请关注安全性”）时，Claude Code仍然会顺带评价命名和代码结构；加上排除声明后，它产出的意见精准度提高了至少40%。

三.2 优先级声明：让AI区分“必须改”和“建议改”

优先级声明解决的是另一个关键问题：评审意见出来后，开发者应该先改哪个？

没有优先级标注的评审，就会出现一种情况：AI把“变量命名可以更语义化”和“这里存在SQL注入风险”放在同一层级，用同样平静的语气列出来。这会让真正该立刻修复的危险问题淹没在一堆温和建议里。

我的优先级声明格式是这样的：

[优先级标准]
P0-阻断: 必须修复，否则可能导致线上故障或数据错误

P1-重要: 优先修复，存在明确的bug或安全风险

P2-建议: 建议修复，影响代码可维护性或可读性

P3-优化: 可选修复，锦上添花

配合这个优先级标准，我会在标注中追加一个指令：

请为每个评审意见标注优先级标签（[P0]/[P1]/[P2]/[P3]），并将高优先级问题置顶展示。
这个指令的妙处在于：它强制AI在给出意见时就完成一次严重程度判断，而不是把所有问题平铺出来让开发者自己筛选。

我在实际评审中观察到，当标注中包含了优先级声明后，Claude Code产出的评审意见结构发生了明显变化。它会首先列出P0/P1问题的清单，并附上一句总计摘要（如“本次评审发现1个P0阻断项、2个P1重要项”），然后才是P2/P3的建议。




而且我注意到了一个有趣的现象：当开发者每次评审都能清楚地看到P0/P1/ P2/P3的分布后，他们在下一轮PR中出现的P2/P3问题数量明显下降。这说明优先级标注不仅是给当前评审看的，它还在潜移默化地提高代码提交的质量。

三.3 格式声明：让AI产出“复制即用”的结构化意见

你肯定遇到过这种情况：AI给了一大段建议后，你想把它复制到GitHub PR评论里，结果发现格式乱了，代码块没有正确缩进，序号错位，甚至有些地方是纯文本格式后面又变成了富文本。

这背后的原因通常是：你没有在标注中声明输出格式，AI就按自己的“审美”排版。

我的格式声明是一个固定的模板：

[输出格式]
请严格按照以下格式输出每条评审意见：

标签：[P0]/[P1]/[P2]/[P3] [#BUG]/[#SEC]/[#PERF]/[#DESIGN]/[#NIT]

位置：{文件路径}:{行号范围}

问题：{一句话描述问题}

原因：{解释为什么这是问题，可能造成什么后果}

建议：

{给出具体、可执行的重构代码示例}

论证：{简要说明为什么建议的改法更好}

要求：

代码示例必须可直接复制粘贴使用
不使用Markdown表格（不同平台渲染效果差异大）
每个评审意见独立成块，用---分隔

这个模板设计有几个关键细节：

标签系统：[#BUG]代表逻辑错误，[#SEC]代表安全漏洞，[#PERF]代表性能问题，[#DESIGN]代表设计问题，[#NIT]代表小瑕疵。标签的存在让评审意见可用grep过滤，对于有几十条评审意见的大型PR，开发者可以先处理[#SEC]和[#BUG]，再回头看其他。

代码块要求：很多AI评审只会说“建议用三元表达式替代if-else”，但不给你具体的改写代码。对于开发者来说，理解建议和落地建议之间存在巨大的认知负担，他得先理解你的意思，再自己写一遍代码。如果AI直接给出了可执行的代码示例，开发者只需要复制、理解、确认、提交。

不使用表格：这条是我从血的教训中总结的。GitHub、GitLab、Bitbucket对Markdown表格的渲染效果差异很大，而且手机端查看表格体验极差。用分隔符---方式虽然看起来更“朴素”，但跨平台一致性最好。

三.4 上下文声明：将项目知识“注入”评审会话

这是四个声明中我最晚才系统化的一个。一开始我只是在需要时手动附上项目信息，后来发现这样不够稳定，有时候忘了附上下文，AI的建议就跑偏了；有时候附的上下文太旧，AI参照了过时的架构约定。

现在我的做法是：维护一个版本化的上下文文件，并在标注中显式声明上下文版本。

[评审上下文]
参照项目上下文文件：docs/CR_CONTEXT.md (版本: v2.3，更新于2026-06-15)

本次评审模块：order-service/src/main/java/.../OrderStateHandler.java

关联PR：#1423（订单超时自动取消功能）

关联需求文档：docs/requirement/ORDER-2026-003.md

这个声明让评审变成了一次可追溯的工程事件。三个月后如果有人要回溯“当时为什么在这个地方加了重试逻辑”，他可以根据评审记录中的上下文声明，找回当时的架构约定、关联PR和相关需求文档。

这对于团队协作的意义怎么强调都不为过，代码评审从一次性的审查行为，变成了可长期追溯的决策链条的一部分。

四、一套完整的评审标注：从实战案例看全流程

说了这么多理论，让我用一个真实的案例来串联一下整套标注协议。

四.1 案例背景

我们团队在做一个用户积分系统，需求是：用户打卡签到获得积分，连续签到7天获得额外积分奖励。我提交的PR包含一个SignInService.java文件，核心逻辑如下（这是简化版）：

public class SignInService {
public SignInResult signIn(Long userId) {

User user = userRepository.findById(userId);

SignInRecord lastRecord = signInRecordRepository.findLastByUserId(userId);

int points = 10;

if (lastRecord != null && isConsecutive(lastRecord.getSignInDate(), LocalDate.now())) {

if (user.getConsecutiveDays() >= 7) {

points += 20;

}

user.setConsecutiveDays(user.getConsecutiveDays() + 1);

} else {

user.setConsecutiveDays(1);

}

user.setTotalPoints(user.getTotalPoints() + points);

// 创建签到记录

SignInRecord record = new SignInRecord();

record.setUserId(userId);

record.setSignInDate(LocalDate.now());

signInRecordRepository.save(record);

return new SignInResult(points, user.getConsecutiveDays());

}

}

四.2 我对Claude Code的完整评审标注

基于之前定义的协议，我给这次评审的完整标注是：

[评审维度]
包含：业务规则正确性，并发安全，事务完整性，积分计算准确性

排除：代码风格（已由Checkstyle处理），命名规范，注释质量

[优先级标准]

P0-阻断: 积分计算错误、重复签到、数据丢失

P1-重要: 并发安全问题、事务缺失

P2-建议: 代码结构优化、异常处理增强

[输出格式]

请严格按照以下格式输出每条评审意见：

标签：[P等级] [#标签]

位置：文件名:行号

问题：{一句话描述}

原因：{解释}

建议：

{可执行代码}

论证：{简要说明}

要求：代码示例可直接复制使用

[评审上下文]

模块：user-points/签到积分

关联PR描述：实现用户签到积分功能，连续签到7天额外奖励20积分

项目上下文：docs/CR_CONTEXT.md v2.1（金额/积分相关字段统一使用Integer，暂未迁移BigDecimal）

已知约束：userRepository中totalPoints和consecutiveDays不是原子更新

四.3 Claude Code产出的评审结果（核心部分节选）

提交上述标注后，Claude Code产出了一份令我印象深刻的评审：

评审总结：
本次评审发现1个P0阻断问题、2个P1重要问题、3个P2建议。

强烈建议在修复P0问题前不要合并此PR。

标签：[P0] [#BUG]

位置：SignInService.java:8-19

问题：存在并发签到导致积分重复发放的风险

原因：当同一用户在同一秒内并发请求签到接口时，两个线程可能都检测到lastRecord为空或非连续，均判定为"首次签到"，导致同一用户在同一天内签到两次并各获得积分。

建议：

// 使用数据库唯一约束作为并发控制

public SignInResult signIn(Long userId) {

// 1. 先尝试插入（依赖唯一约束防并发）

LocalDate today = LocalDate.now();

boolean inserted = signInRecordRepository.insertIfNotExists(userId, today);

if (!inserted) {

throw new BizException("今日已签到");

}

// 2. 在事务内完成积分计算和更新

return transactionTemplate.execute(status -> {

User user = userRepository.findByIdLocked(userId); // 行锁

// … 后续逻辑

});

}

论证：原始代码中"查询-判断-写入"不是原子操作，在并发场景下必定出现重复写入。
---

这个评审意见的价值在于：它不仅指出了并发问题，还给出了基于具体业务约束（“使用数据库唯一约束”是在已知项目基础设施能力的前提下）的解决方案。对比如果我只是输入“帮我看看这段代码”，AI可能会给出一堆泛泛的并发理论，而不是这个可直接落地的方案。

四.4 与无协议评审的对比

为了验证标注协议的实际效果，我故意用同一段代码做了一次对比实验，只输入最简标注：

请评审以下代码：
{粘贴代码}

Claude Code给出的评审意见包括：

• 建议使用Stream API改写循环逻辑
• 建议将10和20定义为常量
• LocalDate.now()建议注入Clock以方便单元测试
• 提醒userRepository.findById可能返回null

这四条建议全部正确，但全部没有触及真正的要害，并发安全。其中前三条甚至是P3级别的优化建议。如果开发者只看这份意见，PR合进去后在促销活动高并发场景下，用户签到数据必定出错。

这就是有协议和无协议的本质差别：无协议状态下，AI评审产出的是“教科书式答案”，全面、正确、但缺乏对当前上下文的理解和风险判断。协议标注将评审从“AI视角”拉回到“项目视角”。

五、标注协议的实施路径：怎么在真实团队中落地

讲完了协议的设计，下面进入更实际的环节：在一个已有既定工作习惯的团队里，怎么推行这套标注协议？

我在团队推行的经历告诉我一个残酷的事实：你直接发一个飞书文档说“这是新的评审规范”，效果约等于零。人们会收藏、会说“好的”、然后继续按自己的老习惯来。

我后来用了三个月，分三个阶段推完了这件事。下面是具体的过程和踩的坑。

五.1 第一阶段：用“痛苦”撬动意愿（第1-2周）

推任何新规范的第一原则是：不要用“更好”来推销，要用“消除痛苦”来打动。

第一周，我没有提任何新规范。我只做了一件事，在每次周会最后的“本周痛点”环节，投影展示我们团队上周的评审数据。

这些数据我是从GitHub PR记录和Claude Code的历史会话中统计出来的：

• 上周合并的8个PR中，平均评审轮次为4.1轮
• 最长的一个PR来回了7轮评审
• 有3个PR的评审意见中，出现了“所以这段到底要不要改”之类的追问

不需要任何说服，数据摆在那里就是痛点。当Tech Lead看到“平均4.1轮评审才能合并一个PR”这个数字时，他自己先开口了：“我们是不是能优化一下评审流程？”

这时候我才顺水推舟地提出：我有一套在Claude Code里用的评审标注格式，目前自己用了两周了，感觉评审效率有提升，要不我们先找两个PR试试？

从“听我说这个规范多好”到“我们一起看看怎么解决评审效率问题”，这是完全不同的两件事。前者的阻力在“你要改变我”，后者的动力在“我要解决问题”。

五.2 第二阶段：双轨运行，用对比说话（第3-6周）

和团队达成初步意向后，我没有一步到位要求全员切换。而是采用双轨运行：

• 新标注协议：由我和另一个认可度最高的同事先行试用，每用完一次就在PR评论中标注“本次使用了结构化评审标注”
• 传统评审：其他同事仍按原有习惯

运行了两周后，我在周会上放了第二组数据：

数据直接说明了问题。更重要的是：采用新协议的PR中，没有一个出现过“所以这段到底要不要改”这类沟通问题。因为标注协议中声明的输出格式，已经将歧义降到了最低。

到这个阶段，不用我再推，其他同事开始主动问：“你那个标注模板能发我一份吗？”

五.3 第三阶段：固化为工具，不做文档做脚本（第7-12周）

当团队认可了协议的价值后，进入最关键也最容易翻车的阶段，长期维护。

我的经验是：规范如果是文档形式，它的命运就是被遗忘。规范如果是工具形式，它就能活下来。

我做了两个工具化的动作：

第一个：创建skeleton.txt模板文件

把所有标注声明做成一个骨架文件，放在项目根目录下：

===Claude Code评审标注模板===
[评审维度]

包含：{根据场景选择}

排除：{根据场景选择}

[优先级标准]

P0-阻断: {定义}

P1-重要: {定义}

P2-建议: {定义}

[输出格式]

标签：[P等级] [#标签]

位置：{文件}:{行号}

问题：{一句话}

原因：{解释}

建议：

{可执行代码}

论证：{说明}

[评审上下文]

模块：{模块名}

关联PR：{PR编号}

上下文文件版本：{版本号，检查docs/CR_CONTEXT.md}

====================================

每次评审时，复制这个文件到Claude Code，填充{}占位符的内容即可。关键是让填模板的成本远低于自己从头写标注的成本。

第二个：在CI中加入评审上下文文件版本检查

这个比较进阶，但非常有效。我在GitHub Actions中加入了一个小检查：

- name: Check CR_CONTEXT.md freshness
run: |

LAST_MODIFIED=$(git log -1 --format=%ct docs/CR_CONTEXT.md)

NOW=$(date +%s)

DAYS_SINCE=$(( (NOW - LAST_MODIFIED) / 86400 ))

if [ $DAYS_SINCE -gt 30 ]; then

echo "⚠️ CR_CONTEXT.md已超过30天未更新，评审上下文可能过时"

exit 1

fi

这确保了评审上下文文件不会被遗忘，MR超过30天不更新上下文，CI就会警告。

六、不同场景下的标注策略取舍

标注协议不是一成不变的。在不同的项目类型、团队规模和技术栈下，你需要灵活调整标注策略。下面是我在实践中遇到的三类典型场景，以及对应的取舍逻辑。

六.1 场景一：初创项目快速迭代期，牺牲全面性，换取速度

如果你的项目处于0到1的阶段，每周要交付两到三个需求，评审流程不能拖慢开发速度。但同时又不能完全不做评审，项目早期的技术债会以复利方式增长。

这个场景下我的标注策略是：极度压缩评审维度，只保留P0/P1，放弃P2/P3。

实际标注长这样：

[评审维度]
包含：业务逻辑正确性，并发安全

排除：代码结构，性能（除非明显N+1），命名，注释，测试覆盖，设计模式

[优先级标准]

P0-阻断: 业务逻辑错误，数据问题

P1-重要: 并发安全，空指针风险

[输出格式]

标签：[P等级]

问题：{一句话}

建议：{一句话 + 关键代码}

要求：每条评审意见不超过3行，优先用伪代码表达建议

你会发现这个版本删掉了大量内容，没有详细的“原因”字段，没有“论证”字段，甚至去掉了完整的代码示例。这是有意为之：对于快速迭代的项目，评审的价值在于快速暴露致命问题，而不是给出重构教案。

我在一个早期项目中用过这个策略，平均每个PR的评审耗时从40分钟压缩到15分钟，而P0问题检出率几乎没有下降。

六.2 场景二：金融/支付类项目，大幅扩展安全相关声明

在金融场景下，评审标注的侧重点完全不同。我会在标注中追加一个独立的安全声明模块：

[安全审查细则]（高风险模块专用）

金额计算：所有货币相关的加减乘除，必须使用BigDecimal（禁止float/double）

SQL注入：所有动态拼接SQL必须改用参数化查询

并发锁：涉及账户余额变更的操作，必须显式声明锁策略

幂等性：所有支付/扣款接口，必须显式说明幂等机制

日志泄露：日志中禁止输出银行卡号、CVV、密码明文

精度问题：BigDecimal除法时必须指定RoundingMode

请在评审时逐一核对上述安全细则，P0/P1问题请在评审总结中显式列出。

这个模块的每个条目背后，都是一次生产事故。“日志中禁止输出银行卡号”这条，是因为我们曾经在日志中打出了完整的用户卡号，幸好被安全团队在日志审计中发现，否则后果不堪设想。

在金融项目中，评审标注的完整性比评审速度重要得多。我宁愿一个PR多等两小时评审，也不愿意一个精度问题在三个月后造成资金差错。

六.3 场景三：跨团队协作的开源项目，增加兼容性约束

开源项目或跨团队协作环境下，评审标注需要额外考虑一个问题：不是所有人都在用Claude Code。可能评审者用的是Copilot，或者干脆就是人工评审。

这时我的标注策略会追加一个兼容性声明：

[兼容性声明]
以下标注指令面向AI评审代理（Claude Code）。人工评审者请忽略指令语法，直接参考[维度]和[优先级]下的内容判断标准。

[人工评审指引]

本次评审关注维度：业务逻辑正确性，并发安全

评审标准：请参照项目CONTRIBUTING.md中的“Code Review Guidelines”

如果你对某处逻辑有疑问，请在评论中明确标注“QUESTION”而非直接要求修改

这个小小的声明解决了一个大问题：避免了人工评审者看到“结构化标注指令”时产生的困惑，“这是在跟我说话还是在跟AI说话？”。

七、我仍在探索的三个未解问题

讲完了成功的经验，我也要诚实地告诉你，这套标注协议依然有几个我正在探索但还没有最优解的问题。

七.1 长上下文导致的标注膨胀

当一个PR涉及15个以上文件、200行以上变更时，光是写完标注的四个声明部分（维度、优先级、格式、上下文），就需要我手动录入大量信息。特别是上下文部分，要准确地告诉AI每个文件的作用、彼此之间的调用关系，这些信息如果纯靠手写，标注本身的工作量就快赶上自己评审了。

我现在的妥协方案是：大PR只写粗粒度的维度声明，然后逐文件或逐模块分次评审。但这样又损失了跨文件逻辑推理的准确性。这可能需要在工程工具层面解决，比如让Claude Code自动索引项目结构后，标注时只需引用索引路径。

七.2 同一段代码被不同评审者标注产生的分歧

当团队有多个开发者同时使用这套标注协议后，我发现了一个新问题：不同人对同一段代码可能给出不同的维度声明。比如上文的签到代码，有人会标注“请评审业务逻辑”，有人会标注“请评审并发安全”，这导致Claude Code产出的评审意见方向和深度完全不同。

这实际上是一个元问题：谁来评审“评审标注”的质量？ 目前我们团队的做法是Tech Lead定期抽查标注质量，但这显然不可规模化。我判断未来可能需要一套元标注标准，或者由Claude Code在评审前先对标注本身进行合理性检查。

七.3 AI幻觉在关键评审意见中的风险

即使有了精确的标注协议，Claude Code仍然偶尔会出现幻觉，指出一段代码中存在一个根本不存在的问题，或者给出的代码示例根本不能编译。

在P2/P3级别的建议中出现幻觉，影响不大。但在P0级别的安全评审中，如果AI断言某处有SQL注入风险而实际上没有，这会导致开发者浪费时间去排查一个不存在的问题；更危险的是反过来，AI漏报了一个真实存在的安全问题。

目前我的做法是：标注中加入“高危判定须提供具体证据”的指令。对于AI标注为P0的问题，要求它必须引用具体的代码行、说明攻击向量，而对于没有提供具体证据的P0意见，由人工二次确认后再决定是否修复。

这条经验还远谈不上成熟，但它是一个必须正视的方向，随着AI更多地参与关键系统的评审，标注协议中必须包含对AI自身输出的可信度约束。

八、总结：从“写标注”到“定义评审语言”

回到文章开头的那个场景：同事留下的17条评审意见让我愣了一上午。这个经历让我意识到，标注不是技术问题，是语言问题。

在没有统一标注协议之前，每个开发者在Claude Code里和AI说话的方式千差万别。有人把它当搜索引擎，有人把它当同事聊天，还有人像在写微博吐槽。这导致AI产出的评审意见也千差万别，有些能用，有些是在浪费阅读时间。

标注协议的真正价值，不是提高了AI的能力，而是在团队和AI之间建立了一套“评审领域的领域特定语言（DSL）”。这套DSL一旦建立，评审就不再是“我请AI帮忙看代码”这个模糊行为，而是一个有明确输入规范、输出格式、质量标准的工程流程。

如果你现在就想在自己的项目里开始用这套方法，我的建议是：

第一周什么都不用做，只做统计。统计你团队当前的评审轮次、P0问题的漏检率、评审意见被忽略的比例。数据有了，推行才有根基。

第二周从最简协议开始。不需要上来就按我的完整模板走。你只做一件事：在任何评审标注前，加上一句维度声明，“本次评审请只关注{X}，不要关注{Y}”。就这么简单的一行字，效果你试了就知道了。

第三周引入优先级标签。让AI给每个评审意见标上[P0]到[P3]。然后观察，你的团队平均评审时长有没有缩短，因为大家知道先看哪些、后看哪些。

一个月后固化模板。把你在这三周里验证有效的标注格式写成骨架文件，放在项目根目录。然后告诉团队：以后评审复制这个文件填充。

这不是一场“要不要用AI评审”的讨论。AI已经在评审里了，问题是：你们团队和AI说的，是不是同一种语言？