用AI Agent固化架构审查经验：从规则库到Skill实战

团队里组织过几次架构评审之后，我最大的感受是：所谓"架构设计审查"这件事，绝大多数时候卡住的不是技术深度，而是大家都没有一个统一的审查基准。同样一套方案，A说应该拆成五个微服务，B说一个单体就够，会上谁也说服不了谁，最后只能看谁嗓门大。后来我花了几周时间，把自己过去做技术评审时沉淀的检查项、反模式、风险判定标准，整理成一个可以直接交给 AI Agent 执行的架构设计审查 Skill，让 Claude Code 这类工具按照"先收集信息、再对照规则、最后输出报告"的方式去审方案。这篇文章把这份 Skill 的设计思路、文件结构、规则写法、集成调试和实测复盘完整交代一遍，想给那些正在把个人经验做成可复用 AI 能力的团队做个参考。

1. 为什么架构设计审查需要一份"标准作业程序"

1.1 架构评审最常见的四个失效场景

先说一个扎心的事实：绝大多数架构评审会，效率低并不是因为工程师水平不行，而是"审查"这件事本身没有一套标准作业程序。我参与过的团队里，最常见的是下面四种情况。

第一种，评审会变成了项目汇报会。设计人花十五分钟过一遍 PPT，讲清楚背景、目标、大概的技术选型，然后主持人问一句"大家有什么问题"，底下鸦雀无声。不是大家没有疑问，而是大多数人根本没在会前看过方案，临时看几分钟根本提不出有质量的问题。

第二种，提问全靠个人发挥，想到哪问到哪。有人关心缓存怎么用，有人盯着消息队列，有人纠结表结构设计，一场评审下来话题跳了七八次，最后什么都没定下来。没有维度的审查，等于没有审查。

第三种恰恰相反，大家只盯着新技术热点。分布式事务、Saga、Service Mesh、单元化部署，哪个概念新就聊哪个。看起来讨论很热烈，实际上方案最致命的边界问题、演进问题、成本问题，反而没人提。

第四种是会后没有闭环。评审记录写了几条意见，但谁去跟进、改没改、改完有没有重新评审，完全没有跟踪。下次再看这个系统，当初的问题一个不少地还在。

我复盘过自己之前做技术负责人时主持的几十场评审，发现真正有效的评审靠的不是临场反应，而是提前积累好的一套判断框架：这个方案在什么条件下成立、哪里是高风险区、该用什么标准判定"可以接受"还是"必须修改"。这套框架，本来只存在少数资深架构师脑子里。

1.2 审查经验可以沉淀为"可复用知识库"

一个成熟的架构师拿到一份设计方案，脑子里会快速跑过无数个问题：依赖关系清不清楚、故障域隔离了没有、数据一致性怎么保证、有没有单点、水平扩展的瓶颈在哪、配置是不是硬编码、日志能不能支撑排查、回滚方案是什么。

这些问题不是灵光一现，而是长期踩坑之后形成的条件反射。但问题在于，这种能力高度依赖个人，而且很难被传播。你可以在分享会上讲"要关注非功能需求"，但这句话太空了。真正值钱的是：针对哪种架构形态，优先检查哪几个点，看到什么信号就可以判定为高风险。

所以我把这些经验整理成了一个 Skill。所谓 Skill，简单说就是把一套"思考方法 + 判定标准 + 输出格式"封装成文件，让 AI Agent 在执行任务时按这套方法来。它和一份设计文档最大的区别是：文档是给人看的，需要人自己去理解和执行；Skill 是给 Agent 用的，加载之后就会按照里面的流程、规则、模板去工作。

我做这个架构设计审查 Skill 的初衷也很直接：把"资深架构师是怎么审一份方案的"这件事，固化成一份可复用、可版本化、可以分发给整个团队的数字资产。架构评审不再依赖某个大牛是否在场，新来的同学拿到这份 Skill，也能按同样的维度去审方案。

2. Skill 究竟是什么：一份能改变 Agent 行为的"说明书"

2.1 先分清 Prompt、MCP、Skill 的边界

在讲怎么写 Skill 之前，必须先把这个概念讲清楚，因为最近讨论的人多，混用的也很多。

