1. 项目概述：从“工具”到“同事”的Agent进化

最近在深度使用Cursor时，我一直在思考一个问题：为什么我们总感觉AI编程助手像个“聪明的工具”，而不是一个能并肩作战的“新同事”？工具的特点是“你指哪，它打哪”，指令必须极其精确，稍有模糊就会出错。而同事则不同，他理解项目背景、团队规范，甚至能主动提醒你“这里是不是该加个异常处理？”。

这个问题的核心，就在于我们如何为AI Agent（智能体）设计“行为准则”和“技能包”。在Cursor的语境下，这对应着Rules和Skills两大核心配置。很多开发者只是简单地在.cursorrules文件里堆砌几条零散的规则，或者从网上复制几个现成的Skills，效果往往差强人意。这就像给新同事一本零散的“员工手册”和几张“技能卡”，指望他能立刻融入团队并高效产出，显然不现实。

分层设计，正是解决这一困境的关键。它不是简单地把规则和技能分开，而是像打造一个真实团队一样，为Agent构建从“公司文化”到“部门规范”，再到“个人专长”的完整认知体系。通过将Rules和Skills进行结构化、层次化的组织，我们可以让Cursor从一个被动的代码补全工具，转变为一个理解上下文、遵循最佳实践、并能主动运用高级技能的“团队新同事”。接下来，我将详细拆解这套分层设计的理念、具体实现方法以及我在多个真实项目中验证过的实战经验。

2. 核心理念：为什么需要分层设计？

在深入实操之前，我们必须先理解分层设计的必要性。这源于当前AI编程助手使用中的几个普遍痛点。

2.1 单一规则文件的局限性

大多数开发者接触Cursor Rules的第一反应，是在项目根目录创建一个.cursorrules文件，然后往里添加诸如“使用TypeScript”、“函数注释要完整”之类的条目。这种做法在小型或个人项目中或许可行，但一旦项目规模扩大、涉及多模块、多技术栈，这个文件很快就会变得臃肿不堪，规则之间可能产生冲突，且难以维护。

例如，一个全栈项目可能同时包含前端（React + TypeScript）、后端（Node.js + Express）和基础设施（Docker, Terraform）代码。将所有这些技术栈的规范混在一个文件里，会导致规则特异性下降。一条针对React组件命名的规则，可能会错误地影响到后端DTO对象的生成。这就像用一本手册同时管理销售、研发、运维三个部门，必然漏洞百出。

2.2 Skills的孤立与滥用

Skills是Cursor的强大扩展，可以赋予Agent执行特定复杂任务的能力，比如“生成完整的CRUD API端点”或“重构代码以符合SOLID原则”。然而，如果不加管理地启用大量Skills，会带来两个问题：

1. 上下文污染：Agent在思考时可能会尝试调用不相关或冲突的Skill，导致输出混乱。
2. 能力浪费：很多Skills是针对特定场景的（如“生成数据库迁移脚本”），在不需要的场景下启用它，只会增加决策负担。

我们需要一个机制，来告诉Agent：“现在我们在写前端UI，请主要使用你的React相关技能，数据库迁移的技能暂时收起来。”

2.3 分层设计的目标：塑造Agent的“角色认知”

分层设计的终极目标，是为Agent建立清晰的“角色认知”。我们可以类比公司管理：

• 公司级规则 (Global Rules)：相当于企业文化、员工守则。定义了所有代码都必须遵守的底线原则，如代码安全规范、基础编码风格（缩进、换行）、禁止使用的危险API等。这些规则适用于所有项目。
• 项目/技术栈级规则 (Project/Tech Stack Rules)：相当于部门规章制度。针对当前项目的技术选型（如Vue 3 + Composition API, Python FastAPI）制定具体规范。它比公司级规则更具体，但只在本项目内生效。
• 模块/目录级规则 (Module/Directory Rules)：相当于小组工作流程。针对特定功能模块（如/src/api/下的所有文件需使用统一的错误处理中间件）或文件类型（如所有.test.js文件需遵循特定的测试结构）进行约束。
• 技能调度策略 (Skills Orchestration)：相当于根据任务类型，调配不同的专家团队。不是所有Skills都一直处于激活状态，而是根据当前编辑的文件、正在进行的任务（是写业务逻辑还是修Bug）来动态推荐或启用最相关的Skills。

