我的 Cursor Rules，用于约束 AI 编码助手的行为规范。
从多个真实项目中沉淀而来，解决的核心问题：AI 写代码很快，但没有规矩就容易返工、漏改、搞砸。
| 文件 | 用途 | 是否上传 git |
|---|---|---|
rule-opensource.mdc |
主开发规范（完整版，覆盖全流程） | ✅ |
writing-style.mdc |
中文写作风格规范（适用于文案/Prompt 生成场景） | ✅ |
secrets.mdc |
API Key、服务器凭据、调用示例模板（占位符，需自行替换真实 Key） | ✅ |
.gitignore |
排除敏感文件 | ✅ |
rule-opensource.mdc 共 14 个章节。下面逐段解释：遇到了什么问题、为什么这样设计、有没有别的做法。
每次新开对话，AI 不知道该调哪个模型、端点是什么、超时设多少。尤其图像生成类 API 经常因为默认 30 秒超时而失败，AI 还会反复尝试相同的错误配置。
把模型选型、超时、代理等环境事实一次性写死在 Rule 里，AI 每次对话自动带入上下文，不用重复交代。相当于给 AI 一份预填好的 .env 说明书。大部分人只在对话里临时告诉 AI 用什么模型，对话一长就忘了，或者新开对话又要重说一遍。也有人把配置写在 .env 文件里让 AI 自己读，但 AI 不一定每次都主动读。Rule 是最稳的注入方式，因为它在每轮对话开始前就被加载进上下文。
AI 拿到需求就开始写代码。写了 200 行后发现理解有偏差，回滚重来。更糟的是改了 7 个文件之后才发现思路错了，逐个 revert 成本极高。
所以强制执行「复述 → PRD → 等确认 → 编码」四步流程，本质上是把软件工程的需求确认环节搬到了人机协作里。另外「修改超过 3 个文件先列计划」是为了在批量变更前设一个人工断点，控制爆炸半径。社区里常见的做法是写一句「请先确认理解后再编码」，但这太模糊了，AI 会自己判断「我已经理解了」然后直接动手。必须给出具体步骤（写 PRD、等待许可），AI 才会真的停下来。实际使用中，简单的一行改动 AI 会自己判断不需要 PRD，这个流程主要拦截的是多文件变更和新功能开发。
UI 功能直接写进页面后，发现动效/样式不对时改一处影响一片，调试时要把整个页面跑起来才能看到一个按钮的效果。
强制先做独立的组件 PlayGround，每个 UI 元素有单独的 demo，调好了再集成进正式页面。Storybook 是行业标准方案，但配置太重，对于 AI 辅助的快速原型项目 overkill 了。PlayGround 就是一个简化版的 Storybook 思路：一个页面把所有组件 demo 排在一起，改组件不影响业务逻辑，调业务逻辑不搞乱组件样式。
AI 生成 UI 时会用 emoji 做按钮、用随机图标库、不处理输入法回车。这些都是细节，但用户体验会因此变得粗糙。
把品味层面的决策固化成规则。比如「Tabler Icons + stroke 1.5」是经过筛选后确定的视觉标准，写进 Rule 后 AI 每次都会遵循，不用每次对话再指定。isComposing 单独拎出来是因为 CJK（中日韩）输入法的回车确认问题，几乎所有用 AI 写聊天输入框的项目都会踩这个坑。AI 的训练数据里 isComposing 覆盖率不高，不在 Rule 里强调就一定会忘。
做 Agent 工具调用时，JSON 嵌套深了容易被 LLM 搞乱括号配对，尤其是字符串里再包含 JSON 时会造成 escape hell。XML 标签闭合更直观，LLM 出错率更低。
Agent 工具调用统一用 XML，数据存储用 YAML，REST API 用 JSON，三种格式各管一个领域，互不混用。主流 Agent 框架（LangChain、CrewAI）默认用 JSON，但 Anthropic 的 Claude 系列在 XML 格式上表现更稳定（Claude 自身的 system prompt 就大量使用 XML）。如果你的项目只用 GPT 系列，JSON 可能更合适，因为 GPT 的 function calling 原生就是 JSON。这条规则是基于多模型混用场景的最大公约数选择。
AI 在不同对话里会选不同框架。今天用 Express，明天用 Fastify，后天觉得 Hono 更好。数据库也是，一会儿 MongoDB 一会儿 PostgreSQL。
锁定技术栈，一旦决定了用什么就不再讨论替代方案。AI 的职责是在确定的技术栈内把代码写好，选型决策是人做的。「避免 5000 端口，随机分配 8000-9000」是因为同时开着多个项目，固定端口必然冲突。让 AI 每次随机选一个，不用人去记哪个项目占了哪个端口。
AI 写的注释全是无意义复述（// 遍历用户列表、// 返回结果）。三个月后回来看代码，完全不知道当初为什么这样实现。另一个问题是 AI 重构时会顺手删掉它认为多余的代码，事后才发现那段代码有用。
注释规范要求写「背景 + 设计意图 + 关键约束」三要素，这是代码本身无法传达的信息，只有写在注释里才能跨时间留存。删除代码必须显式声明，是为了防止 AI 的善意清理变成破坏性操作。Google 的代码规范也有类似要求（注释解释 why，不解释 what），但大部分人的 Cursor Rule 里只写「写好注释」四个字，太模糊了，必须给出具体的三要素结构和示例，AI 才能执行到位。
AI 遇到报错后的第一反应是猜一个可能的原因然后改代码试试，改了不行就再猜一个。三轮下来代码已经面目全非，原始 Bug 反而被掩盖了。
强制「先加 Log → 定位根因 → 再改代码」的流程，这就是人类 debug 的正确姿势，AI 也必须遵循。「禁止猜测性修复」是最核心的一条：AI 修 Bug 的默认行为就是猜测性修复，因为这样看起来效率高。但实际上猜错一次的返工成本远大于花 2 分钟加 Log 确认根因。修复后声明影响范围是为了让人知道需要回归测试哪些地方。
做了 30 个功能，三个月后想查「某个功能是什么时候加的」「当时为什么这样设计」「中间方案改过几次」，翻遍 git log 也找不到。Changelog 积压了半个月才补写，时间和细节全不准。
三份文档各管一个维度：FEATURES.md 记录功能的完整生命周期（从想法到上线，包括中间每次方案变更）；CHANGELOG.md 记录每次代码改动的技术细节（问题、根因、影响面）；RELEASE_NOTES.md 面向用户，只写用户能感知的变化。三份文档格式都做了严格模板约束，AI 按模板填写就行，不需要每次想该写什么字段。FEATURES 要求记录历史沿革是为了解决「当初为什么放弃了 A 方案」这种跨时间的决策追溯问题，只靠 git log 和 commit message 做不到。
发版时以为只改了 A 功能，实际 diff 里混进了上周调试 B 功能时的临时改动，上线后半成品代码出现在生产环境。
发版前强制做 diff 审查，独立跑一遍「Release Notes 描述的改动」vs「实际 diff 里的改动」，有差异就暂停报告。这相当于一个自动化的 code review checklist。正规团队用 CI/CD + PR review 解决这个问题，但独立开发者或小团队用 AI 辅助开发时往往跳过 PR review 直接 push。这条规则是在没有 reviewer 的情况下，用 AI 充当 reviewer 的角色。
AI 非常喜欢分期交付。你说要做一个完整的认证系统，它会说「我们先做一个简版的用户名密码登录，后续再加 OAuth」。结果后续永远不会来，简版代码成了永久的技术债。
不接受分期。要么给出完整方案和工作量评估，要么明确说「这个太复杂，需要你做哪些前置决策」。把选择权交给人，但不允许 AI 自作主张降级方案。这条规则在大型项目里可能显得激进，如果一个功能真的需要 2000 行代码，一次性全写完确实不现实。但实践中，AI 说「先做简版」往往不是因为复杂度高，而是因为它想快速给你一个能跑的东西来获得正反馈。打破这个模式后，AI 反而会更认真地分析完整方案。
和 AI 讨论产品设计时，会产出很多有价值的决策（为什么选 A 方案不选 B、用户体验上偏好 X 风格）。但这些散落在聊天记录里，下次新开对话又要重新解释一遍。
让 AI 主动识别对话中的方法论内容，提炼后写入 METHODOLOGY.md，项目会逐渐积累一份产品设计决策手册，新对话自动继承这些共识。大部分人把设计决策写在 Notion 或飞书文档里，但 AI 读不到这些外部文档。放在项目仓库内的 Markdown 文件是唯一能让 AI 自动获取上下文的方式。
对话超过 20 轮后，AI 会忘记早期的约定。比如开头说了「用 PostgreSQL」，聊了 30 轮后它突然建议你用 SQLite，因为当前上下文窗口里 PostgreSQL 那句话已经被截断了。
超过 10 轮后强制复述当前目标和关键约束，相当于给 AI 一个周期性的 checkpoint，防止上下文窗口截断导致的认知漂移。这条规则在模型上下文窗口越来越大后可能不再那么必要，但即使是 200K token 的模型，attention 在长文本尾部的衰减也是真实存在的，强制复述是一个低成本的保险措施。
AI 生成的中文文案有明显的「AI 腔」：大量使用「不是 A，而是 B」对比句式、过度使用省略号和破折号、喜欢加情绪评价（「非常有道理」「真的很震撼」）。
写作规范独立成文件，设为 alwaysApply: false，只在需要写文案或 Prompt 时手动引用，避免污染编码对话的上下文。大部分人在 prompt 里写「请用自然流畅的中文」，但这太含糊了，AI 认为的自然和你认为的自然可能完全不同。必须给出具体的违禁模式列表（哪些词禁用、哪些句式禁用），AI 才能精确执行。
- 将
.mdc文件放入你项目的.cursor/rules/目录下 - 根据需要修改 frontmatter 中的
alwaysApply字段：true：所有对话自动生效false：需要手动 @ 引用时才生效
- 按自己的项目情况替换模型配置、技术栈等内容
这套规则不是拿来即用的模板，而是一个思路参考。你应该：
- 删掉不适合你的章节：比如你不做中文内容创作，就不需要写作规范
- 替换技术栈声明：把 React / FastAPI / SQLite 换成你自己的选型
- 调整严格程度：比如「修改超过 3 个文件才确认」，你可以改成 5 个或 1 个
- 补充你自己的踩坑经验：每发现一次 AI 反复犯的错误，就加一条规则
规则的价值不在于多，而在于每条都解决一个真实问题。
我们正在做 AI 陪伴方向的产品。如果你对 AI Agent、Rust、Tauri、React 这些技术栈感兴趣，欢迎看看我们的招聘页面：
MIT