Cursor Composer 实战：1 个 prompt 改 5 个文件

30 秒了解：Cursor Composer 是什么、为什么是杀手锏

Cursor Composer 是 Cursor 编辑器里的「多文件改写模式」——按 Cmd+I（Mac）或 Ctrl+I（Windows / Linux）打开后，输入一句话需求，AI 会同时改 3-10 个相关文件，每个文件给 diff 让你逐个审。跟 Cmd+K 单文件改写比，Composer 是「能跑一小时活的 Agent 模式」；跟 Claude Code 终端 CLI 比，Composer 在图形界面里跑、所有 diff 可视化、回滚一键搞定。

这是 Cursor 跟 VS Code + Copilot 拉开距离的核心功能，也是「一个独立开发者顶 3 个人」的关键武器。这篇带你 30 分钟完整跑通。

如果你还没用过 Cursor，先看 Cursor 怎么用跑通基础，再回来。

准备工作：3 件事

Cursor 装好且登录：免费 Hobby 档也能用 Composer，只是次数有限；建议升 Pro
一个真实项目：纯空目录练不出感觉，至少 10 个文件以上
项目是干净的 git 状态：跑 Composer 前先 git commit，万一改飞了能 reset

第 1 步：打开 Composer 面板

打开 Cursor，按 Cmd+I（Mac）或 Ctrl+I（Windows / Linux）。屏幕中间弹一个大输入框——这就是 Composer 主面板。

跟 Chat（Cmd+L）的区别：

维度	Chat（Cmd+L）	Composer（Cmd+I）
主要用途	问代码、讨论方案、不改文件	让 AI 真正动手改多个文件
输出	文字回答 + 代码片段	多文件 diff
改文件能力	不改（需要你手动复制）	直接改，给 diff 你审
适用	探索、提问、debug	加功能、重构、跑长任务

记住一句话：讨论用 Chat，干活用 Composer。

第 2 步：喂对上下文（最关键的一步）

Composer 的效果 80% 取决于上下文。3 种喂法：

方式 1：让它自动找（最懒）

直接说「重构 UserCard 组件，拆成 Avatar + UserInfo」。Composer 会基于项目索引自己找相关文件。适合小项目（< 50 文件）+ 命名规范的代码。

方式 2：用 `@` 精准指定（最准）

输入 @ 触发引用：

@file 指定某个文件
@folders 指定某个文件夹
@codebase 让它搜整个项目

例：

@components/UserCard.tsx 这个组件拆成两个：
- Avatar 组件放头像逻辑
- UserInfo 组件放名字 / 邮箱

更新所有 @components 下用 UserCard 的地方

这种「主体文件 + 影响范围」的双 @，效果比纯自然语言准 3 倍。

方式 3：贴整段代码（最猛）

如果你想让 Composer 严格按某个参考实现来改，直接把参考代码贴进 Composer 输入框：

按下面这段 design tokens 的规范，
把 @components 下所有硬编码的颜色换成 token：

[此处贴参考代码]

Composer 会以贴入的代码为「事实标准」执行。

第 3 步：写一个好 prompt

Composer 的 prompt 跟普通 AI 对话不一样，要更结构化。推荐 5 段式：

📋 Prompt 模板

任务：把当前项目的 React Class 组件全部重构成函数组件 + hooks

范围：

只动 src/components 下的 .tsx 文件
不动 src/pages 和 src/api
不动测试文件

约束：

保持原有 props 接口不变
保持原有外部行为不变
用 useState / useEffect / useMemo 重写状态管理

步骤：

先扫描列出所有 Class 组件文件
一个文件一个文件改，每改完一个先停下来给我审
改完所有文件后，跑一次构建确认没报错

输出：

每改一个文件前，先用一句话说”这个组件涉及哪些 state / lifecycle”
改完所有文件后，列出可能影响的外部调用方

注意：

任务 / 范围 / 约束 / 步骤 / 输出 5 段分清楚
明确说不要动什么（比纯说”动什么”更重要）
要求分步停下来给你审（避免一口气改 20 个文件没法回退）

第 4 步：审 diff，逐个 Accept / Reject

Composer 跑完，左侧面板列出所有改动的文件，每个文件点开是 diff（红绿对比）。你的工作：

