s2f/cursor-rules/ai-coding-workflow.md

# Cursor 全局 AI Coding 协作规则

本规则应用于所有项目。核心目标是：先建立清晰需求与模块边界，再推进实现；以 `pmdocs/0-req-XXX.md` → `pmdocs/1-prd-XXX.md` → `pmdocs/2-task-XXX.md` → 开发执行的五阶段工作流为主。

## 0. 优先级与适用范围

### 0.1 指令优先级
- 用户当前明确指令优先于本规则。
- 项目内已有规范优先于本全局规则。
- 本规则作为所有项目的默认协作、架构、编码、文档和质量基线。

### 0.2 工作流主线
- 涉及"做一个项目 / 实现一个功能 / 非平凡改造"的请求，默认使用五阶段工作流。
- 统一使用 `pmdocs/` 作为 PM 文档目录：
  - `pmdocs/0-req-XXX.md`：需求与目标文档
  - `pmdocs/1-prd-XXX.md`：产品需求文档
  - `pmdocs/2-task-XXX.md`：开发任务文档
  - `pmdocs/changes/YYYY-MM-DD-序号-主题.md`：需求变更文档
  - `pmdocs/CHANGELOG.md`：需求与 PM 文档变更索引
  - `pmdocs/adr/YYYY-MM-DD-序号-主题.md`：架构决策记录
  - `pmdocs/ui-components.md`：UI 公共组件登记表
- 简单任务走快速流程，不强制产出三份阶段文档。

### 0.3 简单任务定义
满足以下情况之一，可走快速流程：
- 单文件小改动，通常小于 50 行代码。
- 明确 bug 修复，影响范围清晰。
- 文案、样式、配置微调。
- 只读检查、解释代码、运行一次命令、查看少量文件。

快速流程：理解需求 → 简要确认 → 实施修改与必要验证 → 简洁说明结果。

## 1. 语言与沟通

- 所有与用户的交流必须使用简体中文。
- 代码标识符、命令、日志、错误原文、文件路径、API 名称保持原语言。
- 回复要直接、客观、简洁；不要输出冗长总结。
- 除非用户明确要求，不使用 emoji。
- 不确定时先提问，不擅自假设关键业务规则。
- 提问应结构化：问题、背景、选项、建议。
- 对用户能理解的内容，优先用模块关系、数据结构、数据流、状态机、作用域、伪代码表达，不沉迷函数级细节。

## 2. 工作区与项目边界

- 当前位于用户主目录时，只处理通用任务、系统探索、一次性命令和非项目工作。
- 一旦任务属于某个明确项目，必须先切换到该项目根目录，再进行编辑、安装依赖、提交、创建文件等项目级操作。
- 如果项目路径不明确，先询问用户。
- 创建新项目时，优先放在 `~/Projects/` 或 `~/Developer/`；若不存在则放在用户主目录下。目录创建并初始化 Git 后，先切换到项目根目录，再继续脚手架、安装依赖或写代码。
- 不回退用户或其他 agent 的脏变更。若冲突，先停下来询问。

## 3. 五阶段工作流

### 3.1 命名约定
- 项目英文缩写记为 `XXX`，由用户提供或确认。
- 阶段文档统一放在项目根目录下的 `pmdocs/` 独立目录：
  - `pmdocs/0-req-XXX.md`：需求与目标文档
  - `pmdocs/1-prd-XXX.md`：产品需求文档
  - `pmdocs/2-task-XXX.md`：开发任务文档
- 需求变更文档统一放在 `pmdocs/changes/`：
  - `pmdocs/changes/YYYY-MM-DD-序号-主题.md`
- 需求与 PM 文档变更索引统一使用：
  - `pmdocs/CHANGELOG.md`
- 架构决策记录统一放在 `pmdocs/adr/`：
  - `pmdocs/adr/YYYY-MM-DD-序号-主题.md`
- UI 公共组件登记表统一使用：
  - `pmdocs/ui-components.md`

### 3.1.1 统一编号体系

- 需求条目使用 `REQ-001`、`REQ-002`。
- PRD 功能使用 `PRD-FUNC-001`；产品场景使用 `SCENE-001`。
- 开发任务使用 `TASK-001`，并映射到对应 `REQ`、`PRD-FUNC` 或 `SCENE`。
- 需求变更使用 `CHG-YYYYMMDD-001`，并写入变更文档和 `pmdocs/CHANGELOG.md`。
- 架构决策使用 `ADR-001`，并写入 `pmdocs/adr/YYYY-MM-DD-序号-主题.md`。
- 权限码使用 `PERM_MODULE_ACTION`，例如 `PERM_USER_CREATE`、`PERM_ORDER_EXPORT`。
- 编号一旦进入已确认文档，不复用、不重排；废弃项保留编号并标注状态。

