1. 项目概述：当AI代码助手遇上敏捷开发

最近在几个敏捷团队里做技术咨询，发现一个挺有意思的现象：大家用Cursor、Copilot这类AI编程工具越来越溜，但团队协作的“味道”却有点变了。以前站会大家聊的是“我昨天重构了那个模块，遇到了一个并发问题”，现在变成了“我让Cursor生成了个函数，但不太敢直接合进去”。代码生成是快了，但代码审查的负担重了，对生成代码的理解深度不够，甚至出现了“AI生成，无人认领”的代码块。这让我开始琢磨，能不能把敏捷开发里那些好用的实践——比如代码规范、团队约定、Definition of Done（完成的定义）——也“教”给AI助手，让它从一开始就写出更符合团队习惯、更安全、更可维护的代码？

这就是“jabrena/cursor-rules-agile”这个项目吸引我的地方。它不是一个独立的工具，而是一套针对Cursor编辑器的规则（Rules）配置方案，核心思想是 将敏捷团队的工程实践和代码质量要求，转化为AI助手能理解和执行的约束条件 。你可以把它理解为给Cursor这个“超级实习生”制定的一份详尽的《团队开发手册》和《代码提交 checklist》。它通过Cursor的“规则”功能，在AI生成代码、补全代码、解释代码的每一个环节，注入团队的共识，确保AI的产出物从诞生那一刻起，就自带质量属性，与团队的工作流无缝集成。

简单来说，这个项目解决了敏捷团队使用AI编程工具时的几个核心痛点： 生成代码与团队规范脱节 、 AI“黑盒”输出带来的审查与理解成本 、 以及缺乏针对AI生成代码的特定质量门禁 。它适合正在或计划深度使用Cursor的敏捷团队（无论是Scrum、Kanban还是XP），尤其适合技术负责人、架构师和追求工程效能的开发者，通过预先配置，让AI助手从“自由发挥的天才”变成“懂规矩、守流程的团队伙伴”。

2. 核心设计理念：规则即共识，Prompt即流程

在深入拆解具体规则之前，我们必须先理解这套方案背后的两个核心设计理念。这不仅仅是技术配置，更是对人机协作模式的一种思考。

2.1 从“事后审查”到“事前约定”

传统的代码质量控制，无论是人工还是通过CI/CD流水线，大多属于“事后检查”。开发者写完代码，提交后触发ESLint、SonarQube等工具扫描，发现问题再回头修改。这种方式对于AI生成代码尤其低效，因为AI可能一次性生成上百行，其中混杂着多种风格或潜在问题，审查者需要花费大量精力去辨别和修正。

cursor-rules-agile 的理念是 “Shift Left” ，将质量关卡尽可能左移，移到代码生成的源头。通过在Cursor中定义规则，我们实际上是在对AI说：“在你开始‘写’之前，请先记住我们团队的这些规矩。” 当开发者触发 @ 命令（如 @ +函数功能描述）时，AI会主动将这些规则作为上下文的一部分来考虑，从而生成更符合预期的代码。这相当于把代码审查的部分工作前置到了生成阶段，大幅降低了后续的审查成本和返工概率。

2.2 规则的双层结构：全局约束与上下文增强

Cursor的规则系统本身支持多层级的配置。 cursor-rules-agile 项目巧妙地运用了这一点，构建了一个双层规则体系：

1. 全局规则（ .cursor/rules 目录下的规则文件） ：这些是团队的“基本法”，适用于所有项目、所有场景。例如，要求所有生成的代码块必须包含JSDoc/TSDoc注释、禁止使用某些不安全的API、强制采用特定的错误处理模式等。这些规则确保了代码质量的底线。

2. 项目级/上下文规则（通过 @ 命令临时附加） ：这是其“敏捷”特性的体现。除了全局规则，在具体的 @ Prompt中，可以动态地引入更具体的上下文或约束。例如，在描述一个“用户注册函数”时，Prompt可以是：“ @ 实现一个用户注册函数，需包含密码加密、邮箱验证，并遵循项目 src/utils/validation.ts 中的输入验证模式”。AI会同时考虑全局规则和这个具体的上下文文件，生成的结果不仅规范，而且直接契合项目现有架构。

