MapLibreParticleLab/docs/00_项目总则/Step指令书与执行报告规范_v1.md

Step 指令书与执行报告规范 v1

1. 命名

指令书：step-xxxx-目的内容.md。 报告：step-xxxx-目的内容-执行报告.md。 统一使用“执行报告”。

2. 同目录

指令书与报告放同一个大阶段目的目录。

3. 指令书固定章节

1. Step 编号和目的
2. 当前已冻结基线
3. 本 Step 目标
4. 非目标/禁止事项
5. 允许修改范围
6. 禁止修改范围
7. 实施要求
8. 构建要求
9. 测试要求
10. 验收标准
11. Git 要求
12. 必做输出
13. 执行报告完整文件名
14. 执行报告固定内容
15. 阻塞与停止条件

4. Codex 前置必读

AGENTS.md → 本目录 README → 三份长期总则 → 当前基线与路线 → 本阶段已有文档 → 上一 Step 执行报告。

5. Jest 特殊规则

GPT 生成任何正式 Step 指令书之前必须先询问用户是否加入 Jest。未经明确确认不得写入。若加入，先确认测试力度、允许修复范围、是否可改生产代码、最大修复轮数、停止条件。

6. 执行报告固定结构

1. 执行结论：PASS/PARTIAL/BLOCKED/FAIL
2. Git 基线：branch/start commit/end commit/working tree/submodule
3. 实际修改文件
4. 新增文件
5. 实际实现内容
6. 与指令书差异（无也写“无”）
7. 构建记录：command/renderer/build type/JOBS/result/关键日志/耗时
8. 测试记录
9. 生成产物：文件名/路径/大小/SHA256/Renderer/Build Type/ABI
10. 已知问题
11. 未完成事项
12. 下一 Step 建议（只建议，不自行创建）

7. 报告必须反映事实

禁止未执行测试写 PASS、计划写成已完成、隐藏失败、用“应该正常”替代结果、把 Win11 人工验证写成 Linux Codex 已完成。若只完成 Linux APK build，必须明确“Win11 Android Simulator 人工验证待用户执行”。

8. 总则修改

普通 Step 禁止修改 docs/00_项目总则/。如认为需调整，只在报告提出建议。

9. GPT 写新 Step 的依据

必须参考：“粒子系统”GPT 项目既有设计、项目总则、当前基线、上一 Step 报告、当前 Git 事实、用户最新确认。