通过这种分层，Agent在处理/src/components/Button.vue文件时，会清晰地知道自己身处“公司”下的“Vue前端项目”中的“组件模块”，因此会自觉运用Vue规范、组件设计模式等相应的Rules和Skills，而不会去考虑如何编写Python的异步上下文管理器。

3. Rules的分层设计与实战配置

理解了“为什么”，我们来看“怎么做”。我将以一个假设的“全栈电商平台”项目为例，展示Rules的分层配置。

3.1 第一层：全局规则 (.cursorrules)

这个文件位于你的用户主目录（如~/.cursorrules），对所有Cursor会话生效。它定义了你的个人或团队的“编码宪法”。

# ~/.cursorrules - 全局编码规范 ## 安全与质量红线 - **绝对禁止**：在任何生成的代码中引入已知的安全漏洞模式，例如：SQL拼接、未经验证的用户输入直接用于文件路径、硬编码敏感信息（密码、API密钥）。 - **错误处理**：必须为可能失败的操作（网络请求、文件IO、数据库查询）添加明确的错误处理（try-catch或.catch），禁止静默吞掉异常。 - **代码审查提示**：在生成复杂逻辑或算法后，主动添加一行注释，如 `// TODO: 在代码审查中重点检查此处的边界条件`。 ## 通用代码风格 - **命名**：变量/函数使用 camelCase，类名使用 PascalCase，常量使用 UPPER_SNAKE_CASE。 - **注释**：所有公共函数、类和方法必须包含JSDoc/TSDoc风格注释，说明用途、参数和返回值。复杂逻辑段落需添加行内注释。 - **异步处理**：优先使用 `async/await`，避免深度嵌套的 `.then()` 链。 ## 与Agent的协作约定 - **当不确定时**：如果对需求或最佳实践存疑，先向我提问确认，而不是基于假设生成可能错误的代码。 - **生成代码前**：简要说明你即将实现的方案思路，获得确认后再生成完整代码。 - **保持简洁**：生成的代码应易于理解。如果一段逻辑可以用更清晰、更直接的方式重写，请优先选择后者。

实操心得：全局规则不宜过多过细，应聚焦于那些“放之四海而皆准”的、关乎代码安全和可维护性根本的原则。它更像是给Agent植入一种“职业素养”。

3.2 第二层：项目级规则 (项目根目录/.cursorrules)

项目根目录下的.cursorrules文件优先级高于全局规则，用于定义本项目特有的技术栈规范。

# 项目级规则：全栈电商平台 (Next.js + TypeScript + Prisma + tRPC) ## 技术栈特定规范 - **前端 (Next.js 14 /app router)**： - 使用React Server Components (RSC) 作为默认选择，仅在需要交互性时使用“use client”。 - 数据获取：在Server Components中使用 `async/await` 直接调用 `prisma`，在Client Components中使用 `tanstack-query` 通过 `tRPC` 调用。 - 样式：使用 Tailwind CSS，遵循项目现有的设计令牌（如 `primary-color` 对应 `bg-blue-600`）。 - **后端/全栈 (tRPC + Prisma)**： - 所有数据库操作必须通过 `prisma` 客户端进行。 - API路由结构需严格遵循 `tRPC` 的 `router/procedure` 模式。 - 输入验证使用 `Zod`，并在tRPC过程中与输入解析器（`input`）集成。 - **类型安全**： - 充分利用TypeScript，避免使用 `any` 类型。必要时使用 `unknown` 并进行类型守卫。 - 从Prisma模型自动生成的类型应作为“单一数据源”。 ## 项目结构约定 - `src/app/api/trpc/[trpc]/route.ts` 是tRPC的单一入口。 - `src/server` 目录下存放所有后端业务逻辑、Prisma客户端实例和tRPC路由定义。 - `src/lib` 存放共享的工具函数和配置。 - 组件放在 `src/components` 下，并鼓励创建可复用的UI组件库 (`src/components/ui`)。 ## 提交前自查 - 生成的代码在提交前应能通过 `pnpm run lint` (ESLint) 和 `pnpm run type-check` (TypeScript编译检查)。

