Cursor

Cursor 是基于 VS Code 的 AI 代码编辑器，内置 Agent、补全、终端与 MCP 等能力，通过 Rules 和 Skills 提供可复用的上下文与工作流。

• 官网与下载：cursor.com/download (opens new window)
• 文档：docs.cursor.com (opens new window)

---

Rules

规则为 Agent 提供系统级指令。它们将提示词、脚本等打包在一起，便于在团队内管理和共享工作流。

Cursor 支持四种类型的规则：

• 项目规则 存储在 .cursor/rules 中，受版本控制且仅作用于你的代码库。
• 用户规则 在你的 Cursor 环境中全局生效，供 Agent (聊天) 使用。
• 团队规则 在仪表盘中集中管理的团队级规则，适用于 Team 和 Enterprise 方案。
• AGENTS.md 以 Markdown 格式编写的 Agent 指令，是 .cursor/rules 的简化替代方案。

大语言模型在各次补全之间不会保留记忆。规则在提示层面提供持久、可复用的上下文。

应用规则时，其内容会被加入到模型上下文的开头。这为 AI 在生成代码、理解修改或协助处理工作流程时提供一致的指导。

项目规则存放在 .cursor/rules 目录中的 Markdown 文件里，并纳入版本控制。它们可以通过路径模式限定作用范围、手动触发，或按相关性自动应用。

使用项目规则可以：

• 固化与你代码库相关的领域知识
• 自动化项目特定的工作流或模板
• 统一风格或架构决策

每条规则对应一个 Markdown 文件，文件名可自定义。Cursor 支持 .md 和 .mdc 扩展名；使用带 frontmatter 的 .mdc 可指定 description 和 globs，以更精细地控制规则的生效条件。

目录示例：

.cursor/rules/
  react-patterns.mdc       # 带前置元数据（description, globs）
  api-guidelines.md        # 简单 Markdown 规则
  frontend/                # 子目录组织
    components.md

规则结构

每条规则是一个带 frontmatter 的 Markdown 文件；在 Cursor 中可通过类型下拉菜单控制 description、globs、alwaysApply 等应用方式。

Frontmatter 字段：

字段	类型	描述	示例
name	string	规则名称	"Git工作流程规则"
description	string	规则描述	"定义 Git 分支管理与提交规范"
priority	number	优先级（数字越小越高）	1
alwaysApply	boolean	是否始终加入上下文	true / false
globs	array	文件匹配模式	["*.vue", "*.ts", "*.js"]

规则示例

---
name: api-guidelines
description: API 与 RPC 服务约定
globs: ["**/api/**/*.ts", "**/services/**/*.ts"]
alwaysApply: false
---

- 定义服务时使用内部 RPC 模式
- 服务名使用 snake_case

@service-template.ts

创建方式

1. 对话中创建：在 Agent 中输入 /create-rule，描述需求，Agent 会生成带正确 frontmatter 的规则并保存到 .cursor/rules。
2. 设置中创建：打开 Cursor Settings → Rules, Commands，点击 + Add Rule，在 .cursor/rules 中新建规则；可在设置中查看所有规则及状态。

规则准则

好的规则应当聚焦、可操作且范围明确：

• 将规则控制在 500 行以内
• 将大型规则拆分为多个可组合的规则
• 提供具体示例或引用相关文件
• 避免模糊的指导，像撰写清晰的内部文档那样来写规则
• 在聊天中重复提示时复用规则
• 引用文件而不是复制其内容——这样可以让规则更简短，并避免在代码变更后规则变得陈旧

应避免：

• 整份照搬风格指南 → 用 linter；Agent 已了解常见风格。
• 把每个命令都写进文档 → Agent 熟悉 npm、git、pytest 等常用工具。
• 为极少出现的边缘情况写规则 → 只聚焦常用模式。
• 重复代码库已有内容 → 引用示例文件，而非复制代码。

推荐Rules

推荐仓库：https://github.com/PatrickJS/awesome-cursorrules (opens new window)

个人收录

---

Skills

Agent Skills 是一个开放标准，用于为 AI Agent 扩展专用能力。Skills 将特定领域的知识和工作流打包封装，供 Agent 调用以完成特定任务。

Cursor 启动时，会自动从技能目录中发现技能，并将其提供给 Agent。Agent 会获知可用的技能，并根据上下文决定何时使用它们。

也可以在 Agent 对话中输入 / 并搜索技能名称来手动调用技能。

Skills 存放目录：

范围	路径
项目级	.agents/skills/、.cursor/skills/
用户级（全局）	~/.cursor/skills/

