cursor-best-practices

cursor-best-practices

一个结构化仓库，用于创建和维护针对 Agent 和大模型优化的 Cursor 最佳实践。本技能提供 references/（按需查阅的文档）和 assets/templates/（规则、命令和子 Agent 模板），涵盖规则、命令、技能、子 Agent、忽略文件、Agent 安全、工作流和社区资源。

---

使用时机

在以下情况下，使用此技能：

• 设置或初始化 Cursor、创建 .cursor 文件夹，或提出“设置我的 .cursor 文件夹”
• 编写或编辑 .cursor/rules、AGENTS.md 或规则 frontmatter
• 创建或使用斜杠命令、技能或子 Agent
• 配置 .cursorignore 或 .cursorindexingignore
• 使用 Agent 模式（Agent、Ask、Plan、Debug）、语义搜索或 @mentions
• 询问 TDD、git 风格的命令、大型代码库或 Cursor 工作流
• 查找规则或 MCP（cursor.directory）或技能推荐（skills.sh）
• 询问插件、钩子、Cloud Agent、CLI、工作树或深度链接

---

规则

位置： 项目 .cursor/rules/（.md/.mdc）、用户的 Cursor Settings → Rules、团队控制面板。优先级： 团队 → 项目 → 用户。

类型及适用场景：

