Cursor 提示词详细分析文档

来源： https://github.com/x1xhlol/system-prompts-and-models-of-ai-tools

概述

Cursor 的提示词系统是一个复杂的、多层次的指令框架，用于指导 AI 编码助手的行为。该系统包含多个版本，从基础的聊天模式到高级的 Agent 模式，每个版本都有其特定的用途和优化方向。

文件清单

文件名	类型	用途	模型基础
Chat Prompt.txt	基础提示词	简单问答和代码建议	GPT-4o
Agent Prompt v1.0.txt	Agent v1.0	早期 Agent 模式	GPT-4.1
Agent Prompt v1.2.txt	Agent v1.2	改进的 Agent 模式	GPT-4.1
Agent Prompt 2.0.txt	Agent 2.0	最新 Agent 模式	GPT-5
Agent Prompt 2025-09-03.txt	最新版本	2025年9月版本	GPT-4.1
Agent CLI Prompt 2025-08-07.txt	CLI 版本	命令行工具模式	GPT-5
Agent Tools v1.0.json	工具定义	工具函数规范	-

文件结构分析

1. Chat Prompt.txt（基础聊天模式）

特点：

最简单的提示词结构
主要用于问答和代码建议
不支持主动执行代码修改
使用简化的工具集

核心结构：


- 身份定义（AI coding assistant）
- 通信规范（<communication>）
- 工具调用规则（<tool_calling>）
- 搜索和阅读策略（<search_and_reading>）
- 代码修改规范（<making_code_changes>）

关键限制：

用户可能只是提问，不要求编辑
只建议编辑，不直接执行
使用简化的代码块格式输出建议

2. Agent Prompt 系列（v1.0, v1.2, 2.0）

核心特征：

自主性：Agent 模式强调自主完成任务，直到问题完全解决
工具丰富性：提供完整的工具生态系统
上下文理解：强调深入理解代码库
并行执行：优化工具调用效率

版本演进：

v1.0 → v1.2 的变化

增加了 <maximize_context_understanding> 部分
强化了语义搜索的使用
添加了记忆系统（<memories>）
引入了 Pull Request 和 Issue 查询功能

v1.2 → 2.0 的重大变化

任务管理系统：引入 todo_write 工具和任务跟踪
状态更新规范：<status_update_spec> 和 <summary_spec>
代码引用规范：详细的 <citing_code> 规则
并行工具调用优化：<maximize_parallel_tool_calls>
代码风格指南：<code_style> 规范

3. Agent Prompt 2025-09-03（最新版本）

新增特性：

更严格的代码引用格式要求
改进的 Markdown 规范
优化的任务管理流程
增强的并行执行能力

关键改进：

明确区分 CODE REFERENCES 和 MARKDOWN CODE BLOCKS
禁止在代码引用中添加语言标签
强制要求代码块前换行
更详细的工具使用示例

4. Agent CLI Prompt（命令行版本）

特殊设计：

针对 CLI 环境优化
使用 grep 作为主要探索工具（而非语义搜索）
简化的任务管理
强调测试和构建验证

与标准 Agent 的区别：

<context_understanding> 中使用 grep 而非 codebase_search
更强调命令执行后的验证
环境信息更详细（OS、Shell、工作目录等）

核心组件分析

1. 通信规范（）

演进过程：

早期版本（Chat Prompt）：

基本的 Markdown 格式要求
使用反引号格式化文件名、目录、函数名
数学公式支持

最新版本（Agent 2.0）：

强调仅格式化相关部分
避免将整个消息包装在代码块中
优化可读性和可扫描性
使用 "edits" 而非 "patches"

关键规则：

markdown
- 使用反引号格式化：文件、目录、函数、类名
- 数学公式：\( \) 用于行内，\[ \] 用于块级
- 代码引用：使用特定格式（见代码引用规范）

2. 工具调用规范（<tool_calling>）

核心原则：

严格遵循工具模式
- 必须提供所有必需参数
- 不调用未提供的工具
- 不向用户提及工具名称
自主性
- 制定计划后立即执行
- 仅在需要用户输入或选择时暂停
- 优先使用工具而非询问用户
并行执行
- 尽可能并行调用工具
- 3-5x 性能提升
- 仅在依赖关系明确时顺序执行

版本差异：

特性	Chat	Agent v1.0	Agent 2.0
工具数量	6个	10+	12+
并行支持	有限	支持	强化
自主执行	否	是	是
任务管理	无	无	有

3. 上下文理解策略

语义搜索优先（Agent 模式）

策略：

从广泛到具体
- 首先使用高级查询（如 "authentication flow"）
- 避免低级术语搜索
- 从整个代码库开始（[]）
多角度搜索
- 使用不同措辞进行多次搜索
- 第一次结果可能遗漏关键细节
- 持续搜索直到确信无遗漏
分而治之
- 将复杂问题拆分为子查询
- 每个查询聚焦一个方面
- 避免并行查询多个不相关主题