这种设计使得规则既有强制性，又不失灵活性。团队共识通过全局规则固化，而项目特定的业务逻辑和模式则通过上下文精准注入。

2.3 Prompt工程与敏捷实践的融合

这个项目的另一个精髓在于，它将 敏捷开发中的具体实践转化为了可操作的Prompt指令或规则条件 。例如：

• 对应“代码集体所有权” ：规则可以要求生成的函数、类必须具有清晰的命名和高内聚性，让任何团队成员都能快速理解。
• 对应“持续集成” ：规则可以强制生成的代码必须是可测试的（如易于注入依赖），甚至直接建议或生成基础的单元测试结构。
• 对应“Definition of Done” ：规则可以检查生成的代码是否包含了必要的日志记录、是否处理了边界条件、是否更新了相关的文档字符串。这相当于为每一段AI生成的代码自动执行了一次微型DoD检查。

通过这样的融合，AI助手不再是孤立的生产力工具，而是被深度整合到了敏捷团队的价值观和工作流之中。

3. 核心规则集详解与配置实战

接下来，我们拆解 cursor-rules-agile 中可能包含的几类核心规则，并给出具体的配置示例和操作步骤。假设我们为一个使用TypeScript、React和Node.js的敏捷团队配置规则。

3.1 代码规范与风格一致性规则

这是最基础也是最重要的一层。目标是让AI生成的代码看起来就像团队中一位资深成员写的一样。

规则示例： enforce_code_style.cursorrule

# 强制代码风格一致性

## 核心指令
你生成的任何代码都必须严格遵循以下风格指南：
1.  **命名**：变量/函数使用`camelCase`，类使用`PascalCase`，常量使用`UPPER_SNAKE_CASE`。布尔变量以`is`， `has`， `can`开头。
2.  **类型**：必须使用TypeScript，显式定义类型。禁止使用`any`。函数参数和返回值必须定义类型。
3.  **导入**：导入语句需分组（React， 第三方库， 内部模块， 类型导入），并使用空行分隔。
4.  **错误处理**：异步操作必须使用`try/catch`包裹，并记录错误日志。禁止吞没错误（即空的catch块）。
5.  **注释**：每个导出函数、类、复杂逻辑块前必须添加JSDoc注释，描述功能、参数、返回值和可能的异常。

## 上下文文件
请参考项目根目录下的 `.eslintrc.js` 和 `prettier.config.js` 以获取更详细的格式规则。

## 生效范围
适用于所有通过`@`命令生成的代码、代码补全和代码解释。

配置与操作步骤：

1. 在项目根目录创建 .cursor 文件夹（如果不存在）。
2. 在 .cursor 文件夹内创建 rules 文件夹。
3. 将上述内容保存为 enforce_code_style.cursorrule 文件并放入 rules 文件夹。
4. 重启Cursor或重新加载项目，该规则即自动生效。

实操心得 ：规则描述要具体、可执行。像“写好注释”这样的指令太模糊，AI可能只生成 // 这是一个函数 。而“必须添加JSDoc注释，包含 @param ， @returns 标签”这样的指令，AI就能生成结构化的文档。初期可以配置得严格一些，后期再根据团队反馈调整。

3.2 安全与最佳实践规则

专门用于规避AI可能引入的常见反模式和安全隐患。

规则示例： security_best_practices.cursorrule

# 安全与最佳实践约束

## 核心指令
生成代码时，必须主动避免以下情况，并采用安全替代方案：