每个文件单独审：点 Accept 接受、Reject 拒绝
整体不满意：右上角 Reject all，全部回退
想改其中一个文件的某段：直接在编辑器里手动调

提示：审 diff 时别只看「改了什么」，重点看「漏改了什么」。Composer 偶尔会漏掉一两个引用，编译之后才报错。

第 5 步：跑完一段活的善后

接受完所有 diff 后，3 件事必做：

跑构建 / 测试：终端跑 npm run build 和 npm test，确认没破坏现有功能
手动审一遍 git diff：终端 git diff 整体过一遍，比 Composer 的逐文件视图更适合看整体改动
commit 落盘：写一条 commit message 说明 Composer 帮你做了什么

如果发现改飞了：

小问题：在 Composer 里继续追问「你刚才改的 UserCard 漏了一个 prop，补一下」
大问题：git reset --hard HEAD 一键回滚到 Composer 跑之前

Composer 的 5 个高级技巧

技巧 1：用 Agent 模式跑长任务

Composer 顶部能切「Normal」和「Agent」两种模式：

模式	行为	适合
Normal	一次响应改一批文件	中等任务（5-10 文件）
Agent	自主迭代、能跑命令、可以跑很久	大任务（半小时以上）

Agent 模式下，Composer 能：

自己跑 npm install 装包
自己跑测试看结果
看到测试失败自己改、再跑
持续迭代直到任务真正完成

适合「让 AI 自己跑 30 分钟把活儿干完」的场景。

技巧 2：用 Checkpoint 安全回滚

每次 Composer 跑完一轮，左侧面板会自动建一个 Checkpoint（快照）。点 checkpoint 旁边的 Restore，能回到那个时刻的代码状态——比 git reset 更细，能在一次会话里来回试。

技巧 3：粘报错让 Composer 自动修

跑测试 / 构建报错？直接把整段报错贴进 Composer，加一句：

按上面这段报错，找到出错的文件、定位原因、改好。
改完跑一次测试确认绿了。

Composer 会顺着报错栈找到对应文件、改完跑测试验证。比你自己 debug 快得多。

技巧 4：用 `.cursorrules` 给 Composer 写约定

项目根目录的 .cursorrules 是 Composer 的「项目级约束」，每次跑都会读。典型内容：

你是一个高级 TypeScript 工程师。

约束：
- 用 strict 模式，禁止 any
- 函数式组件 + hooks，不要 class
- 样式用 Tailwind，不要 CSS Module
- 测试用 vitest

约定：
- 组件文件名 PascalCase.tsx
- 工具文件名 camelCase.ts
- 每个 export 函数必须有 JSDoc

改文件前必看：
- src/types/index.ts 里的全局类型
- src/utils/api.ts 里的 fetch 封装

禁止：
- 不要装新依赖（如果必须装，先停下来问我）
- 不要改 src/legacy/ 下的代码

写好这份文件，Composer 跑出来的代码风格立刻跟项目对齐，省一大半 review 时间。

技巧 5：拆任务比一次扔大单更稳

新手最爱犯的错：

「重构整个前端，加上 i18n、深色模式、PWA 支持」

一句话扔进 Composer，结果改 50 个文件、漏 10 处、最后 reset 重来。

正确姿势：

今天这次会话只做 1 件事：给项目加 i18n（中英双语）。

步骤：
1. 先列出 plan（不要动文件）
2. 我审完 plan 后，按 plan 第 1 步执行
3. 一步一步走，每步停下来等我审

一句话 = 一件事。复杂任务拆成 3-5 次 Composer 调用，比一次扔大单稳得多。

常见的 4 个坑

现象	原因	解决
Composer 改了不该改的文件	没明确限定范围	prompt 里加「只动 X 目录，不动 Y 目录」
改完代码跑测试报错	没让它跑测试验证	prompt 里加「改完跑测试确认绿了」
一次改 30 个文件没法审	任务太大	拆成 3 次 Composer 调用，每次 10 个
Composer 跑到一半卡住	上下文超限 / 网络波动	切 Agent 模式 + 分步任务，或换更轻的模型

一个完整实战：让 Composer 给项目加深色模式

假设你接手一个只有亮色主题的 React + Tailwind 项目，老板说「给我加深色模式，1 天搞定」。

