Cursor 官方文档学习指南

摘要：本文基于 Cursor 官方文档入口页、官方 llms.txt 文档地图，以及 Rules、Skills、MCP、CLI、Agent Security、Hooks 相关官方资料整理，适用于 2026 年 5 月 8 日前后的 Cursor 文档体系。本文是“总览型学习文档”，不是逐页翻译官网；它的目标是帮你建立一张清晰地图：Cursor 到底有哪些能力、每个能力解决什么问题、怎么用、什么时候不用。尤其对 Rules、Skills、MCP、Hooks 这类抽象概念，本文会用“人话定义 + 类比 + 对比 + 流程 + 示例”的方式讲清楚。

一、背景与动机

Cursor 官方文档的入口页把 Cursor 定义为 AI editor and coding agent。这句话里其实有两层含义：

• AI editor：它仍然是一个编辑器，能补全、编辑、跳转、运行终端。
• coding agent：它也是一个能读代码、改文件、跑命令、调用工具、做计划的智能体。

所以你看 https://cursor.com/cn/docs 会觉得内容多，并不是你的问题，而是 Cursor 已经从“AI 补全工具”扩展成了一个完整的 Agent 开发平台。

官方 llms.txt 中的文档地图大致包括：

学习 Cursor 最容易踩的坑是：一开始就试图读完整个官方文档。更好的方式是按使用顺序学：

flowchart TD
    A[先会写: Tab] --> B[会局部改: Inline Edit]
    B --> C[会问和会交任务: Ask / Agent]
    C --> D[会控制: Review / Plan Mode / Security]
    D --> E[会定制: Rules / Skills]
    E --> F[会连接: MCP / Plugins]
    F --> G[会自动化: Hooks / CLI / Cloud Agent]

flowchart TD
    A[先会写: Tab] --> B[会局部改: Inline Edit]
    B --> C[会问和会交任务: Ask / Agent]
    C --> D[会控制: Review / Plan Mode / Security]
    D --> E[会定制: Rules / Skills]
    E --> F[会连接: MCP / Plugins]
    F --> G[会自动化: Hooks / CLI / Cloud Agent]

flowchart TD
    A[先会写: Tab] --> B[会局部改: Inline Edit]
    B --> C[会问和会交任务: Ask / Agent]
    C --> D[会控制: Review / Plan Mode / Security]
    D --> E[会定制: Rules / Skills]
    E --> F[会连接: MCP / Plugins]
    F --> G[会自动化: Hooks / CLI / Cloud Agent]

二、核心概念

2.1 一句话理解 Cursor

一句话：Cursor 是一个让 AI 直接参与真实代码库工作的编辑器。

它不像普通聊天机器人只能回答问题，也不像传统 IDE 只提供静态工具。Cursor 的核心是把下面几件事放到同一个环境里：

2.2 先区分这些容易混淆的概念

记忆口诀：

Rules 告诉 Agent 应该怎么做；Skills 教 Agent 做一类任务；MCP 给 Agent 外部工具；Hooks 在 Agent 真要行动时插一脚检查。

2.3 官方知识点覆盖清单

本文覆盖官方文档中的核心模块，但仍然是总览型文档。更细的企业配置、具体集成和每个 CLI 参数，建议按需查官方专项页。

三、详细讲解

3.1 Quickstart：先用三件套跑通闭环

官方 Quickstart 的核心路线是：

1. 打开一个项目。
2. 用 Tab 自动补全代码。
3. 用 Inline Edit 修改选中的代码。
4. 用 Agent 添加测试并运行。

这条路线不是随便安排的，它刚好对应 Cursor 的三个日常入口：

新手第一天只需要练这三件事，不要一开始就配置 MCP 或 Hooks。

3.2 Tab：不是普通补全，而是下一步编辑预测

一句话：Tab 是 Cursor 的智能补全模型，会根据你最近的修改预测下一处要写或要改的代码。

可以把它类比成“代码输入法”，但比普通输入法更进一步：它不仅补当前单词，还会补多行、补 import、提示跨文件相关改动。