Prompt 是一次性的对话指令。你把一段精心写好的提示词发给 AI，它能按照提示词完成任务，但这段提示词本身不负责管理知识，也不具备结构化的文件体系，下次用还得重新粘贴。

MCP（Model Context Protocol）解决的是"Agent 能不能做到某件事"的问题。它像是一个插头，通过标准协议给 Agent 接上外部工具、数据库、API，让 Agent 有能力去读文件、查数据库、调接口。但 MCP 不负责告诉 Agent"做这件事的正确流程是什么""判定标准是什么"。

Skill 解决的是"Agent 怎么把一件事做好"的问题。它是一个文件夹，里面装着 SKILL.md 主文件、参考资料、规则库、脚本。Agent 加载 Skill 后，会按照里面定义的流程去思考、按照规则去判断、按照模板去输出。

用生活化的类比：MCP 是给厨师提供食材和厨具的供应链，Skill 是厨师的菜谱。没有菜谱，厨师可能不知道该按什么顺序下锅、每种调料放多少；没有供应链，菜谱写得再好也没东西可做。两者是互补关系，不是替代关系。

2.2 Skill 的标准文件结构

我用的 Skill 目录结构大概是这样的：

code复制architecture-review-skill/
├── SKILL.md
├── references/
│   ├── architecture-review-checklist.md
│   ├── risk-levels.md
│   └── anti-patterns.md
├── scripts/
│   └── collect_context.py
└── assets/
    └── report-template.md

SKILL.md 是这个 Skill 的入口文件，必须放在根目录。文件开头是 YAML 格式的 frontmatter，里面至少要有 name 和 description 两个字段。name 是这个 Skill 的标识，description 是给 Agent 看的说明，用于判断"用户当前的请求是否应该触发这个 Skill"。

正文部分我一般分三块：Instruction（行为指令），Workflow（工作流程），Output Format（输出格式）。Instruction 告诉 Agent 自己是什么角色、在什么场景下使用；Workflow 明确执行的先后步骤；Output Format 规定最终交付的报告长什么样。

references 目录放参考资产。Agent 在执行过程中会根据需要读取这些文件，比如反模式库、检查清单。scripts 目录放可执行脚本，比如我写了一个自动提取方案文本的脚本，Agent 可以调用它对输入做预处理。assets 目录放静态资源，比如报告模板。

很多人写 Skill 只写一个 SKILL.md，内容全部堆在一起，文件动辄几千字。这样也能用，但可维护性很差。我建议把规则、清单、模板拆到 references 里，让主文件保持精简，专注定义工作流程。Agent 在需要时按文件名去加载对应内容，效率更高，也不会一次塞进太多无关 token。

2.3 Agent 在什么情况下会加载这份 Skill

搞清楚了文件结构，还得理解 Agent 的加载机制，否则可能会出现你明明装好了 Skill，Agent 却从来不用的情况。

目前主流 Agent 工具加载 Skill 大致有三种方式。第一种是用户显式指定，比如在对话里直接说"用架构设计审查 Skill 分析下面的方案"；第二种是描述匹配，Agent 根据用户输入的目标和 SKILL.md 里的 description 字段做语义匹配，觉得"这件事应该用到这个 Skill"，就自动加载；第三种是命令触发，比如通过斜杠命令 /skill-name 手动调用。

也就是说，description 写得好不好，直接决定了 Skill 被自动触发的概率。写得越具体、越贴近用户可能的表达方式，命中率越高。如果 description 里只有"架构设计审查"五个字，Agent 在遇到"帮我看看这个系统拆分得合理吗"这类问题时，很可能不会联想到。所以我的 description 里会写一堆触发场景：微服务拆分方案评审、数据库分库分表方案检查、系统扩容设计评估……

这个理解对整个 Skill 设计的价值很大：你是在给一个"会自己判断要不要用你的方法"的 Agent 写手册，不是在给固定流程的脚本写逻辑。

3. 从零编写架构审查 Skill：核心文件与规则分层

3.1 目录与命名：让 Agent 一进来就知道干什么

命名这件事看似琐碎，实际很影响加载效果。Skill 文件夹的名字我会用连字符命名的全小写形式，比如 architecture-review-skill，这样在各种操作系统和工具链里都不会出问题。SKILL.md 的文件名必须跟规范完全一致，不能是 main.md，也不能是 skill.md。

