我做架构评审这些年见过太多“名义上用了设计模式、实际上只是抄了个类图”的代码。设计模式这东西真正的难点从来不是背角色和类图而是没法快速验证“你用的到底是不是你声称的那个模式”。后来我开始用 Claude Code 当评审助理把设计模式验证变成了一次可对话、可存档的工程活动比光靠人眼扫代码靠谱得多。这篇就从架构师视角讲清楚我怎么用 Claude Code 验证设计模式、验证什么、环境怎么搭、提问方法是什么再带两个实战案例和一批我踩过的坑。适合正在做架构评审的技术负责人也适合正在写设计模式大作业、想证明自己方案合理性的同学。1. 为什么架构师需要“验证”设计模式1.1 设计模式验证不是背诵模式定义很多人理解设计模式停留在“背出 23 种模式的类图和角色”这个层面。但架构师在评审代码时要做的完全不是这件事。你要回答的是三个更尖锐的问题这个实现的结构是不是符合模式定义它的行为流转是不是符合模式意图它在当前场景下引入是不是真的划算举个例子有个人跟我说他用了策略模式结果我打开代码一看一个巨型 switch-case 把几十种算法全塞在同一个方法里。名义上是策略模式实质上只是给分支代码换了个名字。这种“名义模式”现象特别常见尤其在赶工期的时候。靠人肉评审你要一行行读分支、理依赖、画调用链效率很低而 Claude Code 可以在几秒内按你指定的评审清单扫完代码把可疑点全部列出来。所以我把验证拆成四层结构层、行为层、语义层、演进层。结构层看类和接口关系行为层看状态与调用时序语义层看是否符合模式背后的设计意图演进层看将来需求变化时这个模式会不会变成负担。这四层里前两层适合让 Claude Code 做第一轮筛选后两层更适合用它来和你做交互式讨论。1.2 人工评审的盲区恰好是工具的价值点人工评审设计模式最大的几个盲区一是慢二是依赖个人经验三是容易漏掉跨文件的隐性关联。比如状态机模式状态和事件分散在好几个文件里人眼很难逐个核对有没有漏掉某个非法迁移但 Claude Code 能一次性把全部状态、事件、迁移规则读进来做枚举式核对这个能力天然适合验证。另一个痛点是不可回溯。人评审完结论写在文档里过两个月想查当时为什么这么判断文档往往只有结论没有推理过程。Claude Code 的对话记录可以完整保留每次验证的输入、输出、追问过程都在相当于把评审变成了一次可审计的工程事件。当然要说清楚一点Claude Code 不是替代架构师做决定而是帮架构师把模糊的设计直觉变成具体的、可讨论的问题清单。它是副驾驶不是自动驾驶。2. 搭建一个可用的 Claude Code 验证环境2.1 三种接入方式怎么选Claude Code 现在有几种常见形态原生 CLI、VS Code 插件、桌面版。我在不同场景下都用过简单说下我的选择逻辑。CLI 是最核心的形态也是我主力使用的。安装很简单只要机器上有 Node.js 18 以上版本执行npm install -g anthropic-ai/claude-code装完在项目目录运行claude按提示登录授权就能进入交互式会话。CLI 适合跑批处理、脚本化验证、和 CI 集成比如我把评审 prompt 写好后直接claude -p 评审这个目录下的订单模块就能拿到结果不用开一个完整交互界面。VS Code 插件适合边看代码边提问。装好插件后在侧边栏可以直接打开 Claude Code 面板选中代码片段就能带着上下文提问。我的习惯是CLI 跑整体评审VS Code 插件做单文件深挖和局部追问。桌面版是近期出的本质上是把 CLI 包了一层可视化壳界面更友好也方便看文件结构。如果你的机器上不方便用终端或者团队里有不熟悉命令行的同学桌面版可以降低使用门槛。但我的感受是现阶段 CLI 的功能完整度和脚本化能力仍然最强我建议主力还是用 CLI。2.2 模型接入与常见兼容性问题默认情况下Claude Code 走 Anthropic 官方模型登录订阅账号就能用。但社区里很多人都想接第三方模型比如 DeepSeek这时候通常会借助 CC Switch 这类工具来做运行商切换。它的本质很简单修改 Claude Code 的环境变量把 API base 和 key 指向第三方服务同时把模型名替换成目标模型。这里我必须要提一个高频报错因为它在社区里被问烂了deepseek-v4-pro is not a model this version of claude code recognizes这个报错的意思很直白你配置的模型名当前这个版本的 Claude Code 不认识。原因通常有两个。一是版本不匹配Claude Code 升级后模型列表变了或者第三方模型名本身是社区自定义的没同步到当前版本二是配置格式不对比如大小写、连接符写错了。我的排查顺序是先用 CC Switch 查看当前配置的模型名确认是否和 provider 提供的一致再检查 Claude Code 版本执行claude --version如果版本过旧或过新考虑升级或降级到和 CC Switch 兼容的版本。另一个常见配置是用环境变量直接指定export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_BASE_URLhttps://api.deepseek.com设置完后在 Claude Code 里输入/status能看到当前生效的模型和 API 地址确认无误再开始评审。2.3 用 CLAUDE.md 和自定义 Skill 固化评审流程我用的比较顺手的一个做法是把评审流程固化成 Skill而不是每次都重新写一遍 prompt。Claude Code 支持自定义 Skill本质上是在~/.claude/skills/下建一个目录里面放一个SKILL.md文件通过 front matter 声明 skill 的 name 和 description然后在正文里写具体指令。我的设计评审 skill 结构大概是这样的~/.claude/skills/design-review/SKILL.mdSKILL.md 内容里会写明这个 skill 用于设计模式验证要求 Claude Code 扮演架构评审委员会成员按四个维度评审输出格式必须包含问题级别、证据位置、修改建议。一旦写好后每次只要说“用 design-review 看看某个模式”Claude Code 就会自动加载这套评审流程不会漏维度。项目级的约定则写在CLAUDE.md里。这个文件放在项目根目录Claude Code 启动时会自动读取。我会在里面写项目的技术栈、关键目录结构、代码规范、以及希望 Claude Code 默认使用中文回复。这样即使换了机器、换了人团队的验证口径也是一致的。3. 验证方法论怎么让 Claude Code 给出有效结论3.1 角色设定与上下文准备很多人在用 Claude Code 做验证时觉得输出“太水”其实问题往往出在上下文没给够。你直接问“这个状态机写得好不好”它只能给你一套万金油回答。我的做法是给它一个完整的三件套背景。第一角色设定。明确告诉它“你是一名架构评审委员会成员负责对设计实现做代码评审重点看设计模式是否被正确运用”。角色设定不是形式主义它决定了 Claude Code 后续回答的立场和深度。第二模式定义。把你要验证的模式定义直接贴给它或者要求它按经典定义来对照。因为设计模式在不同语境下理解有偏差明确标准才能让结论可对齐。第三约束与场景。告诉它这个代码所在的业务场景、关键约束、未来可能的演进方向。比如“这个模块预计三个月后要接入新的支付渠道”它就能在验证时把可扩展性纳入考量而不是只盯着当前代码。我通常会把这三部分打包成一段 prompt放在整个对话的最前面。后续再贴代码或者问具体问题Claude Code 都会基于这段上下文来回答。3.2 输出格式控制与提问模板控制输出格式是让验证结果真正可用的关键。不给格式它会给你一大段散文式的分析看起来很专业但没法直接落地到评审报告里。我的输出格式要求是结构化问题清单每条必须包含问题级别、问题描述、证据位置、修改建议。下面这个模板我一直在用直接抄走就行请以架构评审委员会成员的身份审查以下代码。审查重点是验证是否真正实现了[模式名称]模式。 请按以下格式输出 1. 问题列表按严重级别排序严重/一般/建议 - 问题级别 - 问题描述 - 证据位置文件名行号 - 修改建议 2. 模式匹配度总结说明该实现与标准模式的符合程度 3. 潜在风险包括过度设计、隐藏耦合、未来演进阻塞 约束条件 - [写你的业务约束] - 只基于你看到的事实不要推测不存在的代码。这个模板跑下来拿到的结果基本上可以直接贴进评审记录。核心思路是让 Claude Code 变成“带格式的检查员”而不是“写作文的分析师”。3.3 对抗式验证主动找反例常规验证只能告诉我们“代码是否符合模式定义”但架构师真正关心的是“这个模式到底该不该用在这里”。这需要对抗式验证。我的做法是主动让 Claude Code 找反例和找过度设计。比如我会追加这样的追问假如三个月后新需求要支持部分退款这个状态机模式还成立吗当前这个实现里有没有哪个状态是永远无法到达的这个策略模式是不是杀鸡用牛刀三个分支根本不需要抽象这些追问本身就是架构评审的核心能力。Claude Code 虽然不会替你做判断但它的上下文处理能力能帮你把潜在风险点全部翻出来。我经常在这种追问里发现隐藏的坑比如一个看起来完美的工厂模式实际上因为参数膨胀导致调用方已经看不懂了这就是典型的过度设计信号。4. 实战用 Claude Code 验证两种典型模式4.1 状态机模式验证状态流转的完备性状态机模式是我认为最适合用 Claude Code 验证的模式因为状态、事件、迁移规则是有限集合可以枚举核对。这种“可枚举”特征让 Claude Code 的错误检查能力发挥到极致。我拿一个订单状态机举例。假设代码里有这样的定义type OrderState pending | paid | shipped | completed | cancelled; const transitions { pending: [paid, cancelled], paid: [shipped, cancelled], shipped: [completed], completed: [], cancelled: [], };我会直接让 Claude Code 审查这个状态机重点看几个维度所有状态是否可达、是否有状态永远无法进入、非法迁移是否都被拦截、取消操作是否在所有阶段都被正确处理。Claude Code 的输出会按级别组织比如它可能指出shipped 状态不能取消如果用户退款只能到 completed 之后这是业务规则还是遗漏cancelled 状态没有任何出边如果业务上有“取消后重新支付”的需求这个状态机就要重构。这些问题在人工评审时往往要花很多时间才能想到。还有一类隐藏问题是重复处理。比如订单支付成功回调触发了两次状态机在 paid 状态收到 pay 事件应该怎么处理如果直接忽略那对账怎么办如果抛异常那幂等怎么做。Claude Code 能顺着事件处理逻辑把这类边界情况列出来你再拿去问业务方效率会高很多。4.2 主从模式与多 Agent 架构subagent 本质上是另一种 tool 调用最近在设计多 Agent 系统时我特别想聊一个最新趋势多 Agent 设计里的主从模式。它的核心洞察在于主 Agent 通过 task 工具把子任务委托给 subagent本质上就是把 subagent 当成一种特殊的 tool 来调用。这个洞察非常有价值因为它把多 Agent 系统拉回到了一个我们非常熟悉的设计模式语境里组合模式和委派模式。从架构师视角看这和“主对象持有工具对象、按需调用”没有本质区别。subagent 的输入是任务描述输出是结果文本中间过程对主 Agent 来说是个黑盒。所以验证这种“主从模式”是否设计合理时我关注的问题和验证一个普通工具层很像subagent 是否真正解耦替换一个 subagent 实现是否影响主 Agentsubagent 的失败是否能被主 Agent 有效捕获并降级subagent 的上下文是否污染主 Agent 的状态并发调用 subagent 时的资源控制和结果聚合是否完备。我会让 Claude Code 用审查工具抽象的眼光去审查我的多 Agent 编排逻辑。比如我会这样问审查当前的多 Agent 编排。主 Agent 将代码审查任务委托给三个 subagent静态分析、依赖分析、测试建议。请用架构师视角分析 1. 这种主从模式是否真正解耦了子任务 2. 如果其中一个 subagent 不可用主 Agent 的行为是什么 3. subagent 返回的结果是否被正确聚合和去重 4. 是否存在上下文污染subagent 的中间思考是否泄漏到最终输出 5. 这个设计本质上等价于把 subagent 当作 tool 调用这个抽象边界是否清晰这套问题跑下来Claude Code 会帮你把多 Agent 系统的设计缺陷暴露得很彻底。我那次评审就发现某个 subagent 的返回结果里混入了大段无效推理而聚合逻辑没有做过滤导致最终报告质量被拉低。这种问题靠人工读日志也能发现但 Claude Code 能直接定位到聚合逻辑的具体实现位置省了大量排查时间。5. 常见问题与排查技巧实录5.1 高频报错速查表用 Claude Code 做验证遇到报错是很正常的。我从热词里挑了几个被问爆的问题整理成速查表方便你直接对号入座。报错信息常见原因处理方法xxx model is not a model this version of claude code recognizes模型名配置错误或版本不匹配用 /status 查当前生效模型核对模型名和 API 地址必要时升级或降级 Claude Code 版本529 错误API 过载或限流稍后重试降低请求频率检查并发数设置your organization has disabled claude subscription access企业团队订阅策略限制联系组织管理员开启访问权限或改用个人授权连接超时或无响应网络问题或代理配置异常检查网络稳定性确认环境变量是否有冲突中文回答不稳定系统提示词或 CLAUDE.md 未设置语言偏好在 CLAUDE.md 里明确写“始终使用中文回答”这里我想重点讲一下 529 的处理。这个错误本质是服务端过载不是你代码的问题。很多人遇到后立刻重试反而更容易被限流。我的做法是如果单次评审任务很大先拆成几个小任务分步跑避免一次性塞进太多代码同时把对话的并发请求数调低避免多个任务同时触发。这样 529 的出现概率会明显下降。5.2 输出质量如何把控Claude Code 在代码评审时最大的风险是幻觉。它可能编造一个不存在的类名或者引用一个根本不对应的行号。如果你不核对就采纳评审意见就会失去可信度。我的应对办法是第一轮要求 Claude Code 的所有结论必须带有证据位置只接受“文件行号代码片段”的表述第二轮把它的结论和真实代码核对一遍重点验证行号和类名是否真实存在。这个过程花不了多少时间但能极大提升结论的可靠性。另一个常见问题是输出过于泛化。比如它说“这个类职责过重建议拆分”但没说是哪个方法导致的职责过重。这时候我会追加约束不允许给笼统建议每一条结论必须对应到具体函数或代码行。语气上可以直接一点比如“如果没有具体证据就标记为存疑不要输出模糊建议”。几次迭代之后输出质量会有明显提升。还有一个技巧是让 Claude Code 自己生成验证用例。比如在验证状态机时我让它列举所有可能的非法迁移然后让它可以试着生成测试用例来描述这些非法迁移。这样就把验证从“找问题”升级成了“补防护”评审的价值又高了一层。设计模式验证这件事我现在的态度很明确它不是让 Claude Code 给你盖一个“设计正确”的章而是让它帮你把说不清的设计直觉变成一条条有证据、有级别的具体问题。你在实际验证里也会发现最有价值的不是它直接给出的答案而是你顺着它的追问重新审视自己设计的过程。我的建议是第一次尝试从状态机这种可枚举的模式入手把验证结果存档和团队过一轮跑通一次完整流程之后再扩展到工厂、策略、观察者这些更依赖语义判断的模式。到那个时候你就会习惯这个“评审副驾驶”的存在了。 用Claude Code验证设计模式：架构师评审实战指南
我做架构评审这些年见过太多“名义上用了设计模式、实际上只是抄了个类图”的代码。设计模式这东西真正的难点从来不是背角色和类图而是没法快速验证“你用的到底是不是你声称的那个模式”。后来我开始用 Claude Code 当评审助理把设计模式验证变成了一次可对话、可存档的工程活动比光靠人眼扫代码靠谱得多。这篇就从架构师视角讲清楚我怎么用 Claude Code 验证设计模式、验证什么、环境怎么搭、提问方法是什么再带两个实战案例和一批我踩过的坑。适合正在做架构评审的技术负责人也适合正在写设计模式大作业、想证明自己方案合理性的同学。1. 为什么架构师需要“验证”设计模式1.1 设计模式验证不是背诵模式定义很多人理解设计模式停留在“背出 23 种模式的类图和角色”这个层面。但架构师在评审代码时要做的完全不是这件事。你要回答的是三个更尖锐的问题这个实现的结构是不是符合模式定义它的行为流转是不是符合模式意图它在当前场景下引入是不是真的划算举个例子有个人跟我说他用了策略模式结果我打开代码一看一个巨型 switch-case 把几十种算法全塞在同一个方法里。名义上是策略模式实质上只是给分支代码换了个名字。这种“名义模式”现象特别常见尤其在赶工期的时候。靠人肉评审你要一行行读分支、理依赖、画调用链效率很低而 Claude Code 可以在几秒内按你指定的评审清单扫完代码把可疑点全部列出来。所以我把验证拆成四层结构层、行为层、语义层、演进层。结构层看类和接口关系行为层看状态与调用时序语义层看是否符合模式背后的设计意图演进层看将来需求变化时这个模式会不会变成负担。这四层里前两层适合让 Claude Code 做第一轮筛选后两层更适合用它来和你做交互式讨论。1.2 人工评审的盲区恰好是工具的价值点人工评审设计模式最大的几个盲区一是慢二是依赖个人经验三是容易漏掉跨文件的隐性关联。比如状态机模式状态和事件分散在好几个文件里人眼很难逐个核对有没有漏掉某个非法迁移但 Claude Code 能一次性把全部状态、事件、迁移规则读进来做枚举式核对这个能力天然适合验证。另一个痛点是不可回溯。人评审完结论写在文档里过两个月想查当时为什么这么判断文档往往只有结论没有推理过程。Claude Code 的对话记录可以完整保留每次验证的输入、输出、追问过程都在相当于把评审变成了一次可审计的工程事件。当然要说清楚一点Claude Code 不是替代架构师做决定而是帮架构师把模糊的设计直觉变成具体的、可讨论的问题清单。它是副驾驶不是自动驾驶。2. 搭建一个可用的 Claude Code 验证环境2.1 三种接入方式怎么选Claude Code 现在有几种常见形态原生 CLI、VS Code 插件、桌面版。我在不同场景下都用过简单说下我的选择逻辑。CLI 是最核心的形态也是我主力使用的。安装很简单只要机器上有 Node.js 18 以上版本执行npm install -g anthropic-ai/claude-code装完在项目目录运行claude按提示登录授权就能进入交互式会话。CLI 适合跑批处理、脚本化验证、和 CI 集成比如我把评审 prompt 写好后直接claude -p 评审这个目录下的订单模块就能拿到结果不用开一个完整交互界面。VS Code 插件适合边看代码边提问。装好插件后在侧边栏可以直接打开 Claude Code 面板选中代码片段就能带着上下文提问。我的习惯是CLI 跑整体评审VS Code 插件做单文件深挖和局部追问。桌面版是近期出的本质上是把 CLI 包了一层可视化壳界面更友好也方便看文件结构。如果你的机器上不方便用终端或者团队里有不熟悉命令行的同学桌面版可以降低使用门槛。但我的感受是现阶段 CLI 的功能完整度和脚本化能力仍然最强我建议主力还是用 CLI。2.2 模型接入与常见兼容性问题默认情况下Claude Code 走 Anthropic 官方模型登录订阅账号就能用。但社区里很多人都想接第三方模型比如 DeepSeek这时候通常会借助 CC Switch 这类工具来做运行商切换。它的本质很简单修改 Claude Code 的环境变量把 API base 和 key 指向第三方服务同时把模型名替换成目标模型。这里我必须要提一个高频报错因为它在社区里被问烂了deepseek-v4-pro is not a model this version of claude code recognizes这个报错的意思很直白你配置的模型名当前这个版本的 Claude Code 不认识。原因通常有两个。一是版本不匹配Claude Code 升级后模型列表变了或者第三方模型名本身是社区自定义的没同步到当前版本二是配置格式不对比如大小写、连接符写错了。我的排查顺序是先用 CC Switch 查看当前配置的模型名确认是否和 provider 提供的一致再检查 Claude Code 版本执行claude --version如果版本过旧或过新考虑升级或降级到和 CC Switch 兼容的版本。另一个常见配置是用环境变量直接指定export ANTHROPIC_MODELdeepseek-chat export ANTHROPIC_BASE_URLhttps://api.deepseek.com设置完后在 Claude Code 里输入/status能看到当前生效的模型和 API 地址确认无误再开始评审。2.3 用 CLAUDE.md 和自定义 Skill 固化评审流程我用的比较顺手的一个做法是把评审流程固化成 Skill而不是每次都重新写一遍 prompt。Claude Code 支持自定义 Skill本质上是在~/.claude/skills/下建一个目录里面放一个SKILL.md文件通过 front matter 声明 skill 的 name 和 description然后在正文里写具体指令。我的设计评审 skill 结构大概是这样的~/.claude/skills/design-review/SKILL.mdSKILL.md 内容里会写明这个 skill 用于设计模式验证要求 Claude Code 扮演架构评审委员会成员按四个维度评审输出格式必须包含问题级别、证据位置、修改建议。一旦写好后每次只要说“用 design-review 看看某个模式”Claude Code 就会自动加载这套评审流程不会漏维度。项目级的约定则写在CLAUDE.md里。这个文件放在项目根目录Claude Code 启动时会自动读取。我会在里面写项目的技术栈、关键目录结构、代码规范、以及希望 Claude Code 默认使用中文回复。这样即使换了机器、换了人团队的验证口径也是一致的。3. 验证方法论怎么让 Claude Code 给出有效结论3.1 角色设定与上下文准备很多人在用 Claude Code 做验证时觉得输出“太水”其实问题往往出在上下文没给够。你直接问“这个状态机写得好不好”它只能给你一套万金油回答。我的做法是给它一个完整的三件套背景。第一角色设定。明确告诉它“你是一名架构评审委员会成员负责对设计实现做代码评审重点看设计模式是否被正确运用”。角色设定不是形式主义它决定了 Claude Code 后续回答的立场和深度。第二模式定义。把你要验证的模式定义直接贴给它或者要求它按经典定义来对照。因为设计模式在不同语境下理解有偏差明确标准才能让结论可对齐。第三约束与场景。告诉它这个代码所在的业务场景、关键约束、未来可能的演进方向。比如“这个模块预计三个月后要接入新的支付渠道”它就能在验证时把可扩展性纳入考量而不是只盯着当前代码。我通常会把这三部分打包成一段 prompt放在整个对话的最前面。后续再贴代码或者问具体问题Claude Code 都会基于这段上下文来回答。3.2 输出格式控制与提问模板控制输出格式是让验证结果真正可用的关键。不给格式它会给你一大段散文式的分析看起来很专业但没法直接落地到评审报告里。我的输出格式要求是结构化问题清单每条必须包含问题级别、问题描述、证据位置、修改建议。下面这个模板我一直在用直接抄走就行请以架构评审委员会成员的身份审查以下代码。审查重点是验证是否真正实现了[模式名称]模式。 请按以下格式输出 1. 问题列表按严重级别排序严重/一般/建议 - 问题级别 - 问题描述 - 证据位置文件名行号 - 修改建议 2. 模式匹配度总结说明该实现与标准模式的符合程度 3. 潜在风险包括过度设计、隐藏耦合、未来演进阻塞 约束条件 - [写你的业务约束] - 只基于你看到的事实不要推测不存在的代码。这个模板跑下来拿到的结果基本上可以直接贴进评审记录。核心思路是让 Claude Code 变成“带格式的检查员”而不是“写作文的分析师”。3.3 对抗式验证主动找反例常规验证只能告诉我们“代码是否符合模式定义”但架构师真正关心的是“这个模式到底该不该用在这里”。这需要对抗式验证。我的做法是主动让 Claude Code 找反例和找过度设计。比如我会追加这样的追问假如三个月后新需求要支持部分退款这个状态机模式还成立吗当前这个实现里有没有哪个状态是永远无法到达的这个策略模式是不是杀鸡用牛刀三个分支根本不需要抽象这些追问本身就是架构评审的核心能力。Claude Code 虽然不会替你做判断但它的上下文处理能力能帮你把潜在风险点全部翻出来。我经常在这种追问里发现隐藏的坑比如一个看起来完美的工厂模式实际上因为参数膨胀导致调用方已经看不懂了这就是典型的过度设计信号。4. 实战用 Claude Code 验证两种典型模式4.1 状态机模式验证状态流转的完备性状态机模式是我认为最适合用 Claude Code 验证的模式因为状态、事件、迁移规则是有限集合可以枚举核对。这种“可枚举”特征让 Claude Code 的错误检查能力发挥到极致。我拿一个订单状态机举例。假设代码里有这样的定义type OrderState pending | paid | shipped | completed | cancelled; const transitions { pending: [paid, cancelled], paid: [shipped, cancelled], shipped: [completed], completed: [], cancelled: [], };我会直接让 Claude Code 审查这个状态机重点看几个维度所有状态是否可达、是否有状态永远无法进入、非法迁移是否都被拦截、取消操作是否在所有阶段都被正确处理。Claude Code 的输出会按级别组织比如它可能指出shipped 状态不能取消如果用户退款只能到 completed 之后这是业务规则还是遗漏cancelled 状态没有任何出边如果业务上有“取消后重新支付”的需求这个状态机就要重构。这些问题在人工评审时往往要花很多时间才能想到。还有一类隐藏问题是重复处理。比如订单支付成功回调触发了两次状态机在 paid 状态收到 pay 事件应该怎么处理如果直接忽略那对账怎么办如果抛异常那幂等怎么做。Claude Code 能顺着事件处理逻辑把这类边界情况列出来你再拿去问业务方效率会高很多。4.2 主从模式与多 Agent 架构subagent 本质上是另一种 tool 调用最近在设计多 Agent 系统时我特别想聊一个最新趋势多 Agent 设计里的主从模式。它的核心洞察在于主 Agent 通过 task 工具把子任务委托给 subagent本质上就是把 subagent 当成一种特殊的 tool 来调用。这个洞察非常有价值因为它把多 Agent 系统拉回到了一个我们非常熟悉的设计模式语境里组合模式和委派模式。从架构师视角看这和“主对象持有工具对象、按需调用”没有本质区别。subagent 的输入是任务描述输出是结果文本中间过程对主 Agent 来说是个黑盒。所以验证这种“主从模式”是否设计合理时我关注的问题和验证一个普通工具层很像subagent 是否真正解耦替换一个 subagent 实现是否影响主 Agentsubagent 的失败是否能被主 Agent 有效捕获并降级subagent 的上下文是否污染主 Agent 的状态并发调用 subagent 时的资源控制和结果聚合是否完备。我会让 Claude Code 用审查工具抽象的眼光去审查我的多 Agent 编排逻辑。比如我会这样问审查当前的多 Agent 编排。主 Agent 将代码审查任务委托给三个 subagent静态分析、依赖分析、测试建议。请用架构师视角分析 1. 这种主从模式是否真正解耦了子任务 2. 如果其中一个 subagent 不可用主 Agent 的行为是什么 3. subagent 返回的结果是否被正确聚合和去重 4. 是否存在上下文污染subagent 的中间思考是否泄漏到最终输出 5. 这个设计本质上等价于把 subagent 当作 tool 调用这个抽象边界是否清晰这套问题跑下来Claude Code 会帮你把多 Agent 系统的设计缺陷暴露得很彻底。我那次评审就发现某个 subagent 的返回结果里混入了大段无效推理而聚合逻辑没有做过滤导致最终报告质量被拉低。这种问题靠人工读日志也能发现但 Claude Code 能直接定位到聚合逻辑的具体实现位置省了大量排查时间。5. 常见问题与排查技巧实录5.1 高频报错速查表用 Claude Code 做验证遇到报错是很正常的。我从热词里挑了几个被问爆的问题整理成速查表方便你直接对号入座。报错信息常见原因处理方法xxx model is not a model this version of claude code recognizes模型名配置错误或版本不匹配用 /status 查当前生效模型核对模型名和 API 地址必要时升级或降级 Claude Code 版本529 错误API 过载或限流稍后重试降低请求频率检查并发数设置your organization has disabled claude subscription access企业团队订阅策略限制联系组织管理员开启访问权限或改用个人授权连接超时或无响应网络问题或代理配置异常检查网络稳定性确认环境变量是否有冲突中文回答不稳定系统提示词或 CLAUDE.md 未设置语言偏好在 CLAUDE.md 里明确写“始终使用中文回答”这里我想重点讲一下 529 的处理。这个错误本质是服务端过载不是你代码的问题。很多人遇到后立刻重试反而更容易被限流。我的做法是如果单次评审任务很大先拆成几个小任务分步跑避免一次性塞进太多代码同时把对话的并发请求数调低避免多个任务同时触发。这样 529 的出现概率会明显下降。5.2 输出质量如何把控Claude Code 在代码评审时最大的风险是幻觉。它可能编造一个不存在的类名或者引用一个根本不对应的行号。如果你不核对就采纳评审意见就会失去可信度。我的应对办法是第一轮要求 Claude Code 的所有结论必须带有证据位置只接受“文件行号代码片段”的表述第二轮把它的结论和真实代码核对一遍重点验证行号和类名是否真实存在。这个过程花不了多少时间但能极大提升结论的可靠性。另一个常见问题是输出过于泛化。比如它说“这个类职责过重建议拆分”但没说是哪个方法导致的职责过重。这时候我会追加约束不允许给笼统建议每一条结论必须对应到具体函数或代码行。语气上可以直接一点比如“如果没有具体证据就标记为存疑不要输出模糊建议”。几次迭代之后输出质量会有明显提升。还有一个技巧是让 Claude Code 自己生成验证用例。比如在验证状态机时我让它列举所有可能的非法迁移然后让它可以试着生成测试用例来描述这些非法迁移。这样就把验证从“找问题”升级成了“补防护”评审的价值又高了一层。设计模式验证这件事我现在的态度很明确它不是让 Claude Code 给你盖一个“设计正确”的章而是让它帮你把说不清的设计直觉变成一条条有证据、有级别的具体问题。你在实际验证里也会发现最有价值的不是它直接给出的答案而是你顺着它的追问重新审视自己设计的过程。我的建议是第一次尝试从状态机这种可枚举的模式入手把验证结果存档和团队过一轮跑通一次完整流程之后再扩展到工厂、策略、观察者这些更依赖语义判断的模式。到那个时候你就会习惯这个“评审副驾驶”的存在了。