Skip to content

spec-driven-development.md

Latest commit

 

History

History
155 lines (108 loc) · 8.46 KB

spec-driven-development.md

File metadata and controls

155 lines (108 loc) · 8.46 KB
Raw

WaveEngine Continuous Spec-Driven Development

SDD 先记录“改变什么、保持什么、怎样证明完成”，随后在同一工作流连续修改生产代码。Spec 是跨 session 的活工作基线，不是授权书；任何状态都不能成为等待人工接受的理由。

1. 文档职责与事实层级

源码、CMakeLists.txt、AGENTS.md、当前验证
    ↓ 约束现状
活跃 Spec 的目标、不变量与假设
    ↓ 持续同步
代码、测试、迁移
    ↓ 留证
Verified Spec Evidence
  • README.md：项目入口和已实现能力摘要。
  • AGENTS.md：编码代理规则和高风险工程契约。
  • docs/architecture/：跨领域长期设计不变量；不代表已经实现。
  • docs/plans/：方向、依赖和未来里程碑；依赖用于安排顺序，不是人工停车点。
  • docs/specs/：一次具体变更的目标、边界、当前进度和完成证据。
  • docs/references/：原始设计输入和校验快照；不具有规范优先级。

Spec 与源码冲突时先查明事实，原位更新 Spec、实现或两者并记录偏差，然后继续。不能选择性忽略，也不能把状态回退当作等待用户的理由。

2. 何时使用

Full SDD

新用户/游戏功能、公共 API/target、跨模块架构、线程/GPU 生命周期、RHI/RenderGraph/Shader、磁盘/协议格式、坐标契约、第三方依赖和多提交高风险变更使用正式 Spec。

没有匹配 Spec 时，在当前 session 创建 Draft，至少记录可观察结果、Non-Goals、关键不变量、失败边界、最小验证和保守假设。内容足以约束首个 Slice 后立即改为 Implementing并继续生产实现，不请求人工接受。

SDD-Lite

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

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

触及 Full SDD 边界时直接建立或复用 Spec，并在同一工作流继续。

无需 Spec

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

3. 生命周期是记录，不是许可

状态 含义 连续动作
Draft 契约仍在形成 补齐受影响契约，记录保守假设，自动进入 Implementing
Accepted 历史或可选人工审查记录 不提供额外权限；开始/继续实现时进入 Implementing
Implementing 设计、生产代码、测试或修复正在推进 按 Slice 连续实现、验证、修复和留证
Verified 当前实现已通过全部必需完成条件 维护；新变化可直接更新为 Implementing并继续
Superseded 已被其他 Spec 替代 只保留历史，剩余工作转到替代 Spec 
Draft ──契约足以约束首个 Slice──→ Implementing ──当前证据完成──→ Verified
Accepted ──历史兼容/开始实现──→ Implementing
Verified ──新实质变化──→ Implementing
Draft / Accepted / Implementing ──被替代──→ Superseded

连续规则：

  • 用户接受不是状态迁移或生产实现的前置条件；Accepted by/on 只保存可选历史 provenance。
  • 第一次生产修改与 Implementing 状态更新放在同一工作流，不拆成等待回合。
  • 实质契约变化原位更新 Spec、假设、测试和迁移；不退回等待重新接受。
  • 未关闭问题不阻止不受影响的 Slice。受影响 Slice 优先依据源码、Architecture、既有契约和最保守可逆方案收口，并记录决定。
  • 依赖未就绪时实现依赖或独立 Slice；不向用户请求状态批准。
  • 验证失败后继续定位、修复和重跑。环境暂不可用则记录 Not Run并推进其他安全工作。
  • 只有缺少新的外部权限、需要不可逆/破坏性动作、具体 push/发布，或不存在安全保守解且选择会实质改变目标时才停下来询问。

4. 新 session 协议

  1. 运行 git status --short，保护用户修改。
  2. 读取根 AGENTS.md、AI-Native Engine Architecture 和 Spec 注册表。
  3. 搜索全部具体 Spec 状态：
rg --threads 1 -n "^- Status: (Draft|Accepted|Implementing|Verified|Superseded)$" docs/specs --glob "!_template.md"
  1. 完整读取匹配 Spec、直接依赖和相关源码，检查是否过时。
  2. 在 commentary 报告 Spec ID、状态、AI-Native Impact、假设和首个 Slice。
  3. 立即行动：无 Spec 则创建；Draft则补齐并自动推进；Accepted/Implementing从记录恢复；Verified有新变化则转Implementing。

仓库内 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。

正文统一为十节：Context；Goals and Non-Goals；Scenarios；Constraints and Invariants（含 AI-Native Impact）；Design；Alternatives；Delivery Slices；Verification and Acceptance；Compatibility/Risks/Open Questions；Implementation Record。

规则：

  • 先写可观察行为、不变量、失败/迁移和验证，再选择设计；允许在后续 Slice 中继续细化。
  • 每个 Full SDD Spec 逐项判断 Identity、Schema、Query、Effect、Determinism、Validation/Evidence、Provenance/Migration、Security/Budget 和 Headless。
  • Required 项必须设计自动 validator 和 Evidence；N/A解释原因；Deferred引用后继 Issue/Spec。
  • Schema、Query、Effect、并发 revision、workspace/staging/conflict 和预算边界必须显式。
  • 至少记录一个未采用方案及原因。
  • Delivery Slice 可独立验证并尽量保持仓库可运行；临时兼容路径写明移除条件。
  • Open Questions 记录假设和影响范围；只在标记 Verified 前要求全部收口。
  • 注册表同步状态，但状态不控制生产修改权限。

6. 连续实施

  • 一次改变一个可陈述不变量，优先建立能失败的测试或基线。
  • 新旧路径并存时写清切换、兼容和移除条件。
  • 格式、cache key、共享 C++/HLSL 布局或协议的版本与迁移同批落地。
  • 实现与 Spec 冲突时先更新契约和测试，再继续修复代码；不等待重新审查。
  • 不顺带实现 Non-Goals。
  • 每个 Slice 后更新 Current Progress、Next Step、Changes and Deviations、Evidence 与 Remaining Work。
  • 一个可陈述且已验证的本地 Slice 可自动创建 checkpoint commit；push、远端写入和发布仍需执行前的明确授权。

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、Command/Steps、Result 和 Artifacts。历史结果不能替代当前结果；未运行写 Not Run。

Verified 完成条件：

  • Acceptance Criteria 全部勾选，Open Questions 已收口。
  • 所有必需验证已在当前实现执行；环境不适用项明确说明。
  • 本次日志无新增 Error、Fatal 或 D3D12 validation。
  • 实际实现偏差、Evidence、注册表和路线图状态已同步。

未满足时保持 Implementing并继续修复，不能伪标完成；这不阻止后续安全工作。

8. 跨 session 交接

任何未完成工作在 session 结束前更新：Current Progress、单一 Next Step、Changes and Deviations、Evidence、Remaining Work，以及未提交 Git 状态与归属。下一 session 直接从该记录继续，不重新请求接受。

9. 流程维护

修改本流程时同步更新 AGENTS.md、文档地图/根 README、Architecture 中的权限边界、路线图、Spec 注册表与模板、Tests/spec_contracts.py。

取消人工等待不等于降低完成标准：工程不变量、输入校验、生命周期、原子性、兼容和当前 Evidence 继续强制；只有本地开发流程保持连续。