【打造AI编程的规则引擎：从混乱到秩序的工程实践】

打造AI编程的规则引擎：从混乱到秩序的工程实践

当AI编程助手越来越强大时，我们发现了一个反直觉的事实：越强大的AI，越需要精确的约束。这篇文章记录了我为Cursor/Qoder设计一套完整项目规则引擎的全过程——从最初的混乱无序，到最终建立起一套11个规则文件组成的"规格驱动开发"体系。

一、为什么AI编程需要规则？

如果你用过AI编程助手一段时间，可能已经体会到一种奇特的矛盾感：AI确实能写出运行正确的代码，但项目整体却在走向混乱。

没有规则时，AI会怎样？

• 自由发挥代码风格：今天驼峰命名，明天下划线，后端用PascalCase，前端也用PascalCase——但你的项目规范明明是前端驼峰、后端PascalCase。
• 跳过文档直接编码：你说"帮我加个字段"，AI立刻开始改代码。但这个字段影响了哪些模块？需不需要改接口？会不会有安全风险？没人思考过。
• 随意commit：代码写完直接git add . && git commit，commit message写个"update"或"fix bug"就推上去了。
• 重复造轮子：项目里明明有封装好的工具函数，AI不知道，又写了一个功能相同但接口不同的版本。
• 测试形同虚设：要么不写测试，要么写了个expect(true).toBe(true)这种无意义断言交差。

这些问题的本质不是AI"不够聪明"——恰恰相反，AI太"聪明"了，它能找到很多种方式完成你的要求，但它不知道哪种方式才是你项目语境下的"正确方式"。

这就是规则引擎存在的意义：把隐性的工程知识显性化，让AI在项目约束内发挥能力。

二、整体架构设计：11个规则文件的层次关系

经过多次迭代，我最终形成了一套由11个.mdc规则文件组成的规则体系。这些规则不是简单堆砌，而是有清晰的层次结构和优先级设计。

2.1 模块化分层

从上到下分为三层：

2.2 触发策略：不是所有规则都需要常驻

规则有两种加载方式：

