直接回答

团队级 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 链接;
  • 验证与升级行为。

例如:

md
---
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 仍需拒绝删除授权或跳过测试的变更。

避免模糊规则

弱规则:

text
始终编写生产级代码,绝不引入 Bug。

可测试规则:

text
修改 services/payments 时:
- 保持公开请求与响应 Schema;
- 从认证上下文获取 Account Ownership;
- 增加 Duplicate、Timeout 与 Unauthorized 测试;
- 运行 `go test ./services/payments/...`;
- 报告未运行的检查。

“整洁”“最佳”“简单”“安全”都需要可观察定义,否则模型只能猜测。

用 AGENTS.md 承载可移植指令

当同一份仓库规范需要同时供人和多个兼容 Coding Agent 阅读时,AGENTS.md 很合适。当前 Cursor 文档支持根目录和嵌套文件,更具体的子目录规则应用于其目录范围。

根文件可以这样写:

md
# 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。

回归测试模板

text
目标:
  为选中函数补充测试。

读取:
  实现、现有测试、公开契约与错误类型。

覆盖:
  正常路径、边界、已记录失败与本次回归。

约束:
  不修改生产行为,不新增依赖。
  不 Mock 被测单元本身。

证据:
  报告修改文件与实际执行命令。
  没有命令输出时,不声称覆盖或成功。

升级:
  依赖缺失、契约冲突或行为不可观察时停止。

重构模板

text
目标:
  改善选中代码,不改变可观察行为。

编辑前:
  找出 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,而不是相信模型摘要。

go
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)
}

预期输出:

text
accepted=true violations=[]

代码检查的是证据,不是措辞。生产实现还应验证命令 Exit Status、Commit Identity、Sandbox Provenance 与 Artifact Hash。

像代码一样版本化、Review 和回滚

Rule 变更流程:

  1. 写清它要修复的重复失败;
  2. 确认负责人和作用域;
  3. 新增或更新 Replay Fixture;
  4. 在相同任务上比较新旧 Rule Bundle;
  5. 检查回归与无关激活;
  6. 通过 Pull Request 审查;
  7. 先在小团队或少量仓库灰度;
  8. 任务成功、审查成本、安全、时延或费用回归时回滚。

记录:

json
{
  "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。迁移应当:

  1. 盘点旧文件真实包含的内容;
  2. 把可移植仓库事实移入 AGENTS.md 或 Canonical Docs;
  3. 把 Cursor 特定行为拆成聚焦的 .cursor/rules/*.mdc;
  4. 为每条 Project Rule 选择明确激活方式;
  5. 删除重复或矛盾副本;
  6. 运行激活与结果 Fixture;
  7. 新路径验证后再删除旧文件。

不要机械地把一个大文件复制进 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 聚焦且有作用域。
  • [ ] 使用当前 .mdc Frontmatter 并验证激活。
  • [ ] 引用权威文件,而不是复制内容。
  • [ ] 用 Scope、Input、Evidence 与 Escalation 定义任务模板。
  • [ ] 在模型之外强制权限和副作用。
  • [ ] 回放普通、边界、过期上下文与 Injection 案例。
  • [ ] 测量成功结果、回归、Review 成本、时延和费用。
  • [ ] 像代码一样 Review、灰度和回滚 Rule 变更。

相关资源

一手资料

总结

好的 Cursor Rules 能减少重复歧义,却不能替代软件控制。维护一份单一事实源,把它映射成聚焦的 .mdc 或 AGENTS.md Adapter,定义可观察结果,并用真实仓库任务回放每次变更。这样建立的团队系统可以随 Cursor 与模型版本演进,同时不会把 Prompt 文本误当成权限或证明。