直接回答
团队级 Cursor 配置应该是一组有作用域、可版本化、可测试的规则,并连接真实仓库证据与确定性交付控制。Rules 可以帮助模型找到约定和检查要求,却不能授予访问权、保护密钥、证明正确性或替代 CI 与 Review。
最易维护的结构是一份供应商无关的单一事实源,加上薄的 Cursor Adapter。不要把同一条策略复制进 Legacy .cursorrules、多个 .mdc、AGENTS.md 和 Wiki,再让这些副本静默漂移。
先理解当前 Rule 类型
当前 Cursor Rules 官方文档定义了四种规则入口:
| 类型 | 存储与作用域 | 合适用途 |
|---|---|---|
| Project Rules | .cursor/rules/*.mdc,受 Git 管理 |
仓库或文件特定约定 |
| User Rules | Cursor 用户配置 | 个人沟通偏好 |
| Team Rules | Team Dashboard,可选或强制 | 组织级要求 |
AGENTS.md |
根目录或子目录的纯 Markdown | 可移植的项目与目录指令 |
Project Rules 可以始终生效、按文件 Glob 生效、由 Agent 根据 Description 选择,或手动启用。.cursor/rules 中的普通 .md 文件不是 Project Rule;当前文档要求 .mdc 扩展名和 Frontmatter。根目录 .cursorrules 已属于 Legacy。
这些是产品契约,不是永久不变的文件语义。应在内部兼容记录中固定 Cursor 版本或核验日期,并在产品更新后重跑激活测试。
保持单一事实源
按所有者划分规则:
| 信息 | Canonical Owner | Cursor Adapter |
|---|---|---|
| Build 与 Test 命令 | Package Script 或构建文档 | 引用命令 |
| API 与数据契约 | Schema 与生成类型 | 链接权威文件 |
| 安全策略 | CI、Sandbox、IAM、分支保护 | 说明期望行为 |
| 架构决策 | 已审阅 Decision Record | 指向当前决策 |
| 文件特定约定 | 模块文档与示例 | Scoped .mdc Rule |
| 个人回答风格 | 个人 | User Rule |
格式能由 Linter 强制时使用 Linter;写操作能由 IAM 拒绝时使用 IAM。Rules 应携带模型做决策所需的信息,而不是重复软件已经能执行的控制。
设计聚焦的 Project Rules
一条 Project Rule 应该具备:
- 单一目的;
- 明确激活方式;
- 尽可能窄的文件作用域;
- 可观察要求;
- Canonical Example 链接;
- 验证与升级行为。
例如:
---
description: "Billing API contracts and verification"
globs: "services/billing/**/*.go"
alwaysApply: false
---
- 编辑前读取 `services/billing/contract.go` 和相邻测试。
- 每次对象查询都保留 Tenant 与 Principal 检查。
- 复用现有 Domain Error 类型。
- 每个行为变更都增加回归测试。
- 运行 `go test ./services/billing/...` 验证。
- 任务与已提交契约冲突时停止并报告。
Frontmatter 决定 Cursor 何时把文本加入上下文,却不会强制执行正文要求。Protected Branch 和 CI 仍需拒绝删除授权或跳过测试的变更。
避免模糊规则
弱规则:
始终编写生产级代码,绝不引入 Bug。
可测试规则:
修改 services/payments 时:
- 保持公开请求与响应 Schema;
- 从认证上下文获取 Account Ownership;
- 增加 Duplicate、Timeout 与 Unauthorized 测试;
- 运行 `go test ./services/payments/...`;
- 报告未运行的检查。
“整洁”“最佳”“简单”“安全”都需要可观察定义,否则模型只能猜测。
用 AGENTS.md 承载可移植指令
当同一份仓库规范需要同时供人和多个兼容 Coding Agent 阅读时,AGENTS.md 很合适。当前 Cursor 文档支持根目录和嵌套文件,更具体的子目录规则应用于其目录范围。
根文件可以这样写:
# Repository instructions
## Source of truth
- Public API contracts live under `api/`.
- Generated files under `gen/` are never edited manually.
## Required checks
- Run `go test ./...`.
- Run `golangci-lint run`.
- Report failures and skipped checks.
## Change boundaries
- Do not change dependencies, migrations, or deployment without approval.
- Never read or print secret files.
services/payments/AGENTS.md 可以增加支付模块约束,但不要重复根文件。重复会制造不清晰的优先级,并提高更新成本。
把 Prompt 模板写成工作契约
可复用模板应该定义输入与验收,不是模仿高级工程师的 Persona。
回归测试模板
目标:
为选中函数补充测试。
读取:
实现、现有测试、公开契约与错误类型。
覆盖:
正常路径、边界、已记录失败与本次回归。
约束:
不修改生产行为,不新增依赖。
不 Mock 被测单元本身。
证据:
报告修改文件与实际执行命令。
没有命令输出时,不声称覆盖或成功。
升级:
依赖缺失、契约冲突或行为不可观察时停止。
重构模板
目标:
改善选中代码,不改变可观察行为。
编辑前:
找出 Caller、副作用、并发假设和现有测试。
证明:
行为未覆盖时先增加 Characterization Test。
必要时比较 API、持久化、日志、指标与顺序。
停止:
需要破坏性变更,或没有可靠 Oracle 时停止。
“不要改变行为”不会自我验证。模板必须指向能让行为可观察的测试或其他 Oracle。
把安全控制放在 Prompt 之外
Rules 可以帮助 Agent 配合策略,但可信系统必须强制:
- 仓库、分支、目录与命令权限;
- Secret 隔离与脱敏;
- 网络目的地与 Tool Allowlist;
- Sandbox 与资源限制;
- Push、Merge、Deploy、Delete 和外部写入审批;
- 必需测试、Review 与签名制品;
- 审计事件和事故响应。
NIST SSDF把安全开发实践放进完整软件生命周期。模型上下文中的一句话无法替代这些控制。
Issue 文本、源码注释、终端输出、文档和生成计划都可能携带恶意指令。它们只能作为当前任务下的证据,不能升级成更高优先级策略。
测试 Rule 激活与结果
需要两类测试。
激活测试
验证:
- Always Apply Rule 出现在所有预期 Agent 会话中;
- Glob Rule 只在匹配文件时生效;
- Agent-selected Rule 的 Description 足够准确;
- Manual Rule 未被请求时不会出现;
- 嵌套
AGENTS.md只应用于预期子树; - Team、Project 与 User 冲突按当前文档解决。
不能因为文件存在于 Git,就假设它已被加载。
结果测试
回放代表性任务并检查:
- 修改文件保持在 Scope 内;
- Protected File 与 Dependency 未发生变化;
- 必需测试确实执行;
- 未尝试越权或破坏性动作;
- 缺失证据被明确报告;
- Diff 满足业务 Oracle;
- 无关 Rule 没有增加错误或成本。
可运行的 Go 结果门禁
下面的无依赖程序根据确定性仓库策略检查已记录的 Agent Run。真实 Harness 应从 Sandbox 与 CI 写入 Observation,而不是相信模型摘要。
package main
import (
"fmt"
"path/filepath"
)
type Observation struct {
ChangedFiles []string
CommandsRun map[string]bool
ExternalWrites int
ReportedSuccess bool
}
type Contract struct {
AllowedRoot string
RequiredCommands []string
MaxExternalWrites int
}
func evaluate(contract Contract, observed Observation) []string {
var violations []string
for _, file := range observed.ChangedFiles {
relative, err := filepath.Rel(contract.AllowedRoot, file)
if err != nil || relative == ".." ||
len(relative) >= 3 && relative[:3] == "../" {
violations = append(violations, "out_of_scope:"+file)
}
}
for _, command := range contract.RequiredCommands {
if !observed.CommandsRun[command] {
violations = append(violations, "missing_check:"+command)
}
}
if observed.ExternalWrites > contract.MaxExternalWrites {
violations = append(violations, "external_write_budget_exceeded")
}
if observed.ReportedSuccess && len(violations) > 0 {
violations = append(violations, "unsupported_success_claim")
}
return violations
}
func main() {
contract := Contract{
AllowedRoot: "services/billing",
RequiredCommands: []string{"go test ./services/billing/..."},
MaxExternalWrites: 0,
}
observed := Observation{
ChangedFiles: []string{"services/billing/handler.go"},
CommandsRun: map[string]bool{"go test ./services/billing/...": true},
ExternalWrites: 0,
ReportedSuccess: true,
}
violations := evaluate(contract, observed)
fmt.Printf("accepted=%t violations=%v\n", len(violations) == 0, violations)
}
预期输出:
accepted=true violations=[]
代码检查的是证据,不是措辞。生产实现还应验证命令 Exit Status、Commit Identity、Sandbox Provenance 与 Artifact Hash。
像代码一样版本化、Review 和回滚
Rule 变更流程:
- 写清它要修复的重复失败;
- 确认负责人和作用域;
- 新增或更新 Replay Fixture;
- 在相同任务上比较新旧 Rule Bundle;
- 检查回归与无关激活;
- 通过 Pull Request 审查;
- 先在小团队或少量仓库灰度;
- 任务成功、审查成本、安全、时延或费用回归时回滚。
记录:
{
"client": "cursor",
"client_version": "recorded-version",
"model": "provider/model@revision",
"rule_bundle": "git-commit",
"fixture_set": "coding-rules-v6",
"result": "canary",
"known_gaps": ["windows-shell", "large-monorepo"]
}
建议被接受不等于工作成功。应测量通过检查并合并的变更、合并后缺陷、不必要改动、Reviewer 时间、事故与 Revert。
谨慎迁移 Legacy .cursorrules
当前 Cursor 文档把 .cursorrules 标记为 Legacy。迁移应当:
- 盘点旧文件真实包含的内容;
- 把可移植仓库事实移入
AGENTS.md或 Canonical Docs; - 把 Cursor 特定行为拆成聚焦的
.cursor/rules/*.mdc; - 为每条 Project Rule 选择明确激活方式;
- 删除重复或矛盾副本;
- 运行激活与结果 Fixture;
- 新路径验证后再删除旧文件。
不要机械地把一个大文件复制进 Always Apply Rule。这样只会保留噪声,并继续隐藏作用域是否正确。
常见问题
Cursor Project Rules 应该放在哪里?
当前 Cursor 文档使用 .cursor/rules/*.mdc。Frontmatter 决定 Rule 是始终生效、按文件匹配、由 Agent 选择,还是手动启用。需要纯 Markdown 和目录作用域时,可以使用 AGENTS.md。
Team Rules 与 Project Rules 有什么区别?
Team Rules 在组织层管理,并可跨仓库强制执行;Project Rules 与单个代码库一起进入版本控制和 Review。产品行为变化后,应重新对照 Cursor 官方文档核验当前优先级。
Cursor Rules 能强制安全策略吗?
不能。它可以向 Agent 解释策略,但模型可能误解或未遵循。Credential、Repository Access、Sandbox、Network Policy、Branch Protection、Required Check 与 Release Approval 都需要确定性强制。
可复用任务模板应该包含什么?
写清 Goal、Scope、Authoritative Reference、Required Output、Verification、Evidence 与 Escalation。身份、权限、价格、Secret 与不可逆审批不能由 Prompt 模板决定。
团队怎样测量 Rule 是否有效?
让新旧 Rule Bundle 在相同版本化仓库任务上回放,比较成功结果、回归、不必要改动、策略违规、实际检查、Review 成本、时延与费用,不能只看建议接受率。
常见失败模式
- 把 Legacy 文件名当成当前默认;
- 把所有约定塞进一个 Always Apply Rule;
- 把 Linter 输出、生成类型或完整风格指南复制进上下文;
- 在 Team Rules、Project Rules 与
AGENTS.md间重复要求; - 本应提供路径、命令或验收测试时只写 Persona;
- 要求“行为不变”却没有 Characterization Test;
- 允许 Issue 文本或代码注释重写策略;
- 把 Agent 声称的测试结果当成执行证据;
- 在 Rules 中存储 Secret 或生产记录;
- 修改规则却没有 Replay、Owner 与 Rollback。
团队检查清单
- [ ] 盘点 Project、User、Team、
AGENTS.md与 Legacy Rule。 - [ ] 为每项要求确定唯一 Canonical Owner。
- [ ] 保持 Cursor Adapter 聚焦且有作用域。
- [ ] 使用当前
.mdcFrontmatter 并验证激活。 - [ ] 引用权威文件,而不是复制内容。
- [ ] 用 Scope、Input、Evidence 与 Escalation 定义任务模板。
- [ ] 在模型之外强制权限和副作用。
- [ ] 回放普通、边界、过期上下文与 Injection 案例。
- [ ] 测量成功结果、回归、Review 成本、时延和费用。
- [ ] 像代码一样 Review、灰度和回滚 Rule 变更。
相关资源
一手资料
总结
好的 Cursor Rules 能减少重复歧义,却不能替代软件控制。维护一份单一事实源,把它映射成聚焦的 .mdc 或 AGENTS.md Adapter,定义可观察结果,并用真实仓库任务回放每次变更。这样建立的团队系统可以随 Cursor 与模型版本演进,同时不会把 Prompt 文本误当成权限或证明。