Cursor Vibe Coding 开发指南

本文档说明如何在 Cursor IDE 中进行 Vibe Coding 开发：如何写提示词、如何为项目建立持久化规范，以及 Cursor 的常见配置（含 DeepSeek V4 中转接入、代码变更自动接受等）。

若你使用 Vue 3 项目 ，可配合阅读 vibe-coding-指南.md------那份文档侧重业务需求 → 架构 → Skill/Rule 的完整项目流程；本文侧重 Cursor 工具本身 的用法与配置。

---

1. 什么是 Vibe Coding

Vibe Coding 指以自然语言与 AI 协作完成软件开发：你描述意图与边界，AI 读代码、改代码、跑命令；你负责方向、验收与关键决策。

在 Cursor 中，这通常通过 Agent 模式 实现------Agent 可以读写工作区文件、执行终端命令、调用 MCP 工具，形成「对话 → 执行 → 验证」的闭环。

正确的 Vibe Coding 不是「一句话让 AI 写完整个项目」，而是：

人：业务目标、边界、验收标准
AI：调研、实现、重构、补测试
机器：Lint / TypeCheck / Test / CI
项目规范：Rules + Skills + docs/ 文档

规矩越前置，AI 越像带规范的 pair programmer，而不是碰运气的代码生成器。

---

2. Cursor 核心能力一览

能力	作用	典型场景
Agent	自主读改代码、跑命令、多步任务	实现功能、修 bug、跑测试
Ask	只读，不改代码	理解代码、架构问答
Plan	只读，先出方案再动手	大改前做设计讨论
Rules	项目级持久规范（.cursor/rules/）	分层、命名、禁止事项
Skills	任务型操作手册（.cursor/skills/）	写 composable、Code Review 流程
@ 引用	把文件/文件夹/文档注入上下文	@src/api/user.ts、@docs/architecture.md
MCP	连接外部工具（Figma、数据库等）	设计稿转代码、查日志

2.1 三种对话模式的选用

模式	何时用
Agent	需要改代码、跑命令、完成可验收任务
Ask	只想问「这段代码干什么」「有没有更好的写法」
Plan	任务大、方案不确定，先对齐再实现

经验法则： 需求清楚、边界明确 → 直接用 Agent；需求模糊或涉及架构取舍 → 先 Plan/Ask，确认后再 Agent。

---

3. 如何为项目写提示词（Prompt）

3.1 提示词规范（CRTC 结构）

高质量 Prompt 建议包含四块，可按任务轻重裁剪：

字母	含义	写什么
C --- Context	背景	功能背景、链到 PRD/architecture、相关 @ 文件
R --- Request	任务	一句话、可验收的具体目标
T --- Constraints	约束	遵循哪些 Rule、不动哪些模块、技术栈限制
C --- Completion	完成标准	跑哪些命令、如何手动验证、输出格式

反模式（避免）：

• ❌ 「帮我优化一下」------ 无范围、无标准
• ❌ 「把整个后台做完」------ 上下文爆炸、易翻车
• ❌ 只写功能不写约束 ------ AI 会自创目录和风格
• ❌ 同一轮里混多个无关任务 ------ 难以 review

正模式：

• ✅ 单次会话一个可验收小任务
• ✅ 显式 @ 相关文件，减少 AI 漏读
• ✅ 写清「不要做什么」
• ✅ 末尾附上验证命令

3.2 标准功能开发 Prompt 模板

## 背景
[1～2 句话，或 @docs/architecture.md]

## 任务
[具体、可验收的一句话，例如：为订单列表页添加分页 composable]

## 约束
- 遵循 docs/architecture.md 与 .cursor/rules/
- 不修改 src/stores/user.ts
- 使用 Composition API + TypeScript
- 最小 diff，不重构无关代码

## 相关文件
@src/views/order/IndexPage.vue
@src/composables/usePagination.ts

## 完成后
1. 运行 npm run lint && npm run typecheck
2. 简述改动文件与如何手动验证

3.3 按场景分类的 Prompt 示例