Grep 搜索优先（CLI 模式）

策略：

使用精确字符串匹配
并行执行多个模式搜索
从关键词开始，逐步缩小范围

4. 代码修改规范（<making_code_changes>）

核心要求：

直接执行，不输出代码
- 除非用户明确要求
- 使用编辑工具而非代码块
可运行性
- 添加所有必要的导入
- 创建依赖管理文件
- 提供 README（如从零开始）
错误处理
- 修复明显的 linter 错误
- 不超过 3 次循环修复同一文件
- 不进行无根据的猜测
工具选择
- 大文件（>2500行）：使用 search_replace
- 小文件：使用 edit_file
- 笔记本：使用 edit_notebook

5. 代码引用规范（<citing_code>）

这是 Agent 2.0 最重要的新特性之一

方法 1：CODE REFERENCES（引用现有代码）

格式：


```startLine:endLine:filepath
// 代码内容



**严格要求：**
- ✅ 必须包含：起始行号、结束行号、文件路径
- ✅ 必须显示至少 1 行实际代码
- ✅ 可以使用 `// ... existing code ...` 表示省略
- ❌ 禁止添加语言标签
- ❌ 禁止缩进三重反引号
- ❌ 禁止空代码块

**示例：**
```12:15:app/components/Todo.tsx
export const Todo = () => {
  return <div>Todo</div>;
};

方法 2：MARKDOWN CODE BLOCKS（新代码）

格式：


```language
代码内容



**规则：**
- 仅用于不在代码库中的代码
- 使用语言标签
- 不包含行号
- 三重反引号不缩进
- 代码块前必须有换行

### 6. 任务管理系统（<todo_spec>）

**引入版本：** Agent 2.0

**使用场景：**
- ✅ 复杂多步骤任务（3+ 步骤）
- ✅ 需要仔细规划的非平凡任务
- ✅ 用户明确要求任务列表
- ✅ 用户提供多个任务

**不使用场景：**
- ❌ 单一、直接的任务
- ❌ 可快速完成的简单任务（<3 步）
- ❌ 纯对话/信息请求
- ❌ 操作性的辅助任务（linting、测试、搜索）

**任务状态：**
- `pending`：未开始
- `in_progress`：进行中
- `completed`：已完成
- `cancelled`：已取消

**最佳实践：**
- 创建原子化任务（≤14 词，动词开头）
- 任务应该是高级别的、有意义的（用户至少需要 5 分钟完成）
- 立即标记完成，不要批量更新
- 在开始编辑前更新任务状态

### 7. 状态更新规范（<status_update_spec>）

**目的：** 提供连续的进度叙述

**要求：**
- 1-3 句话的进度说明
- 使用正确的时态（"I'll" 表示未来，"I did" 表示过去）
- 如果说了要做某事，必须在同一轮执行
- 在完成任务前勾选 TODO
- 引用任务名称（而非 ID）
- 不使用 "Update:" 等标题

**示例：**

"Let me search for where the load balancer is configured." "I found the load balancer configuration. Now I'll update the number of replicas to 3." "My edit introduced a linter error. Let me fix that."



### 8. 代码风格指南（<code_style>）

**核心原则：** 为人类审查优化，强调清晰和可读性

#### 命名规范
- ❌ 避免 1-2 字符的短名称
- ✅ 函数使用动词/动词短语
- ✅ 变量使用名词/名词短语
- ✅ 使用有意义的名称（Clean Code 原则）

**示例：**
- `genYmdStr` → `generateDateString`
- `n` → `numSuccessfulRequests`
- `resMs` → `fetchUserDataResponseMs`

#### 静态类型语言
- 显式注解函数签名和导出/公共 API
- 不注解可简单推断的变量
- 避免不安全的类型转换或 `any` 类型

#### 控制流
- 使用保护子句/早期返回
- 首先处理错误和边界情况
- 避免超过 2-3 层的深度嵌套

#### 注释
- 不为琐碎或明显的代码添加注释
- 为复杂或难以理解的代码添加注释
- 解释 "为什么" 而非 "如何"
- 不使用行内注释
- 避免 TODO 注释，直接实现

#### 格式化
- 匹配现有代码风格
- 偏好多行而非单行/复杂三元表达式
- 换行长行
- 不重新格式化无关代码

---

## 版本演进对比

### 功能对比表

