如何让 Cursor 更懂你的项目

码上暴富

403人浏览 · 2026-08-25 14:15:35

码上暴富 · 2026-08-25 14:15:35 发布

如何让 Cursor 更懂你的项目

基于 Cursor 官方 Rules 文档（2026）整理。行为以 cursor.com/docs/rules 为准。

0. 结论

Cursor 没有跨对话的项目记忆。每次 Agent 对话能稳定用上的，只有：

本轮打开 / @ 引用的文件与搜索结果
自动注入的 Rules / AGENTS.md / User Rules / Team Rules
相关时被拉取的 Skills、MCP、Hooks 等扩展能力

「更聪明」= 把只有熟手才知道的知识，写成可版本管理、可按需加载的持久化上下文，并在对话里主动 @ 关键证据。

推荐分层（从小到大项目）：

层级	位置	何时用
项目说明书	根目录 / 子目录 `AGENTS.md`	架构、命令、模块地图、常见任务步骤
细粒度规则	`.cursor/rules/*.mdc`	按文件类型 / 场景注入的硬约定
可复用流程	`.cursor/skills/*/SKILL.md`	「怎么做某类任务」的标准作业流程
个人习惯	Customize → Rules（User Rules）	跨项目的回复风格、commit 习惯
团队强制	Dashboard Team Rules	组织级合规 / 统一标准（Team/Enterprise）

弃用根目录 .cursorrules（legacy）。改用 .mdc 或 AGENTS.md。

重要边界： Rules / User Rules 只影响 Agent（Chat），不影响 Cursor Tab，也不影响 Inline Edit（Ctrl/Cmd+K）。

1. 四种规则类型（核心机制）

.cursor/rules/*.mdc = Markdown 正文 + YAML frontmatter。
普通 .md 放在 .cursor/rules/ 会被忽略（没有 frontmatter 控制字段）。要纯 Markdown 指令，用 AGENTS.md。

1.1 frontmatter 如何决定是否注入

`alwaysApply`	`description`	`globs`	行为
`true`	任意	任意	每次对话都注入（globs/description 被忽略）
`false`	—	有	匹配文件进入上下文时自动附着
`false`	有	无	Agent 根据 description 自行判断是否拉取（Apply Intelligently）
`false`	无	无	仅 `@规则名` 时生效（Manual）

创建入口：

聊天里 /create-rule
Customize → Rules → Add Rule
或直接手写 .mdc 文件

1.2 glob 写法

多个 pattern 用逗号分隔：

globs: src/**/*.ts, src/**/*.tsx

Pattern	含义
`*/.ts`	任意目录下的 `.ts`
`src/**`	`src/` 下所有文件
`docs/*/.md, docs/*/.mdx`	docs 下 md/mdx
`tailwind.config.*`	任意扩展名的该配置文件

1.3 规则正文怎么写才有效

官方建议：

单文件 建议 < 500 行；实践上 alwaysApply 尽量 < 50 行
一条规则一件事，可拆可组合
可执行：写「要做什么 / 不要做什么 / 改哪些文件」，少写空话
引用文件，不要把代码贴进规则：@path/to/canonical-example.ts（规则随代码演进更不易过期）
不要把整本 style guide、所有 CLI 命令塞进规则（用 linter；Agent 已会常见工具）
不要为罕见 edge case 写规则；Agent 反复犯同错时再补

2. AGENTS.md

2.1 定位

纯 Markdown，无 frontmatter、无 glob
适合：项目介绍、目录地图、启动命令、架构原则、常见任务 checklist
跨工具友好（多款 Agent 也认 AGENTS.md）
与 .mdc 可并存：AGENTS.md 管总览；.mdc 管精细触发

2.2 嵌套（官方已支持）

project/
  AGENTS.md                 # 全局
  frontend/AGENTS.md        # 前端目录生效
  frontend/components/AGENTS.md
  backend/AGENTS.md

在某目录工作时，会合并祖先链上的 AGENTS.md，更近的目录优先级更高。

2.3 建议目录（与技术栈无关）

# 项目名

