SDD — 基于 Speckit 的规格驱动开发

English: sdd.md

Coffer 用 Speckit 做规格驱动开发。凡是改动对外可见行为的 PR，必须先更新对应的 spec.md，再改代码。

目录结构

所有 spec 平铺在 specs/<NNN>-<short-name>/ 下，NNN 是三位补零的序号（001、002……）。spec 只有一种类型——不分 foundation / capability / quality。

跨切面机制（audit、credentials、events、jobs、storage、session）抽出为共享模块，而不是各自的独立 spec；「只在第二个 feature 也需要它时才抽取」这条规则是 .specify/memory/constitution.md 中的不变量 (invariant)。

specs/<NNN>-<short-name>/
  spec.md              # User-visible contract. Generated by /speckit-specify.
                       # Includes "## Acceptance Scenarios" section
                       # (Spec Kit convention — scenarios live in spec.md,
                       #  NOT in a separate .feature file).
  plan.md              # Implementation plan. Generated by /speckit-plan.
  tasks.md             # Work breakdown. Generated by /speckit-tasks.
  research.md          # Background, alternatives. /speckit-plan Phase 0.
  data-model.md        # Entities, fields, relationships. /speckit-plan Phase 1.
  contracts/
    api.openapi.yaml   # Wire contract (hand-authored, PR-reviewed).
    events.json        # Event schemas (when applicable).
    tools.json         # MCP tool schemas (when applicable).
  quickstart.md        # How to use this feature. /speckit-plan Phase 1.
  checklists/
    review.md          # Generated by /speckit-checklist.
    release.md

一个行为对应一个 spec，而不是一层对应一个 spec。 一个 spec 覆盖完整的垂直切片——后端服务，以及交付该用户可见行为所需的任何 surface（CLI、MCP / shim、REST）。不要把同一个行为按 surface 拆成多个 spec，那只会让一份契约的两半之间漂移。

骨架优先阶段：新建 spec 时先写 spec.md。其他文件（plan.md、tasks.md、contracts/ 等）在 spec 进入实现阶段时，通过 /speckit-plan 和 /speckit-tasks 补齐。

让文档与代码保持同步

当改动会改变行为时，要在同一个 PR 里更新 spec 及其所有相关文档——在写代码之前或同时，绝不留作后续补做。spec 优先：spec 是事实来源，代码向它看齐。「相关文档」是整套，而不只是 spec.md：

specs/<NNN>/spec.md（及其 spec.zh.md 对照）——用户可见的契约与验收场景。
specs/<NNN>/contracts/api.openapi.yaml——线上契约；增删/重命名端点与 schema 以匹配代码。
specs/<NNN>/data-model.md、plan.md、quickstart.md（及各自的 .zh.md 对照）——实体、计划与用法说明。
改动触及的跨切面文档：相关的 docs/decisions/ ADR、.specify/memory/architecture.md，以及受影响的 agents/* 约定（如 agents/visual-language.md）。

每个 prose .md 都有 .zh.md 对照，必须在同一个 commit 中一并更新（仅 tasks.md 与 OpenAPI YAML 例外）。验收审计（scripts/audit_acceptance.py，由 make verify 运行）把每个 spec.md 场景名绑定到测试标记，所以重命名/新增/删除场景时，也要同步更新其 @pytest.mark.acceptance(... scenario=...) / acceptance(...) 标记。纯重构、或没有契约影响的纯前端改动无需改 spec——但只要行为、端点、schema 或 IA 变了，文档就要随之改动。

验收场景 (Acceptance Scenarios) —— 写在 `spec.md` 里，Gherkin 风格

在 spec.md 的 ## Acceptance Scenarios 一节内用 Gherkin 风格表达。每个场景对应一个或多个测试（见 testing.md）。

markdown

## Acceptance Scenarios

### Scenario: <verb-led short name>

- **Given** <precondition>
- **When** <action>
- **Then** <observable outcome>
- **And** <additional assertion>

测试通过 acceptance(spec, scenario) 标记覆盖每个场景——见 testing.md 的 "Acceptance Scenarios — Cross-Tier Markers" 一节。

端到端可交付规则

每个功能完成时必须交付一个可用的端到端产品：后端持久化 + 暴露它的 surface（CLI、MCP / coffer-mcp-shim、REST）——全部接通，用户能真正使用该功能。

只有当端到端可交付物真的能用、并且每个验收场景至少有一个覆盖测试时，spec 才算「shipped」。

`spec.md` 的 Markdown 风格

spec.md 写用户可见的契约；建议 ≤ 300 行。
不在 spec.md 中重述架构；引用 .specify/memory/constitution.md。
用平实英语，避免行话。
spec / plan / research / data-model / quickstart 内不写时间标注（Day N、Last updated 之类）。

SDD — 基于 Speckit 的规格驱动开发 ​

目录结构 ​

让文档与代码保持同步 ​

验收场景 (Acceptance Scenarios) —— 写在 spec.md 里，Gherkin 风格 ​