需求澄清（不写代码）

我要做 [一句话功能描述]。
请列出：① 可能遗漏的用户场景 ② 边界情况 ③ 非功能风险 ④ 需要我确认的 10 个问题（按优先级排序）。
不要写代码，只输出结构化追问。

架构设计（只出方案）

基于 @docs/prd-order.md，为 Vue 3 项目设计订单模块架构。
要求：
1. 给出 src/ 目录树及职责说明
2. 画数据流 mermaid
3. 列出 3 条禁止事项（如：页面不得直接 axios）
输出 markdown，不要写实现代码。

Code Review（只读）

Review 本次 diff（不要改代码）：
1. 是否违反 docs/architecture.md
2. 是否有重复逻辑可抽取
3. 是否有明显性能问题
输出按 P0/P1 排序的 findings。

Bug 修复

## 现象
[复现步骤 + 期望 vs 实际]

## 相关文件
@src/lib/notationHit.ts
@tests/unit/notationHit.spec.ts

## 约束
- 先定位根因再改，不要猜测性大改
- 改完后补/更新单测
- npm run test:unit 必须通过

创建 Cursor Rule

根据 @docs/architecture.md，生成 .cursor/rules/api-layer.mdc：
- globs: src/api/**
- 可执行条目（禁止在组件里裸 fetch 等）
- 一个正确示例
控制在 50 行以内。

3.4 提示词进阶技巧

技巧	说明
先规划后动手	加一句「先列出要改的文件清单，确认后再改」
显式 Skill	如 Use vue skill，激活项目 .cursor/skills/ 中的领域手册
分阶段	大任务拆成：调研 → 方案 → 实现 → 测试，每阶段新会话或新消息
引用文档而非重复	用 @docs/architecture.md 代替粘贴大段文字
写反模式	「不要引入新依赖」「不要改 public API」比只说「小心」有效
指定输出格式	「输出 markdown 表格」「只给 findings 不改代码」

---

4. 项目级规范：Rules 与 Skills

单靠聊天里的 Prompt 无法跨会话保持风格；应把 稳定约束 写进仓库。

4.1 Rules（.cursor/rules/*.mdc）

作用： 约束「在这个项目里必须/禁止怎样写」------规范型、边界型。

格式示例：

---
description: API 层约定
globs: src/api/**
alwaysApply: false
---

# API 层

- 所有 HTTP 调用集中在 src/api/
- 组件与 composable 不得直接 import axios
- 错误统一抛 ApiError，由调用方处理 UI 提示

字段	说明
description	规则简介，出现在规则选择器
globs	匹配文件时自动注入（如 **/*.vue）
alwaysApply: true	每次对话都生效（适合放技术栈摘要）

编写原则：

• 一条 rule 一个关注点，50 行以内
• 写可执行句子（「用 storeToRefs」而非「注意响应式」）
• 引用仓库内真实文件作范本

建议拆分：

