用项目规则约束 AI 编程助手的改动

让 AI 修一个小问题，结果它顺手重构了几个文件；接口能用了，却漏掉了数据归属校验；测试报错，最后被「修」成跳过。这篇文章把这些常见事故归因于一件事：项目没有明确告诉编程代理，哪些边界不能碰。

作者提供了一套免费、采用 MIT 许可证的 vibe-coding-rules-starter，用 AGENTS.md 统一规则，再让 Cursor 和 Claude Code 加载。它值得参考的地方，是把「写好代码」拆成了可执行、可检查的约束。不过，原文没有提供事故率下降的对照数据，效果仍需结合项目验证。

先规定冲突时听谁的，再谈怎么写代码

作者把规则分成四层：安全边界最高，其次是用户要求的任务，再往下是仓库已有的技术栈约定，最后才是工作风格。发生冲突时，代理还要说明自己遵循了哪一层。

这个顺序解决的是代理经常遇到的选择题。用户说「赶紧让它跑起来」，是否允许绕过权限检查？任务需要改动几个文件，是否每一步都得确认？按照模板，任务明确需要的修改已经获得授权，但必须留在安全边界内；需要确认的事项放进「Needs your OK」。

把选择过程写进回复，才能让人看见代理有没有误解任务。

作者建议把完整规则集中放在 AGENTS.md，其他工具文件引用它，减少多份规则各改各的风险。原文把 AGENTS.md 称为最接近共享标准的方案，也提到了 Copilot、Windsurf，但具体接入说明只覆盖 Cursor 和 Claude Code，不能据此认为所有工具的加载行为都一致。

安全规则要写到接口和环境变量这一层

「注意安全」太宽泛，代理很难据此决定某一行代码该怎么写。作者给出的规则直接落到了公开变量前缀、身份认证和数据授权：

- Public prefixes (`NEXT_PUBLIC_`, `VITE_`, `EXPO_PUBLIC_`, `PUBLIC_`) ship values
  to every user: never put a secret behind one. Work that needs a secret moves
  to a server or edge function.
- Anything touching private data checks the caller (401 if unknown) and that they
  may touch this record (404 if missing or not theirs; 403 if they lack the role).
  Hiding a button isn't security.
- Admin features need sign-in plus a role stored in the database and checked on
  the server, never a client flag or hard-coded emails or IDs.

最该盯住的是第二条：检查用户登录，还要检查他是否有权访问当前记录。否则，用户只需修改 URL 中的 ID，就可能读到别人的数据。模板规定，身份未知返回 401，记录不存在或不属于调用者返回 404，缺少角色权限返回 403。

登录检查只能回答「你是谁」，记录授权才回答「这份数据你能不能碰」。

对前端开发者，第一条同样直接。给变量加上 NEXT_PUBLIC_、VITE_、EXPO_PUBLIC_ 或 PUBLIC_，不能用来保护密钥。需要秘密凭据的调用，应移到服务端或 edge function。管理员身份也不能靠隐藏按钮、客户端标志，或硬编码邮箱和 ID 判断，模板要求在服务端校验数据库中的角色。

另一类规则限制代理自行采取的动作：未经明确要求，不得执行 rm -rf、git reset --hard、git push --force，不得删表、重置数据库或修改远程及生产数据库，也不能通过跳过测试、放松 lint 和类型检查换取通过。安装新依赖需要确认，并先核对包的准确名称，防止装入拼写仿冒包。

限制改动范围，也要限制失败后的继续尝试

原文认为，很多项目损坏来自任务范围失控。对应的要求很朴素：不重命名、不格式化、不整理无关代码；优先做最小修改；不要整份重写正常工作的文件；不要编造 API、包名和路径，使用前检查已安装版本的文档。

调试流程则是：复现问题，读完整错误，说明可能原因，再做最小修复。连续两次失败后停止，汇总接下来的两个选项，而不是继续猜。