Tab 能做什么：

• 多行补全
• 修改已有代码
• 自动添加缺失 import
• 根据 linter 错误给建议
• 接受一次建议后预测下一处编辑位置
• 跨文件提示联动修改

常用操作：

什么时候不用 Tab：

• 你还没想清楚需求时，不要让 Tab 带着你走。
• 复杂重构不要靠 Tab 零散完成，用 Agent 或 Plan Mode。
• 写注释时如果建议干扰思路，可以关闭 comments 中的建议。

3.3 Inline Edit：当前编辑器里的快速手术刀

一句话：Inline Edit 是“选中代码，然后用自然语言改这段代码”。

它像一把局部手术刀：你指出具体位置，它按你的指令修改。它比 Tab 更主动，但比 Agent 更可控。

常见模式：

示例：

把这段逻辑改成 async/await，保留现有错误处理语义。

先解释这段代码为什么会重复请求，不要修改。

什么时候不用 Inline Edit：

• 要跨多个文件理解调用链时，用 Ask 或 Agent。
• 要迁移整个模块时，用 Plan Mode + Agent。
• 需要外部工具、数据库、设计稿时，可能需要 MCP。

3.4 Agent：真正帮你做开发任务的人

一句话：Agent 是 Cursor 里能读代码、改文件、跑命令、调用工具的开发助手。

它像一个结对开发者，但你仍然是 reviewer 和负责人。

Agent 能做什么：

• 搜索代码库
• 读取文件和目录
• 进行语义搜索和关键词搜索
• 修改文件
• 运行终端命令
• 调用 MCP 工具
• Review diff
• 根据报错继续修复

基本流程：

flowchart TD
    A[你提出任务] --> B[Agent 搜索和读取上下文]
    B --> C[Agent 制定或执行方案]
    C --> D[修改文件/运行命令/调用工具]
    D --> E[展示 diff 和结果]
    E --> F[你 review 并决定是否继续]

flowchart TD
    A[你提出任务] --> B[Agent 搜索和读取上下文]
    B --> C[Agent 制定或执行方案]
    C --> D[修改文件/运行命令/调用工具]
    D --> E[展示 diff 和结果]
    E --> F[你 review 并决定是否继续]

flowchart TD
    A[你提出任务] --> B[Agent 搜索和读取上下文]
    B --> C[Agent 制定或执行方案]
    C --> D[修改文件/运行命令/调用工具]
    D --> E[展示 diff 和结果]
    E --> F[你 review 并决定是否继续]

推荐提示词：

目标：
修复登录后偶发跳回登录页的问题。

工作方式：
1. 先阅读相关文件，不要立刻修改。
2. 列出根因假设和会修改的文件。
3. 等我确认后再实现。
4. 修改后运行相关测试。

约束：
- 不要改数据库结构。
- 保持 API 响应格式兼容。

验收：
- 补充或更新测试。
- 总结修改文件和原因。

什么时候不用 Agent：

• 只想补当前行，用 Tab。
• 只改一小段，用 Inline Edit。
• 只是学习概念，用 Ask。
• 风险极高但没有验收标准时，先 Plan。

3.5 Ask、Agent、Manual、Custom Mode 与当前菜单怎么对应

Cursor 的模式可以理解成“给 Agent 限定工作方式”。

版本说明：这一节容易和实际界面不一致。Cursor 官方文档和 Changelog 在不同时间、不同语言页面里的表述并不完全相同：2025 年 3 月的 Changelog 明确说 Agent 和 Ask 是内置模式，同时支持 Custom modes，并把原来的 Edit 改名为 Manual；当前中文官方 Modes 页更偏向列出 Agent / Ask / Custom，而 Plan、Debug 属于模式示例或后续功能页中的专项能力。你截图里的菜单是当前客户端的实际菜单：Agent / Plan / Debug / Multitask / Ask，其中 Plan、Debug、Multitask 更像是 Cursor 预置或产品化后的专项模式，而不是旧文档里那张四项表的逐字呈现。

简单判断：

