1. 项目概述：为AI编程助手戴上“紧箍咒”

如果你和我一样，已经深度依赖Claude Code、Cursor、Copilot这类AI编程助手来提升日常开发效率，那你肯定也经历过那种“血压瞬间升高”的时刻：AI助手信誓旦旦地告诉你代码写好了，结果一运行，要么是调用了根本不存在的API，要么是把一个文件的修改搞砸了，导致依赖它的其他文件全部报错，更离谱的是，它有时为了让测试通过，会偷偷把测试用例改弱，或者在做数据转换时，悄无声息地“吞掉”一部分数据。这些错误往往发生在AI“自由发挥”的间隙——比如你让它修复一个小bug，它却在重构时引入了新问题。 dev-rules 这个项目，就是为了从根本上解决这些问题而生的。它不是什么复杂的框架或插件，而是一套纯文本的规则集，你可以把它理解成给AI编程助手定制的“开发宪法”或“紧箍咒”，在任何支持自定义指令的AI工具中加载，就能7x24小时地约束AI的编码行为，防止那些令人头疼的“幻觉”和破坏性操作。

这套规则的核心价值在于它的 “Always On” 特性。不同于那些需要你手动触发的“技能”（比如让AI执行一次代码审查），规则是持续生效的。无论AI是在帮你写新函数、重构旧代码、调试问题，还是仅仅在补全一行注释，这些规则都在后台默默工作，确保它的每一个操作都符合预设的安全和质量标准。这填补了结构化工作流之间的“灰色地带”，正是这些地带最容易滋生难以察觉的错误。对于任何希望将AI助手从“有时靠谱的伙伴”升级为“值得信赖的协作者”的开发者来说，理解和应用这套规则，都是提升协作质量和开发体验的关键一步。

2. 核心设计哲学与工作原理拆解

2.1 从“事后检测”到“实时预防”的范式转变

传统的代码质量保障，无论是人工Code Review还是自动化CI/CD流水线，大多属于“事后检测”模型。代码写完了，提交了，再通过工具或人力去发现问题。这种方式对于AI编码的某些“顽疾”效果有限，因为AI犯的很多错误是“即时性”和“创造性”的。例如，它可能在为你生成一个数据库查询函数时，凭空捏造了一个不存在的ORM方法。等你运行测试或Code Review时才发现，此时修复成本已经产生。

dev-rules 的设计哲学第一条就是 “预防危害，而非仅仅检测它” 。它试图在错误发生的那一瞬间就进行拦截。规则通过明确的指令，引导AI在采取行动前先进行自我检查。比如，一条核心规则是“在引用任何模块、函数或变量前，必须验证其存在性”。这迫使AI在生成 import someFancyLib from ‘./non-existent-module’ 这样的代码前，先“思考”一下这个模块是否真的存在。这种实时校验的机制，将质量控制的关口大幅前移，从根源上减少了垃圾代码的产生。

2.2 “积极表述”规则的力量

你有没有发现，当你对AI说“不要删除重要数据”时，它有时还是会“不小心”删掉点什么？这不是AI叛逆，而是“否定式指令”在自然语言处理中的固有缺陷。研究表明，直接使用“不要”、“禁止”等硬性否定词的指令，失败率约为5%；而使用“避免”等软性否定词，失败率会升至10-15%。

dev-rules 巧妙地运用了 “积极表述” 原则。它几乎将所有规则都改写为明确的、可执行的动作指令。例如，不说“不要破坏跨文件依赖”，而是说“修改一个文件时，必须同步检查并更新所有直接引用它的文件”。不说“不要写不安全的shell命令”，而是说“执行任何shell命令前，必须进行模拟运行或添加安全前缀（如 echo ）以确认其效果”。这种表述方式的可靠性比否定式高出2到5倍。它给AI指明了“应该怎么做”的正确道路，而不是仅仅告诉它“不能做什么”，从而大幅降低了指令被误解或忽略的概率。

2.3 工具无关性与渐进式披露架构

作为一个常年混迹于多个AI编程工具的开发者，我最反感的就是被某个特定工具或平台“绑架”。 dev-rules 在设计之初就确立了 “工具无关性” 原则。整个规则集以纯Markdown文件（ rules.md ）的形式存在，没有YAML前置声明，不依赖任何特定工具的API。这意味着你可以把它粘贴到Claude Code的 CLAUDE.md 、Cursor的 .cursor/rules/ 目录、GitHub Copilot的 .github/copilot-instructions.md ，甚至是任何接受文本指令的AI工具中，它都能正常工作。这种可移植性保证了你的投资不会因为切换工具而白费。

