每件文档怎么写、什么时候写

19 件标准制品 —— 每件回答一个问题、有 ID 规范、严禁写什么

每个 change 涉及的文档总共就这 19 件，看你档位决定写哪些（怎么选档）。

每件文档只回答一个问题。 越界写会被 Validator 抓出来，下游也不知道该看你这件还是另一件。

产品 / BA 写的（PD 包 · 10 件）

文档	回答什么	千万别写	ID 长什么样
`vision.md`	为什么做、给谁、范围、什么时候发	功能能力、NFR 数字、AI 模型	`VISION-* / GOAL-* / PERSONA-* / SCOPE-* / MILE-*`
`stories.md`	用户视角的场景与故事	"系统 SHALL/MUST" 这种系统视角	`SCEN-* / STORY-*`
`requirements.md`	系统应做哪些功能	完整 EARS / 表名 / API 字段	`REQ-FN-* / REQ-ALG-* / REQ-SEC-* / REQ-DOC-*`
`nfr.md`	系统属性的目标值是多少	功能行为、实现策略	`REQ-NFR-PERF/AVAIL/SEC/OBS/COMPAT/I18N/A11Y-*`
`acceptance.md`	怎样算达标	需求叙述、测试执行步骤、实现方案	`ACC-*`
`product-design.md`	产品层设计约束（原型 / IA / 交互）	表结构、API 字段、视觉规范	`DESIGN-* / IA-* / INTERACT-* / INTEG-* / CONSTR-*`
`risks.md`	产品视角的风险与假设	工程实施细节	`ASSUM-* / DEP-* / RISK-*`
`rollout.md`	怎么发布、监控、回滚、客服	工程部署细节、代码级监控	`ROLL-* / METRIC-* / ALERT-* / SOP-*`
`glossary.md`	术语是什么意思	mermaid 图（归 architecture）	`GLOSS-*`
`ai-spec.md`	为什么用 AI、怎么用、怎么评、怎么兜底	具体模型品牌、Prompt 话术	`AI-FRAME-* / MODEL-* / DATA-* / EVAL-* / GUARD-*`

起草技巧：在 Aiko Chat 里调 /aiko-pd-package <feature>-pd 让 AI 按你的 vision 一口气起 10 件骨架，你只改不写。

架构师写的（架构包 · 3 件）

文档	回答什么	千万别写	ID
`architecture.md`	系统级边界与共享机制	capability 内部实现（归 `design.md`）	`ARCH-*`
`adr.md`	关键决策被选择、为什么（含模型品牌选型）	业务规则、普通任务	`ADR-*`
`quality-attributes.md`	NFR 通过哪些架构策略保障	重新定义目标值	`QA-PERF-* / QA-AVAIL-* / QA-SEC-* / QA-OBS-* / QA-COMPAT-*`

起草技巧：调 /aiko-pd-to-arch <feature> 从 PD 包推架构骨架。

adr.md 每条决策建议这样写：

- id: ADR-007
  title: 折扣引擎选用 Rete 算法
  status: accepted
  date: 2026-05-20
  context: |
    需要支持 1000+ 条优惠券规则,实时计算延迟 < 50ms
  decision: |
    采用 Rete 算法的开源实现 Drools
  consequences:
    - 学习曲线高,但社区成熟
    - JVM 内存占用增加 ~200MB
  alternatives:
    - 自研规则引擎: 排除 (开发成本高)
    - SQL CASE: 排除 (规则爆炸)

开发写的（开发包 · 4 件）

文档	回答什么	千万别写	ID
`proposal.md`	这次工程 change 启动原因	PD 需求事实（只引 ID）	change id
`specs/*/.md`	capability 对外行为契约（EARS + Gherkin）	业务背景、架构选型	OpenSpec Requirement / Scenario
`design.md`	capability 内部怎么实现	系统级架构、需求目标	章节标题 + trace
`tasks.md`	怎么实施、怎么验证	新方案、新需求	checkbox / task id

起草技巧：调 /aiko-pd-to-dev <feature> 自动生成 spec + tasks + aiko.pipeline 骨架。

specs/ 里的 capability 这样写：

## Requirement: 折扣计算引擎 [satisfies: REQ-FN-007]

When a 购物车包含可叠加优惠券, the system shall 按优先级矩阵计算
最终折扣金额, returning 折扣后的订单总价.

### Scenario: 单张满减券生效
  Given 购物车总价 200 元
  And 用户持有"满 100 减 20"券
  When 用户选中该券
  Then 订单总价显示 180 元

tasks.md 必须按 pipeline 五段分节（看推进开发任务）。

QA 写的（测试包 · 2 件）

文档	回答什么	千万别写	ID
`test-cases.md`	怎么测	验收标准重述、实测结果	`TC-*`
`test-evidence.md`	实际跑了什么、结果如何	用例步骤重述、标准改写	`EV-*`

起草技巧：调 /aiko-pd-to-test <feature> 从 acceptance 自动生成 test-cases 骨架，AI 会把每条 ACC-* 拆成 1+ 条 TC-*。

评审记录（通用 · 1 件）

文档	干什么
`review-log.md`	评审记录 / 升降档决策 / SKIPPED-CONDITIONAL 留痕

主要给评审者用，开发不用主动写，但升降档时记得加一条。

文档之间是怎么引用的

实线 = 强引用（下游 ID 必须存在）；虚线 = 弱引用。

改了上游 ID，所有引用它的下游都会被 trace Validator 抓出来，IDE 会高亮。

字段是什么类型？entity schema

每件文档的字段类型 / 是否必填 / 枚举值都由 openspec/schemas/<lane>/entities/<artifact>.yaml 决定。比如 acceptance 的 schema：

entity: acceptance
fields:
  - name: id
    type: string
    pattern: "^ACC-\\d{3,}$"
    tier: core
    required: true
  - name: satisfies
    type: array
    items: { type: string, pattern: "^REQ-FN-\\d+$" }
    tier: core
    required: true
  - name: given/when/then
    type: string
    tier: extended    # m 档以上才必填
  - name: examples
    type: array
    tier: full        # 仅 l 档必填

tier 三档随你的 change scale 联动：

xs / s → 只必填 core
m → core + extended 必填
l → 全集

字段格式不对会被 entity-schema Validator 抓出来。

关联

怎么选档 — 决定写哪几件
为什么不要复制粘贴 — 那个"千万别写"列的逻辑
校验报错了怎么办

每件文档怎么写、什么时候写

On this page