1. 项目概述：为你的AI助手装上“永久记忆”

如果你和我一样，每天都在用Cursor IDE写代码，那你肯定也经历过这种抓狂时刻：每次打开一个新项目，或者隔几天再回来，你的AI助手就像得了失忆症，之前反复强调的代码规范、安全红线、项目架构，它全都忘得一干二净。你不得不像个复读机一样，在每个对话里重复：“别硬编码API密钥”、“用这个命名规范”、“测试覆盖率要达到90%”。这不仅浪费宝贵的对话轮次，更是在烧钱——每一次无效的上下文重复，都在消耗本可以用于生成代码的Token。

这就是 cursor-handbook 要解决的痛点。它不是一个简单的规则集，而是一个开源的、包含 208个组件 的规则引擎，专门为 Cursor IDE 设计。你可以把它理解为给你AI助手的“永久记忆”和“操作手册”。一旦部署到你的项目中，它就能让AI助手记住你的所有开发标准、安全策略和工作流，从此告别重复教学，把Token用在刀刃上。

简单来说， cursor-handbook 通过一套精密的规则、代理、技能、命令和钩子体系，把你的AI从一个“健忘的新手”训练成一个“懂你项目、守你规矩的资深工程师”。无论你是独立开发者，还是团队协作，它都能确保AI产出的代码风格一致、安全合规，并且能帮你省下至少30%的Token开销。接下来，我会带你深入拆解它的工作原理、如何快速上手，以及如何根据你的技术栈进行深度定制。

2. 核心设计思路：分层治理与事件驱动

cursor-handbook 的成功，源于其清晰的分层架构和事件驱动模型。它不是把一堆规则粗暴地塞给AI，而是设计了一个精密的“过滤-执行-验证”管道，确保每一次AI交互都在可控、高效的轨道上运行。

2.1 四层处理管道：从输入到产出的全链路控制

整个系统的运作可以看作一个四层流水线，每一层都有其明确的职责。

第一层：预处理钩子 这是第一道防线。当你在Cursor里输入一个提示或命令时， beforeSubmitPrompt 钩子会率先被触发。它的工作主要有两个： 上下文注入 和 危险拦截 。比如，它会自动读取你的 project.json 配置，把当前项目的技术栈、关键路径等信息附加到你的提示词后面，这样AI从一开始就知道“我在一个TypeScript + Express项目里工作”。同时，它会扫描你的指令，如果发现类似“删除整个node_modules”或“运行所有测试”这种可能消耗大量时间或Token的高成本操作，它会先发出警告，甚至直接拦截，建议你使用更高效的替代命令（如 /type-check ）。

第二层：规则引擎 这是系统的“宪法”。47条始终生效的规则构成了AI的行为准则。这些规则不是简单的“不要做什么”，而是包含了 架构模式 （如遵循清晰的Handler分层）、 代码标准 （命名规范、错误处理）、 安全策略 （禁止硬编码密钥）、 数据库约定 （软删除字段名）和 测试阈值 （覆盖率要求）。它们被无缝地注入到每一次与AI模型的对话上下文中，无声地引导AI的思考路径，确保输出的代码从基因上就符合你的要求。

第三层：专业化处理 经过规则过滤和丰富的提示词，会被路由到最合适的处理单元。系统内置了62个 代理 、50个 技能 和37个 命令 。它们各司其职：

  • 代理 像是专家顾问，处理复杂任务（如 /code-reviewer 进行代码审查）。
  • 技能 是引导式的工作流，一步步带你完成多步骤任务（如创建API端点，它会引导你完成从Controller到Service的9个文件）。
  • 命令 是即用即走的快捷工具，追求极致的Token效率（如 /type-check 只做类型检查）。

系统会根据你的提示词关键词和项目上下文，智能地选择激活哪一个组件。

第四层：后处理钩子 代码生成或修改后，工作并未结束。 afterFileEdit 等后处理钩子会接管，进行 输出验证 。这包括自动格式化代码、扫描是否有敏感信息被意外写入、运行轻量级的语法检查等。这相当于给AI的产出又加了一道质量安检，确保交到你手里的代码是干净、合规、可直接使用的。

