freedakgmail
106 lines
4.7 KiB
Markdown
106 lines
4.7 KiB
Markdown
# 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 / 测试
|
||
- [ ] 无关脏变更未混入提交 |