1.  **SQL/NoSQL注入**：禁止使用字符串拼接生成查询。当检测到数据库操作意图时，必须使用参数化查询或ORM的安全方法（如Prisma的`$queryRaw`带参数，或Mongoose的查询构造器）。
2.  **硬编码敏感信息**：绝对禁止在生成的代码中硬编码API密钥、数据库密码、JWT密钥等。必须使用环境变量（`process.env.XXX`）或配置服务。
3.  **不安全的依赖函数**：避免使用`eval()`， `setTimeout`/`setInterval` 传入字符串， `Function`构造函数等。
4.  **资源泄漏**：生成的代码若涉及文件操作、数据库连接、网络请求，必须确保在`finally`块或使用`try...with...`（Python）、`using`（C#）等方式正确关闭和释放资源。
5.  **XSS防护（前端）**：在生成React/Vue代码时，如果涉及渲染用户输入，必须默认使用文本节点或合适的转义库（如`DOMPurify`），避免直接使用`dangerouslySetInnerHTML`或`v-html`。

## 示例：错误 vs 正确
- **错误**：`const query = `SELECT * FROM users WHERE name = '${userInput}';``
- **正确**：`const query = `SELECT * FROM users WHERE name = $1`; const values = [userInput];`

## 生效范围
所有代码生成场景，尤其是当用户Prompt中包含“数据库”、“查询”、“保存”、“渲染”、“输入”等关键词时。

配置步骤 ：同上，创建 .cursor/rules/security_best_practices.cursorrule 文件。

注意事项 ：安全规则有时会“过度防御”。例如，AI可能在一个纯粹的内部工具脚本里也拒绝任何形式的字符串拼接。因此，团队需要明确这些规则的边界，或者通过更精确的Prompt（如“这是一个仅供内部使用的、无网络访问的脚本”）来临时“豁免”某些规则。

3.3 领域驱动设计与架构约束规则

对于中大型项目，让AI理解项目的分层架构和领域模型至关重要。

规则示例： ddd_architecture.cursorrule

# 遵循领域驱动设计(DDD)架构

## 项目上下文
本项目采用分层架构：`presentation` (UI/API层) -> `application` (用例层) -> `domain` (领域层) -> `infrastructure` (基础设施层)。请严格遵循依赖方向：内层不依赖外层。

## 核心指令
根据用户Prompt的意图，将代码生成到正确的层，并遵循各层的职责：

1.  **`domain/` (领域层)**：
    *   当涉及核心业务实体（如`User`， `Order`）、值对象、领域服务、仓储接口时，代码应在此层。
    *   此层代码**必须纯净**，不依赖任何框架、数据库或外部服务库。只能包含业务逻辑和规则。
    *   示例Prompt：“`@`定义一个`Payment`聚合根，包含状态机和支付验证规则。”

2.  **`application/` (应用层)**：
    *   当涉及协调领域对象完成一个具体用例（如“创建用户订单”）时，代码应在此层。
    *   生成`UseCase`或`Service`类，注入领域服务和仓储接口。
    *   此层负责事务管理、权限校验（非领域逻辑）等。
    *   示例Prompt：“`@`实现一个‘处理订单退款’的用例服务。”

3.  **`infrastructure/` (基础设施层)**：
    *   当涉及数据库操作（实现`domain`层的仓储接口）、外部API调用、消息队列发送时，代码应在此层。
    *   可以引入Prisma、TypeORM、Axios等具体技术库。
    *   示例Prompt：“`@`实现一个基于Prisma的`UserRepository`。”

4.  **`presentation/` (表现层)**：
    *   当需要生成REST API控制器、GraphQL Resolver或React组件时，代码应在此层。
    *   此层应非常薄，仅负责接收输入、调用应用层服务、返回响应或渲染视图。
    *   示例Prompt：“`@`创建一个处理`POST /api/orders`的Express控制器。”

## 文件路径参考
请始终参考项目现有文件结构，将新生成的代码放入正确的目录。例如，领域实体放在`src/domain/entities/`， 用例放在`src/application/use-cases/`。

配置步骤 ：创建 .cursor/rules/ddd_architecture.cursorrule 文件。 关键在于 ## 项目上下文 部分 ，这里需要你根据自己项目的实际结构进行定制。