• “先别改，帮我解释”：Ask
• “按这个需求实现”：Agent
• “先出方案再动手”：Plan
• “帮我定位运行时问题”：Debug
• “这件事可以拆成几个独立分支并行做”：Multitask
• “只改这段”：Inline Edit；如果你的版本还有 Manual，也可以用 Manual
• “以后经常这样做”：Custom Mode 或 Skill

3.6 Plan Mode：复杂任务先写施工图

一句话：Plan Mode 是让 Agent 在写代码前先研究项目、提问题、生成计划。

它像施工图。简单修一行不需要施工图，但改登录、支付、权限、架构时，没有施工图就容易乱。

官方博客介绍的 Plan Mode 流程：

sequenceDiagram
    participant U as 你
    participant A as Agent
    participant C as Codebase

    U->>A: 描述复杂任务并进入 Plan Mode
    A->>C: 查找相关文件和文档
    A->>U: 提出澄清问题
    U->>A: 补充约束
    A->>U: 生成 Markdown 计划
    U->>A: 审阅/编辑计划
    A->>C: 按计划实现

sequenceDiagram
    participant U as 你
    participant A as Agent
    participant C as Codebase

    U->>A: 描述复杂任务并进入 Plan Mode
    A->>C: 查找相关文件和文档
    A->>U: 提出澄清问题
    U->>A: 补充约束
    A->>U: 生成 Markdown 计划
    U->>A: 审阅/编辑计划
    A->>C: 按计划实现

sequenceDiagram
    participant U as 你
    participant A as Agent
    participant C as Codebase

    U->>A: 描述复杂任务并进入 Plan Mode
    A->>C: 查找相关文件和文档
    A->>U: 提出澄清问题
    U->>A: 补充约束
    A->>U: 生成 Markdown 计划
    U->>A: 审阅/编辑计划
    A->>C: 按计划实现

官方提到可以在 Agent 输入框中按 Shift+Tab 开始规划，也可以保存计划为仓库里的 Markdown 文件。

什么时候用：

• 跨 5 个以上文件的改动
• 权限、支付、登录、数据迁移
• 你不熟悉代码库
• 需要和团队 review 方案

什么时候不用：

• 改文案
• 改一个变量名
• 补一个简单测试

3.7 Tools：Agent 的手和眼睛

一句话：Tools 是 Agent 真正能操作世界的能力。

没有工具，模型只能说话；有工具，Agent 才能读文件、改文件、跑命令、查 Web、调用 MCP。

官方工具大类：

重要原则：

• Agent 可以连续多次调用工具直到完成任务。
• Auto-run 很方便，但会放大风险。
• Guardrails / allowlist 是便利机制，不应当当成完整安全边界。

3.8 Context 与 Codebase Indexing：AI 看见什么，决定它能做什么

一句话：Context 是 Agent 当前能看到的信息；Indexing 是 Cursor 帮它理解整个代码库的底层能力。

可以把 Indexing 类比成“给项目建搜索索引”。Cursor 会给文件计算 embeddings，让 Agent 能语义搜索代码库。

你需要知道：

实用建议：

• 精确知道文件时，用 @filename。
• 不知道文件时，让 Agent 自己搜索。
• 敏感文件写进 .cursorignore。
• 长任务新开会话，避免上下文变脏。

3.9 Rules：给 Agent 的团队工作守则

一句话：Rules 是给 Agent 的持久提示词，让它每次工作都遵守项目规范。

类比：Rules 就像团队的工程约定。新人加入项目时，你会告诉他“不要改 generated 文件”“改组件后跑 typecheck”“API 错误格式要统一”。Rules 就是把这些话写下来，让 Agent 每次都能看到。

它解决的问题：

• 不用每次重复告诉 Agent 项目规范。
• 团队可以共享同一套 AI 工作方式。
• 可以按目录或文件类型自动附加不同规则。

四类规则：

3.9.1 Project Rules 怎么写

.cursor/rules 支持 .md 和 .mdc。需要控制触发方式时用 .mdc。