2.2 事件驱动与智能路由：让对的组件处理对的事

这套系统的巧妙之处在于其“事件驱动”的设计。钩子监听Cursor IDE的特定事件（如提交提示前、编辑文件后），规则在每次对话时自动加载，而代理、技能和命令则按需触发。

智能路由是关键。例如，当你输入“创建一个用户注册的POST接口”时，系统会识别出“创建”、“POST”、“接口”等关键词，并结合项目是后端服务的上下文，优先激活 generate-handler 技能，而不是启动一个前端组件代理。这种基于上下文和意图的路由，大大提升了AI助手的响应准确度和效率。

实操心得：理解“规则”与“技能”的区别 这是很多初学者容易混淆的地方。 规则是“约束” ，是始终存在的背景条件，告诉AI“不能做什么、必须怎么做”，比如“所有错误必须被捕获并记录”。 技能是“引导” ，是主动触发的任务流程，告诉AI“现在我们来一步步完成某件事”，比如“技能：创建CRUD接口”。规则塑造行为习惯，技能提供具体解决方案。在配置时，把通用的、强制性的要求放在规则里，把特定的、复杂的操作流程封装成技能或代理。

3. 核心组件深度解析

cursor-handbook 的强大，建立在它那208个精心设计的组件之上。这些组件不是随意堆砌的，而是构成了一个完整的工具生态。我们来逐一拆解这些核心部件，看看它们各自扮演什么角色，以及如何协同工作。

3.1 规则：构建AI的行为准则

47条规则是系统的基石。它们被分类管理，确保覆盖开发的方方面面：

规则类别 核心规则示例 作用与原理
架构规则 enforce-clean-architecture.mdc 强制遵循分层架构（如Controller-Service-Repository），禁止循环依赖。原理是在每个代码生成请求的上下文中，注入架构约束描述，引导AI按模式思考。
后端规则 backend-error-handling.mdc 统一错误处理：所有异步操作必须try-catch，错误必须使用项目约定的 AppError 类抛出，并包含上下文信息。这避免了AI生成裸的 throw new Error 。
安全规则 security-no-hardcoded-secrets.mdc 绝对禁止 在代码中硬编码API密钥、数据库密码等。规则会强制AI引用环境变量（如 process.env.API_KEY ），并在后处理钩子中通过正则扫描进行二次校验。
数据库规则 database-soft-delete.mdc 约定所有表的“软删除”使用统一的字段名（如 deleted_at ），并要求相关的查询都必须包含 WHERE deleted_at IS NULL 条件。这确保了数据删除策略的一致性。
测试规则 testing-coverage-threshold.mdc 设定测试覆盖率最低要求（如90%）。当AI生成或修改测试时，会提醒它需要满足该覆盖率，并倾向于生成更全面的测试用例，而不是简单的Happy Path。

这些规则文件（ .mdc ）本质上是一种给AI看的“强化版注释”，使用特定的格式和指令来最大化其影响力。它们会在 每次 AI对话时被加载，形成一种强大的“上下文惯性”，让AI的输出自然而然地符合规范。

3.2 代理与技能：你的专属专家团队

如果说规则是“法律”，那么代理和技能就是“执法部门”和“专业服务机构”。

代理 是领域专家。每个代理都被训练专注于解决一类特定问题。例如：

  • /code-reviewer 代理 ：它不仅仅检查语法。它会基于安全规则检查是否有潜在的SQL注入、XSS漏洞；基于性能规则检查是否有N+1查询问题；基于代码规范检查命名和结构。它像一个不知疲倦的资深架构师，为每次提交把关。
  • /query-opt-agent 代理 ：当你在优化数据库查询时调用它，它会模拟分析执行计划（EXPLAIN ANALYZE），建议添加索引，甚至重写查询逻辑。它封装了DBA的经验。
  • /deployment-agent 代理 ：在部署前运行，它会生成一份部署清单，检查环境变量是否齐全、数据库迁移是否就绪，并自动生成回滚方案。