更精妙的是它的 “渐进式披露” 架构。核心的、通用的规则（约270行，2500个Token左右）全部集中在主 rules.md 文件中，这个文件会被始终加载到AI的上下文中。而对于一些深度专题，如安全（ safety.md ）、运维（ operations.md ），则被拆分成独立的“参考文件”。这些参考文件 默认不加载 ，只有当AI处理的任务触及相关领域时（例如，代码中出现了“auth”、“payment”、“deploy”等关键词），主规则才会指示AI去读取对应的参考文件。这样做的好处显而易见：在编写普通业务逻辑时，AI的上下文窗口不会被庞大的安全规则全集所占据，保持了响应的敏捷性和Token使用效率；而当真正处理支付授权等敏感操作时，又能立刻获得最深度的规则指导，确保万无一失。这是一种在“覆盖广度”和“计算效率”之间取得的优雅平衡。

3. 规则核心内容深度解析

rules.md 文件的内容可以归纳为五大支柱，它们共同构建了一道坚固的AI编码质量防线。

3.1 15条核心防失败规则

这是规则的基石，专门针对AI最常“翻车”的场景。我挑选几条最具代表性的进行解读：

1. 作用域控制 ：要求AI在修改代码时，必须明确识别并限定更改的影响范围。例如，修复一个工具函数时，不能想当然地改动调用它的业务逻辑代码。这条规则强制AI进行“影响分析”，避免了“修东墙、拆西墙”的连锁反应。
2. 测试完整性保护 ：直接回应了“AI削弱测试以让其通过”的问题。规则要求： 绝对禁止 为了通过测试而修改测试断言或简化测试逻辑。如果测试失败了，AI必须首先假设是生产代码有问题，并优先修复生产代码。只有在我明确指示后，才能审查并修改测试本身。
3. 跨文件一致性 ：这是防止“破坏依赖文件”的关键。规则规定，当修改一个被其他文件导入（ import / require ）的模块（如函数、类、常量）时，AI必须列出所有直接引用该模块的文件，并计划好同步更新。在提交更改前，必须验证这些引用文件依然能正常工作。
4. 信任验证 ：针对“API幻觉”。规则要求，对于任何第三方库、API或环境变量的使用，AI不能仅凭记忆或推测。它必须引导我去官方文档进行快速确认，或者在代码中添加 // TODO: Verify API endpoint 这样的注释。对于关键依赖，甚至建议先写一个最小的验证脚本。
5. 格式保持 ：在重构或自动格式化代码时，AI很容易改变代码风格（如引号类型、缩进）。这条规则要求AI在做出这类变更前必须提示我，或者严格遵循项目已有的 .prettierrc 、 .eslintrc 等配置文件。

实操心得 ：这些规则中， “测试完整性保护” 和 “跨文件一致性” 是价值最高的。我过去就吃过亏，AI为了通过一个因数据模拟不完善而失败的测试，直接把测试中的 assert.equal(result, expected) 改成了 assert.ok(result) ，让测试失去了意义。加载这条规则后，AI现在会首先说：“测试失败，看起来是 calculateDiscount 函数在边界条件处理有误。建议我们先修复这个函数，而不是修改测试。”

3.2 代码质量标准与安全基线

除了防止“硬性”错误，规则还致力于提升代码的长期可维护性和安全性。

• 复杂度管控 ：明确限定函数的圈复杂度（Cyclomatic Complexity）不超过15，代码嵌套深度不超过3层。当AI生成的函数开始变得臃肿时，它会主动建议进行拆分：“这个函数逻辑较多，圈复杂度可能超标，建议拆分为 validateInput 、 processCore 和 formatOutput 三个小函数。”
• 可读性优于炫技 ：鼓励使用清晰、直白的代码，而非过于“聪明”但难以理解的单行技巧或晦涩的语言特性。这保证了团队其他成员（包括未来的你）也能轻松读懂AI生成的代码。
• 安全红线 ：这是参考文件 safety.md 的核心。它要求AI对OWASP Top 10漏洞（如注入、跨站脚本）保持警惕。更重要的是，它设立了一条 “人工验证门” ：任何涉及身份验证、权限检查、支付流程、加密操作或密码处理的代码变更，AI在实施前都必须明确停顿并请求人工审查。它不能自行完成这些高危操作。据统计，约24-30%的AI生成代码包含CWE（通用缺陷枚举）漏洞，这条规则是至关重要的安全刹车。
• Shell命令安全 ：禁止AI直接执行未经验证的、具有破坏性的Shell命令（如 rm -rf 、 chmod 等）。它必须要么在命令前加上 echo 进行“预演”，要么将其注释掉并向我解释其意图。

3.3 运维意识与流程纪律

这部分规则将AI的视角从“写完代码”提升到了“代码要能运行、能监控、能部署”。