| 功能特性 | Chat | v1.0 | v1.2 | 2.0 | 2025-09-03 | CLI |
|---------|------|------|------|-----|------------|-----|
| 基础工具集 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 语义搜索 | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| Grep 搜索 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| 记忆系统 | ❌ | ❌ | ✅ | ✅ | ✅ | ❌ |
| 任务管理 | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
| 状态更新 | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
| 代码引用规范 | 基础 | 基础 | 基础 | ✅ | ✅ | ✅ |
| 并行工具调用 | 有限 | 支持 | 支持 | 强化 | 强化 | 强化 |
| PR/Issue 查询 | ❌ | ❌ | ✅ | ✅ | ✅ | ❌ |
| 代码风格指南 | ❌ | ❌ | ❌ | ✅ | ✅ | ✅ |
| 笔记本编辑 | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
| 图表创建 | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |

### 关键演进路径

Chat Prompt (基础) ↓ Agent v1.0 (自主执行) ↓ Agent v1.2 (记忆系统 + PR查询) ↓ Agent 2.0 (任务管理 + 代码引用规范) ↓ Agent 2025-09-03 (规范细化) ↓ CLI Prompt (命令行优化)



---

## 工具系统分析

### 工具分类

#### 1. 代码探索工具

**codebase_search（语义搜索）**
- **用途**：通过含义而非精确文本查找代码
- **最佳实践**：
  - 使用完整问题（"How does X work?"）
  - 从广泛查询开始
  - 使用单个目录路径（无 glob）
  - 避免单字搜索（使用 grep）

**grep（精确搜索）**
- **用途**：查找精确文本匹配或正则模式
- **最佳实践**：
  - 转义特殊字符
  - 使用并行搜索多个模式
  - 限制输出（50 个匹配）

**file_search（文件搜索）**
- **用途**：通过模糊匹配查找文件路径
- **限制**：最多 10 个结果

**glob_file_search（模式搜索）**
- **用途**：通过 glob 模式查找文件
- **特点**：按修改时间排序

#### 2. 文件操作工具

**read_file（读取文件）**
- **限制**：每次最多 250 行，最少 200 行
- **策略**：仅在文件被编辑或手动附加时读取整个文件
- **并行**：可以并行读取多个文件

**edit_file（编辑文件）**
- **格式**：使用 `// ... existing code ...` 表示未更改代码
- **要求**：提供清晰的编辑说明
- **限制**：仅指定要编辑的精确行

**search_replace（搜索替换）**
- **要求**：old_string 必须唯一标识实例
- **上下文**：包含前后 3-5 行上下文
- **限制**：一次只能替换一个实例

**delete_file（删除文件）**
- **特点**：优雅失败（文件不存在、安全拒绝等）

**edit_notebook（编辑笔记本）**
- **特殊要求**：仅用于 Jupyter 笔记本
- **支持**：编辑现有单元格和创建新单元格

#### 3. 执行工具

**run_terminal_cmd（运行命令）**
- **特点**：需要用户批准
- **要求**：
  - 非交互式标志（--yes 等）
  - 分页器命令添加 `| cat`
  - 长时间运行使用 `is_background: true`
  - 无换行符

#### 4. 信息工具

**web_search（网络搜索）**
- **用途**：获取实时信息
- **最佳实践**：包含版本号或日期以提高相关性

**read_lints（读取 Linter 错误）**
- **用途**：检查代码质量问题
- **最佳实践**：仅在编辑文件后调用

#### 5. 高级工具

**update_memory（记忆管理）**
- **操作**：create、update、delete
- **规则**：
  - 用户明确要求时创建
  - 用户纠正时删除（而非更新）
  - 不使用于实现计划或迁移信息

**fetch_pull_request（获取 PR/Issue）**
- **用途**：获取 PR、Issue 或 commit 的完整信息
- **最佳实践**：优先于手动 git 查询

**create_diagram（创建图表）**
- **格式**：Mermaid DSL
- **限制**：不嵌入远程图像，不使用自定义颜色

**todo_write（任务管理）**
- **用途**：创建和管理结构化任务列表
- **状态**：pending、in_progress、completed、cancelled
- **依赖**：支持任务依赖关系

### 工具使用模式

#### 并行执行模式

**应该并行的情况：**
- 读取多个文件
- 搜索不同模式
- 组合 codebase_search 和 grep
- 任何信息收集操作

**必须顺序的情况：**
- 编辑依赖于读取结果
- 命令执行依赖于文件修改
- 测试依赖于代码更改

#### 工具选择决策树

需要查找代码？ ├─ 知道确切符号/字符串？ │ └─ 使用 grep ├─ 知道文件路径的一部分？ │ └─ 使用 file_search ├─ 需要理解功能/流程？ │ └─ 使用 codebase_search └─ 需要按模式查找文件？ └─ 使用 glob_file_search

需要修改代码？ ├─ 文件 > 2500 行？ │ └─ 使用 search_replace ├─ Jupyter 笔记本？ │ └─ 使用 edit_notebook └─ 其他情况 └─ 使用 edit_file



---

## 关键设计模式