文件	globs	内容
project-stack.mdc	alwaysApply: true	技术栈、测试命令、分支策略
vue-pages.mdc	**/*.vue	组件放置、props/emits
api-layer.mdc	src/api/**	HTTP 封装约定
domain-lib.mdc	src/lib/**	纯 TS、禁止 import Vue

4.2 Skills（.cursor/skills/）

作用： 教 AI 如何完成某类任务 的步骤------流程型、任务型。

与 Rule 互补：Skill 管方法，Rule 管边界。

.cursor/skills/your-feature/
├── SKILL.md       # 必需：frontmatter + 分步 workflow
├── reference.md   # 可选：详细 API
└── examples.md    # 可选：正反例

SKILL.md 示例 frontmatter：

---
name: add-vue-feature-module
description: >-
  Add a new feature module: views, composable, api, tests.
  Use when creating routes or feature folders.
---

在 Prompt 中可写：Use add-vue-feature-module skill（具体 invocation 以 Cursor 当前版本为准）。

4.3 可选：AGENTS.md

在仓库根目录放 AGENTS.md，作为 AI 的 项目入口索引：如何启动、测试命令、目录地图、链接到 architecture。适合 onboarding，与 Rules 配合使用。

4.4 规范与 Prompt 的关系

Rules/Skills/docs  →  持久、跨会话、团队共享
单次 Prompt        →  任务范围、本次约束、@ 文件
Lint/CI            →  机器兜底，AI 改完必须过门禁

从失败中迭代： AI 重复犯同一错 → 写进 Rule（硬约束）或 Skill（流程步骤），必要时加单测。

---

5. 日常 Vibe Coding 工作流

flowchart LR A[澄清需求] --> B[写 Prompt + @ 文件] B --> C[Agent 执行] C --> D[Review diff] D --> E[跑 lint/test] E --> F{通过?} F -->|否| B F -->|是| G[提交 / PR]

1. 拆任务 --- 一个会话内可完成、可验收
2. 写 Prompt --- 用 CRTC 模板 + @ 相关文件
3. Agent 执行 --- 关注 diff，不盲信
4. 机器验证 --- lint、typecheck、test
5. 人工验证 --- 关键用户路径走一遍
6. 沉淀规范 --- 翻车点写回 Rule/Skill

适合交给 AI： 样板代码、重构抽取、修 lint/类型、纯函数单测、文档草稿。

需人工主导： 安全权限、支付合规、核心算法 spec、破坏性 API 变更。

---

6. Cursor 接入 DeepSeek V4（含中转方案）

DeepSeek V4 提供 OpenAI 兼容 API，可在 Cursor 中作为 自定义模型（BYOK） 使用。但 V4 系列（尤其 deepseek-v4-pro）默认开启 Thinking 模式 ，多轮对话 + 工具调用时存在与 Cursor 的兼容问题，通常需要 中转代理。

6.1 为什么需要中转

DeepSeek V4 在 thinking 模式下会在响应中返回 reasoning_content 字段。多轮对话（尤其 Agent 读文件、改代码等 tool call）时，必须把上一轮的 reasoning_content 原样回传给 API。

Cursor 在 BYOK 路径上 目前不会保存并回传 该字段，因此会出现类似错误：

The reasoning_content in the thinking mode must be passed back to the API.

简单单轮问答可能正常；一旦 Agent 开始读项目代码、多轮 tool call，就容易 400 失败。

解决方案： 在 Cursor 与 DeepSeek API 之间加一层 OpenAI 兼容中转 ，由代理缓存并回注入 reasoning_content，或默认关闭 thinking 以规避问题。

参考：Cursor 社区讨论

6.2 方案 A：直连 DeepSeek API（简单场景）

适用于：Chat 单轮/少轮对话 ，或 flash 等非强 reasoning 场景。

1. 在 DeepSeek 开放平台 注册并创建 API Key
2. 打开 Cursor Settings → Models
3. 开启 Override OpenAI Base URL（或 Custom API）
4. 配置：

项	值
OpenAI Base URL	https://api.deepseek.com（不要 手动加 /v1，Cursor 会拼 /chat/completions，重复 /v1 易 404）
API Key	你的 DeepSeek Key（sk-...）
Model Name	deepseek-v4-pro 或 deepseek-v4-flash（须与 API 文档一致，区分大小写）

5. 点击 Verify 验证连通性
6. 在 Chat/Agent 模型选择器中选该自定义模型

注意：

• Tab 自动补全等部分 Cursor 原生能力可能仍走 Cursor 自带模型，不一定会走 BYOK
• Agent 多轮 + tool call 仍可能触发 6.1 中的 reasoning_content 错误

6.3 方案 B：社区中转代理（推荐用于 Agent / Composer）

常用开源中转（任选其一，以各自 README 为准）：

项目	语言	说明
yxlao/deepseek-cursor-proxy	Python	缓存并回注入 reasoning_content，支持 v4-pro / v4-flash
hhz-168/cursor-deepseek-bridge	Go	默认关闭 thinking；-thinking 后缀可开启并桥接多轮

通用部署步骤（以 Python 代理为例）

1. 安装并启动本地代理

# 示例：deepseek-cursor-proxy
pip install deepseek-cursor-proxy
# 或 uv / 克隆仓库后按 README 运行
deepseek-cursor-proxy
# 默认监听本地端口，如 http://127.0.0.1:8000

2. 暴露为公网 HTTPS（必需）

Cursor 的 SSRF 防护 会拒绝 localhost / 127.0.0.1 作为 Base URL，因此本地代理必须通过隧道暴露：

# 示例：ngrok（免费 tier 即可个人使用）
ngrok http 8000
# 得到类似 https://xxxx.ngrok-free.app

也可使用 Cloudflare Tunnel 等，关键是 HTTPS + 公网可达。

3. 在 Cursor 中配置

项	值
OpenAI Base URL	https://xxxx.ngrok-free.app/v1（中转文档通常要求带 /v1）
API Key	你的 DeepSeek API Key（代理转发，不在代理层另设 auth）
Model Name	deepseek-v4-pro 或 deepseek-v4-flash

4. Verify → 在 Agent 中试多轮读代码任务

若单轮正常、多轮失败，检查代理日志是否成功缓存 reasoning_content。

cursor-deepseek-bridge 补充

该代理支持通过 模型名后缀 控制 thinking：

Cursor 中填写的 Model	行为
deepseek-v4-pro	thinking 关闭（兼容性最好）
deepseek-v4-pro-thinking	开启 thinking + 自动桥接 reasoning

6.4 模型选型建议

模型	特点	适用
deepseek-v4-pro	推理强、成本较高	复杂架构、难 bug
deepseek-v4-flash	快、便宜	日常小改、样板代码

成本： BYOK 按 DeepSeek 官方 token 计费；注意在平台设置用量上限与 Key 权限。

6.5 故障排查清单

现象	检查项
Verify 404	Base URL 是否重复 /v1
400 reasoning_content	是否需中转；Agent 多轮是否触发
连不上 API	Key 余额、公司代理/证书、Cursor 网络诊断
localhost 不可用	必须用 ngrok 等隧道
模型不存在	模型名是否与 DeepSeek 文档完全一致

---

7. Cursor 开发配置指南

7.1 设置入口

• Cursor Settings （Cmd/Ctrl + Shift + J 或菜单 Cursor → Settings → Cursor Settings）
• VS Code 用户设置 （settings.json）：编辑器字体、format on save 等
• 工作区设置 （.vscode/settings.json）：仅当前项目

类型	路径（macOS 示例）
Cursor 用户设置 UI	Cursor Settings 面板
VS Code settings.json	~/Library/Application Support/Cursor/User/settings.json
项目 Rules	.cursor/rules/*.mdc
Agent 权限	Cursor Settings → Agents；或项目 permissions.json

7.2 代码变更：自动接受 vs 手动 Review

这是 Vibe Coding 中 最常混淆 的配置。

Inline Diffs（内联 diff / 是否「自动 Keep」）

设置	路径	效果
Inline Diffs = ON	Cursor Settings → Agents → Applying Changes → Inline Diffs	编辑器显示红绿 diff，可 Keep / Undo 逐块审查（推荐）
Inline Diffs = OFF	同上	变更 直接写入磁盘，无审查 UI（即 onboarding 时可能出现的「auto keep」行为）

若发现 Agent 改代码后没有 diff、无法 Accept/Reject：

1. 打开 Inline Diffs ，确认已 开启
2. 关闭再打开一次，完全退出并重启 Cursor
3. 审查面板有时在编辑器 右上角，注意查看
4. 仍异常时用 Checkpoints （聊天面板）或 git diff 回滚

社区中 onboarding 弹窗说的「auto keep」对应设置名是 Inline Diffs，不是 Auto-Run。

Auto-Run / Run Mode（终端与工具调用）

控制 Agent 跑终端命令、MCP 工具 时是否要批准，不控制 文件编辑是否自动落盘（文件编辑由 Inline Diffs 等机制决定）。

路径：Cursor Settings → Agents → Run Mode（或 Auto-Run）

模式	说明
Auto-review（3.6+ 默认）	允许列表内自动跑；其余经 LLM 分类器判断
Ask Every Time	终端/MCP 每次询问（文件编辑审查仍看 Inline Diffs）
Allowlist	仅白名单命令自动执行
Run Everything	全部自动（风险高，仅可信环境）

安全建议（来自 Cursor Agent Security 文档）：

• 始终使用 Git，便于 revert
• 敏感文件用 .cursorignore 阻止 Agent 读取
• 配置类文件修改通常仍需你批准
• 若开启 auto-reload，Agent 改动可能在 review 前就被热更新执行

7.3 模型与 API 配置

Cursor Settings → Models：

• 选择默认 Chat / Agent 模型
• 配置 OpenAI API Key 、Override Base URL（接入 DeepSeek 等）
• Add Model 添加自定义模型名

Cursor Pro 用户： 也可直接使用 Cursor 内置模型额度，无需 BYOK。

7.4 常用编辑器配置（settings.json 示例）

{
  "editor.formatOnSave": true,
  "editor.tabSize": 2,
  "files.autoSave": "onFocusChange",
  "editor.inlineSuggest.enabled": true
}

工作区可在 .vscode/settings.json 覆盖，例如指定 ESLint、Vue 格式化。

7.5 隐私与索引

设置/文件	作用
.cursorignore	排除 Agent 索引与读取（类似 .gitignore）
Privacy Mode	Cursor Settings → 控制代码是否用于训练（视版本与订阅）
Codebase Indexing	大仓库首次索引耗时，可在设置中查看状态

7.6 推荐配置组合

稳妥型（团队 / 生产代码）

• Inline Diffs：ON
• Run Mode：Auto-review 或 Ask Every Time
• Git：必须，小步提交
• 项目：Rules + lint-staged + CI

高效型（个人原型、可信沙箱）

• Inline Diffs：可 OFF（接受自动写入，靠 Git 回滚）
• Run Mode：Allowlist （放行 npm test、npm run lint 等）
• 仍建议保留 typecheck + test 在 Prompt 完成标准里

---

8. 快速 Checklist

## Cursor Vibe Coding 上手清单

- [ ] 项目有 docs/architecture.md（或等价架构说明）
- [ ] .cursor/rules/ 已按模块拆分
- [ ] 需要时安装/编写 .cursor/skills/
- [ ] Prompt 使用 CRTC 结构，单次任务可验收
- [ ] Inline Diffs 已按工作流开启或关闭
- [ ] Run Mode 与团队安全策略一致
- [ ] DeepSeek V4：直连或中转 + ngrok 已验证多轮 Agent
- [ ] lint / typecheck / test 在 Prompt 与 CI 中强制执行

---

9. 附录：Prompt 速查表

场景	一句话模板
需求澄清	针对 [功能]，列出 10 个必确认问题，不要写代码
架构	输出目录树 + 数据流 mermaid + 3 条禁止事项，不要实现
开发	任务：... 约束：@architecture + rules 完成后 lint + test
Review	Review diff，只输出 P0/P1 findings，不改代码
写 Rule	根据 @architecture 生成 .mdc，globs + 可执行条目 + 正例
写 Skill	为 [任务] 起草 SKILL.md：workflow + anti-patterns

---

10. 总结

主题	要点
Vibe Coding	人定边界 + AI 执行 + 机器校验；规范前置
提示词	CRTC 结构；小任务；@ 文件；写清约束与验收
项目规范	Rules 管边界，Skills 管流程，docs 管架构
DeepSeek V4	OpenAI 兼容 API；Agent 多轮建议中转 + HTTPS 隧道
自动接受	Inline Diffs 控制代码审查；Run Mode 控制终端/MCP

Cursor 的价值不在于「少写代码」，而在于 在明确边界内放大实施速度。把规矩写进 Rules、把任务写进 Prompt、把质量交给 Lint 和 Review------这三者齐备，Vibe Coding 才可持续。