Skip to content

spec-driven-development.md

Latest commit

 

History

History
209 lines (154 loc) · 8.27 KB

spec-driven-development.md

File metadata and controls

209 lines (154 loc) · 8.27 KB
Raw

WaveEngine Spec-Driven Development

SDD 先定义“改变什么、保持什么、怎样证明完成”，再修改生产代码。Spec 是跨 session 的持久契约，不是大而全的设计报告。

1. 文档职责与事实层级

源码、CMakeLists.txt、AGENTS.md、当前验证
    ↓ 约束现状
Accepted / Implementing Spec
    ↓ 驱动
代码、测试、迁移
    ↓ 留证
Verified Spec Evidence
  • README.md：项目入口和已实现能力摘要。
  • AGENTS.md：编码代理规则和高风险工程契约。
  • docs/architecture/：跨领域长期设计不变量；不代表已经实现。
  • docs/plans/：方向、依赖和未来里程碑，不代表已实现。
  • docs/specs/：一次具体变更的目标、边界和验收。
  • docs/references/：原始设计输入和校验快照；不具有规范优先级。
  • Spec 与源码冲突时必须先查明是实现偏离还是 Spec 过时，不能选择性忽略。

2. 何时使用

Full SDD

以下任一情况必须创建或复用正式 Spec：

  • 新用户/游戏功能，公共 C++/HLSL/API 或 target 边界。
  • 跨核心模块架构、线程、任务、所有权或启动/关闭顺序。
  • RHI、RenderGraph、Renderer Pass、Shader schema 或 GPU 生命周期。
  • Scene、WEMesh、Asset、配置、MCP、Trace、SaveGame 等格式/协议。
  • 坐标、Transform、Rotator、相机 basis 或资产规范化。
  • 引入/升级第三方依赖。
  • 多提交变更，或失败可导致数据破坏、GPU use-after-free、协议不兼容。

没有 Accepted Spec 时只能调研、测量、原型和完善 Draft，不得开始生产实现。

SDD-Lite

局部 bug fix、无语义机械重构、构建/警告修复和纯诊断增强可不建文件，但修改前必须写明：

  1. 当前问题或目标。
  2. 必须保持的不变量。
  3. 最小验证。

一旦触及 Full SDD 边界立即升级为正式 Spec。

无需 Spec

只读解释/审查、状态报告、不改变约束的文档修正，以及用户明确要求的 Git 操作通常无需 Spec。

3. 生命周期

状态 含义 允许工作
Draft 调研或等待审查 调研、原型、更新 Spec；禁止生产实现
Accepted 用户已明确接受契约 实施准备
Implementing 正在修改生产代码 实现、测试、分片验证和交接
Verified 当前实现已通过全部必需验收 维护与后续 Spec
Superseded 已被其他 Spec 替代 仅保留历史 
Draft --用户明确接受--> Accepted --开始生产修改--> Implementing --当前实现验收留证--> Verified
Accepted / Implementing --实质契约变化--> Draft
Draft / Accepted / Implementing --被替代--> Superseded

门禁：

  • 代理不能推断用户接受；Accepted by/on 只能在明确确认后填写。
  • 第一次生产修改前进入 Implementing。
  • 目标、非目标、外部行为、不变量、格式或迁移实质变化时先更新 Spec，必要时退回 Draft。
  • 未运行验证必须记为未运行；历史结果不能把 Spec 变成 Verified。
  • Superseded 必须链接替代 Spec并说明剩余工作归属。

4. 新 session 协议

  1. 运行 git status --short。
  2. 读取根 AGENTS.md、AI-Native Engine Architecture 和 Spec 注册表。
  3. 搜索全部具体 Spec 状态：
rg -n "^- Status: (Draft|Accepted|Implementing|Verified|Superseded)$" docs/specs --glob "!_template.md"
  1. 用用户请求识别 Spec ID，完整读取匹配 Spec、直接依赖和相关源码。
  2. 对照源码、CMakeLists.txt 与当前状态检查 Spec 是否过时。
  3. 在 commentary 报告 Spec ID、状态和本次允许范围。
  4. 按状态行动：
    • 无 Spec：创建 Draft。
    • Draft：只完善/审查。
    • Accepted：建立计划后进入 Implementing。
    • Implementing：从 Current Progress/Next Step 恢复。
    • Verified：新需求通常建立后继 Spec。