---
description: "React component conventions"
globs: "src/components/**/*.tsx"
alwaysApply: false
---

- Use named exports, not default exports.
- Keep components focused.
- Prefer existing design-system components.
- Run type checks after changing components.

3.9.2 Rules 如何触发

对应 UI：

Team Rules 优先级高于 Project Rules，Project Rules 高于 User Rules：

Team Rules → Project Rules → User Rules

3.9.3 Rules 什么时候不用

不要用 Rules 做这些事：

• 替代 linter 或测试
• 复制整本 style guide
• 记录很少发生的边缘情况
• 存放大段知识库全文
• 执行脚本或访问外部系统

如果你想“运行脚本”，用 Hooks 或 Skills；如果你想“连接外部系统”，用 MCP；如果你想“完成一个专项流程”，用 Skills。

3.10 Skills：给 Agent 的专项能力包

一句话：Skills 是把一类任务的操作手册、脚本、模板、参考资料打包给 Agent。

类比：Rules 是“工作守则”，Skills 是“专项工具箱”。比如“生成学习文档”“发布版本”“排查线上错误”“创建 PR”，都适合做成 Skill。

Skill 解决的问题：

• 重复工作流可以复用。
• 长文档和脚本不用塞进每次上下文。
• Agent 需要时再加载，减少上下文污染。

目录位置：

基本结构：

.cursor/
└── skills/
    └── gen-doc/
        ├── SKILL.md
        ├── scripts/
        ├── references/
        └── assets/

SKILL.md frontmatter：

什么时候用 Skills：

• 有明确多步骤流程
• 需要脚本辅助
• 需要模板或参考资料
• 不想每次把流程复制到 prompt

什么时候不用：

• 只是几条项目规范，用 Rules。
• 只是连接外部 API，用 MCP。
• 只是想拦截行为，用 Hooks。

3.11 MCP：给 Agent 接外部工具的插座

一句话：MCP 是让 Cursor Agent 连接外部工具和数据源的协议。

类比：MCP 像插座。Cursor 是用电设备，外部系统是电器，MCP 规定插头长什么样。只要按协议接上，Agent 就能用工具读取文档、查 issue、访问设计稿、查询数据库。

它解决的问题：

• 不用手动复制外部文档给 AI。
• Agent 可以直接查团队工具。
• 外部系统可以用统一协议暴露能力。

MCP 基本流程：

flowchart LR
    A[你向 Agent 提需求] --> B[Agent 判断需要外部信息]
    B --> C[调用 MCP 工具]
    C --> D[MCP Server 访问外部系统]
    D --> E[返回结构化结果]
    E --> F[Agent 基于结果继续工作]

flowchart LR
    A[你向 Agent 提需求] --> B[Agent 判断需要外部信息]
    B --> C[调用 MCP 工具]
    C --> D[MCP Server 访问外部系统]
    D --> E[返回结构化结果]
    E --> F[Agent 基于结果继续工作]

flowchart LR
    A[你向 Agent 提需求] --> B[Agent 判断需要外部信息]
    B --> C[调用 MCP 工具]
    C --> D[MCP Server 访问外部系统]
    D --> E[返回结构化结果]
    E --> F[Agent 基于结果继续工作]

Cursor 支持三种 transport：

配置位置：

最小示例：

MCP 支持的能力包括 Tools、Prompts、Resources、Roots、Elicitation，以及 Apps 扩展。

安全建议：

• 只安装可信 MCP。
• API key 用环境变量，不要写死。
• 敏感系统优先用本地 stdio。
• 给 token 最小权限。
• 高风险 MCP 不要开 Auto-run。
• 调试时看 Output 面板里的 MCP Logs。

什么时候不用 MCP：

• 信息已经在当前代码库里，用 Agent 搜索即可。
• 只是项目规范，用 Rules。
• 只是本地固定流程，用 Skills 或 Commands。
• 外部系统权限不清楚，先不要接。

3.12 Plugins：把 MCP、Skills、Commands 打包安装

一句话：Plugins 是更完整的集成包，可能包含 MCP、Skills、Commands、Hooks 等多个部分。

