在微服务架构向多仓库演进的过程中，团队内部沉淀了数十条隐性的编码约束。例如，日志必须使用统一的 `tracing` crate，错误处理需遵循 `Result
一、规则文件的目录结构与优先级机制
Cursor 的规则系统采用分层加载策略，确保在不同作用域内指令的准确性。规则文件主要分布在三个层级：全局用户级、项目根目录级以及特定目录级。理解这些层级的加载顺序，是避免规则冲突的前提。
全局规则位于 `~/.cursor/rules/`，适用于当前用户的所有项目，适合定义通用的语言偏好，如强制使用 4 空格缩进或特定的注释风格。项目级规则存放在项目根目录的 `.cursor/rules/` 中，这是团队协同开发的核心载体，用于固化架构约束。当用户打开特定文件夹时，该文件夹下的局部规则会被优先加载，覆盖全局和项目级配置。
优先级遵循“就近原则”。若全局规则要求使用 `snake_case` 命名，而项目级规则强制使用 `camelCase`，在项目目录下工作时，项目级规则生效。这种机制允许团队在保持个人开发习惯一致性的同时，严格约束项目代码质量。对于大型 Monorepo，建议在子模块目录下创建独立的 `.cursor/rules`，以实现域驱动的规则隔离。
二、编写基础规则：从自然语言到结构约束
规则文件的本质是 Prompt 的固化。早期的 Cursor 版本仅支持 `AGENTS.md`，而新版引入了更细粒度的 Markdown 规则文件。编写有效的规则，关键在于“明确性”与“可执行性”。模糊的指令如“代码要简洁”是无效的，具体的约束如“函数体不超过 50 行，超过则需拆分”才是可被模型精准执行的。
# .cursor/rules/golang-style.md
# 规则名称：Go 语言风格规范
# 适用语言：go
## 核心约束
1. **错误处理**：所有返回 error 的函数必须检查 error，禁止使用 `_ = xxx()` 忽略非预期错误。
2. **命名规范**：
- 导出标识符使用 PascalCase。
- 局部变量和函数参数使用 camelCase。
- 包级常量使用 PascalCase，局部常量使用小写。
3. **注释**：每个导出函数必须包含 Doc 注释，说明入参、返回值及可能的 Panic 场景。
## 代码示例（Few-Shot）
// 禁止：
// func GetID() string { ... } // 无注释
// 允许：
// // GetID 返回当前会话的唯一标识符。
// // 如果会话不存在，返回 error。
// func GetID() (string, error) { ... }在上述示例中，采用 Markdown 格式清晰界定章节。通过提供“禁止”与“允许”的代码对比（Few-Shot Learning），模型能更准确地理解边界。注意，规则文件应尽量短小精悍，过长的规则会挤占上下文窗口，降低对代码库的感知能力。
三、项目级规则：注入架构约束与依赖规范
在复杂项目中，架构约束往往比语法风格更重要。例如，禁止在 `controller` 层直接调用 `database` 包，必须经过 `service` 层。这类依赖关系无法通过简单的命名规范体现，需要明确的包层级规则。
# .cursor/rules/architecture.md
# 规则名称：分层架构约束
# 触发条件：始终（Always）
## 依赖方向
严格遵循 DDD 分层依赖：
1. Controller (API) -> Service (Business Logic) -> Repository (Data Access)
2. 禁止 Service 直接引用 Controller 中的 DTO。
3. 禁止 Repository 包含业务逻辑，仅处理 CRUD 与 SQL 映射。
## 外部服务集成
- 所有 HTTP 客户端必须通过 `internal/clients/` 包统一管理。
- 禁止在业务代码中直接硬编码 URL，必须通过 `config` 包加载。
- 重试机制必须使用 `pkg/retry` 工具包，禁止手动循环 sleep。
## 禁止事项
- 禁止使用 `os.Exit()` 或 `panic()` 终止程序，必须返回 error 由顶层中间件处理。
- 禁止在循环内进行数据库查询（N+1 问题），必须使用批量操作。这类规则通常标记为“Always”应用，即在整个项目编辑过程中持续生效。通过明确禁止项，可以大幅减少 AI 生成代码后的 Review 工作量。特别是对于 N+1 查询等性能隐患，显式的规则约束能确保生成的数据访问层代码符合团队的高并发标准。
四、对比：规则文件与上下文引用的差异
许多开发者倾向于在对话框中手动 @ 引用文件，而非编写规则文件。两者有本质区别：手动引用是临时的、易忘的；规则文件是持久的、自动化的。下表对比了两种方式的适用场景：
| 维度 | 手动上下文引用 (@) | 规则文件 (.cursor/rules) |
|---|---|---|
| 持久性 | 单次会话有效，刷新后消失 | 持久化，跨会话生效 |
| 适用场景 | 特定任务的临时约束、复杂架构设计探索 | 通用编码规范、团队风格统一、合规检查 |
| 维护成本 | 低（无需维护） | 高（需随架构演进定期更新） |
| 触发方式 | 用户主动注入 | 基于语言/文件夹/Always 自动注入 |
| 推荐程度 | 用于探索性任务 | 用于日常生产代码编写 |
最佳实践是混合使用：将稳定的团队规范写入规则文件，而将当前迭代的特殊需求（如本次需求特有的接口字段）通过手动 @ 引用传入。这种组合拳能最大化 AI 的贴合度。
五、高级技巧：基于文件路径的条件规则
并非所有规则都适用于全项目。例如，`frontend` 目录下的代码需要遵循 React 18 的 Hook 使用规范，而 `backend` 目录则遵循 Go 1.21 规范。Cursor 支持基于 glob 模式的路径匹配规则，实现更精细的控制。
# .cursor/rules/frontend-react.md
# 规则名称：React 前端规范
# 匹配路径：frontend/**/*.{js,ts,tsx}
## Hook 使用规范
1. 所有自定义 Hook 必须以 `use` 开头。
2. 禁止在组件渲染期间修改 ref。
3. 使用 `useMemo` 包裹计算密集型纯函数，避免重复计算。
4. 列表渲染必须提供唯一的 `key`，禁止使用 index。
## 样式规范
- 使用 CSS Modules，禁止全局 class。
- 颜色值必须引用 `styles/variables.css` 中的变量，禁止硬编码 Hex 值。当光标位于 `frontend` 目录下时，上述规则自动加载；切换到 `backend` 目录时，该规则失效，转而加载后端规则。这种隔离机制在多技术栈项目中尤为重要，避免了前端规则干扰后端代码生成。
六、规则调优与反馈闭环
规则文件不是一次性的文档，而是需要迭代进化的资产。常见的调优方法包括：观察 AI 生成的代码是否频繁违反某条规则，若是，说明规则描述不够清晰或权重不够。
例如，若 AI 频繁忘记添加错误日志，可在规则中增加“必须记录上下文变量”的具体示例。此外，团队应建立规则审查机制，当架构变更（如引入新的消息队列）时，及时更新 `.cursor/rules/architecture.md`，确保 AI 不会生成过时的代码模式。对于涉及安全合规的规则，建议结合 Lint 工具进行双重校验，AI 生成代码后自动运行 `golangci-lint`，将报错反馈给 Cursor 进行修复，形成自动化闭环。
七、团队协作与版本管理
规则文件应纳入 Git 版本管理。在 `.gitignore` 中保留 `.cursor/rules` 目录，确保团队成员共享同一套规范。对于个人偏好，可使用 `.cursor/rules.local/` 目录，并将其加入 `.gitignore`，实现公私分离。在代码审查（Code Review）过程中，若发现 AI 生成的代码违背团队规范，审查者应直接指出对应的规则条款，促使开发者修正规则或改进提示，而非仅仅修改代码。这种“治本”的思维模式，能逐步减少 AI 幻觉，提升团队对 AI 辅助工具的信任度。在涉及复杂逻辑的领域，如构建带记忆的状态机管理客服会话，规则的精细化定义尤为关键，参考 用 LangGraph 构建带记忆的状态机管理客服会话 可理解状态转换中的规范约束。
八、小结：从工具到标准的跃迁
Cursor 规则文件的核心价值，在于将隐性的团队知识显性化、结构化。它不仅仅是 AI 的配置文件，更是团队工程标准的数字化映射。通过合理设计全局、项目、局部三层规则，并结合路径匹配与条件触发，开发者可以显著降低代码风格不一致带来的维护成本。在本地化部署大模型的场景下，如 用 Ollama 本地部署 Qwen2 并接入 LangChain 实现离线知识库问答，定制化的规则文件还能增强模型对内部领域术语的理解，实现更精准的上下文对齐。持续迭代规则文件，使其成为团队代码质量的守门人，是提升 AI 辅助编码效率的必经之路。对于希望在本地环境中深入实践工作流编排的开发者，建议阅读 用 Dify 本地编排 RAG 与代码 Agent 工作流，进一步探索规则与自动化流程的结合点。