注意事项：项目级规则是核心，它直接决定了Agent生成代码的“技术风味”。这里需要非常具体，甚至可以直接引用项目的tsconfig.json、tailwind.config.js等配置文件中的设定，让Agent的产出与现有代码库无缝融合。

3.3 第三层：目录/模块级规则 (嵌套.cursorrules)

这是最精细化的控制层。你可以在任何子目录下创建.cursorrules文件，其规则仅对该目录及其子目录生效。

示例1：API路由目录规则 (/src/app/api/products/.cursorrules)

# 产品相关API端点规范 - 所有路由处理器必须包含完整的Zod输入验证。 - 错误响应需统一使用 `next/server` 的 `NextResponse.json()` 格式，并包含 `errorCode` 和 `message`。 - 数据库查询必须包含分页逻辑（使用 `skip` 和 `take`），除非特别指定为单条查询。 - 所有变更操作（POST, PUT, DELETE）必须在操作前后添加审计日志（调用统一的 `auditLog` 函数）。

示例2：组件目录规则 (/src/components/ui/.cursorrules)

# UI基础组件库规范 - 所有组件必须为“headless”或高度可定制，通过 `className` 和样式属性支持外部样式覆盖。 - 使用 `React.forwardRef` 暴露DOM引用。 - 组件属性定义必须使用TypeScript接口，并为可选属性提供合理的默认值。 - 必须编写配套的Storybook故事（.stories.tsx），展示主要变体（Variant）和状态。

踩坑记录：我曾在一个大型Monorepo项目中，为每个子包（package）都设置了目录级规则。起初效果很好，但后来发现维护成本很高。一个经验是：仅在确实存在显著差异的、稳定的核心模块使用目录级规则。对于频繁变动或差异不大的目录，过度分层反而会成为负担。

4. Skills的编排与情境化激活

Rules定义了“什么不能做”和“应该怎么做”，而Skills则提供了“如何做得更好”的能力。分层设计同样适用于Skills管理。

4.1 技能分类与存储

不要将所有Skills都塞进Cursor的全局Skills列表。我建议按类别建立你自己的Skills仓库：

1. 项目核心Skills (/.cursor/skills/): 存放在项目根目录，仅与本项目强相关。

   • generate-trpc-procedure.skill: 根据Prisma模型快速生成包含CRUD操作、输入验证和错误处理的tRPC过程。
   • create-nextjs-page.skill: 根据路由和需求，生成一个包含数据获取、SEO设置和基本样式的完整Next.js页面组件。

2. 技术栈通用Skills (~/dev/cursor-skills/): 存放在个人开发目录，适用于特定技术栈。

   • react-hook-form-setup.skill: 快速搭建一个包含验证、错误状态和提交处理的React Hook Form表单。
   • prisma-migration-helper.skill: 根据数据模型变更描述，生成Prisma迁移文件的建议命令和草稿。

3. 全局通用Skills (Cursor内置或社区精选): 只有那些真正通用的，如explain-code,refactor-code等，才放在全局启用列表。

4.2 基于上下文的技能调度

这是让Agent像“同事”一样思考的关键。我们不能被动地等待用户从列表里挑选Skill，而应让Agent根据当前上下文主动推荐最相关的几个Skill。

实现方式：通过精心设计的项目级.cursorrules来实现。

# ... (其他项目规则同上) ## 技能调度策略 - **当正在编辑 `/src/server/routers/` 下的 `.ts` 文件时**：优先考虑使用 `generate-trpc-procedure` 技能来快速构建API端点。 - **当正在编辑 `/src/app/(pages)/` 下的 `page.tsx` 文件时**：优先考虑使用 `create-nextjs-page` 技能来搭建页面框架。 - **当检测到代码中存在复杂条件逻辑或重复模式时**：主动询问是否需要使用 `refactor-code` 技能进行重构。 - **当我的提问中包含“如何实现”、“最佳实践”等开放式问题时**：在回答中除了给出方案，还可以提示“我可以使用 `explain-code` 技能对这段实现进行更详细的逐行解读，是否需要？”。

