s2f/cursor-rules/quick-reference.md

AI Coding 工作流快速参考

用于快速判断当前处于哪个阶段、该产出什么、是否需要用户确认。

新项目强制检查点

识别条件：用户说"做一个项目"，或项目根目录不存在 pmdocs/。

强制流程：

1. 确认项目英文缩写
2. 创建 pmdocs/ 目录结构
3. 进入阶段 1：接收需求
4. 禁止提前编码，直到 0-req、1-prd、2-task 全部确认

详见 new-project-checkpoint.md。

阶段与产出对照表

场景	应读取	应产出	必须确认	备注
新项目启动	用户描述	pmdocs/0-req-XXX.md	✓	理解需求、识别风险、拆 MVP
需求确认后	0-req	pmdocs/1-prd-XXX.md	✓	产品场景、UI/UX、公共组件规划
PRD 确认后	0-req + 1-prd	pmdocs/2-task-XXX.md + run.md	✓	任务拆分、编号、依赖、验收
任务确认后	run.md + 2-task + changes + adr	代码 + 测试 + Done 闭环	-	按执行前读取顺序
需求变更	原 0-req / 1-prd / 2-task	pmdocs/changes/CHG-*.md + 7 维评估	✓	只影响需求/PRD/任务/DB/接口/权限/UI 时启用
重大技术决策	当前上下文	pmdocs/adr/ADR-*.md	✓	技术栈、认证、模块边界、部署
公共组件沉淀	页面实现	pmdocs/ui-components.md	-	登记组件类型、输入输出、使用页面
简单任务	上下文	代码 + 简要说明	-	单文件 < 50 行、bug 修复、文案调整

执行前读取顺序

执行项目任务前，按以下顺序读取上下文：

1. run.md → 运行方式
2. pmdocs/2-task-XXX.md → 任务边界
3. pmdocs/changes/*.md → 变更来源
4. pmdocs/1-prd-XXX.md → 产品原因
5. pmdocs/0-req-XXX.md → 原始约束
6. pmdocs/adr/*.md → 技术取舍

Definition of Ready

允许开始开发的条件：

• pmdocs/0-req-XXX.md 已确认
• pmdocs/1-prd-XXX.md 已确认
• pmdocs/2-task-XXX.md 已确认
• 当前任务具备 TASK 编号、验收标准、依赖、测试要求
• 技术栈明确，涉及运行/构建/迁移时 run.md 已存在或任务中明确补充
• 重大决策已有 ADR 或计划创建
• 关键风险、权限边界、数据边界、回滚策略已说明

Definition of Done

任务完成标准：

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

编号体系速查

• 需求：REQ-001
• PRD 功能：PRD-FUNC-001
• 场景：SCENE-001
• 任务：TASK-001
• 变更：CHG-YYYYMMDD-001
• 架构决策：ADR-001
• 权限码：PERM_MODULE_ACTION

编号一旦进入已确认文档，不复用、不重排；废弃项保留编号并标注状态。

禁止行为清单

• ❌ 跨阶段抢跑：未确认 0-req 就写 1-prd，未确认 2-task 就开始编码
• ❌ 文档与代码不同步：run.md 过期、ui-components.md 不更新、变更未闭环
• ❌ 编号混乱：REQ / TASK / CHG 编号重复、跳号、随意改动
• ❌ 过度文档化：明显 bug 修复创建完整变更文档，单文件改动走五阶段
• ❌ 架构决策口头化：技术栈、认证方案只在聊天里说，未写入 ADR
• ❌ API / DB 变更无迁移：改表结构不写 migration，改 API 不说明兼容性
• ❌ 公共组件参数爆炸：把页面路由、接口请求、特定文案硬塞进基础组件

紧急情况降级策略

• 线上紧急 bug：可先修复上线，24 小时内补 pmdocs/changes/CHG-*.md 和回归测试
• 技术栈探索期：可先做 POC，技术栈确定后立即补 run.md 和 ADR
• 用户明确"先上后补"：必须在任务或聊天中明确风险、缺失文档清单和补齐时间点
• 外部不可控因素：在 0-req 或 1-prd 中标注"假设 X 可用"；若假设失效，进入变更流程

文档健康检查清单

定期或阶段结束时验证：

• 0-req、1-prd、2-task 已确认并有版本记录
• 所有 REQ / PRD-FUNC / TASK 编号唯一且可追溯
• run.md 能直接执行，命令无误
• 变更文档已闭环，CHANGELOG.md 同步
• ADR 覆盖所有重大技术决策
• ui-components.md 与实际组件一致
• API / DB 变更有 migration / rollback / 测试
• 无关脏变更未混入提交