## 一句话与技术栈
## 常用命令（dev / test / build / lint）
## 目录地图（只写「谁负责什么」，不贴长树）
## 架构与数据流（模块边界、禁止跨层调用）
## 常见任务（加 API / 加页面 / 加迁移…分步）
## 约定与禁止事项
## 相关规则索引（指向 .cursor/rules/xxx.mdc）

易变细节（路由表、事件名、权限清单）放 AGENTS.md，改架构时同步更新；稳定原则放 alwaysApply 的短 .mdc。

3. 其它上下文层

3.1 User Rules

路径：Customize → Rules。

全项目生效
放：语言偏好、回复风格、通用 commit/PR 习惯
不要放某个仓库的架构细节

3.2 Team Rules（Team / Enterprise）

Dashboard 管理；可 Enforce（成员无法关闭）
可带 glob；无 glob 则每次对话生效
冲突时优先级：Team → Project → User（全部合并，冲突时靠前的优先）

3.3 Skills（标准作业流程）

规则偏「约束」；Skills 偏「怎么完成一类任务」。

类型	路径
项目 Skill	`.cursor/skills/<name>/SKILL.md`
个人 Skill	`~/.cursor/skills/<name>/SKILL.md`

适合：发版流程、写迁移、排查某类线上问题、按团队模板开 PR。
Agent 按 Skill 的 description 判断是否调用；也可在对话里点名使用。

3.4 Hooks（可选进阶）

.cursor/hooks.json：在 tool 调用前后跑脚本（审计、拦截危险命令、注入环境信息）。
适合团队治理，不是「让 AI 懂项目」的第一步。

3.5 MCP / Docs

MCP：接数据库、Issue 系统、内部 API 等外部事实源
@Docs / 文档索引：框架官方文档进上下文，减少幻觉 API

4. 什么会自动进上下文，什么不会

来源	是否自动注入
`alwaysApply: true` 的 `.mdc`	是
匹配 globs 且相关文件在上下文中的 `.mdc`	是（自动附着）
仅有 description 的 Intelligent 规则	Agent 判断相关时拉取
根目录 / 嵌套 `AGENTS.md`	设计上会加载（嵌套按工作目录）
User / Team Rules	是（各自范围）
`README.md`、普通 docs	否；除非 `@` 或 Agent 搜索读到
`.cursorrules`	legacy，Agent 不可靠
Skills	相关时按 description 拉取，或手动点名

验证是否加载

新开对话：

列出当前已注入的 always_applied / 项目规则名字，不要读任何文件。

没有预期项 → 本轮未注入。兜底：消息里 @AGENTS.md 或 @某条规则。

长对话遗忘

上下文压缩后，顶层规则可能被挤掉。症状：开始乱改架构、忘约定。
处理：新开对话，或再次 @AGENTS.md / 关键 .mdc。

5. 推荐仓库结构（通用）

my-project/
├── AGENTS.md
├── apps/web/AGENTS.md              # 可选：大仓按包嵌套
├── packages/api/AGENTS.md
└── .cursor/
    ├── rules/
    │   ├── project-core.mdc        # alwaysApply: 核心约定（短）
    │   ├── frontend.mdc            # globs: **/*.{tsx,vue,svelte}
    │   ├── backend.mdc             # globs: **/server/**, **/api/**
    │   └── testing.mdc             # description: 写测/改测时（Intelligent）
    └── skills/
        └── add-feature/
            └── SKILL.md            # 可选：标准加功能流程

拆分原则：

放 alwaysApply	放 glob / Intelligent	放 AGENTS.md
极少、稳定、违反成本高的硬约束	某目录/某技术域约定	地图、步骤、易变清单
例：「禁止改 generated/」「业务逻辑不进 UI」	例：ORM 用法、组件分层	例：模块职责、加接口步骤

6. 对话怎么给上下文（比写规则更即时）

写法	作用
`@文件`	精确塞进相关代码
`@文件夹`	整目录
`@Codebase` / 语义搜索	全仓检索后再答
`@AGENTS.md` / `@规则名`	强制对齐项目约定
`@Docs`	官方/已索引文档
`@Git` / Diff / PR	变更范围、审查
`@Past Chats`	承接历史结论（仍不如规则稳定）
`@Web`	查最新外部信息

提问模板：