类型	适用场景
始终应用	必须影响每个请求（例如“TS 中禁止使用 any”“完成前运行测试”）。谨慎使用。
智能应用	相关时提供通用指导（例如“优先使用函数组件”）。
应用于特定文件	使用 globs（例如 **/*.test.ts、**/api/**）。仅当这些文件处于上下文中时才加载规则。
手动应用	需要时由用户通过 @rule-name 调用（例如发布流程、遗留问题）。

Frontmatter： description（包含丰富关键词，有助于提高相关性）、globs（针对特定文件）、alwaysApply（少用）。每条规则保持在 <500 行；按关注点拆分，并链接到 references/。AGENTS.md = 项目根目录中的纯 Markdown 替代方案；不含 frontmatter。

最佳实践： 规则应可组合，并包含具体示例。引用较长的操作手册，而非复制。先从简单做起；当 Agent 一再犯同样的错误时，再添加规则。将旧版 .cursorrules 迁移到 Project Rules 或 AGENTS.md。

参阅： 规则。assets/templates/rules/_sections.md | references/templates-index.md | references/rules-and-commands.md。

---

命令

**位置：**项目 .cursor/commands/、用户 ~/.cursor/commands/、团队仪表板。**格式：**纯 Markdown .md；文件名 = 命令名称。在聊天中输入 / 触发。**参数：**命令后的文本会作为上下文传入（例如，/fix-issue 123 → “123”）。

可用模板（复制到 .cursor/commands/）：

命令	用途
/code-review	检查正确性、安全性、质量和测试。输出：关键问题 / 建议 / 锦上添花。
/pr	总结更改、拟定 PR 标题和描述，并建议评审清单。
/run-tests-and-fix	运行测试、修复失败项，并重新运行直至全部通过；总结更改。
/security-audit	以安全为重点进行评审（注入、身份验证、密钥、依赖项）。
/setup-new-feature	提出计划（文件、模块、模式），并建议实现步骤。
/fix-issue	根据 Issue 编号 # 或描述修复 Bug 或实现功能。
/update-deps	更新依赖项、运行测试并报告破坏性更改。
/docs	为通过 @ 提及的代码或当前功能生成或更新文档。
/make-cursor-compatible	使代码库兼容 Cursor：添加 .cursor 文件夹、.cursorignore、AGENTS.md、规则、命令和索引。
/lint-and-fix	运行 Linter、自动修复问题并报告剩余问题。
/format	按照项目标准格式化代码。
/check-coverage	检查测试覆盖率、找出缺口并建议改进。
/analyze-deps	分析依赖树、找出未使用或重复的依赖项，并建议优化。
/generate-types	根据架构、API 或 JSON 生成 TypeScript/类型。

参见：命令。assets/templates/commands/。

---

技能和子代理

技能： 从 .agents/skills/、.cursor/skills/ 或 ~/.cursor/skills/ 加载（并为兼容性支持 .claude/skills/、.codex/skills/）。每个技能都是一个包含 SKILL.md 的文件夹；可选包含 scripts/、references/、assets/。Frontmatter：必填项为 name、description；可选项为 license、compatibility、metadata、disable-model-invocation（为 true 时，技能仅在通过 /skill-name 调用时生效）。Agent 会在相关时自动应用技能，也可通过 /skill-name 调用。使用 /migrate-to-skills（Cursor 2.4+）将符合条件的规则和命令转换为技能。子代理： 位于 .cursor/agents/ 或 ~/.cursor/agents/；使用 Markdown 和 YAML，包含 name、description，以及可选的 model、readonly、background。可在前台或后台运行；内置子代理包括 Explore、Bash、Browser。

何时使用： 子代理 — 适用于隔离上下文、并行工作、多步骤专业任务（例如，只运行测试和 lint 的验证器）。技能 — 适用于单一用途、可重复的任务（变更日志、格式化、特定领域的工作流）。

模板： 将子代理模板从 assets/templates/agents/ 复制到 .cursor/agents/。可用的子代理：

只读（审查/分析）：

• verifier.md — 运行测试和 lint，仅报告结果
• reviewer.md — 审查代码的正确性、安全性、质量和测试
• security-auditor.md — 专注于安全性的审查
• linter.md — 检查 lint 和代码风格
• architect.md — 审查架构模式和设计

可编辑（可修改代码）：

• documenter.md — 生成/更新文档
• tester.md — 编写和更新测试
• refactorer.md — 在保持功能的同时重构代码
• debugger.md — 调查并定位 Bug
• performance-analyzer.md — 分析性能问题和瓶颈
• accessibility-checker.md — 检查代码是否符合 a11y 标准
• migrator.md — 系统地处理代码迁移
• dependency-manager.md — 审查和管理依赖项
• formatter.md — 按照标准格式化代码
• type-generator.md — 根据架构/API 生成类型

技能推荐： 仅推荐 assets/recommended-skills.md 和 skills.sh；建议使用 npx skills add <owner/repo>。

参见： 技能、子代理。

---

忽略文件

.cursorignore： 位于项目根目录；语法与 .gitignore 相同。排除的路径不会用于语义搜索、Tab、Agent、Inline Edit 和 @mentions。不影响终端/MCP。用途： 安全性（机密、密钥、凭据）、性能（大型仓库）。.cursorindexingignore： 仅影响索引；通过 @ 提及的文件仍可使用。

必须排除： .env、.env.*、*.key、*.pem、credentials.json、**/secrets/**。添加项目特定路径。谨慎使用 !；父级排除规则会限制重新包含的文件。

参见： 忽略文件。assets/templates/rules/ignore-cursorignore-secrets.md。

---

Agent 和安全

Agent： 规则 + 工具（搜索、读取、编辑、终端、MCP）+ 你的消息。支持摘要（/summarize）和检查点。排队（Enter）与 Ctrl+Enter（立即发送）。

安全： 允许编辑文件（受保护的配置除外）；请使用 VCS。终端： 默认需要批准；避免选择“Run everything”。MCP： 需批准连接和每次工具调用。网络： 仅限 GitHub、获取链接和搜索。将机密放入 .cursorignore。

参见： Agent 概览、Agent 安全。references/agent-and-security.md。

---

Agent 模式

模式	用途	工具
Agent	实现、重构、多文件工作。	完整（搜索、读取、编辑、终端、MCP）。
Ask	学习、问答、探索。	仅搜索和读取；不能编辑。
Plan	研究 → 澄清 → 规划 → 由你审核 →“构建”。	搜索和读取。计划位于 .cursor/plans/；按 Shift+Tab 切换。
Debug	可复现的 bug；假设 → 添加检测 → 复现 → 修复 → 验证。	完整。

**切换：**在聊天中使用模式选择器；按 Ctrl+. 循环切换。**最佳实践：**用 Ask/Plan 制订计划，用 Agent 实施。如果 Agent 构建错了，还原 → 优化计划 → 重新运行。

参阅：计划模式、调试模式。assets/templates/rules/modes-plan-then-agent.md。references/modes-context-tools.md。

---

工作流和大型代码库

**TDD：**编写测试 → 运行（预期失败）→ 提交测试 → 实现 → 运行直至通过 → 提交实现。完成前运行测试：assets/templates/rules/workflows-run-tests-before-done.md。

Git 风格的命令：.cursor/commands/ 中的 /pr、/fix-issue、/review、/update-deps、/docs。**了解代码库：**询问“X 是如何工作的？”、“如何添加 Y？”；由宽泛到具体。**图表：**让助手生成 Mermaid 架构图/数据流图。**Hooks：**使用 .cursor/hooks.json 处理长时间运行的循环。**设计 → 代码：**粘贴模型图；使用 Browser 预览。

**大型代码库：**在 .cursor/rules 中使用 glob 配置领域规则；用 Ask 制订计划，用 Agent 实施。Tab = 快速编辑；Inline Edit（Ctrl+K）= 单文件；Chat/Agent = 多文件。使用 @files、@folder、@Code；缩小范围；上下文杂乱时新建聊天。

参阅：Agent 工作流、大型代码库。references/workflows-and-codebases.md。

---

语义搜索、@提及、Tab

**语义搜索：**基于含义；适合自然语言问题。打开工作区时开始索引；完成约 80% 后即可使用。**两者都用：**grep（精确匹配）和语义搜索（概念匹配）：assets/templates/rules/context-use-grep-and-semantic.md。

@Files 和 Folders：按路径引用；从侧边栏拖入。@Code：特定代码片段（最精确）。@Docs：使用内置文档或添加新文档（URL）。/summarize — 压缩上下文。最佳实践：assets/templates/rules/context-use-at-mentions.md。

**Tab：**行内自动补全；按 Tab 接受，按 Esc 拒绝，按 Ctrl+Right 部分接受。用于加快速度；进行较大更改时使用 Inline Edit 或 Chat。

参阅：语义搜索、@ 提及、Tab。

---

Bugbot、MCP、快捷键

**Bugbot：**审查 PR（bug、安全性、质量）。在项目根目录放置 .cursor/BUGBOT.md（始终包含），并可在各目录中放置同名文件（审查该路径下的文件时包含）；仪表板中的 Team 规则适用于所有仓库。触发方式：评论 cursor review 或 bugbot run；使用 verbose=true 获取请求 ID。自动修复会启动 Cloud Agent 来修复报告的问题（提交到当前分支或新分支）。**MCP：**外部工具；需批准连接和工具调用。cursor.directory 提供社区规则和 MCP。**技能：**仅使用 skills.sh。

**快捷键：**Ctrl+I Agent | Ctrl+K Inline Edit | Ctrl+. 循环切换模式 | Enter 排队，Ctrl+Enter 发送 | Tab 接受补全，Esc 拒绝。

参阅：Bugbot、MCP。

---

插件、钩子、Cloud Agent、CLI、Worktrees、深层链接

插件： 将规则、技能、Agent、命令、MCP 服务和钩子打包成可分发的软件包。使用 .cursor-plugin/plugin.json 清单；从 Cursor Marketplace 或团队 Marketplace（Teams/Enterprise）安装。参见： 插件。

钩子： 使用 .cursor/hooks.json（项目级）或 ~/.cursor/hooks.json（用户级）。观察或控制 Agent 循环阶段（例如 beforeShellExecution、afterFileEdit、sessionStart）。支持基于命令（脚本）或提示词（大模型）的钩子。参见： 钩子。

Cloud Agent： Agent 在云端运行；可通过 API、Linear、GitHub、Slack、桌面应用（下拉菜单中的 Cloud）或 cursor.com/agents（Web/PWA）访问。支持 MCP；可设置支出限额；使用“Apply”将 worktree 更改应用到你的分支。参见： Cloud Agent。

CLI： 使用 agent 命令进行交互式或非交互式操作。模式：Agent、Plan、Ask。交接到云端：在聊天中使用 &，或运行 agent -c "prompt"。会话：agent ls、agent resume。参见： CLI。

Worktrees： 多个 Agent 在独立的 Git worktree 中并行运行。使用 .cursor/worktrees.json 进行设置（例如 setup-worktree，以及特定操作系统的设置）。Best-of-N：在多个模型上运行相同的提示词；使用 Apply 合并结果。参见： Worktrees。

深层链接： 通过 cursor://anysphere.cursor-deeplink/ 或 https://cursor.com/link/ 分享提示词、命令或规则。最多 8,000 个字符。参见： 深层链接。

---

.cursor 目录结构与设置工作流

文件夹： rules/、commands/、skills/、agents/。可选：hooks.json、worktrees.json。AGENTS.md 是规则的简易替代方案。

设置我的 .cursor 文件夹

当用户要求设置、初始化或创建 .cursor 文件夹时：

1. 创建： .cursor/rules/、.cursor/commands/、.cursor/skills/、.cursor/agents/。
2. 可选的 .cursorignore： 如果文件不存在，则添加最简内容（例如 node_modules/、.env、*.log、dist/）。使用 .gitignore 语法；根据技术栈进行调整。
3. 可选模板： 提议从此技能复制模板。如果用户同意：
   • 命令： 从 assets/templates/commands/ 复制到 .cursor/commands/（例如 code-review.md、lint-and-fix.md、format.md 等）。
   • Agent： 从 assets/templates/agents/ 复制到 .cursor/agents/（例如 verifier.md、reviewer.md、linter.md、formatter.md 等）。
   • 规则： 可选从 assets/templates/rules/ 复制，或添加一条入门规则或 AGENTS.md。
4. 确认： 列出创建的内容及其用法（例如“在聊天中使用 /code-review”，“将规则添加到 .cursor/rules/”）。

参见： assets/templates/rules/context-setup-cursor-folder.md。references/templates-index.md。

---

故障排除

规则没有生效？ 检查类型（Always / Intelligent / Globs / Manual）、description（关键词）和 globs（路径是否匹配）。请求 ID： 报告问题时选择“Get request ID”，或使用 cursor review verbose=true。参见： 常见问题、故障排除指南。references/modes-context-tools.md。

---

另请参阅

• 模板索引： references/templates-index.md
• 模板： assets/templates/commands/（14 个命令模板）、assets/templates/agents/（15 个子 Agent 模板）、assets/templates/rules/_sections.md、assets/recommended-skills.md
• 参考资料： rules-and-commands | agent-and-security | workflows-and-codebases | modes-context-tools | quick-reference
• 权威来源： Cursor 文档 | cursor.directory（规则和 MCP） | skills.sh（技能）
• 安全的技能编写： 不使用提示词注入模式，不硬编码机密信息，不提供不安全的下载/执行示例。请参阅 references/agent-and-security.md。