用途：让 AI Agent 为新项目生成可直接交付给编码 Agent 的工程规范 使用方式：将下方「提示词正文」复制给 Agent，填入 [] 占位符后使用 前提：必须先有对应的架构白皮书，本文档是白皮书的工程落地子集
提示词正文
你需要为项目 [项目名] 的 [阶段名，如 Phase 1 / MVP / Sprint 3] 写一份工程实现规范。
配套白皮书：[白皮书文档路径或内容] 技术栈：[语言、运行时、主要依赖，如 Python 3.12 + PostgreSQL / Go 1.22 + SQLite / Rust + RocksDB]
文档定位
- 受众：AI 编码 Agent（不是人类开发者）——措辞必须零歧义，可机械执行
- 层级：可直接操作的工程军规，不含架构愿景
- 与白皮书的关系：白皮书写「是什么、为什么」，本文档写「怎么实现、验收标准是什么」
必须包含的章节
0. 开发策略
说明为什么采用当前策略（全新 clean room / 渐进重构 / 并行双轨等）。 用 ASCII 树展示物理目录结构，明确各目录的职责和隔离边界。 如果存在「禁止互相引用」的目录，显式列出。
1. 导航文档目录树
定义 docs/ 或等效文档目录的完整结构，包括：
- 接口契约文件清单（类型定义 / schema / proto / OpenAPI 等，视技术栈而定）
- 架构决策记录（ADR）文件清单
- 操作手册清单
Agent 必须遵守的读取规则（如：「开始编码前必须先读 CODEBASE_MAP」）。
2. CODEBASE_MAP
用表格定义所有模块：模块名 | 路径 | 核心职责 | 唯一变更入口文件
用 ASCII 树定义严格单向依赖关系。 列出「禁止依赖」表：哪个模块绝不能调用哪个模块。
3. 测试门控流水线（Stage Gates）
定义三道关卡，未通过当前关卡禁止进入下一关卡：
Gate 1：单元测试
- 执行命令：[视技术栈填写，如
pytest/go test ./.../cargo test] - 覆盖范围表：模块 | 必须覆盖的测试场景
- 通过标准：全部测试通过 + 无类型逃逸 + 无循环依赖
- Agent 规范：测试失败时修改代码，不允许修改测试来适配代码
Gate 2：集成测试
- 执行命令：[集成测试命令]
- Mock 策略：说明哪些依赖用内存/stub替代，哪些必须用真实实现
- 必须覆盖的端到端场景（至少包含：正常流程 + 并发冲突 + 原子回滚）
- Agent 规范：每个测试用例使用独立隔离的存储实例，互不干扰
Gate 3：人类审批
- 触发条件：Gate 1 + Gate 2 全部通过，且 Agent 认为当前 Milestone 完成
- Agent 必须输出的状态报告模板：
## Milestone [X] 完成报告 ### 变更摘要 - 新增文件： - 修改文件： ### 依赖关系验证 - [ ] 无循环依赖 - [ ] 依赖方向与 CODEBASE_MAP 一致 - [ ] 无禁止引用 ### 测试覆盖 - 单元测试：X 个，全部通过 - 集成测试：X 个，全部通过 ### 已知限制 ### 下一步 - 铁律：未获人类
/approve，Agent 禁止进入下一个 Milestone
4. 核心接口契约
这些是「契约」——实现必须严格遵守，Agent 不允许自行修改签名。 用项目所用语言的惯用方式表达（TypeScript interface / Python Protocol + dataclass / Go interface / Protobuf / OpenAPI Schema 等）。
每个接口必须包含：
4.1 公共类型
- 所有跨模块共享的 ID 类型、枚举、请求头、统一响应结构
- 错误码必须穷举，不允许有「其他错误」的模糊出口
4.2 数据写入接口
- 幂等键的命名空间（哪几个字段组合唯一）及重复请求的返回语义
- 乐观锁机制（version / etag / timestamp，视设计而定）
- 并发写保护机制（fencing token / sequence number 等）
4.3 数据读取接口
- 游标语义（游标不存在时的行为、游标为空时的行为）
- 结果排序保证
4.4 并发控制接口（如适用）
- 获取 / 续约 / 释放的完整语义
- 租约边界值（最小、默认、最大时长）
- 续约语义（避免续约后剩余时间反而变短的边界情况）
- 重入语义（已持有时再次获取的行为）
- 错误码拆分（被他人持有 / 已过期 / token 不匹配，分开定义）
4.5 跨域原子操作接口（如适用）
- 事务边界：明确哪几步必须在同一事务内完成
- 申请顺序：如何防止死锁（如按固定顺序申请）
- 失败语义：任一步骤失败时的回滚范围和副作用
4.6 状态投影 / 派生视图接口（如适用）
- 全量重建 vs 增量更新的接口定义
- version 单调性保证
4.7 存储层 Schema
- 所有必要的建表语句（SQL DDL / schema 定义 / migration 脚本）
- 所有必要的索引及其用途说明
- append-only 或不可变约束的实现方式
对于每个关键方法，写出「完整执行流程」：
- 编号步骤
- 每一步失败时的错误码和返回值（不允许用「返回错误」代替具体错误码）
- 哪几步必须在同一事务内（精确到步骤编号）
5. Milestone 分解
表格：任务 | 验收标准 | 最少测试数量（写具体数字，不写「足够多」） 每个 Milestone 末尾写明「Gate 3 交付物」一句话描述。
6. Agent 行为军规
必须做（编号列表）：
- 每条规则必须是可验证的（能判断 pass/fail）
- 包含：读文档顺序、写代码后立即运行测试、类型约束要求等
绝对禁止（❌ 开头，无例外，无商量余地）：
- 引入被隔离目录的代码
- 在本阶段调用范围外的外部服务
- 修改测试来适配代码
- 跳过测试（no skip / no only）
- 未获
/approve进入下一 Milestone - 使用 sleep / 定时轮询做并发控制（用存储层事务和锁机制代替）
- 添加本阶段范围外的功能
写作风格要求
- 每条规则必须是可验证的，不写「尽量」「尽可能」「合理」
- 执行流程必须完整枚举：每步失败时的行为都要显式写出
- 错误码必须穷举
- 并发相关约束必须精确到「哪几步在同一事务内」
- 幂等性约束必须写明命名空间（哪几个字段组合唯一）
- 接口契约用项目实际使用的语言表达，不强制用某种语言
禁止
- 禁止写「可选」的测试——测试要么必须有，要么删掉这条
- 禁止在契约接口里写「TODO」或「待定」
- 禁止只列接口名不列完整字段定义
- 禁止把白皮书的愿景描述当作验收标准——验收标准必须可测量
- 禁止绑定与项目技术栈无关的工具或框架