这里的「两次」是一条工作约定，作者没有证明它适合所有任务。它的作用是强制重新审视问题，避免每次都在前一次猜测上继续叠补丁。

模板还要求，涉及超过两个文件的任务先写短计划，等待确认；后台代理无法询问时，把计划放在最终摘要顶部。后者只能留下记录，不能提供事前审查，这个差别需要团队自己权衡。

交付报告也有固定内容：改了什么、改了哪些文件、执行了哪些命令及其结果、用户如何验证，以及「Needs your OK」中的风险和未完成事项。原文用「运行 npm test，41 项通过，lint 因某个原因未执行」示范报告粒度，这不是作者实测得到的 41 项测试结果。

文件放进去，还要确认工具确实读到了

按照原文说明，Cursor 会自动读取 AGENTS.md；模板另用 .cursor/rules/security.mdc 和 alwaysApply: true，让安全规则持续进入对话。Claude Code 则通过 CLAUDE.md 中的 @AGENTS.md 导入完整规则，同时重复关键安全要求，作为文件缺失或内容被截短时的补充。

下面这组命令用于在项目根目录复制模板：

git clone --depth 1 https://github.com/theodorecreatesco/vibe-coding-rules-starter.git /tmp/vcrs
cp /tmp/vcrs/AGENTS.md /tmp/vcrs/CLAUDE.md .
mkdir -p .cursor/rules && cp /tmp/vcrs/.cursor/rules/security.mdc .cursor/rules/

要留心第二行：已有 AGENTS.md 或 CLAUDE.md 时，不应直接覆盖。作者要求把模板中 BEGIN 和 END 标记之间的内容合并到现有文件顶部。

接入后，新开对话询问项目的最高优先级规则，检查回答是否提到优先级和安全边界。若没有，先检查文件是否位于项目根目录，以及隐藏的 .cursor 文件夹是否复制完整。能复述规则可以帮助排查加载问题，但还不能证明代理会在复杂任务中始终遵守。

分享应用前，仓库还提供一份 10 项检查清单，包括将 .env 和 .env.* 加入 .gitignore，让 .env.example 只保留变量名；运行 git check-ignore -q .env.local 应得到退出码 0；检查每个 API route、server action 和 edge function 的身份与记录授权；为 OpenAI、Anthropic 等付费 API 和托管服务设置额度或告警。另有密钥扫描提示词，要求检查仓库及可访问的 Git 历史，且不打印密钥值。

我的判断

我赞成把它当作团队协作约定的起点。相比一句「遵守最佳实践」，明确的变量前缀、授权条件和交付报告，更容易执行，也更方便审查。

但作者没有提供不同模型、工具或项目的对照数据，「能解决大部分损害」仍是经验判断。规则文件能影响代理行为，实际约束还要靠代码审查、自动检查和权限控制。

两个阈值也不宜照搬。跨三个文件的小修复可能很普通，复杂故障也可能需要多次验证。更合理的取舍，是保留「扩大范围先说明、连续失败先复盘」的意图，再按团队工作方式调整数字。

原文最后还推介了付费 Vibe Coding Rules Kit，列举 Next.js + Supabase、Lovable、Bolt、FastAPI、Expo 等适配方向，但没有展开其实现，免费模板的判断不必与付费产品绑定。

能拿来做什么

• 给现有 AGENTS.md 补上规则优先级、最小修改要求和交付报告格式；已有项目约定时先合并，避免复制模板覆盖原规则。
• 检查前端项目中的公开环境变量，把携带密钥的调用移到服务端，并逐个审查接口是否同时验证身份和记录访问权限。
• 给日常 AI 调试设置复盘节点，连续两次修复失败后，要求代理列出完整错误、已尝试方案和后续两个选项，再决定下一步。
• 分享应用前执行环境文件忽略检查，并审查认证、支付和个人数据相关代码；让代理报告实际运行的命令与结果，未执行的检查明确写出原因。