实操心得 ：这类架构规则的效果，极度依赖于Prompt描述的清晰度。如果开发者只说“ @ 写个保存用户的函数”，AI可能无从判断层。因此，团队需要培养“精准Prompt”的习惯，例如“ @ 在 infrastructure 层，实现一个基于MongoDB的 UserRepository 接口的具体类”。这本身也是推动团队更清晰思考代码职责的好机会。

4. 高级应用：将敏捷仪式与团队习惯编码为规则

真正的“敏捷”融合体现在这里。我们可以创建一些规则，来强化特定的团队工作习惯。

4.1 站立会（Daily Stand-up）驱动的问题定位规则

假设团队习惯在站会上快速同步阻塞问题。可以创建一条规则，让AI在生成代码时，如果遇到需要复杂决策或可能产生技术债的地方，主动添加特殊的 TODO 注释，并关联到团队成员。

规则示例： standup_todos.cursorrule

# 生成站会可讨论的TODO注释

## 核心指令
在生成代码时，如果遇到以下情况，请插入格式化的TODO注释：
1.  **技术决策点**：当存在多种实现方案（如选择A库还是B库），且各有利弊时。
2.  **已知妥协**：由于时间限制，采用了非最优但可快速实现的方案时。
3.  **外部依赖**：代码的实现依赖于另一个团队尚未完成的接口或服务时。
4.  **复杂度警示**：生成了特别复杂（圈复杂度高）的逻辑，需要后续重构时。

## TODO注释格式
请使用以下格式，以便在站会上快速识别和讨论：
```typescript
// TODO: [@username1 @username2] [决策|妥协|依赖|复杂度] - 简要描述。例如：选择使用本地缓存而非Redis，因后者环境未就绪，需后续评估性能影响。

示例

当生成一个临时用 setTimeout 实现轮询的函数时，应添加：

// TODO: [@team/backend] [妥协] - 使用setTimeout轮询查询订单状态，应改为WebSocket或Server-Sent Events以实现实时性。

生效范围

主要适用于通过 @ 命令生成的新功能或复杂逻辑块。

### 4.2 团队知识传承与模式复用规则

每个团队都有自己沉淀下来的“独门秘籍”——一些处理特定问题的模式或工具函数。我们可以让AI学会这些模式。

**规则示例：`team_patterns.cursorrule`**
```markdown
# 复用团队特定模式

## 核心指令
当用户请求的功能与以下已知团队模式匹配时，优先使用或参考这些模式，而不是从头生成通用方案。

## 模式库
1.  **API响应封装**：所有Controller必须使用`src/common/utils/apiResponse.ts`中的`success`和`error`函数来包装响应。
2.  **异步任务队列**：对于耗时操作（如发送批量邮件、生成报表），应使用`src/infrastructure/queue/taskQueue.ts`中定义的`createQueueTask`模式，将任务推入Redis队列。
3.  **缓存策略**：对于高频读取、低频变更的数据，使用`src/infrastructure/cache/pattern.ts`中的`cacheAside`（旁路缓存）模式。
4.  **错误分类**：业务错误必须使用`src/domain/errors/BusinessError.ts`中定义的特定错误类（如`ValidationError`， `NotFoundError`），而非通用的`Error`。

## 上下文文件
请仔细阅读`src/common/utils/apiResponse.ts`和`src/domain/errors/BusinessError.ts`的代码风格和用法。