技能 是向导式的工作流。它把复杂的、多步骤的任务拆解成一个个可检查的节点。最典型的例子是 generate-handler 技能 。当你触发它来创建一个新的API端点时，它会引导你并执行以下步骤：

  1. 确认实体 ：你操作的是 User 还是 Product ？
  2. 选择操作 ：是Create、Read、Update、Delete还是List？
  3. 生成Controller ：包含路由定义、参数验证和响应格式。
  4. 生成Service ：包含核心业务逻辑。
  5. 生成Repository ：包含数据库交互代码。
  6. 生成DTO ：生成请求和响应的数据传输对象。
  7. 生成验证Schema 。
  8. 生成单元测试 。
  9. 更新API文档 （如OpenAPI Spec）。

整个过程是交互式的，你可以在每一步确认或调整。这确保了生成的代码不是一堆散件，而是一个完整、可运行、符合项目约定的功能模块。

3.3 命令与钩子：效率提升的利器

命令 追求的是极致的速度和Token效率。它们通常是单个、原子性的操作。

  • /type-check ：这是“省流神器”。运行整个测试套件可能需要消耗10万以上的Token，但仅仅进行类型检查可能只需要1万Token。当你只是做一个小改动，想快速验证类型安全时，这个命令能省下90%的Token。
  • /lint-check ：它利用Cursor的 read_lints 工具，只读取代码的linting结果，而不是重新运行整个linter，Token消耗极低。
  • /audit-deps ：快速扫描 package.json 或 pom.xml ，使用内置的漏洞数据库检查依赖是否有已知的安全漏洞（CVE）。

钩子 是自动化脚本，它们挂载在开发工作流的特定节点上。

  • beforeSubmitPrompt ：如前所述，用于提示词增强和危险操作拦截。
  • afterFileEdit ：文件编辑后自动触发格式化、简单语法检查。我通常会在这里配置一个轻量级的秘密扫描，防止AI不小心把模拟的密钥留在代码里。
  • onStartup ：当Cursor或项目打开时运行，可以用来初始化一些环境状态，或者检查 project.json 配置的完整性。

注意事项：钩子的执行顺序与性能 钩子是同步执行的，过多的或过于复杂的钩子会拖慢Cursor的响应速度。特别是 beforeSubmitPrompt ，因为它发生在你敲下回车之后、AI思考之前。务必确保这里的逻辑轻量级。复杂的检查（如全量安全扫描）应该放到独立的命令或代理中，由开发者手动触发，而不是阻塞每一次交互。

4. 从零到一：完整配置与实战指南

了解了核心组件，我们来实战如何将一个全新的项目武装起来。我会以最常见的 TypeScript + Express + PostgreSQL 技术栈为例，带你走完全流程。

4.1 快速初始化：五分钟部署手册

最快的方式是使用npm包，这也是官方推荐的方式。

# 在你的项目根目录下执行
npx cursor-handbook init

执行这个命令后，你会看到一个交互式命令行界面。它会问你：

  1. 是否复制所有组件？ 对于首次尝试，我建议选择“是”，先获得完整体验。
  2. 选择你的技术栈分类 ：它会列出前端、后端、数据库等类别，你可以按需勾选。对于我们的TS+Express项目，勾选“Backend”、“Database”、“Testing”、“DevOps”即可。

命令执行后，你的项目根目录下会生成一个 .cursor 文件夹，里面就是完整的规则引擎。同时，它会生成一个初始的 .cursor/config/project.json 文件，里面充满了 {{PLACEHOLDER}} 等待你填写。

关键一步 ：完成初始化后，记得运行 npm uninstall cursor-handbook 。因为这个npm包只是一个“安装器”，它的使命在复制完文件后就结束了，不需要留在你的项目依赖里。

4.2 核心配置：定制你的 project.json

project.json 是 cursor-handbook 的大脑，所有组件都通过读取这个文件的配置来适应你的项目。编辑这个文件是定制的核心。以下是一个针对我们示例项目的配置详解：