• alwaysApply: true（常驻）：00-global、01-sdd、03-testing、04-security、07-git、graphify、08-knowledge-graph、conversation-principles——这些是流程和安全相关的，必须时刻生效。
• globs 按文件类型触发：02-code-style（**/*.{cs,js,vue}）、05-api（**/*.cs）、06-frontend（**/*.{vue,js,ts}）——只在编辑对应文件时加载，避免浪费token。

这个设计的考量是：流程约束要常驻（防止AI跳步），编码细节按需加载（节省上下文空间）。

2.3 优先级层级表：解决规则冲突

当多个规则产生冲突时，按以下层级裁决（数字越小优先级越高）：

为什么需要这张表？因为规则之间不可避免会有张力。比如"交互规范"说"保持轻量极简表达"，但"SDD流程"说"必须先写规范文档"——当用户说"帮我改个文案"时，该走哪个？有了优先级表，AI就能明确判断：这是hotfix量级，SDD流程优先但走简化路径。

三、核心规则详解

3.1 SDD四阶段流程——核心创新点

SDD（Spec-Driven Development，规格驱动开发） 是整套规则体系的灵魂。它的核心理念是：AI在写代码之前，必须经过"想清楚"的过程。

每个阶段都有明确的入口条件、产出物和评审门：

第一阶段：规范（Specify）

• 入口：用户提出需求
• 产出：docs/specs/FR-XXX.md 或 docs/change/CHG-*.md
• 必须包含：验收标准（AC）、安全影响声明、变更文件清单
• 评审门：feature/structural需用户"通过"，hotfix可Agent自评

第二阶段：技术方案（Plan）

• 入口：规范评审通过
• 产出：docs/plans/YYYY-MM-DD-*.md
• 必须覆盖：架构选择、影响文件、实现路径、风险、测试策略
• 评审门：同上

第三阶段：任务拆解（Tasks）

• 入口：方案评审通过
• 产出：Plan文档## Tasks章节 + TodoWrite任务清单
• 每个Task关联对应AC，标注文件路径与测试路径

第四阶段：实施与验证（Implement）

• 入口：强制前置检查（规范文档存在 + 技术方案存在）
• 每个Task必须通过五道门：TDD写测试 → 编码实现 → 测试通过 → 安全自检 → AC验收

为什么要这么设计？ 因为AI最大的问题不是"写不出来"，而是"写的不是你要的"。四阶段流程强制AI在动手之前把需求理清、方案想透、任务拆细，这样每一步都有明确的验收标准，不会出现"AI写了一堆代码但方向完全错了"的情况。

3.2 变更量级分级——实用主义设计

四阶段流程好是好，但如果改个文案也要走全套，那效率就崩了。所以我引入了变更量级分级：

hotfix的测试判定也有客观标准，避免"是否写测试"变成主观争论：

• 纯新增字段无条件分支 → 补最小序列化测试
• 修改了条件/计算逻辑 → 必须覆盖新分支
• 纯文案/配置无代码 → 可免测，标注原因

这个分级设计体现了一个核心思想：好的规则要"分级"——不同量级的变更走不同流程。一刀切只会导致两种结果：要么形同虚设（大家都绕过），要么效率崩溃（改个错别字也走全套）。

3.3 知识图谱集成——给AI装上"记忆"

AI编程助手最大的痛点之一是"没有记忆"——每次对话都像从零开始，不知道项目里已经有什么、模块之间怎么关联。

我的解决方案是集成Graphify知识图谱：

入口查询机制：每次涉及业务代码的对话，AI必须先查图谱：

1. 提取查询词（Spec ID → 文件名 → 领域关键词）
2. 执行query（MCP或CLI）
3. 判定命中，回复模板：图谱：<查询词> | <命中/未命中> | <关联节点>

未命中分级入图：

• L1：轻量更新，再次query
• L2：补规范文档，强制更新，再query
• L3：扩白名单，强制更新

增量更新时机：

• 新Spec/CHG、新表/字段/API
• 跨模块新依赖
• Implement阶段所有Task完成后

这个设计让AI不是在"真空"中编码，而是能快速定位到相关模块、已有规范、历史变更，大幅减少"重复造轮子"和"改了A忘了B"的问题。

3.4 Git提交授权机制——人始终掌握最终控制权

在所有规则中，07-git.mdc的提交授权被赋予了业务规则最高优先级。核心条款：

Agent 禁止自动执行 git add / git commit / git push 等任何会改写Git历史的命令。仅当用户明确发出提交指令时，Agent才可执行。

为什么这么严格？

Git操作是不可逆的（尤其是push），而且commit是代码的"正式发布"。如果AI在你不知情的情况下自动commit了一段有问题的代码，或者把未完成的半成品推到了远程仓库，后果可能很严重。

更细致的约束包括：

• 用户说"实施方案"不构成提交授权（即使方案里有"提交"章节）
• 授权一次只对一个commit生效
• 写完代码后只简要说明改动，不主动附带commit命令

这体现了一个设计哲学：AI是强大的助手，但人始终掌握最终控制权。代码可以让AI写，但"认可这段代码并纳入版本历史"的决定权必须在人手里。

3.5 交互规范——直接执行vs深度交互

conversation-principles.mdc解决的是另一个常见问题：AI要么"太话唠"（一个简单问题写三屏分析），要么"太沉默"（直接上代码不解释风险）。

我的方案是分层回答设计：

• 直接执行：按用户当前要求直接给出结果，推动任务前进
• 深度交互：回到原始目标审慎分析，识别目标偏移、XY问题、路径依赖

配合交互力度控制：

• 小任务/低风险 → 保持轻量，只指出明显更优路径
• 大任务/高风险/需求模糊 → 严格目标审视、方案比较、边界确认

还有一个我很喜欢的设计——审慎挑战：当怀疑用户在解决表象而非根问题时，AI应主动指出。但前提是"审慎挑战的目标是提升结果质量，不是替代用户做目标决策"。

四、巧妙设计点总结

4.1 存量代码策略：“触碰即纳入”

面对遗留代码，我设计了一个务实的策略：

• 不动存量：已上线功能不主动回溯补Spec/注释/测试
• 触碰即纳入：当你需要变更存量功能时，先补简化版Spec（状态Deployed），再按四阶段执行

这避免了两个极端：既不强制对整个老项目补文档（不现实），也不允许改存量代码时完全没有规范约束（质量失控）。

4.2 测试豁免机制：只要求diff覆盖

测试规范中有一条关键的"存量改动豁免"：

变更已上线模块时，仅要求覆盖本次新增/变更的代码行（diff覆盖），不要求整模块达到80%/70%；上述覆盖率仅对新建模块强制。

这解决了一个经典矛盾：改存量代码一行，不应该被迫把整个模块的测试覆盖率从20%补到80%。规则要可执行，不可执行的规则注定被绕过。

4.3 CLAUDE.md同步治理

结构性变更（新增/删除目录、入口路径变化等）必须同步更新CLAUDE.md。这保证了项目的"自我描述"始终与实际一致，AI下次阅读时不会被过时的项目描述误导。

4.4 Hook自动化辅助

规则不完全依赖AI的"自觉"，还有Hook机制作为安全网：

Hook设计为failClosed: false——崩溃时放行不阻断。这体现了"辅助而非阻塞"的理念：Hook是提醒机制，不是铁壁门禁。

五、优化迭代：从"过度工程化"到"实用主义"

任何规则体系的第一版都会有问题。我的第一版规则在实际使用中暴露了不少痛点，促使了一轮显著的优化。

5.1 发现的问题

问题一：hotfix流程过载

改一个文案/单字段，也要走完整四阶段：建CHG → 建plan → 写AC → 写安全声明 → 更新Spec变更历史 → 更新Spec状态。单行修改的文档成本远高于代码本身，产出大量低信噪比文档。

更矛盾的是，conversation-principles自己要求"最小充分解、避免为形式完整引入复杂度"，而四阶段强制恰好违背了它。规则集内部自相矛盾。

问题二：alwaysApply规则太长浪费token

01-sdd-spec原始版本287行，每轮对话都全量加载。配合其他7个常驻规则，大量token消耗在"提醒AI注意规则"上，而不是用来解决实际问题。

问题三：测试门禁与存量冲突

03-testing要求"禁止提交无测试的新增/变更代码" + 覆盖率80%/70%/100%；但又说"触碰即纳入"。改存量一行就要把模块测试补到80%，实操根本落不了地。一旦规则普遍无法遵守，就会被整体忽略——破窗效应。

问题四：Graphify强制查询开销大

对纯问答、评价类对话也强制查图谱并输出模板行，开销与收益不成比例。

问题五：重复定义导致漂移

命名规范在02-code-style、05-api、06-frontend三处重复，时间长了容易不一致。

问题六：硬性指标缺乏工具卡口

“函数≤50行、参数≤5个、Vue≤300行”——没有lint规则真正检查，就是装饰性条款。SpreadJS绑定类文件天然超长，规则注定被破例。

5.2 优化方案

基于实践反馈，我做了以下调整：

5.3 优化感悟

这轮优化让我深刻认识到：

1. 规则本身也需要迭代优化。第一版规则往往过度工程化——因为写规则时你想的是"理想情况下应该怎样"，但实际使用时发现很多"理想"落不了地。

2. 规则的核心矛盾是"严vs松"。太严导致效率低下，太松导致质量失控。解决方案不是找一个"中间值"，而是分级——不同场景用不同严格度。

3. 不可执行的规则比没有规则更糟。因为它会产生破窗效应：当大家习惯性绕过A规则时，也会开始绕过B规则、C规则。所以规则必须是"能做到的"。

六、实践效果与感悟

这套规则体系运行一段时间后，带来了几个明显的改善：

减少返工：AI在写代码前被迫"想清楚"，方向性错误大幅减少。以前经常出现"写了200行代码发现理解错了需求"的情况，现在在规范阶段就能发现偏差。

提高一致性：代码风格、命名规范、API返回格式等高度统一。不再出现"同一个项目像三个人写的"的感觉。

知识沉淀：通过知识图谱和Spec文档，项目知识不再只存在于人脑中。新加入的开发者（或新的AI对话session）能快速了解项目全貌。

安全保障：安全自检机制确保每次涉及API/DB的变更都经过安全审查，不会因为"太小了不用查"而遗漏。

掌控感：Git授权机制让我始终知道"什么被提交了"，不会出现AI偷偷改了什么我不知道的情况。

当然，也有成本：

• 规范文档确实需要时间写（即使是AI辅助）
• hotfix这种小改动的流程虽然已简化，但仍比"直接改"慢
• 规则维护本身也是工作量

但总体而言，规则设计的ROI是正的：投入规则设计和维护的时间，通过减少返工、提高一致性、降低Bug率来回报。特别是在项目规模增长时，这个ROI会越来越高。

七、几个深层感悟

1. AI不是不需要规则，越强大的AI越需要精确的约束

弱AI"不会"做的事不需要约束；强AI"能但不该"做的事才需要约束。GPT-3时代不用担心它自动commit，因为它做不到。但今天的AI完全能做到——所以你需要明确告诉它"这件事不许做"。

2. 知识图谱是给AI"记忆"的方式

人类开发者在一个项目待久了，脑子里会形成"这个模块和那个模块有关联"的直觉。AI没有这种跨session的记忆。知识图谱就是把这种"项目直觉"外化成可查询的结构，让AI不会每次都从零开始。

3. 规则设计是"工程"而非"管理"

好的规则不是"禁止这个禁止那个"的管理条例，而是帮助AI做出正确决策的工程工具。就像代码里的类型系统——不是为了限制你，而是为了在错误发生前就拦住。

4. 人机协作的最佳模式：AI负责执行效率，人负责决策质量

四阶段流程的精髓是：需求定义和方案审批由人决策，具体编码和测试执行由AI高效完成。评审门就是人机协作的"接口"——人在关键节点把关，AI在确定方向后全速推进。

八、结语：AI编程规则设计的展望

回顾这套规则体系的演进，我看到了几个趋势：

规则会越来越"智能"。现在的规则是静态的文本文件，未来可能是动态的——根据项目当前状态、代码复杂度、历史bug率来自动调整流程严格度。

知识图谱会成为标配。当项目足够复杂时，没有结构化知识管理，AI就只能靠grep全库碰运气。图谱让AI从"暴力搜索"升级为"理解性导航"。

"规格驱动"会成为AI编程的主流范式。不管叫SDD还是别的什么名字，"先定义清楚再让AI实现"这个思路一定会普及。因为这是成本最低的质量保障方式。

规则设计本身会被AI辅助。我已经在用AI帮我评审和优化规则了——AI能发现规则间的矛盾、冗余和不可执行之处。这是一个有趣的递归：用AI来设计约束AI的规则。

最后分享一个感悟：规则不是限制创造力的枷锁，而是释放创造力的结构。就像诗词的格律不是限制诗人，而是在约束中催生出更精炼的表达。好的规则让AI把精力集中在真正需要创造力的地方，而不是浪费在"该用驼峰还是下划线"这种已有答案的问题上。

给AI编程定规则，本质上是在回答一个问题：在这个项目中，什么是"好代码"的定义？ 一旦你把这个定义写清楚了，AI就能成为一个高效、可靠、符合预期的开发伙伴。

本文基于实际项目中11个规则文件的设计与优化实践，规则体系适用于Cursor/Qoder等AI编程助手。如果你也在思考如何让AI更好地融入你的开发流程，希望这些经验能给你启发。