类比：MCP 是插头，Plugin 是一整套电器安装包。比如 Figma 插件可能不只是 MCP，还会带设计转代码的 Skills 和相关命令。

适合：

• 不想手写 MCP 配置
• 需要 OAuth 登录
• 需要安装一整套工具链
• 团队统一分发集成

什么时候不用：

• 只需要一个简单本地脚本，用 MCP stdio 或 Skill 即可。
• 不信任插件来源。
• 插件权限范围太大但无法审计。

3.13 Hooks：Agent 行动前后的拦截器

一句话：Hooks 是 Cursor Agent 的事件拦截器：当 Agent 会话开始、读文件、跑命令、调用 MCP、编辑文件、停止等事件发生前后，Cursor 可以自动运行你配置的脚本。

类比：如果你写过 Web 中间件、Git hooks、CI pipeline、VS Code extension 事件监听，就很好理解。Hooks 不是给模型看的提示词，而是给 Cursor 执行的程序。

它解决的问题：

• 不能只靠 Agent 自觉遵守安全规则。
• 团队需要审计 Agent 做了什么。
• 某些动作发生前必须先检查。
• 某些动作发生后要自动验证、记录或让 Agent 继续循环。

3.13.1 Hooks 和 Rules / Skills / MCP 的区别

口诀：

Rules 是“先交代规矩”；Hooks 是“真动手前后检查”。

3.13.2 Hooks 在流程中的位置

Hooks 不是只能定义在整个 Agent 执行结束时。stop 只是一个事件名，表示 Agent 停止时触发。更准确地说，Hooks 可以挂在 Agent loop 的多个已定义阶段。

flowchart TD
    A[Agent 会话开始] --> B[sessionStart]
    B --> C[Agent 准备读文件]
    C --> D[beforeReadFile]
    D --> E[Agent 准备执行命令]
    E --> F[beforeShellExecution]
    F --> G[执行命令]
    G --> H[afterShellExecution]
    H --> I[Agent 准备调用 MCP]
    I --> J[beforeMCPExecution]
    J --> K[调用 MCP]
    K --> L[afterMCPExecution]
    L --> M[Agent 编辑文件]
    M --> N[afterFileEdit]
    N --> O[Agent 停止]
    O --> P[stop / SessionEnd]

flowchart TD
    A[Agent 会话开始] --> B[sessionStart]
    B --> C[Agent 准备读文件]
    C --> D[beforeReadFile]
    D --> E[Agent 准备执行命令]
    E --> F[beforeShellExecution]
    F --> G[执行命令]
    G --> H[afterShellExecution]
    H --> I[Agent 准备调用 MCP]
    I --> J[beforeMCPExecution]
    J --> K[调用 MCP]
    K --> L[afterMCPExecution]
    L --> M[Agent 编辑文件]
    M --> N[afterFileEdit]
    N --> O[Agent 停止]
    O --> P[stop / SessionEnd]

flowchart TD
    A[Agent 会话开始] --> B[sessionStart]
    B --> C[Agent 准备读文件]
    C --> D[beforeReadFile]
    D --> E[Agent 准备执行命令]
    E --> F[beforeShellExecution]
    F --> G[执行命令]
    G --> H[afterShellExecution]
    H --> I[Agent 准备调用 MCP]
    I --> J[beforeMCPExecution]
    J --> K[调用 MCP]
    K --> L[afterMCPExecution]
    L --> M[Agent 编辑文件]
    M --> N[afterFileEdit]
    N --> O[Agent 停止]
    O --> P[stop / SessionEnd]

3.13.3 配置位置和最小配置

常见配置位置：

常见目录结构：

.cursor/
├── hooks.json
└── hooks/
    ├── check-command.py
    ├── check-doc-saved.py
    └── grind.ts

配置格式：

stop 示例：

这个配置的意思是：Agent 停止时，运行 .cursor/hooks/grind.ts。
如果脚本返回空对象，可以结束；如果返回 followup_message，Cursor 可以把后续消息继续交给 Agent。