### 3.1.2 执行前读取顺序

执行项目任务前，按以下顺序读取上下文，避免重复摸索：

1. `run.md`：确认安装、启动、构建、测试、迁移命令。
2. `pmdocs/2-task-XXX.md`：确认当前任务边界、验收标准、依赖关系。
3. `pmdocs/changes/*.md`：若任务关联变更，确认变更原因、影响评估和状态。
4. `pmdocs/1-prd-XXX.md`：确认产品场景、优先级、UI/UX 和公共组件规划。
5. `pmdocs/0-req-XXX.md`：确认原始需求、非功能要求和范围边界。
6. `pmdocs/adr/*.md`：若涉及技术栈、模块边界、认证、部署或数据方案，确认架构决策。

原则：运行方式看 `run.md`，任务边界看 `2-task`，变更来源看 `changes`，产品原因看 `1-prd`，原始约束看 `0-req`，长期技术取舍看 `adr`。

### 3.2 阶段 1：接收需求与目标
- 完整读取和理解用户的需求描述或已有文档。
- 识别目标用户、使用场景、优先级、性能、安全、数据规模、兼容性、第三方依赖等关键缺口。
- 对模糊、矛盾或高风险信息先澄清。
- 若需求明显过大，先拆出 MVP 与后续扩展边界。

### 3.3 阶段 2：生成 `pmdocs/0-req-XXX.md`
仅在阶段 1 信息足够后进行。

文档必须包含：
- 引言与目标
- 术语表
- 角色定义
- 功能性需求，优先使用 EARS 格式：`WHEN / IF / WHILE / WHERE / THE ... SHALL ...`
- 非功能性需求：性能、安全、兼容性、可用性、可扩展性、可维护性、合规性
- 范围边界：包含 / 不包含
- 关键约束与假设
- 验收标准

生成后必须请用户检查确认。未确认前不进入阶段 3。

### 3.4 阶段 3：生成 `pmdocs/1-prd-XXX.md`
仅在 `pmdocs/0-req-XXX.md` 确认通过后进行。

文档必须包含：
- 产品概述与定位
- 目标与成功指标
- 用户画像与核心场景，每个场景标注"痛点解法"
- 功能清单与优先级，使用 MoSCoW，并映射回需求编号
- 关键流程
- 角色权限矩阵
- UI/UX 设计原则：布局结构、导航方式、表单交互、列表/表格、筛选、分页、时间段选择、空状态、加载状态、错误状态、响应式和可访问性
- 公共组件抽取规划：页面布局、分页组件、时间段组件、筛选栏、搜索框、表格、表单项、弹窗/抽屉、状态标签等
- 版本规划：MVP / 二期 / 三期
- 非功能性要求
- 外部依赖、内部依赖与风险

生成后必须请用户检查确认。未确认前不进入阶段 4。

### 3.5 阶段 4：生成 `pmdocs/2-task-XXX.md`
仅在 `pmdocs/1-prd-XXX.md` 确认通过后进行。

任务文档要求：
- 使用可勾选清单 `- [ ]`。
- 编号清晰，任务粒度可执行、可验证。
- 每个任务标注：目标、对应需求 / PRD 条目、验收标准、依赖关系、优先级、阶段。
- 前后端技术栈、编译、启动、数据库迁移等一旦确认，必须包含创建或更新 `run.md` 的任务。
- 涉及重大技术决策时，必须包含创建或更新 `pmdocs/adr/*.md` 的任务。
- 涉及 API 或数据库变更时，必须包含接口契约、迁移、回滚、seed、权限和测试任务。
- UI 页面开发前，应先识别可复用公共组件，并将页面布局、分页、时间段、筛选、表格、表单、弹窗等抽取任务排在具体页面任务之前。
- 涉及可复用 UI 组件时，必须包含创建或更新 `pmdocs/ui-components.md` 的任务。
- 明确测试要求：单元测试、集成测试、端到端测试、构建验证或手工验证。
- 开发过程中持续更新任务状态和进度记录。

生成后必须请用户确认。未确认前不进入阶段 5。

### 3.6 阶段 5：按任务文档执行开发
- 仅在 `pmdocs/2-task-XXX.md` 确认通过后开始编码。
- 严格按确认后的任务文档推进。
- 每完成一个任务或一组任务：
  - 做相应验证：linter、构建、单元测试、集成测试或必要的手工验证。
  - 更新 `pmdocs/2-task-XXX.md`。
  - 简洁汇报结果、问题和下一步。
- 若任务执行发现需调整需求或 PRD，必须进入需求变更流程。
- 不在代码、文档或聊天中硬编码密钥、令牌、密码。

### 3.7 Definition of Done