通过这样的规则描述，你是在“训练”Agent的上下文感知能力。它开始学习将特定的工作场景（编辑某个路径的文件、遇到某类代码问题）与最有效的工具（Skill）关联起来。

4.3 创建自定义Skill的实战指南

一个强大的自定义Skill是分层策略的“利剑”。以创建generate-trpc-procedure.skill为例：

1. 定义技能元信息：在技能文件顶部，用YAML格式描述。

   name: generate-trpc-procedure description: 根据给定的Prisma模型名称和操作类型（findMany, create, update, delete），生成一个完整的、类型安全的tRPC过程，包括输入验证、错误处理和Prisma调用。 author: YourName version: 1.0

2. 编写技能提示词 (Prompt): 这是技能的核心。要清晰定义输入、处理逻辑和输出格式。

   你是一个TypeScript和tRPC专家。请根据以下输入生成代码： - **模型名**: {{ModelName}} (e.g., Product, User) - **操作类型**: {{Operation}} (必须是 findMany, create, update, delete 之一) 生成要求： 1. 导入必要的依赖（`prisma`, `zod`）。 2. 使用Zod为`create`和`update`操作定义输入模式（`inputSchema`）。参考Prisma模型定义，为必填字段添加`.min(1)`等验证。 3. 生成tRPC过程定义。对于`findMany`，要支持分页（`skip`, `take`）和排序（`orderBy`）输入。 4. 在Prisma调用中使用 `try...catch` 进行错误处理，并将数据库错误转换为对客户端友好的API错误。 5. 输出格式为完整的、可直接粘贴到 `src/server/routers/{{modelName}}.ts` 文件中的代码块。 示例输入：ModelName=Product, Operation=create

   这个提示词结构清晰，约束明确，并且通过{{}}定义了变量，使技能可复用。

3. 在Rules中调用技能：在你的项目级或目录级规则中，可以这样引导：

   # 在 `/src/server/routers/.cursorrules` 中 - 当你需要为新的数据模型创建API时，请主动建议：“我可以使用 `generate-trpc-procedure` 技能来快速生成标准的CRUD过程，你需要我为哪个模型（如Product、Order）生成什么操作（findMany, create等）？”

核心技巧：编写自定义Skill的Prompt时，要像给一位能力很强但需要明确指引的实习生写任务清单。背景、输入、约束条件、输出格式、甚至示例，都要尽可能清晰。模糊的Prompt会导致不稳定的输出。

5. 高级技巧与避坑指南

经过多个项目的实践，我总结出一些让分层设计发挥最大效能的进阶技巧和常见问题的解决方案。

5.1 规则冲突与优先级管理

当全局、项目、目录规则出现冲突时，Cursor的默认优先级是就近原则（目录 > 项目 > 全局）。但我们可以利用这一点进行精细控制。

• 场景：全局规则要求“所有函数必须有JSDoc”，但项目中的一个工具函数目录 (/src/lib/utils/) 里都是非常简短的、自解释的辅助函数（如const add = (a,b) => a+b），写JSDoc显得累赘。
• 解决方案：在/src/lib/utils/.cursorrules中设置一条覆盖规则：

  # 工具函数目录特例 - 对于本目录下单行、功能明确的纯函数，可以省略JSDoc注释。 - 但函数名必须完全自解释，否则仍需添加注释。

  这样，Agent在这个目录下生成代码时，就会采用更宽松的注释标准。

5.2 动态上下文感知的进阶用法

除了基于文件路径，还可以利用Cursor的对话上下文来动态调整Agent行为。这需要在.cursorrules中使用更灵活的指令。

