`.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. 双文件协同工作流

一句话总结：
.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-lintuses: cursor-ai/cursorlint@v1with:rules: .cursorrulesfail-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 冲突？
→ 职责不同。