第 1 步：先用 Chat（Cmd+L）调研

📋 Prompt 模板

我要给当前项目加深色模式（dark mode）。
先帮我分析：

当前用的 Tailwind 配置是什么版本（v3 还是 v4）
项目里硬编码颜色的地方大概有多少处（grep 一下 bg-white / text-black 等）
推荐的实现方案（class strategy / media query / next-themes 之类的库）
给我一个 5-7 步的实施 plan
只输出分析和 plan，不要动任何文件。

第 2 步：审完 plan，开 Composer（Cmd+I）跑第 1 步

📋 Prompt 模板

按 plan 第 1 步执行：配置 Tailwind dark mode strategy。

具体动作：

改 tailwind.config.ts，加 darkMode: ‘class’
在 src/app/layout.tsx 顶层加一个根 div，挂 className 用于切换 dark class
安装并配置 next-themes 提供 ThemeProvider
在 components/ui 下新建一个 ThemeToggle 按钮组件

只做这 4 件事，不要动具体 UI 组件的颜色。改完跑构建确认没报错。

第 3 步：审 diff、跑构建、git commit，再开 Composer 跑第 2 步「批量替换硬编码颜色」。

第 4 步：跑完一轮 UI 验证（终端 npm run dev 打开浏览器实际看效果）。

跑完整套你会发现：Composer 的真正价值不是「AI 自动写代码」——而是 「AI 写、你审、git 兜底」三方协作。养成这套节奏，1 个人确实能干 3 个人的活。

下一步

想换更便宜模型给 Composer 用 → Cursor 切换模型全教程
想看 Cursor 基础操作 → Cursor 怎么用
想看 Cursor vs Copilot → Cursor vs Copilot 对比
想看 CLI 派的杀手锏 → Claude Code 怎么用
想看 AI 编程全景 → AI 写代码完全指南
想接 Cursor 进国产模型 → Cursor 切换模型教程

常见问题

Q：Composer 跟 Cmd+K 的区别是什么？ A：Cmd+K 一次只能改你选中的那一段代码，单文件单段。Composer 能同时改 3-10 个文件，跨文件协作。简单改写用 Cmd+K，加功能 / 重构用 Composer。

Q：Composer 算 Cursor 的什么档？ A：免费 Hobby 档每天有限次数，Pro 档（20 美元每月）几乎不限。一天 10-20 次 Composer 调用，Hobby 大概率不够，开发主力建议升 Pro。

Q：Composer 改完没法 undo 怎么办？ A：3 道防线：1) Composer 左侧面板的 Checkpoint Restore（最方便），2) Cursor 自身的 Cmd+Z（单文件级别），3) git reset --hard（全项目级别）。所以跑 Composer 前一定 commit。

Q：Agent 模式会自动 commit 吗？ A：默认不会。它只改代码、跑命令，不会主动 git commit——commit 这个动作必须人来做（也是最后一道审查关）。如果你想让它 commit，prompt 里明确说「改完帮我 git add 并 commit」。

Q：Composer 出来的代码质量怎么样？ A：取决于模型 + 上下文。用 Claude Opus 4.5 / GPT-5 + 写好 .cursorrules + 精准 @ 引用，质量接近中级工程师。用 cursor-small 跑大重构，质量会差很多——按任务难度匹配模型。

30 秒了解：Cursor Composer 是什么、为什么是杀手锏

准备工作：3 件事

第 1 步：打开 Composer 面板

第 2 步：喂对上下文（最关键的一步）

方式 1：让它自动找（最懒）

方式 2：用 @ 精准指定（最准）

方式 3：贴整段代码（最猛）

第 3 步：写一个好 prompt

第 4 步：审 diff，逐个 Accept / Reject

第 5 步：跑完一段活的善后

Composer 的 5 个高级技巧

技巧 1：用 Agent 模式跑长任务

技巧 2：用 Checkpoint 安全回滚

技巧 3：粘报错让 Composer 自动修

技巧 4：用 .cursorrules 给 Composer 写约定

技巧 5：拆任务比一次扔大单更稳

常见的 4 个坑

一个完整实战：让 Composer 给项目加深色模式

下一步

常见问题

方式 2：用 `@` 精准指定（最准）

技巧 4：用 `.cursorrules` 给 Composer 写约定