`.cursorrules` 与 `.cursorcontext`：Cursor AI 编程助手时代下的“双轨配置”指南

.cursorrules 与 .cursorcontext：AI 编程助手时代下的"双轨配置"指南

关键词：Cursor、AI 编程、上下文管理、开发规范、技术治理

适合读者：前端 / 全栈工程师、技术负责人、AI 辅助编程实践者

---

1. 为什么又多了两个"点"文件？

随着 Cursor、GitHub Copilot、Windsurf 等 AI 原生 IDE 的普及，"如何给 AI 立规矩" 成了技术团队的新刚需。

社区里陆续出现了两种文件：

• .cursorrules ------ 官方背书，相当于给 AI 的"员工手册"；
• .cursorcontext ------ 民间演化，相当于给 AI 的"项目备忘录"。

二者名字相近，却各司其职。本文帮你一次理清差异、给出落地模板，并回答一个关键问题：
"我能不能只留一个？"

---

2. 一张表看清差异

维度	.cursorrules	.cursorcontext
官方地位	Cursor 原生读取，文档已收录	社区约定，IDE 不强制解析
作用对象	AI 的"决策大脑"	AI 的"记忆缓存"
内容本质	规则（Rule） → 应该怎么做	上下文（Context） → 当前是什么
失效后果	AI 可能写出违背规范的代码	AI 可能重复问"项目用的啥框架"
典型字段	useStrictAsync: true / maxLineLength: 120	techStack: [Next.js, Prisma, PostgreSQL]
版本化策略	随仓库强制评审，CI 可校验	可放 .gitignore，允许本地差异化

---

3. 文件解剖：把抽象翻译成代码

3.1 .cursorrules ------ AI 的"eslint.config.js"

{
  "scope": "fullstack",
  "language": "typescript",
  "arch": "hexagonal",
  "rules": [
    {
      "id": "api-naming",
      "severity": "error",
      "pattern": "^((get|post|put|delete)[A-Z]|websocket)",
      "message": "API 函数必须以前缀 + 大写驼峰命名"
    },
    {
      "id": "no-sync-fs",
      "severity": "warn",
      "deny": ["fs.readFileSync", "fs.writeFileSync"],
      "suggest": "用 fs/promises 替代"
    }
  ],
  "style": {
    "semicolon": "always",
    "quote": "single",
    "trailingComma": "es5"
  }
}

写法提示

• 支持 JSON / YAML / CSON 三种格式，Cursor 0.10+ 优先 JSON Schema。
• severity 三档：error 直接阻断生成，warn 给出 inline 提示，info 仅日志记录。

3.2 .cursorcontext ------ AI 的"README.oneline"

# 项目速览
- 名称：go-micro-activiti
- 主语言：Go 1.22
- 依赖：Kafka, Postgres, Redis
- 启动：make dev (docker-compose up -d)
- 端口：8080 (gateway), 9090 (grpc), 16686 (jaeger UI)
- 特性开关：FF_NEW_RENDERER=true (see /internal/ff)
- 测试：go test ./... -race -cover
- 文档：/docs/swagger.yaml

写法提示

• 纯 Markdown 即可，Cursor 会自动做向量化检索。
• 把"经常要被问"的内容放这里，减少 AI 反复确认。

---

4. 双文件协同工作流

生成代码骨架 补全业务细节 fail pass 开发者提问 AI 读取 .cursorrules AI 读取 .cursorcontext 返回最终代码 本地 lint / test 更新 .cursorrules commit & push

一句话总结：
.cursorrules 保证"风格不跑偏"，.cursorcontext 保证"信息不重复"。

---

5. 落地三步法

Step 1 初始化

# 项目根目录
touch .cursorrules .cursorcontext
# 把官方模板拷进去
curl -o .cursorrules https://raw.githubusercontent.com/cursor-ai/template/main/.cursorrules

Step 2 评审

• 把 .cursorrules 纳入 PR 模板，改动需架构师 +1；
• .cursorcontext 由各自模块 Owner 维护，允许跳过 MR，直接 push。

Step 3 自动化

# .github/workflows/cursor-lint.yml
- name: cursor-lint
  uses: cursor-ai/cursorlint@v1
  with:
    rules: .cursorrules
    fail-on-warn: true

---

6. FAQ

Q1 能只保留一个文件吗？

→ 可以跑，但体验打折。

• 只有 .cursorrules：AI 懂规范，却可能把 Kafka 写成 RabbitMQ；
• 只有 .cursorcontext：AI 懂背景，却给你 Tab 宽度 4 的代码。

Q2 多仓库复用怎么搞？

→ 把 .cursorrules 抽成独立 npm 包（或 Git Submodule），在根目录 .cursorrules 里 extends: "@myorg/cursor-config"。
.cursorcontext 建议各仓自行维护，保证差异化信息。

Q3 会不会和 EditorConfig / ESLint 冲突？

→ 职责不同。

• ESLint 管"人写出来的代码"；
• .cursorrules 管"AI 即将生成的代码"。
  两者互补，最好保持规则一致，可用 eslint-config-cursor 一键同步。

---

7. 结论

把 .cursorrules 当成强制性规范 ，把 .cursorcontext 当成速查便利贴，让 AI 在"懂规矩"的同时"长记忆"，才是大型项目可持续的 AI 协作方式。

"规则"与"上下文"双轨并行，既防 AI 乱来，也防自己遗忘。

---