{
  "project": {
    "name": "my-express-api",
    "description": "A RESTful API for order management",
    "repositoryUrl": "https://github.com/yourname/my-express-api"
  },
  "techStack": {
    "language": "typescript",
    "framework": "express",
    "runtime": "node",
    "packageManager": "npm"
  },
  "paths": {
    "sourceRoot": "src",
    "handlerBasePath": "src/handlers",
    "serviceBasePath": "src/services",
    "repositoryBasePath": "src/repositories",
    "testBasePath": "tests"
  },
  "domain": {
    "entities": ["Order", "Product", "Customer"],
    "lifecycleStates": {
      "Order": ["PENDING", "PROCESSING", "SHIPPED", "DELIVERED", "CANCELLED"]
    }
  },
  "patterns": {
    "handlerFlow": "7-step", // 使用约定的7步处理流程
    "errorHandlingStrategy": "centralized" // 集中式错误处理
  },
  "testing": {
    "framework": "jest",
    "coverageMinimum": 90,
    "testCommand": "npm test -- --coverage",
    "typeCheckCommand": "npx tsc --noEmit",
    "lintCommand": "npx eslint ."
  },
  "database": {
    "orm": "prisma",
    "softDeleteField": "deleted_at",
    "timestampFields": ["created_at", "updated_at"]
  },
  "conventions": {
    "branchPrefix": "feat/|fix/|chore/",
    "commitFormat": "conventional"
  }
}

配置解析与实操要点：

  • techStack.language/framework ：这决定了哪些规则会生效。设置为 typescript 和 express ，那么针对Python或React的规则就会被自动忽略。
  • paths ： 务必与实际目录结构匹配 。这是AI生成代码时放置文件的依据。如果这里写 src/handlers ，但你实际用的是 src/controllers ，生成的代码就会放错地方。
  • database.softDeleteField ：这是一个强大的约定。设置后，所有涉及“删除”的数据库操作，AI都会自动使用 UPDATE ... SET deleted_at = NOW() 而不是 DELETE ，并在查询中自动加上 WHERE deleted_at IS NULL 。这极大地保证了数据安全性和一致性。
  • testing.coverageMinimum ：设置一个较高的阈值（如90%）会“逼迫”AI生成更完善的测试，而不是敷衍了事。

4.3 使用Cursor设置代理进行智能配置

对于不想手动筛选组件的新手，或者项目技术栈比较复杂的情况， @cursor-setup-agent 是更好的选择。它的工作流程非常智能：

  1. 准备 ：确保你已经将 cursor-handbook 仓库克隆到本地（不一定非要在项目内，可以是一个临时目录）。
  2. 启动 ：在你的项目根目录打开Cursor IDE，在聊天框中输入 @cursor-setup-agent 并发送。
  3. 扫描 ：代理会开始“扫描”你的项目。它通过识别关键文件来推断你的技术栈：
    • tsconfig.json -> TypeScript
    • package.json 中的 express 依赖 -> Express框架
    • prisma/schema.prisma 或 package.json 中的 pg -> PostgreSQL
    • jest.config.js -> Jest测试框架
    • Dockerfile -> 使用Docker
  4. 推荐 ：扫描完成后，代理会生成一份报告，列出它检测到的技术栈，并推荐一套适合的组件子集（例如，从208个组件中筛选出约120个与TS/Express相关的）。
  5. 确认与安装 ：它会展示一个变更预览，问你“是否要应用这些配置？”。确认后，它会自动生成定制的 project.json 、 CLAUDE.md 和 AGENTS.md 文件，并将筛选出的组件复制到你的 .cursor 目录。

这个代理最大的价值在于 “开箱即用” 和 “减负” 。它帮你跳过了“哪些组件对我有用？”的决策过程，直接给你一个量身定制的基础配置。

4.4 验证与试运行

配置完成后，重启Cursor IDE以确保所有新规则和组件被加载。然后，你可以进行几个简单的测试来验证是否生效：

  1. 测试安全规则 ：在聊天框里对AI说：“写一个函数，调用外部API，密钥是 12345abcde 。” 观察AI的反应。正确的行为应该是它拒绝硬编码，并提示你“请使用环境变量 process.env.API_KEY ”。
  2. 测试架构规则 ：说：“给我写一个用户登录的API。” 观察生成的代码。它应该遵循你配置的分层模式（如生成 auth.handler.ts 、 auth.service.ts 等），而不是把所有逻辑堆在一个文件里。
  3. 测试效率命令 ：输入 /type-check 。它应该快速运行TypeScript编译器并输出结果，而不是去运行整个测试套件。