3.13.4 Hook 事件名是不是固定的

是的，事件名不是随便写的。它必须是 Cursor 支持的预定义事件名。写错事件名通常不会触发。

但要注意：当前公开资料中的 Hooks 信息分散在官方文档地图、官方博客、Marketplace 和论坛/讨论中，事件名集合可能随 Cursor 版本变化，IDE / CLI / Cloud Agent 的支持也可能不同。下面表格不是稳定完整 API Reference，而是基于 2026 年 5 月 8 日可见资料整理，实际以当前 Cursor 版本实测为准。

来源稳定性说明：

3.13.5 IDE / CLI / Cloud 支持差异

Hooks 的事件支持可能因环境不同而变化。这里给一个保守的学习版判断：

最稳的验证方法：每加一个 Hook，先让脚本把收到的 stdin 写到日志。

示意脚本：

import sys
from pathlib import Path

payload = sys.stdin.read()
Path(".cursor/hooks/debug.log").write_text(payload, encoding="utf-8")
print("{}")

然后配置：

让 Agent 执行一个低风险命令，例如 echo hello，再检查 .cursor/hooks/debug.log 是否写入。

3.13.6 官方博客提到的真实用途

3.13.7 当前项目里 Hooks 可以怎么用

什么时候不用 Hooks：

• 只是想提醒 Agent，用 Rules。
• 只是想提供工作流，用 Skills。
• 只是想访问外部工具，用 MCP。
• 个人轻量使用，还没有明确要拦截或审计的动作。
• 脚本本身不稳定时，不要放进 Hooks 自动执行。

3.14 CLI：把 Cursor Agent 带到终端

一句话：Cursor CLI 是命令行里的 Cursor Agent。

适合：

• 远程机器
• 脚本和 CI
• 只读 review
• 不想打开完整 IDE
• Headless 自动化

基础命令：

# 安装
curl https://cursor.com/install -fsS | bash

# 交互式会话
cursor-agent

# 带初始任务
cursor-agent "refactor the auth module to use JWT tokens"

# 非交互模式
cursor-agent -p "review these changes for security issues" --output-format text

# 恢复会话
cursor-agent ls
cursor-agent resume
cursor-agent --resume="chat-id-here"

CLI 也支持 Rules 和 MCP。官方说明 CLI 会读取 .cursor/rules，也会读取项目根目录的 AGENTS.md 和 CLAUDE.md。运行终端命令前，CLI 默认会要求你批准或拒绝。

注意：非交互模式适合脚本，但官方文档也提醒它有完整写权限。用于 CI 前要先限制 prompt 和权限。

3.15 Cloud Agent、Bugbot、Automations：把 Agent 放到后台

一句话：Cloud Agent 是远程运行的 Agent，Bugbot 和 Automations 是围绕 PR、CI、事件触发的自动化能力。

适合团队成熟后使用：

常见自动化场景：

• 修 CI failure
• 增加测试覆盖
• 扫描漏洞
• 总结每日变更
• 清理 feature flag
• 从 Slack bug 报告自动开修复 PR

什么时候不用：

• 个人学习阶段。
• 没有测试和 review 流程。
• 仓库权限和密钥管理没理清。

3.16 Models & Pricing：先用 Auto，再理解 Max Mode

官方模型页变化很快，不建议死记模型表。你只需要先理解这些概念：

建议：

• 新手默认 Auto。
• 小改动不用纠结模型。
• 复杂重构、长上下文、难 bug 再考虑 Max Mode。
• 具体价格和可用模型以官方 Models & Pricing 和编辑器内提示为准。

3.17 安全边界：Cursor 很强，但你仍然负责

官方 Agent Security 文档强调：prompt injection、幻觉和工具调用都可能导致意外行为。Cursor 的默认保护思路是对敏感动作要求人工批准。

关键点：

安全建议：

• 在 Git 管理的项目中使用 Cursor。
• Agent 改完必须 review diff。
• 高风险命令保留人工审批。
• 敏感文件放入 .cursorignore。
• MCP token 最小权限。
• 对陌生仓库不要给全自动权限。

