AI 工作项约定

工作项是 AI 可独立执行的最小非平凡变更包,不是新的需求或设计来源。它把已确认的需求和架构约束压缩成可审阅的执行边界;实时状态仍以 TODO 为准。

何时创建

满足任一条件时创建 W-<阶段>-<序号>-<短名>.md:跨越两个以上目录、改变公开合同/数据格式、安全边界、引入依赖、需要迁移/异步任务,或预期无法在一次小改动中明确验收。纯文案修正、已有测试覆盖的一行 bug 修复不必创建。

模板

# W-M0a-02:短标题

状态:TODO | IN PROGRESS | BLOCKED | DONE
关联需求:R-xxx
关联设计/决策:相对链接
父计划:M0a

## 目标与非目标

- 目标:用户/系统可观察的结果。
- 非目标:本次明确不改变的能力。

## 允许影响面

- 允许路径:`backend/...`、`frontend/...`、`docs/...`
- 禁止路径/边界:例如 gold、跨页面内部导入、未批准的 migration。

## 实施与验收

1. 可验证的步骤(不是思维过程)。
2. 自动检查、fixture、测试或人工验收条件。

## 完成证据

- 命令、结果、artifact/截图链接,或明确的阻塞原因。

同一时间只能有一个叶子工作项标记为 IN PROGRESS。父里程碑可以保持进行中,但不替代叶子工作项的边界。完成后只保留目标、最终事实和证据;过程中的尝试与失败分析放在工作记录或 PR,不写成长期规范。