# 动态行为规则 - **当我在对话中提及“这是一个原型”或“快速验证想法”时**：生成的代码可以适当放宽代码质量要求（如暂时省略部分错误处理、使用简写），但必须添加 `// PROTOTYPE: 此处需在正式版本中完善` 的标记。 - **当我在对话中提及“这是核心逻辑”或“生产代码”时**：必须严格执行所有安全、错误处理和测试相关规则，并考虑生成配套的单元测试用例。 - **当我连续追问同一个技术细节时**：请主动询问是否需要启用 `explain-code-deeply` 技能，进行更底层的原理剖析。

5.3 团队协作与规则版本化

分层设计的.cursorrules和自定义Skills应该被视为项目代码的一部分，纳入版本控制（如Git）。

1. 共享项目级配置：将项目根目录的.cursorrules和/.cursor/skills/目录提交到仓库。这样，任何克隆该项目的团队成员，其Cursor都会自动遵循同一套项目规范，极大统一了代码风格和生成质量。
2. 个人全局规则个性化：~/.cursorrules不必共享，允许开发者保留个人偏好的全局设置（如更喜欢某种注释风格）。只要项目级规则定义清晰，个人规则不会造成冲突。
3. 技能的迭代与维护：像维护函数库一样维护你的Skills集合。当技术栈升级（如从Next.js 13到14），需要及时更新对应的Skills。在团队内部分享优秀的自定义Skill，能整体提升开发效率。

5.4 常见问题排查（Q&A）

Q1：我设置了多层规则，但感觉Agent有时会忽略某些特定规则，为什么？A1：首先检查规则冲突和优先级。其次，确保你的规则描述是具体、可执行的指令，而不是模糊的愿望。对比“代码要健壮”（模糊）和“所有异步函数必须用try-catch包裹，并处理至少三种错误类型”（具体）。Agent更擅长执行后者。

Q2：自定义Skill有时候好用，有时候生成的内容完全跑偏，怎么办？A2：这是Prompt工程不稳定的常见现象。解决方法是：

• 增加约束：在Prompt中更严格地限定输出格式（“必须输出JSON格式”、“代码必须包含以下三个函数”）。
• 提供更丰富的示例：不止一个，最好提供2-3个不同但典型的输入输出示例，让Agent更好地理解模式。
• 迭代测试：创建一个测试文件，用不同的输入反复调用该Skill，观察输出，并持续优化Prompt。

Q3：分层配置会不会让启动新项目变得很麻烦？A3：恰恰相反。你可以为自己常用的技术栈（如“Next.js + tRPC + Prisma + Tailwind”）创建一个项目模板仓库。这个仓库已经包含了最优化的、分层设计的.cursorrules文件和一套核心自定义Skills。每次开新项目，直接复制这个模板，就能立即获得一个高度智能、懂规范的“AI同事”环境，这反而是效率的飞跃。

6. 效果评估与持续优化

引入分层设计后，如何评估其效果？不能只凭感觉。我建议从以下几个维度进行观察和优化：

1. 代码生成准确率：Agent生成的代码，有多少比例是可以直接使用或仅需微调的？记录下需要你手动大改的情况，分析是哪个层面的规则或技能缺失导致了偏差。
2. 上下文切换流畅度：当你在前端组件和后端API之间切换文件时，Agent是否能迅速调整其“知识焦点”，应用正确的规则和技能？如果它还在用React的思维写Prisma查询，说明目录级规则或技能调度没生效。
3. 主动建议的价值：Agent主动提出的建议（如“这里需要错误处理”、“可以使用XX技能来优化”）有多少是被你采纳的？高采纳率的主动建议，是Agent“同事化”程度的重要指标。

基于这些观察，你可以定期（如每两周）回顾和更新你的Rules和Skills：

• 补充规则：将频繁出现的手动修正点，固化为新的规则。
• 优化技能：对输出不稳定的Skill，重构其Prompt。
• 精简结构：移除那些很少被触发或已过时的规则，保持配置的简洁和高效。

最终，一个经过良好分层设计的Cursor Agent，会真正成为你团队中一位“沉默但高效”的新同事。它不会在会议上夸夸其谈，但总能在你写代码时，恰到好处地提醒你规范、为你补全细节、甚至帮你把繁琐的样板代码一键生成。这种协作体验的提升，才是AI编程进化带来的真正生产力革命。