如果以上测试都符合预期，恭喜你，你的AI助手已经成功升级。

5. 高级定制与团队协作实战

当个人使用得心应手后，你会自然地想把它推广到团队，或者根据更复杂的项目需求进行深度定制。这部分是发挥 cursor-handbook 最大威力的关键。

5.1 创建组织级规则与组件

团队或公司内部往往有更严格的代码规范、安全审计流程或特有的技术栈。你可以在 cursor-handbook 的基础上进行扩展。

案例：添加公司内部包命名规则 假设你的公司要求所有内部NPM包都必须以 @your-company/ 开头。你可以创建一个新的规则文件 .cursor/rules/company-naming-convention.mdc ：

# 规则：内部包命名规范
- **目标**：确保所有对 `package.json` 的修改中，内部依赖的命名符合公司规范。
- **触发条件**：任何涉及添加、修改 `dependencies` 或 `devDependencies` 的AI操作。
- **规则内容**：
  1.  所有公司内部的npm包引用，必须使用 `@your-company/` 作用域。
  2.  禁止使用公司内部包的公共仓库名称或未经批准的别名。
  3.  当AI检测到可能添加内部包时，应主动询问或确认包的正确名称（如 `@your-company/ui-components`）。
- **示例**：
  - ✅ `"@your-company/logger": "^2.0.0"`
  - ❌ `"company-logger": "^1.0.0"`

然后，在你的团队共享的 project.json 中，通过 extends 字段（如果支持）或直接将该规则放入 rules 目录，确保所有成员都应用此规则。

案例：创建领域特定代理 如果你的团队大量进行支付相关开发，可以创建一个 /payment-integration-agent 代理。这个代理的指令里可以封装：

  • 公司支付网关（如Stripe、Braintree）的特定配置方式。
  • 合规性要求（如PCI-DSS相关代码规范）。
  • 错误处理标准（如如何记录支付失败、重试策略）。
  • 测试支付环境的模拟数据。

这样，任何一个团队成员在处理支付功能时，只需要调用这个代理，就能获得符合所有内部标准和最佳实践的代码建议。

5.2 团队共享方案：Git Submodule vs 内部仓库

如何让团队所有成员都用上统一的配置？有两种主流方案。

方案一：Git Submodule（适合中小型团队） 这是最轻量、最直接的方式。将定制化的 cursor-handbook 仓库作为子模块添加到每个项目仓库中。

# 在团队共享的配置仓库中准备好你的定制版cursor-handbook
# 然后在每个项目仓库中执行：
git submodule add https://github.com/your-org/cursor-handbook.git .cursor
git commit -m "chore: add team cursor rules as submodule"

优点 ：配置与项目代码绑定，版本清晰。新成员克隆项目后，只需 git submodule update --init 即可获得所有规则。 缺点 ：更新团队规则时，需要在每个项目里更新子模块指针。

方案二：内部NPM包或模板仓库（适合大型组织） 你可以将定制好的 .cursor 目录打包，发布到公司的私有NPM仓库，或者创建一个标准的“项目模板仓库”。

  • NPM包 ：创建一个包，其 postinstall 脚本将 .cursor 目录复制到用户项目。团队成员只需 npm install @your-company/cursor-rules --save-dev 。
  • 模板仓库 ：在GitHub/GitLab上创建一个“Project Template”，里面已经内置了配置好的 .cursor 目录、 Dockerfile 、CI流水线等。新项目直接从此模板创建。

优点 ：中心化管理，更新一次，所有新项目自动受益。版本控制更规范。 缺点 ：初始设置稍复杂，需要维护包或模板。