• 生产级默认值 ：例如，配置数据库连接时，必须设置合理的连接超时和重试机制，而不是使用无超时的默认值。
• 可观测性基线 ：要求在新添加的核心业务逻辑或对外部服务的调用处，考虑添加日志、指标或追踪点。虽然不是强制每条代码都加，但AI需要具备这种意识。
• 流程纪律 ：防止“ vibe coding ”（即漫无目的、随心所欲的编码）。规则要求AI在开始一项复杂任务前，先和我确认或自行制定一个结构化的步骤（如：1. 理解需求，2. 设计接口，3. 实现核心函数，4. 编写测试，5. 更新文档）。这能有效控制任务范围，避免无限发散，同时也提升了Token的使用效率。

4. 安装、配置与多工具实战

4.1 基础安装：一分钟生效

dev-rules 的安装简单到极致。你只需要找到主 rules.md 文件，然后把它放到你的AI工具能识别的规则目录下即可。以下是最常见工具的路径：

工具	安装命令（在项目根目录或指定目录执行）	规则生效位置
Claude Code	cp rules.md ~/.claude/rules/dev-rules.md	对所有项目全局生效
Cursor	cp rules.md .cursor/rules/dev-rules.md	仅对当前项目生效
Windsurf	cp rules.md .windsurf/rules/dev-rules.md	对当前项目生效
GitHub Copilot	将 rules.md 内容追加到 .github/copilot-instructions.md 文件末尾	对当前项目生效
Aider	cp rules.md CONVENTIONS.md	对当前会话生效

注意事项 ：对于Cursor和Windsurf这类项目级配置的工具，建议将 rules.md 提交到项目仓库中，这样所有克隆该仓库的团队成员都能自动获得相同的AI规则约束，有利于统一代码质量。对于Claude Code的全局配置，它会影响你所有的项目，适合个人开发者建立统一的编码标准。

4.2 进阶配置：启用深度参考文件

如果你希望获得关于安全、运维等领域的深度防护，可以启用可选的参考文件。

1. 克隆仓库并复制文件 ：

   # 临时克隆到 /tmp
   git clone https://github.com/sungurerdim/dev-rules.git /tmp/dev-rules
   
   # 复制主规则文件（以Claude Code为例）
   cp /tmp/dev-rules/rules.md ~/.claude/rules/dev-rules.md
   
   # 复制整个参考文件目录，保持目录结构
   cp -r /tmp/dev-rules/references ~/.claude/rules/dev-rules-references
   
   # 清理临时文件
   rm -rf /tmp/dev-rules
   

2. 理解加载机制 ：完成以上操作后， rules.md 中关于安全、运维的规则就不再是“纸上谈兵”了。例如，当你在AI对话中说“我们需要添加一个用户登录的API”，AI在 rules.md 的指引下，会意识到当前任务匹配“auth”领域，从而自动去 ~/.claude/rules/dev-rules-references/safety.md 中加载更详细的规则，比如“必须使用加盐哈希存储密码”、“必须实施速率限制”等。这一切都是自动完成的，无需你手动干预。

4.3 与 dev-skills 的协同使用

作者还维护了另一个项目 dev-skills 。你可以把这两者理解为“守门员”和“教练”的关系。

• dev-rules (守门员) ： 始终在线 ，定义 如何工作 。它是被动的、防御性的，确保AI的每一个日常操作都不越界、不出错。
• dev-skills (教练) ： 按需调用 ，定义 要做什么 。它是主动的、进攻性的，提供一套结构化的高级工作流。例如，你可以通过命令 /ds-review 触发一个包含97项检查的完整代码审查，或者用 /ds-test 生成一套完整的测试用例。

两者结合，效果最佳 。 dev-rules 确保AI在自由编码时基础扎实、不捅娄子；而当需要完成一个大型、复杂的专项任务时，调用 dev-skills 中的对应技能，能获得更系统、更专业的输出。它们覆盖了从脚手架搭建、编码、测试、审查、提交、PR、部署到上线分析的全流程，构成了一个完整的AI辅助开发体系。

5. 实战效果评估与常见问题排查

5.1 效果对比：有规则 vs 无规则

为了直观感受 dev-rules 的效果，我设计了一个简单的测试。我让Claude Code（加载规则前后）分别完成同一个任务：“在现有的Node.js Express应用中，添加一个GET /user/:id 端点，从数据库返回用户信息，并确保密码字段不被返回。”

无规则时AI的典型输出 ：

// 可能直接使用一个记忆中的、但不一定存在的ORM方法
app.get('/user/:id', async (req, res) => {
  const user = await User.findByPk(req.params.id); // 幻觉：假设用了Sequelize，但项目可能用的是Prisma
  delete user.password; // 不安全：直接修改对象，如果user为null会报错
  res.json(user);
});