兼容性：Cursor 会同时从 Claude / Codex 的目录加载技能，便于与 Claude Code 共用一套 skills：

• 项目：.claude/skills/、.codex/skills/
• 用户：~/.claude/skills/、~/.codex/skills/

每个技能都应当是一个包含 SKILL.md 文件的文件夹

.agents/
└── skills/
    └── deploy-app/
        ├── SKILL.md
        ├── scripts/                      # 可选的脚本文件 智能体可以运行的可执行代码
        │   ├── deploy.sh
        │   └── validate.py
        ├── references/                   # 可选的参考文件 按需加载的补充文档
        │   └── REFERENCE.md
        └── assets/                       # 可选的资源文件 模板、图片或数据文件等静态资源
            └── config-template.json

SKILL.md 文件格式

每个技能都在带有 YAML frontmatter 的 SKILL.md 文件中定义

---
name: my-skill
description: Short description of what this skill does and when to use it.
---

# My Skill

Detailed instructions for the agent.

## When to Use

- Use this skill when...
- This skill is helpful for...

## Instructions

- Step-by-step guidance for the agent
- Domain-specific conventions
- Best practices and patterns
- Use the ask questions tool if you need to clarify requirements with the user

Frontmatter 字段：

字段	必填	说明
name	是	技能标识符，小写字母、数字、连字符，需与父文件夹名一致
description	是	功能与使用场景描述，供 Agent 判断是否自动加载
license	否	许可证名称或随附许可证文件引用
compatibility	否	环境要求（系统依赖、网络等）
metadata	否	任意键值对元数据
disable-model-invocation	否	为 true 时仅支持通过 /skill-name 显式调用，不自动应用

script：存放供 Agent 运行的可执行代码；在 SKILL.md 中引用时使用相对于技能根目录的路径。

提示

脚本应自包含、有清晰错误提示，并能优雅处理边缘情况。

示例：

---
name: deploy-app
description: Deploy the application to staging or production environments. Use when deploying code or when the user mentions deployment, releases, or environments.
---

# Deploy App

Deploy the application using the provided scripts.

## Usage

Run the deployment script: `scripts/deploy.sh <environment>`

Where `<environment>` is either `staging` or `production`.

## Pre-deployment Validation

Before deploying, run the validation script: `python scripts/validate.py`

references：补充文档。主 SKILL.md 保持精简，详细内容放到单独文件，Agent 会按需加载，节省上下文。

assets：模板、图片、数据文件等静态资源。

推荐SKILL

推荐仓库：https://github.com/ComposioHQ/awesome-claude-skills (opens new window)

---

中国国内环境最佳配置

在国内网络环境下，Cursor 连接官方 API 可能不稳定或无法访问，可通过以下方式改善体验。

代理与网络

方式	说明
系统/应用代理	在系统或 Cursor 设置中配置 HTTP(S) 代理（如 http://127.0.0.1:7890），使 Cursor 流量走代理。
环境变量	设置 HTTP_PROXY、HTTPS_PROXY（及可选 NO_PROXY），对 Cursor 内嵌终端和部分请求生效。

注意

Cursor 的 AI 请求由应用自身发起，不一定读取终端环境变量。若仅设环境变量无效，需在 Cursor 或系统级配置代理。

模型与 API

• 使用 Cursor 自带模型：依赖 Cursor 官方线路，受网络影响大；开代理后通常可正常使用。
• 自建/中转 API（若支持）：若 Cursor 或插件支持自定义 OpenAI/Anthropic 兼容端点，可将 base_url 指向国内中转或自建网关，减少直连海外。

更新与下载

• 安装包：从 cursor.com/download (opens new window) 下载可能较慢，可尝试镜像站或离线包（若有社区维护）。
• 扩展与 MCP：部分扩展从境外拉取，可对 marketplace.visualstudio.com、GitHub 等配置代理以加速。

推荐做法小结

1. 在系统或 Cursor 中配置稳定的 HTTP(S) 代理。
2. 需要时在终端环境变量中设置 HTTP_PROXY/HTTPS_PROXY，便于 Agent 执行命令时的网络访问。
3. 将大文件、锁文件、构建产物等加入 .cursorignore，减少索引与请求量，在弱网下更稳定。

---

与 Claude Code 的兼容

Cursor 与 Claude Code 在「规则 + 技能」思路上相近，部分目录和格式可复用，便于同一项目在两种环境中一致使用。

规则（Rules）对应关系

能力	Cursor	Claude Code
项目规则目录	.cursor/rules/	.claude/rules/
路径匹配字段	globs（数组）	paths（数组）
始终应用	alwaysApply: true	无 paths 的规则在会话启动时加载