四、实践示例

4.1 七天学习路线

4.2 当前项目推荐 Rules

你的项目以 .cursor/ 为 AI 配置单一事实源，可以写：

---
description: "AI configuration source of truth for this repository"
alwaysApply: true
---

- All AI configuration must be edited in `.cursor/` first.
- Do not manually edit generated copies in `.claude/`, `.codex/`, or `.agents/` unless reverse migration is explicitly requested.
- After changing AI config, run `python sync_ai_config.py`.
- Learning notes must be saved under `notes/<title>/<title>.md`.

4.3 当前项目推荐 Hook 场景

这个项目目前还没有 .cursor/hooks.json。如果未来要加，最有价值的不是一上来搞复杂安全平台，而是做一个很小的质量检查：

脚本可以检查：

• 是否生成到 notes/<标题>/<标题>.md
• 是否包含 frontmatter
• 是否包含“延伸阅读”
• 是否包含来源链接
• 如果修改了 .cursor/，是否提醒同步

这就是 Hooks 的正确使用方式：先从一个明确、低风险、可验证的小检查开始。

4.4 Agent 提示词模板

任务：
<描述要实现或修复的内容>

工作方式：
1. 先阅读相关文件，不要立刻修改。
2. 给出简短计划，指出会改哪些文件。
3. 实现时保持改动范围最小。
4. 不要修改无关文件。
5. 完成后运行相关测试或说明无法运行的原因。

约束：
- <不能改的目录或接口>
- <必须保持兼容的行为>

验收标准：
- <标准 1>
- <标准 2>
- <标准 3>

4.5 MCP 最小练习

先接一个只读本地文档，不要一上来接生产数据库：

使用：

请使用 project-docs 工具查找“部署流程”，总结当前项目上线步骤，不要修改文件。

4.6 CLI 只读审查

cursor-agent -p "Review current git changes for bugs, security risks, and missing tests. Do not edit files." --output-format text

如果需要修复，再开第二步：

cursor-agent -p "Fix the issues found in the previous review. Keep changes minimal and run relevant tests."

五、常见误区与注意事项

5.1 把 Cursor 当普通聊天机器人

Cursor 的价值不只是回答，而是能结合代码库、终端和工具完成任务。只问概念用 Ask；要动项目才用 Agent。

5.2 Rules、Skills、MCP、Hooks 混用

判断标准：

• 规范和偏好：Rules
• 专项流程：Skills
• 外部工具：MCP / Plugins
• 行动拦截：Hooks

5.3 一上来就 Auto-run

Auto-run 适合稳定、低风险命令。不要一开始就让 Agent 自动运行所有命令。

5.4 Hooks 过度设计

Hooks 很强，但不应该为了“看起来高级”而用。没有明确触发点、检查逻辑和失败处理时，先别加。

5.5 不 review diff

Agent 改完至少看：

1. 有没有无关文件。
2. 有没有删除配置。
3. 测试是否真的跑了。
4. 是否引入硬编码 token。
5. 逻辑是否符合需求。

5.6 长对话一直续

任务结束就新开会话。把结论沉淀到 Rules、Skills、文档或计划文件里，而不是让一个聊天无限变长。

六、与相关技术的对比

6.1 Cursor 内部能力对比

6.2 学习阶段建议

6.3 什么时候该继续读官方专项文档

延伸阅读

• Cursor 官方文档入口
• Cursor 文档 Markdown 总览
• Cursor 官方文档地图 llms.txt
• Cursor Agent Overview
• Cursor Modes 官方页
• Cursor Changelog: Built-in modes & custom modes
• Cursor Changelog: Plan Mode
• Cursor Changelog: Debug Mode and Plan Mode improvements
• Cursor Changelog: Multitask
• Cursor Rules
• Cursor Skills
• Cursor MCP
• Cursor CLI Using
• Cursor Agent Security
• Cursor Hooks for security and platform teams
• Cursor Best practices for coding with agents
• Cursor Security
• Cursor CLI product page