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最常“翻车”的场景。我挑选几条最具代表性的进行解读作用域控制要求AI在修改代码时必须明确识别并限定更改的影响范围。例如修复一个工具函数时不能想当然地改动调用它的业务逻辑代码。这条规则强制AI进行“影响分析”避免了“修东墙、拆西墙”的连锁反应。测试完整性保护直接回应了“AI削弱测试以让其通过”的问题。规则要求绝对禁止为了通过测试而修改测试断言或简化测试逻辑。如果测试失败了AI必须首先假设是生产代码有问题并优先修复生产代码。只有在我明确指示后才能审查并修改测试本身。跨文件一致性这是防止“破坏依赖文件”的关键。规则规定当修改一个被其他文件导入import/require的模块如函数、类、常量时AI必须列出所有直接引用该模块的文件并计划好同步更新。在提交更改前必须验证这些引用文件依然能正常工作。信任验证针对“API幻觉”。规则要求对于任何第三方库、API或环境变量的使用AI不能仅凭记忆或推测。它必须引导我去官方文档进行快速确认或者在代码中添加// TODO: Verify API endpoint这样的注释。对于关键依赖甚至建议先写一个最小的验证脚本。格式保持在重构或自动格式化代码时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 Codecp rules.md ~/.claude/rules/dev-rules.md对所有项目全局生效Cursorcp rules.md .cursor/rules/dev-rules.md仅对当前项目生效Windsurfcp rules.md .windsurf/rules/dev-rules.md对当前项目生效GitHub Copilot将rules.md内容追加到.github/copilot-instructions.md文件末尾对当前项目生效Aidercp rules.md CONVENTIONS.md对当前会话生效注意事项对于Cursor和Windsurf这类项目级配置的工具建议将rules.md提交到项目仓库中这样所有克隆该仓库的团队成员都能自动获得相同的AI规则约束有利于统一代码质量。对于Claude Code的全局配置它会影响你所有的项目适合个人开发者建立统一的编码标准。4.2 进阶配置启用深度参考文件如果你希望获得关于安全、运维等领域的深度防护可以启用可选的参考文件。克隆仓库并复制文件# 临时克隆到 /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理解加载机制完成以上操作后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编程助手变为高效、可信赖的结对编程伙伴的关键。