• 格式差异：Cursor 用 globs（如 ["*.vue", "src/**/*.ts"]），Claude Code 用 paths（如 ["src/api/**/*.ts"]），语义类似。若需双端共用，可写两份 frontmatter 或在一个文件中同时写 globs 与 paths（各自工具只读自己识别的字段）。
• 共用策略：把通用内容放在同一份 Markdown 里，仅 frontmatter 按工具区分；或项目内同时维护 .cursor/rules/ 与 .claude/rules/，内容上保持对齐。

技能（Skills）兼容

Cursor 会从 Claude/Codex 的 skills 目录加载技能，因此：

• 在 .claude/skills/<skill-name>/SKILL.md 或 ~/.claude/skills/<skill-name>/SKILL.md 中放置的技能，在 Cursor 中也可用。
• 使用 Agent Skills (opens new window) 标准（SKILL.md + frontmatter），两边格式一致即可；Cursor 还支持 .cursor/skills/、.agents/skills/。

若希望「一个项目同时给 Cursor 和 Claude Code 用」，优先把共享技能放在 .claude/skills/，这样 Cursor 与 Claude Code 都能加载。

项目级指令文件

文件	Cursor	Claude Code
主指令	可选 AGENTS.md（根目录）	CLAUDE.md 或 .claude/CLAUDE.md
说明	AGENTS.md 作为 .cursor/rules 的简化方案	CLAUDE.md 为会话级持久指令

• 二者互不替代：Cursor 不会读 CLAUDE.md，Claude Code 不会读 AGENTS.md。若需双端一致，可在项目中同时维护两者，或把通用说明放在一个共享文档中，在 AGENTS.md / CLAUDE.md 里用简短描述 + 引用该文档。

小结

• Skills：放在 .claude/skills/（或 ~/.claude/skills/）可被 Cursor 与 Claude Code 共用。
• Rules：目录与 frontmatter 字段不同，可内容共用、frontmatter 按工具写，或双目录同步。
• 项目指令：AGENTS.md 与 CLAUDE.md 各用各的，需双端一致时两处都写或引用同一份说明。

---

.cursorignore

Cursor 会读取并索引您的项目代码库，以支持其功能。

您可以在项目根目录创建一个 .cursorignore 文件，控制 Cursor 可以访问的目录和文件，使用与 .gitignore 相同的语法。

在 .cursorignore 中列出的文件将被 Cursor 限制访问，包括：

• 代码库索引
• Tab、Agent 与 Inline Edit 可读取的代码
• 通过 @ 引用可访问的代码

警告

由 Agent 发起的工具调用（如终端、MCP 服务器）不会受 .cursorignore 限制，仍可能访问被忽略路径。

默认忽略列表（节选）：

package-lock.json
pnpm-lock.yaml
yarn.lock
composer.lock
Gemfile.lock
bun.lockb
.env*
.git/
.svn/
.hg/
*.lock
*.bak
*.tmp
*.bin
*.exe
*.dll
*.so
*.lockb
*.qwoff
*.isl
*.csv
*.pdf
*.doc
*.xls
*.xlsx
*.ppt
*.pptx
*.odt
*.ods
*.odp
*.odg
*.odf
*.sxw
*.sxc
*.sxi
*.sxd
*.sdc
*.jpg
*.jpeg
*.png
*.gif
*.bmp
*.tif
*.mp3
*.wav
*.wma
*.ogg
*.flac
*.aac
*.mp4
*.mov
*.wmv
*.flv
*.avi
*.zip
*.tar
*.gz
*.7z
*.rar
*.tgz
*.dmg
*.iso
*.cue
*.mdf
*.mds
*.vcd
*.toast
*.img
*.apk
*.msi
*.cab
*.tar.gz
*.tar.xz
*.tar.bz2
*.tar.lzma
*.tar.Z
*.tar.sz
*.lzma
*.ttf
*.otf
*.pak
*.woff
*.woff2
*.eot
*.webp
*.vsix
*.rmeta
*.rlib
*.parquet
*.svg
.egg-info/
.venv/
node_modules/
__pycache__/
.next/
.nuxt/
.cache/
.sass-cache/
.gradle/
.DS_Store/
.ipynb_checkpoints/
.pytest_cache/
.mypy_cache/
.tox/
.git/
.hg/
.svn/
.bzr/
.lock-wscript/
.Python/
.jupyter/
.history/
.yarn/
.yarn-cache/
.eslintcache/
.parcel-cache/
.cache-loader/
.nyc_output/
.node_repl_history/
.pnp.js/
.pnp/