references 里的文件命名我建议带上用途前缀，比如 architecture-review-checklist.md 一看就是审查清单，anti-patterns.md 明确是反模式库。Agent 在决定读取哪些 reference 时，会根据用户当前的任务和文件名做相关性判断，名字取得足够清晰，它就能更快找到自己需要的材料。

3.2 SKILL.md 正文：先流程后标准再输出

SKILL.md 的正文我建议按"流程优先"的原则来写，而不是一上来就罗列一堆规则。Agent 是需要先知道"我该按什么步骤做"，再知道"每一步用什么标准判断"。

我这份 Skill 的 SKILL.md 核心内容大概是下面这个逻辑：首先明确角色身份——你是一名拥有 15 年经验的软件架构师，工作内容是审查用户提供的架构设计方案；接着定义输入格式——方案文本、系统描述、代码仓库地址等；然后进入工作流程：第一步收集背景信息，第二步按规则库逐项审查，第三步识别反模式命中情况，第四步交叉验证规则冲突，第五步输出结构化报告。

我给 Agent 写的流程指令可以简化成下面这个骨架：

code复制## 执行流程

1. 接收方案后，先要求自己整理一份"方案摘要"，包括：业务边界、模块划分、技术选型、关键链路。
2. 依次加载 references/architecture-review-checklist.md 中的检查项，对方案逐条审查。
3. 对照 references/anti-patterns.md 识别是否有已知反模式命中。
4. 对命中项做风险分级，标注为 P0/P1/P2/P3。
5. 输出最终报告，必须包含：总体结论、风险清单、修改建议、验收要点。

这个骨架的关键在于把"自由发挥"的空间压缩到可控范围内。Agent 本身很聪明，但如果完全不约束流程，它可能只审查它熟悉的几个点，漏掉真正重要的维度。给出明确流程，相当于强迫它从头到尾走完一整条审查链路。

3.3 审查规则四层设计

规则库是整个 Skill 的灵魂。我做规则分层时参考的是"从能不能跑，到跑得好不好，再到以后还改不改得动"这条主线，一共分了四层。

第一层是可运行性基础规则，解决的是方案"能不能落地"的问题：依赖清不清楚、环境配置是否完整、数据库选型是否匹配数据规模、接口协议是否定义完备。

第二层是架构风格规则，解决的是"结构合不合理"的问题：模块边界是否清晰、分层是否合理、是否出现循环依赖、职责是否越界、扩展点有没有预留。

第三层是非功能质量规则，解决的是"扛不扛得住"的问题：性能瓶颈、单点故障、数据一致性、安全管控、可观测性、容灾容量。

第四层是演进性规则，解决的是"以后改起来会不会死"的问题：技术债务、版本兼容、数据迁移路径、灰度回滚方案、团队可维护性。

四层规则的权重不一样。第一层有硬伤，方案直接打回；第二层有问题，需要修改；第三层和第四层往往是评审里最容易被忽略但又最致命的。

注意，这份规则不是一次性写完的，它一定是跟着团队踩坑史持续迭代的。下面这两章我详细讲讲规则条目本身怎么写。

4. 审查规则怎么写才有价值：从检查项到判定标准

4.1 检查项不等于判定标准

我见过很多团队整理过"架构设计检查清单"，格式基本都是"是否考虑缓存""是否考虑容灾""是否做日志监控"，每一项后面打勾或打叉。问题在于，这种检查项没有任何判定标准。什么叫"考虑缓存"？是提了一句"可以用 Redis"就叫考虑，还是必须给出缓存粒度、更新策略、一致性保障方案？

真正能指导 Agent 做判断的规则，必须包含两个部分：识别信号和判定阈值。

举一个我实际写过的例子。缓存穿透这条规则，差的写法是"检查方案是否考虑缓存穿透"；我的写法是：

code复制规则：缓存穿透防护
识别信号：
- 存在面向公网的查询接口
- 请求参数为外部可控制的主键
- 缓存未命中时会直接访问数据库

判定标准：
- 当 DB 预期读 QPS 超过集群容量的 10%，且方案中没有任何空值缓存、布隆过滤器或并发限流措施时，判定为 P1 风险
- 若存在空值缓存但未设置过期时间，判定为 P2 风险，需补充说明