## 示例Prompt与预期输出
- **用户Prompt**： “`@`创建一个用户登录的API端点，成功返回JWT token，失败返回错误信息。”
- **AI应生成类似代码**：
```typescript
import { success， error } from ‘../../../common/utils/apiResponse’;
import { ValidationError } from ‘../../../domain/errors/BusinessError’;
// ... 其他导入
export const login = async (req， res) => {
 try {
 // ... 验证逻辑
 if (!valid) throw new ValidationError(‘邮箱或密码无效’);
 // ... 登录逻辑
 return success(res， { token: jwtToken });
 } catch (err) {
 // 错误会被全局中间件或此处处理，并转换为统一错误响应
 return error(res， err);
 }
};

配置这条规则后，AI生成的代码会自然而然地融入团队的“基因”，大大提升了代码的一致性和可维护性，也让新成员能通过AI快速学习团队的最佳实践。

## 5. 实战演练：从零配置并验证一个用户故事

让我们模拟一个完整的用户故事，看看配置了`cursor-rules-agile`规则的团队是如何协作的。

**背景**：一个电商团队，需要实现“用户下单后，如果30分钟未支付，自动取消订单”的功能。

**步骤一：精准的Prompt输入**
开发者不会简单地说“`@`写个取消超时订单的功能”。而是结合规则训练出的习惯，输入更精准的Prompt：
> “`@`在`application/use-cases`层实现一个‘取消超时未支付订单’的用例服务。需依赖`OrderRepository`和`NotificationService`接口。使用`src/infrastructure/queue/taskQueue.ts`中的模式，将检查逻辑放入延迟任务。参考`src/domain/entities/Order.ts`中的状态枚举。”

这个Prompt包含了**架构分层**、**依赖注入**、**团队模式复用**和**上下文参考**，信息量十足。

**步骤二：AI的规则约束生成**
Cursor在生成代码时，会同时应用：
1.  `enforce_code_style`：生成格式规范、带有JSDoc的TypeScript代码。
2.  `ddd_architecture`：将代码生成到`src/application/use-cases/cancelUnpaidOrder.ts`。
3.  `team_patterns`：使用`createQueueTask`来创建队列任务，而非自己写一个`setTimeout`。
4.  `security_best_practices`：确保数据库查询使用参数化（通过Repository接口）。

生成的代码骨架会非常贴近团队现有风格，并且直接可集成。

**步骤三：审查与合并**
审查者收到Pull Request时，会发现代码结构清晰、符合规范、使用了团队熟悉的模式。审查重点可以从“风格对不对”、“有没有安全漏洞”这类基础问题，转移到“业务逻辑是否完整”、“异常场景是否覆盖”、“领域模型使用是否恰当”等更高层次的问题上。效率和质量同步提升。

## 6. 常见问题、排查技巧与避坑指南

在实际引入和配置`cursor-rules-agile`这类规则集的过程中，团队一定会遇到各种问题。以下是我在多个团队中实践后总结的常见“坑”和解决方案。

### 6.1 规则冲突与优先级混乱

**问题**：当多条规则同时对同一段代码生成提出要求，且要求可能矛盾时，AI会困惑。例如，一条规则要求“函数必须简短”，另一条要求“必须处理所有错误边界”，而一个复杂的错误处理函数很难简短。

**排查与解决**：
1.  **明确规则层次**：在规则文件开头用`## 优先级`或`## 覆盖关系`说明。通常，安全规则 > 架构规则 > 代码风格规则。
2.  **细化规则条件**：使用更精确的描述。例如，将“函数必须简短”改为“非控制器类的业务函数，行数应尽量控制在50行以内，若超过应考虑拆分。控制器函数可适当放宽。”
3.  **利用Cursor的规则测试功能**：在Cursor中，可以对某条规则或一组规则进行测试。编写一个典型的Prompt，观察AI的输出，如果不符合预期，则调整规则描述。这是一个迭代的过程。

### 6.2 规则过多导致生成速度变慢或效果下降

**问题**：给AI加载了太多、太复杂的规则，每次生成都需要处理巨大的上下文，可能导致响应变慢，甚至有时AI会“忽略”部分规则。

**排查与解决**：
1.  **按需加载，分组管理**：不要把所有规则都放在全局。可以创建不同的规则集，如`basic.cursorrule`（风格+安全）、`frontend.cursorrule`（React特定规则）、`backend.cursorrule`（API+DB规则）。在项目开始时通过`.cursorrules`文件（项目级规则入口）按需引入。
2.  **精简规则描述**：避免冗长的散文式描述。使用清晰的列表、关键词和“必须”、“禁止”、“参考”等强动词。AI对结构化指令的理解更好。
3.  **定期回顾与清理**：在团队迭代会上，定期回顾规则的有效性。移除那些很少被触发或已被团队内化的规则，合并相似的规则。