任务完成标准：
- 对应 `TASK` 已在 `pmdocs/2-task-XXX.md` 标记完成。
- 代码实现完成，职责清晰，无复杂度扩散。
- lint / build / test 或必要手工验证已完成。
- `run.md` 已同步（若涉及）。
- 变更文档已闭环，`pmdocs/CHANGELOG.md` 已同步（若涉及）。
- API / DB / 权限码契约、迁移、回滚、测试已处理（若涉及）。
- UI 加载、空态、错误、分页、权限状态已覆盖（若涉及）。
- 无关脏变更未混入。

## 4. 文档管理

- 阶段文档是当前功能的事实来源：`pmdocs/0-req-XXX.md` 管需求，`pmdocs/1-prd-XXX.md` 管产品决策，`pmdocs/2-task-XXX.md` 管执行进度。
- 不为每个小任务创建重复文档。
- 项目级文档只在以下情况更新：新增用户可见功能、API 变化、配置格式变化、部署流程变化、重大架构调整、破坏性变更。
- 文档过大时按模块或层次拆分，并保留导航入口。
- 优先使用自动化文档：OpenAPI、GraphQL Schema、GoDoc、JSDoc、Sphinx、类型声明等。

### 4.1 `run.md` 运行手册

- 一旦确认前端、后端、数据库、包管理器、运行时或部署方式，必须在项目根目录创建或更新 `run.md`。
- `run.md` 是项目运行事实来源；后续编译、启动、测试、数据库迁移等操作必须优先读取它，不要每次重新查找和试错。
- 如果实际命令与 `run.md` 不一致，先验证真实行为，再更新 `run.md`，保持文档与运行时一致。
- `run.md` 至少包含：
  - 技术栈：前端、后端、数据库、包管理器、运行时版本。
  - 本地环境：必要环境变量、配置文件、端口、依赖服务。
  - 安装命令：依赖安装、初始化步骤。
  - 开发命令：前端启动、后端启动、全栈启动、后台任务或 worker。
  - 构建命令：前端构建、后端构建、类型检查、lint。
  - 测试命令：单元测试、集成测试、端到端测试、覆盖率。
  - 数据库命令：迁移、回滚、seed、reset、schema 生成。
  - 常见问题：已验证的坑、报错原因、修复方式。
- `pmdocs/2-task-XXX.md` 中涉及环境准备、技术栈确认、数据库接入或部署改动时，必须包含更新 `run.md` 的任务。

## 5. Git 与协作

- 不主动提交代码，除非用户明确要求。
- 不主动 push，除非用户明确要求。
- 不使用破坏性 Git 操作，例如 `reset --hard`、强制 push、丢弃他人改动，除非用户明确要求并理解风险。
- 提交粒度应是一个逻辑完整单元。
- 提交信息优先遵循 Conventional Commits：`feat`、`fix`、`docs`、`style`、`refactor`、`test`、`chore`。
- 发现无关脏变更时忽略；若与当前任务冲突，先询问用户。

## 6. 特殊场景

### 6.1 Bug 修复
- 先定位根因，再修复。
- 说明影响范围。
- 优先补测试或最小复现。
- 修复后做回归验证。

### 6.2 性能优化
- 先测量再优化。
- 识别瓶颈后再改代码。
- 给出优化前后对比或可复现验证方式。
- 说明优化副作用。

### 6.3 重构
- 先说明重构目标和边界。
- 保持外部行为不变。
- 小步推进，保持可回滚。
- 对遗留代码先理解再修改，必要时先加测试建立安全网。

### 6.4 Cursor 相关问题
- 当用户询问 Cursor 使用方式、配置、设置或功能时，使用最新 Cursor 指南或可用专用能力，不凭记忆回答。

## 7. 核心原则

1. 用户目标优先，不替用户做关键业务决策。
2. 架构与模块职责优先，不让复杂度在局部扩散。
3. 工作流以 `pmdocs/0-req-XXX.md`、`pmdocs/1-prd-XXX.md`、`pmdocs/2-task-XXX.md` 为主，关键节点必须确认。
4. 代码必须可维护、可测试、可验证。
5. 沟通简洁透明，风险和阻塞及时说明。
6. 不把密钥、令牌、密码放进全局规则或项目源码。

## 8. 相关规则

本规则聚焦工作流主线和核心原则。详细规范请参考：

- `quick-reference.md`：快速参考卡、阶段对照表、禁止行为、紧急降级
- `architecture-and-design.md`：架构原则、ADR、API/DB 变更约束、代码质量、测试、安全
- `ui-components-standard.md`：UI/UX 设计原则、公共组件抽取、组件登记表、参数膨胀应对
- `change-management.md`：需求变更识别、7 维评估、六步流程、文档追加、闭环机制