为什么必须这么写？因为 Agent 做判断的依据是我给它的文本规则，如果规则本身是含糊的，它只能靠猜，猜出来的结果自然不稳定。给它明确的信号和阈值，它的判断才可复现、可解释。

4.2 反模式库：把踩过的坑变成命中条件

规则库负责"按维度逐项排查"，反模式库则负责"看到坑直接报警"。两者互补。我维护了一个简版反模式库，里面每条反模式都包含识别信号、风险等级、建议方案。

反模式的价值在于给 Agent 装上"火眼金睛"。它不需要每次从头推理这个方案有没有问题，而是直接拿已知的模式去匹配。这跟资深架构师看到某种设计立刻觉得"这个坑我见过"是一个道理。

4.3 风险分级与冲突处理

规则之间经常会打架。比如某个方案为了追求高性能，绕开了统一的领域服务，直接跨表读写，性能上没问题，但违反了模块边界规则。这时候如果两条规则同时命中，Agent 不能简单地把两条都列出来就完事，我得告诉它怎么处理冲突。

我的做法是定义优先级：P0 级是不能接受的，一票否决，比如明文存储密钥、核心链路无备份；P1 是在上线前必须整改的；P2 是建议优化但不阻塞发布的；P3 是可以记录为技术债的。

当低层级规则与高层级规则冲突时，明确要求 Agent 在报告中单独设立一节"风险取舍说明"，写清楚妥协的代价、缓解措施和后续治理计划。比如某个高性能方案绕开了领域服务，虽然违反了 L2 规则，但如果方案明确说明该链路数据一致性要求极低、未来两年内无复杂业务演进，并且配套了旁路对账机制，那我允许它降级为 P2 或 P3。有了这一层，报告才不会变成一个只会说"不"的机器人。

4.4 结构化审查报告的字段设计

规则定好了，最后输出环节也得定标准。不然让 Agent 自由发挥，它可能给你写一篇散文式的评审意见，看起来很有道理，实际上没人知道该按什么优先级去改。

我这份 Skill 统一要求输出下面这个结构：

markdown复制# 架构审查报告

## 1. 方案摘要
（用 200 字以内概括原方案的核心设计）

## 2. 总体结论
（P0 项数量 / P1 项数量 / 总体是否通过）

## 3. 风险清单
表格，列：编号、规则来源、风险描述、风险级别、涉及模块、触发条件

## 4. 修改建议
针对每个 P0/P1 风险给出具体可行的整改建议

## 5. 冲突取舍说明
（如无冲突可以省略）

## 6. 验收要点
（修改完成后再评审时，重点看哪几个点）

字段固定的好处是，多份方案的审查结果可以做横向对比，也可以直接进入团队的问题跟踪系统，不会出现"每条报告的格式都不一样"的混乱。

5. 让 Skill 真正跑起来：与 Claude Code 等 Agent 的集成与调试

5.1 文件路径与加载机制

Skill 写完之后，要放到 Agent 能发现的位置。以 Claude Code 为例，可以放在两个位置：全局目录 ~/.claude/skills/，或者项目目录 .claude/skills/。全局目录下任何项目都能用，适合放"架构设计审查"这种通用能力；项目目录只对当前仓库生效，适合放跟业务强绑定、含有内部规范的 Skill。

Codex、Cursor 等工具的命令行版本，对 Skill 规范也有支持，路径和加载机制大同小异。我不建议一份 Skill 只服务一个工具，最好把它设计成纯 Markdown + 目录结构的标准形态，这样迁移成本最低。

5.2 触发 Skill 的三种方式

集成之后第一步是验证它能不能被触发。我用得最多的是显式指名，直接在对话里说"用架构设计审查 Skill 审查下面的方案"。这种方式最稳，不会出现加载不上的情况。

自动匹配模式需要验证 description 的效果。我会准备几条和描述措辞不太一样、但含义相同的指令，比如"这是个电商中台的设计方案，帮我评估一下""这个系统之后要支撑双十一，架构上有没有隐患"，看 Agent 能不能把它们和架构审查 Skill 关联起来。自动匹配不总能 100% 命中，所以我的建议是：重要评审任务就显式指名，日常快速过方案才依赖自动触发。

5.3 调试技巧：验证加载、检查输出、回归规则