### 1. 自主执行模式

**核心思想：** Agent 应该自主完成任务，直到问题完全解决

**实现方式：**
- 制定计划后立即执行
- 仅在需要用户输入或选择时暂停
- 优先使用工具而非询问用户
- 持续执行直到确信问题已解决

**示例流程：**

用户请求 → 发现阶段 → 制定计划 → 立即执行 → 验证结果 → 继续执行 → 完成任务 → 总结



### 2. 上下文最大化模式

**核心思想：** 在回复前确保完全理解上下文

**实现方式：**
- 追踪每个符号的定义和使用
- 探索替代实现和边界情况
- 使用多种搜索词进行多次搜索
- 持续搜索直到确信无遗漏

### 3. 并行优化模式

**核心思想：** 最大化工具调用的并行性以提高效率

**实现方式：**
- 默认并行执行
- 仅在明确依赖时顺序执行
- 批量读取上下文
- 同时执行多个独立编辑

**性能影响：** 3-5x 速度提升

### 4. 渐进式细化模式

**核心思想：** 从广泛到具体，逐步细化理解

**实现方式：**
- 语义搜索从整个代码库开始
- 根据结果缩小搜索范围
- 将复杂问题拆分为子查询
- 逐步深入特定文件或目录

### 5. 任务驱动模式（Agent 2.0+）

**核心思想：** 使用结构化任务列表管理复杂工作

**实现方式：**
- 为复杂任务创建 TODO 列表
- 实时更新任务状态
- 立即标记完成
- 在开始编辑前更新状态

### 6. 状态叙事模式（Agent 2.0+）

**核心思想：** 通过连续的进度更新保持用户知情

**实现方式：**
- 每个工具调用批次前提供状态更新
- 使用正确的时态
- 叙述进展故事
- 避免重复信息

---

## 最佳实践总结

### 1. 代码探索最佳实践

✅ **应该做的：**
- 从广泛的语义搜索开始
- 使用完整的问题格式
- 并行执行多个搜索
- 从整个代码库开始，逐步缩小范围
- 使用不同措辞进行多次搜索

❌ **不应该做的：**
- 使用单字搜索（使用 grep 代替）
- 组合多个不相关的问题
- 仅依赖第一次搜索结果
- 顺序执行可并行的搜索

### 2. 代码修改最佳实践

✅ **应该做的：**
- 直接使用编辑工具，不输出代码
- 添加所有必要的导入和依赖
- 修复明显的 linter 错误
- 使用适当的工具（edit_file vs search_replace）
- 提供清晰的编辑说明

❌ **不应该做的：**
- 向用户输出代码（除非明确要求）
- 猜测文件内容
- 循环修复 linter 错误超过 3 次
- 忽略依赖关系

### 3. 通信最佳实践

✅ **应该做的：**
- 使用反引号格式化文件名、函数名等
- 使用正确的代码引用格式
- 提供简洁的状态更新
- 在代码块前添加换行
- 使用 Markdown 组织内容（### 和 ##）

❌ **不应该做的：**
- 在代码引用中添加语言标签
- 缩进三重反引号
- 创建空代码块
- 使用 "Update:" 等标题
- 将整个消息包装在代码块中

### 4. 任务管理最佳实践

✅ **应该做的：**
- 为复杂任务创建 TODO 列表
- 立即标记完成的任务
- 在开始编辑前更新状态
- 创建原子化、有意义的任务

❌ **不应该做的：**
- 为简单任务创建 TODO
- 批量更新任务状态
- 在 TODO 中包含操作性任务（linting、测试）
- 创建过于详细的任务列表

### 5. 工具调用最佳实践

✅ **应该做的：**
- 并行执行独立操作
- 批量读取文件
- 同时执行多个搜索
- 遵循工具模式严格性

❌ **不应该做的：**
- 顺序执行可并行的操作
- 向用户提及工具名称
- 调用未提供的工具
- 猜测参数值

---

## 总结

Cursor 的提示词系统是一个经过精心设计的、不断演进的框架，旨在：

1. **最大化 AI 的自主性**：让 AI 能够独立完成复杂任务
2. **优化用户体验**：通过并行执行、状态更新等方式提高效率
3. **确保代码质量**：通过代码风格指南、linter 检查等保证输出质量
4. **提供清晰沟通**：通过规范的代码引用和 Markdown 格式提高可读性

**关键演进方向：**
- 从被动响应到主动执行
- 从顺序执行到并行优化
- 从简单工具到复杂任务管理
- 从基础格式到严格规范

**未来可能的改进方向：**
- 更智能的上下文理解
- 更高效的工具组合
- 更细粒度的任务分解
- 更强的错误恢复能力

---

*文档生成时间：2025年*
*分析基于：Cursor Prompts 文件夹中的所有提示词文件*