差：菜单关不掉怎么办
好：@useMenu.ts @Menu.vue 关闭父菜单时子菜单未销毁，对照现有关闭逻辑找根因并修

原则：先给证据（文件/报错/复现），再给目标与约束（不要重构无关模块）。

任务类型对应模式：

任务	建议
Bug	`@` 报错栈相关文件 + 复现步骤 +「最小改动」
新功能	`@AGENTS.md` + 参考实现文件 + 验收标准
重构	先让 Agent 画影响面，再改；事后同步文档
审查	`@Git` 或 PR diff + 明确审查维度（安全/性能/兼容）

7. 文档不会自动更新（必须当流程做）

AGENTS.md / .mdc / Skills 都是普通文件。代码变了，文档不会变。
过期文档比没有文档更糟：Agent 会按错约定改代码。

固定动作：

alwaysApply 里加一条：架构 / API / 目录 / 协议变更时，同一任务内更新对应文档
重构结束明确说：更新受影响的 AGENTS.md 与 .mdc
大改后新开对话：@AGENTS.md，要求「先对照代码校验文档，过期再改文档」

8. `.mdc` 模板

alwaysApply（短）

---
description: 项目核心约定
alwaysApply: true
---

# 核心约定

技术栈：[填写]

## 硬约束
1. …
2. …

## 文档同步
涉及架构、模块边界、对外 API/事件、目录结构的改动，同一任务内更新 AGENTS.md 与相关 .mdc。

细节见根目录 AGENTS.md。

glob 自动附着

---
description: [模块] 约定
globs: path/to/module/**/*
alwaysApply: false
---

# [模块]

## 模式
- …

## 新增步骤
1. …
2. …

## 不要
- …

## 参考
@path/to/good-example.ts

Intelligent（靠 description）

---
description: 数据库迁移与 schema 变更规范（写 migration、改表结构时使用）
alwaysApply: false
---

# Migrations
- 必须同时有 up/down
- 禁止原地改不兼容列类型；用加列 → 回填 → 删旧列

Manual（仅 @）

---
alwaysApply: false
---

# 发版检查清单
- …

对话里：@release-checklist。

9. 可复制提示词

9.1 从零搭 AGENTS.md + 规则

阅读本仓库代码后：

1. 根目录创建 AGENTS.md：简介与技术栈、命令、目录地图、架构边界、常见任务分步、禁止事项。
2. 在 .cursor/rules/ 创建：
   - project-core.mdc（alwaysApply: true，尽量短）
   - 按技术域 2～4 个 glob 或 intelligent 规则

要求：只写代码里真实存在的内容；规则可执行并带路径示例；不要用 .cursorrules；不要主动写 README。

9.2 校验并增量更新 AGENTS.md

对照代码检查 AGENTS.md。不一致处以代码为准，只改过期段落，不整篇重写。

9.3 新增一条 glob 规则

模块：[描述]。相关文件：[@a @b]
在 .cursor/rules/ 创建 xxx.mdc：匹配相关 globs；写清模式、命名、禁止事项；引用典范文件；尽量短。

9.4 重构后同步文档

刚完成：[重构说明]。
先读相关代码，标出 AGENTS.md 与 .cursor/rules/ 过期处，只更新受影响段落。

9.5 长对话重新对齐

@AGENTS.md
先校验文档是否与代码一致，过期则更新；再继续：[任务]

9.6 从重复错误沉淀规则

你刚才犯的错误是：[简述]。
写成一条 .mdc（选对 alwaysApply / globs / description），防止以后再犯。规则要短、可执行。

10. 常见误区

误区	真相
写了 README AI 就懂	README 不自动注入
`.cursorrules` 够用	legacy，Agent 不可靠
rules 里用 `.md`	被忽略；要用 `.mdc` 或改用 `AGENTS.md`
规则越长越好	占 context，重点被稀释
全部 alwaysApply	应用 glob / Intelligent / Manual 按需加载
一次写完美规则	官方建议：从简开始，重复犯错再补
规则 = 全套 style guide	交给 linter/formatter；规则写架构与业务约定
User Rules 管 Ctrl+K / Tab	不管；只影响 Agent Chat
文档写完一劳永逸	必须随重构同步