团队协作避坑指南：

  1. 统一配置版本 ：务必锁定子模块或NPM包的版本号，避免因某个成员更新了规则而导致团队其他成员行为不一致。
  2. 文档至关重要 ：在团队Wiki或README中，明确记录所有自定义规则和代理的用途、触发条件。否则，新成员会对AI的某些“固执”行为感到困惑。
  3. 设立反馈渠道 ：建立一个渠道（如Slack频道、GitHub Issues）让团队成员报告规则是否好用，或者发现AI在哪些场景下依然会“犯错”。持续优化规则集是一个长期过程。

5.3 性能调优与Token节省策略

cursor-handbook 宣称能节省30%以上的Token，这并非虚言。但节省的效果取决于你是否正确使用。以下是一些高级策略：

1. 精细化规则作用域 不是所有规则都需要在 所有 对话中加载。有些规则可能只在前端组件开发时有用，有些只在写数据库查询时有用。 cursor-handbook 支持基于文件路径或语言的作用域规则。

  • 你可以将 react-component-conventions.mdc 规则的作用域设置为 **/*.tsx 或 **/*.jsx ，这样当你在处理 .py 文件时，这条规则就不会被加载，从而减少不必要的上下文长度。

2. 善用轻量级命令替代复杂操作 这是节省Token最有效的一招。养成使用命令的习惯：

  • 想检查类型？用 /type-check (约1万Token)，而不是说“运行测试” (可能触发10万Token的完整测试)。
  • 想看看代码风格问题？用 /lint-check (利用 read_lints ，约2千Token)，而不是“运行ESLint” (可能需要重新分析所有文件，消耗5万Token以上)。
  • 只测试一个文件？用 /test-single src/services/user.service.test.ts ，而不是运行整个测试套件。

3. 优化 project.json 的上下文信息 project.json 中的信息会被注入到上下文。确保里面的描述是 简洁、准确 的。避免在 description 里写长篇大论的项目背景故事。只保留对AI生成代码有直接指导意义的信息，比如关键的目录结构、命名约定、领域实体。

4. 定期审计与清理组件 随着时间推移，你可能会尝试很多代理和技能。定期检查 .cursor/agents 和 .cursor/skills 目录，删除那些你从未使用或已经过时的组件。每个未被使用的组件，虽然不一定会被加载，但维护它们会增加认知负担和潜在的配置冲突风险。

6. 故障排除与常见问题

即使配置得当，在实际使用中也可能遇到一些问题。这里记录了一些我踩过的坑和解决方案。

6.1 AI似乎“无视”某些规则

问题描述 ：你明明配置了“禁止使用 any 类型”的TypeScript规则，但AI生成的代码里还是出现了 any 。

排查步骤：

  1. 检查规则文件语法 ：打开对应的 .mdc 规则文件，确保其Markdown语法正确，指令清晰。AI对格式错误很敏感。
  2. 检查规则加载顺序 ：在 .cursor/rules 目录下，文件是按字母顺序加载的吗？有时后面的规则可能会覆盖前面的。确保核心规则（如 main-rules.mdc ）先被加载。
  3. 检查作用域 ：该规则是否被错误地限制了作用域？比如，一个针对 .ts 文件的规则，不会对 .js 文件生效。
  4. 上下文过载 ：如果你在一次对话中进行了非常长的、多轮次的复杂操作，最初的规则上下文可能会被“挤”出AI的上下文窗口。尝试开启一个新的聊天会话，规则会重新加载。
  5. 提示词冲突 ：你的提示词是否过于强势，包含了“忽略所有规则，用最快的方式实现”之类的指令？检查你的输入。

解决方案 ：最有效的方法是 强化规则描述 。不要只说“禁止使用any”，要告诉AI“为什么”以及“应该用什么替代”。例如：

“禁止使用TypeScript的 any 类型，因为它破坏了类型安全。对于暂时无法推断类型的场景，优先使用 unknown 类型，并通过类型守卫进行收窄。对于第三方库没有类型的，使用 @ts-ignore 注释并附上理由，或者为其创建 .d.ts 声明文件。”

6.2 命令 /type-check 或 /lint-check 不工作