### 6.3 AI生成的代码“看似正确，实则有问题”

**问题**：AI生成的代码通过了所有规则检查，语法正确，风格一致，但存在逻辑缺陷、业务理解偏差或性能问题。例如，它可能生成一个O(n²)的数组去重算法，而不是用`Set`。

**排查与解决**：
1.  **规则无法替代人的审查**：这是最重要的认知。规则主要用于保障“形式质量”，无法保障“逻辑质量”。审查者必须对AI生成的核心算法、业务逻辑保持警惕。
2.  **在规则中加入“思维链”要求**：可以创建一条规则，要求AI在生成复杂算法时，在代码注释中简要说明其选择该算法的原因（例如，“// 使用Map实现，时间复杂度O(n)，空间复杂度O(n)”）。这既有助于AI自我检查，也方便审查者理解其意图。
3.  **建立针对AI代码的审查清单**：在团队的PR模板中，增加专门针对AI生成代码的检查项，例如：
    *   [ ] 生成的算法逻辑是否最优？（时间/空间复杂度）
    *   [ ] 业务边界条件是否全部覆盖？（空值、极值、异常状态）
    *   [ ] 生成的代码是否与现有业务逻辑冲突？
    *   [ ] 是否需要为这段生成代码补充单元测试？

### 6.4 团队适应与习惯培养的挑战

**问题**：开发者不习惯写详细的Prompt，或者觉得配置规则太麻烦，宁愿关掉规则自己写。

**排查与解决**：
1.  **价值引导，而非强制**：通过一次结对编程或工作坊，向团队展示一个对比案例：没有规则时AI生成的“通用但不合规”代码，与有规则时生成的“开箱即用”代码。让大家直观感受规则带来的审查时间节省和返工减少。
2.  **降低启动门槛**：由技术负责人或架构师先搭建一个最小可用的规则集（包含代码风格、1-2条安全规则、1条架构规则），让团队先用起来。再鼓励大家共同贡献和优化规则，将其视为团队资产建设的一部分。
3.  **奖励“好Prompt”**：在代码审查中，如果发现某段AI生成的代码质量极高，可以公开表扬开发者提供的精准Prompt。将编写清晰、具体的Prompt视为一项重要的工程能力。

### 6.5 规则维护与版本化

**问题**：规则文件散落在各个项目的`.cursor/rules`目录下，难以同步更新，不同项目间规则可能出现分歧。

**排查与解决**：
1.  **集中化管理**：将核心的、通用的规则（如代码风格、安全基线、公司级架构约束）放在一个独立的Git仓库中（例如`company-cursor-rules`）。
2.  **使用子模块或npm包**：在各个业务项目中，通过Git子模块或私有npm包的方式引用这个中央规则库。这样，中央规则的更新可以同步到所有项目。
3.  **项目级扩展**：在中央规则的基础上，允许各个项目在本地`.cursor/rules`目录中添加自己特有的规则（如项目特定的领域模式）。Cursor会合并加载这些规则。
4.  **为规则添加版本号**：在规则文件的注释中，加入版本号（如`## Version: 1.2.0`）和更新日志，便于跟踪变化。

引入`cursor-rules-agile`这类实践，本质上是一场关于人机协作模式的微小变革。它要求团队从被动地接受AI的“惊喜”（有时是惊吓），转变为主动地、有意识地去设计和引导AI，使其成为团队价值观和工程规范的忠实执行者。这个过程必然会遇到挑战，但一旦磨合成功，带来的将是代码质量底线的大幅提升、团队认知负荷的显著降低，以及工程效能可持续的、健康的增长。最终，我们不是被工具所改变，而是用工具更好地实践我们认同的敏捷与工程之道。