仓库内 Spec 和 Git 状态是跨 session 真值，不能依赖旧聊天记忆。

5. Spec 内容

文件名：

docs/specs/YYYY-MM-DD-<spec-id>-<short-name>.md

顶部元数据必须包含：Spec ID、Status、Created、Updated、Roadmap、Architecture、Depends on、Owners、Accepted by/on、Supersedes、Superseded by。

正文统一为十节：

  1. Context：摘要、当前事实、问题和源码证据。
  2. Goals and Non-Goals。
  3. Scenarios：主路径、失败和关闭。
  4. Constraints and Invariants；包含 AI-Native Impact。
  5. Design。
  6. Alternatives。
  7. Delivery Slices。
  8. Verification and Acceptance。
  9. Compatibility, Risks, and Open Questions。
  10. Implementation Record。

规则：

  • Spec ID 唯一并优先复用路线图 Issue；文件日期不随更新重命名。
  • Draft 先写可观察行为、不变量、失败/迁移和验收，再选择设计。
  • 每个 Full SDD Spec 必须逐项判断 Identity、Schema、Query、Effect、Determinism、Validation/Evidence、Provenance/Migration、Security/Budget 和 Headless。
  • AI-Native Impact 使用 Required、N/A 或 Deferred；N/A 写明原因，Deferred 引用后继 Issue/Spec，所有 Required 项进入验收与验证。
  • Schema 决策包含兼容版本；Query 决策包含 snapshot/diff/change feed、revision/freshness 和 resync；Effect 决策说明 target scope 与真实 undo/cancel/compensation 边界。
  • 涉及 Human/Agent 并发写时明确 base/expected revision、workspace/staging 和 conflict，不采用 silent last-writer-wins。
  • 至少记录一个未采用方案及原因。
  • Delivery Slice 必须能独立验证并保持仓库可运行。
  • Accepted 前关闭所有会改变契约的 Open Questions。
  • 注册表必须同步，但 Spec 文件自身状态是最终真值。

6. 接受与实施

用户明确接受后：

  • 更新为 Accepted，填写 Accepted by/on，同步注册表。
  • 开始生产修改前从 Delivery Slices 建立计划并改为 Implementing。

实施时：

  • 一次改变一个可陈述不变量，优先建立能失败的测试或基线。
  • 新旧路径并存时写清切换、兼容和移除条件。
  • 格式、cache key、共享 C++/HLSL 布局或协议的版本与迁移同批落地。
  • 实现与 Spec 冲突时暂停代码，先更新并重新审查 Spec。
  • 不顺带实现 Non-Goals。
  • 每个 Slice 后更新进度、偏差和证据。

7. 验证与完成

Spec 文档契约：

py -3 Tests/spec_contracts.py .
ctest --test-dir Build -C Debug -R SpecContracts --output-on-failure

功能验证按范围选择 CPU、Debug/Release、CTest、MCP/WEMesh、WAVE_RG_STRICT=1、raster、DXR、Editor/PIE、failure injection、package smoke 和 performance baseline。

Evidence 记录：

字段 内容
Date 实际日期
Commit 精确提交或明确 working tree
Environment 配置、GPU/driver、环境变量
Command/Steps 实际命令或手工步骤
Result Pass/Fail/Not Run
Artifacts 日志、trace、截图、dump 或报告

Verified 门禁：

  • Acceptance Criteria 全部勾选。
  • 所有必需验证已在当前实现执行；未运行项不是完成前置且写明原因。
  • 本次日志无新增 Error、Fatal 或 D3D12 validation。
  • 实际实现偏差、Evidence、注册表和路线图状态已同步。

8. 跨 session 交接

停止 Implementing 工作前更新：

  • Current Progress：已完成且验证的 Slice。
  • Next Step：下一次 session 的单一首要动作。
  • Changes and Deviations：文件、关键决策和偏差。
  • Evidence：本次验证与未验证项。
  • Remaining Work：剩余 Slice/验收项。
  • Git 状态：未提交修改及归属。

9. 提交与流程维护

建议把 Draft、接受记录、实现 Slice 和最终验证拆成可审查提交；实现提交引用 Spec ID。实现完成不授权自动 push。

修改本流程时同步更新：

  • AGENTS.md 的简明门禁。
  • docs/architecture/ai-native-engine.md 的影响维度。
  • docs/specs/_template.md。
  • Tests/spec_contracts.py。

不能通过放宽状态含义把未验证实现标记为完成。