调试 Skill 跟调试代码是类似的思路。我在写规则之后会用一批测试方案跑回归，这些方案里有的是明显有缺陷的，有的是基本健全的，专门用来验证 Skill 会不会漏报和误报。

一个很实用的技巧是，在规则里临时加一个 Debug 模式。当用户在对话中说"开启调试"时，让 Agent 在输出报告的末尾额外附上"本次审查实际加载了哪些规则文件、哪几条规则命中、哪几条规则因缺少上下文被跳过"。这样我能一眼看出它有没有按预期走完整个流程，是不是漏掉了某些规则。

版本管理我直接用了 Git。Skill 本身是纯文本，非常适合做 diff，每次规则增删、阈值调整都留下记录。哪次调整导致误报率上升，可以快速回滚。

6. 一次真实审查的复盘：一个订单服务拆分方案的实测记录

6.1 测试输入：一份简化版微服务方案

为了说明这份 Skill 的实际效果，我构造了一次真实的测试。输入是一份简化版的订单中台微服务拆分方案，核心内容大概是：将订单中心拆为订单服务、支付服务、库存服务、履约服务四个模块；订单服务与支付服务通过消息队列异步通信；库存服务直连 MySQL，且为每个商品建立库存流水表；支付回调采用轮询数据库表的方式获取支付结果；服务间接口统一走 HTTP，当前无注册中心；网关层为单节点；所有服务密钥以明文形式写在各自配置文件中。

这个方案其实埋了不少我精心设计的问题，用来验证 Skill 能不能准确识别。

6.2 Skill 输出与人工复核对照

Skill 输出的报告与我和另一位资深工程师的人工复核结果做了对比，结果如下表：

整体来看，Skill 命中了大部分人工评审的关键问题，没有漏掉最严重的密钥问题，这是让我比较满意的。它最大的价值是稳定：无论谁来执行，这些问题都会被捞出来，不用依赖评审人当天状态好不好。

6.3 误报分析：规则迭代的方向

这次测试也暴露出两个误报，正好说明规则库需要持续迭代。

第一个误报是"网关单节点无备"。Skill 判定为 P1，但在人工复核时发现方案附带的运维说明里写了网关前有云负载均衡和跨可用区部署，只是方案文本没有描述清晰。这个问题的根因是规则触发时没有要求 Agent 检查"是否存在外部兜底条件"。我随后在规则里补充了一条前置检查：判定单点故障前，必须先确认方案中是否已存在负载均衡、主备切换、跨可用区冗余等措施。

第二个误报是"库存服务直连 MySQL 且无分库分表"。Skill 简单套用了"大规模数据必须具备分库分表能力"的规则，但这个方案当前阶段订单量很小，单库单表完全够用。后来我把这条规则的触发条件改成了"数据量预估超过单库物理上限或预估年增长率超过 100% 时才触发"，误报就没有了。

这次复盘让我得到一个原则：规则不能只有"设计良好"的理想态，还要内置"当前阶段是否真的需要这个能力"的判断条件。否则 Skill 会变成一个只会搬运大厂架构经验的复读机。

6.4 规则迭代怎么管理

每次实测后，我都会把误报、漏报、边界情况记录到 Skill 的变更日志里。比如"2025-01 版本：修复网关单点误报，增加外部兜底前置检查""2025-02 版本：库存分库分表规则增加量级触发条件"。

更重要的是，我会把真实的评审案例脱敏后沉入 references 目录。这样 Skill 在不知道如何权衡的时候，可以引用往期案例作为判例。这与法律体系里"先例"的作用类似：遇到新的边界情况时，去看历史类似场景当时是怎么处理的，比凭空推理更可靠。持续积累后，这份 Skill 会从一个静态规则集变成一个会成长的团队知识库。

最后再分享一个我个人的体会：Skill 写到后面，真正值钱的不是那一堆检查项，而是每条检查项背后的判定标准——什么条件下算合格，什么信号下要报警，什么场景下可以妥协。一个只有 Checklist 的 Skill 和一个带反模式库、带风险分级、带历史判例的 Skill，跑出来的报告质量完全是两个档次。后续我打算把容量规划、成本估算、合规检查这类规则也加进去，让每次架构审查不只停留在"设计是否合理"，还能回答"这个设计值不值得做、能不能持续演进"。希望你们团队的第一个审查 Skill 也能这么长出来。