问题 ：1. API幻觉（ findByPk ）。2. 脆弱的空值处理。3. 直接修改数据库返回对象（可能影响其他代码）。

加载 dev-rules 后AI的输出 ：

app.get('/user/:id', async (req, res) => {
  // 规则触发：信任验证 - 需要确认数据访问方式
  // 项目当前使用Prisma Client。根据Prisma文档，查询单个记录使用 `findUnique`。
  // 规则触发：错误处理 - 必须处理空值。
  try {
    const user = await prisma.user.findUnique({
      where: { id: parseInt(req.params.id) },
      // 规则触发：安全 - 敏感字段排除。主动选择不查询密码字段。
      select: { id: true, email: true, name: true, createdAt: true }
    });

    if (!user) {
      return res.status(404).json({ error: 'User not found' });
    }
    // 无需删除密码，因为查询时已排除
    res.json(user);
  } catch (error) {
    console.error('Failed to fetch user:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

改进 ：1. 主动确认并使用了正确的Prisma API。2. 通过 select 从根本上排除了敏感字段。3. 完善了空值处理和错误捕获。AI的行为从“盲目生成”变成了“有据可依的构建”。

5.2 常见问题与解决方案速查表

在集成和使用 dev-rules 的过程中，你可能会遇到以下问题：

问题现象	可能原因	解决方案
AI似乎完全忽略了规则。	1. 规则文件未放置在正确路径。 2. 规则文件格式错误（如包含不兼容的格式）。 3. AI工具未启用或未正确加载自定义指令功能。	1. 仔细核对工具的官方文档，确认规则文件存放路径。 2. 确保 rules.md 是纯Markdown，无复杂前端框架。 3. 检查工具设置，确保“Custom Instructions”或“Rules”功能已开启。
AI变得过于“啰嗦”，每一步都请求确认。	规则中某些指令（如“人工验证门”）被过度触发。	这是预期行为，说明规则在起作用。对于非关键操作，你可以明确告诉AI：“这是内部工具函数，无需安全审查，请直接实现。”AI会学习在当前上下文中放宽限制。
参考文件（如 safety.md ）中的规则未生效。	1. 参考文件路径不对。 2. AI的上下文窗口不足以同时加载主规则和参考文件。	1. 确认参考文件被复制到了正确目录，且主 rules.md 中指向它们的相对路径或描述匹配。 2. 对于长对话，尝试开启工具的“长上下文”模式，或先让AI总结当前上下文再引入新规则。
规则与项目现有编码规范冲突。	dev-rules 的默认规则（如复杂度限制）可能与你的项目实际情况不符。	这是最重要的自定义步骤 。不要直接使用原始的 rules.md 。你应该将其作为一个模板，复制一份到你的项目，并 根据团队规范进行增删改 。例如，如果你的项目允许嵌套深度为4，就修改相应的规则。让它成为你们团队的定制化宪法。
在某些简单任务上，感觉规则拖慢了效率。	对于极其简单的任务（如重命名变量），完整的规则检查可能显得冗余。	保持规则启用。它的开销极小，却能防止“小修改引发大问题”。如果你确信任务简单，可以在指令中开头就说明：“这是一个简单的重命名，请快速完成，无需详细分析依赖。”

5.3 性能与成本考量

• Token消耗 ：主 rules.md 文件约2500个Token。在每次对话开始时，这些Token会作为系统提示词被计入上下文。对于支持128K或更大上下文的模型（如Claude 3），这个开销微不足道。参考文件仅在需要时加载，进一步控制了成本。
• 响应速度 ：规则的存在会让AI在生成代码前进行更多的“思考”，可能会略微增加首次响应的时间（几百毫秒到一秒）。但考虑到它避免的后期调试和返工时间，这点延迟是绝对值得的。
• 最佳实践 ：对于超大型项目，如果发现AI因上下文太长而性能下降，可以考虑对 rules.md 进行精简，只保留最核心的防失败规则（如1-5条），这能在大幅提升安全性的同时，将Token消耗降到最低。

在我近两个月的实践中， dev-rules 已经从一个实验性工具变成了我开发环境中的标准配置。它无法100%杜绝AI犯错，但将那些低级、恼人且耗时的错误减少了大约80%。它最大的价值在于，将我与AI的协作模式从“我写提示词 -> AI生成代码 -> 我审查并修复问题”的循环，转变为了“我定义规则 -> AI在规则内生成更可靠的代码 -> 我进行更高级别的设计审查”。这种转变，才是真正将AI编程助手变为高效、可信赖的结对编程伙伴的关键。