问题描述 ：输入命令后，Cursor没有执行预期操作，或者报错。

排查步骤：

  1. 验证命令文件存在 ：检查 .cursor/commands/ 目录下是否有 type-check.mdc 或 lint-check.mdc 文件。
  2. 检查项目配置 ：确认 project.json 中的 testing.typeCheckCommand 和 testing.lintCommand 配置是否正确。这些命令是调用你项目本地已安装的工具（如 tsc , eslint ）。如果命令路径错误或工具未安装，就会失败。
  3. 检查Cursor设置 ：确保Cursor的设置中， Commands 相关的功能是启用的。有时需要重启Cursor来刷新命令列表。
  4. 查看命令内容 ：打开命令文件，看它具体执行什么Shell命令。你可能需要根据自己项目的实际情况进行微调（例如，你的TypeScript检查命令可能是 npm run type-check 而不是 npx tsc --noEmit ）。

6.3 自定义代理/技能无法被触发

问题描述 ：你创建了一个新的代理文件 my-special-agent.mdc 放在 .cursor/agents/ 目录下，但在聊天框中输入 /my-special-agent 没有反应。

排查步骤：

  1. 命名与调用匹配 ：代理的触发指令通常在文件开头的指令中定义，如 COMMAND: /my-special-agent 。确保你输入的命令与此完全一致（包括斜杠）。
  2. 文件格式 ：确保你的 .mdc 文件是有效的Markdown格式，并且包含了必要的指令块。可以参照现有的代理文件格式。
  3. 重启Cursor ：添加新的组件后，通常需要重启Cursor IDE才能被识别和加载。
  4. 权限与路径 ：确保Cursor有权限读取 .cursor 目录下的新文件。

6.4 性能问题：Cursor响应变慢

问题描述 ：安装 cursor-handbook 后，感觉AI生成代码的速度变慢了。

可能原因与解决：

  1. 规则过多 ：加载了太多全局规则，尤其是那些包含大量示例代码的规则，会显著增加每次请求的上下文长度，从而增加延迟和Token消耗。 解决方案 ：定期审查规则，将非全局的规则加上作用域限制，或移至按需触发的技能中。
  2. 钩子脚本过重 ： beforeSubmitPrompt 或 afterFileEdit 钩子中执行了复杂的同步操作（如大量文件I/O）。 解决方案 ：确保钩子逻辑尽可能轻量。将重型检查（如全项目安全扫描）移到独立的、手动触发的命令中。
  3. 项目配置复杂 ： project.json 文件过于庞大，包含了许多不必要的信息。 解决方案 ：精简 project.json ，只保留核心配置。

6.5 与其他IDE扩展或配置冲突

问题描述 ： cursor-handbook 的某些行为（如自动格式化）与你已有的VS Code或Cursor其他扩展冲突。

解决方案 ：

  • 检查优先级 ： cursor-handbook 的钩子执行顺序。有时需要调整钩子脚本，避免重复操作。
  • 选择性禁用 ：你可以在 project.json 中配置一个开关，或者直接注释掉 .cursor/hooks/ 目录下某个特定钩子文件的内容，来禁用某项自动化功能。
  • 融合配置 ：最好的方式是调整你的其他工具配置，使其与 cursor-handbook 的约定保持一致。例如，如果 cursor-handbook 的规则要求使用双引号，那么你也应该将Prettier或ESLint配置为使用双引号，避免格式大战。

记住， cursor-handbook 是一个高度可定制的系统。遇到问题时，最有效的办法是打开对应的组件文件（ .mdc ），阅读其中的指令，理解其工作原理，然后进行针对性的调整。它不是一个黑盒，而是一个你可以完全掌控的白盒工具。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

DeepSeek-V4 RAG 分块策略优化：512 vs 1024 token 的实测边界与工程取舍

avatar DeepSeek技术社区
cover

企业知识库问答中的权限迷宫：如何用 DeepSeek 实现文档级 ACL 下沉与安全召回

avatar DeepSeek技术社区
cover

RAG 文档预处理：为什么 90% 的失败案例源于切分策略不当

avatar DeepSeek技术社区