在架构 sidebar 写 ADR

如果你是架构师，架构 sidebar 是你的主战场。只在 m / l / tech 档的 change 上才会用到（s / xs 档没架构包）。

你要起草的 3 件文档

文档	你写什么	不要碰
`architecture.md`	系统级边界、模块划分、共享机制	capability 内部实现（开发自己写 design.md）
`adr.md`	关键决策 + 取舍理由（含模型品牌选型）	普通工程任务
`quality-attributes.md`	PD 的 NFR 用哪些架构策略保障	重新定义目标值

不同档位你写多少

档位	architecture	adr	quality-attributes
xs / s	⛔ 跳过	⛔ 跳过	⛔ 跳过
tech	✅ 必填	✅ 必填	⚪ 可选
m / l	✅ 必填	✅ 必填	✅ 必填

architecture.md：画系统级边界

只写系统级：模块、外部依赖、跨模块通信。不写 capability 内部实现。

例子：

PlantUML / Mermaid 图块在 IDE 内实时渲染。

adr.md：每条决策记录一次

每条 ADR 记录一个关键决策。模板：

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

注意：adr 不被 PD 引用（PD 不关心技术选型），只被下游 architecture / design / tasks 引用。

quality-attributes.md：NFR 怎么靠架构保

PD 的 nfr.md 定目标值（"p99 latency < 100ms"），你在 quality-attributes.md 写怎么用架构策略保住。

- id: QA-PERF-001
  satisfies: REQ-NFR-PERF-003
  strategy: |
    - Pricing Engine 走 read replica,避免主库锁竞争
    - 折扣规则 Redis 缓存 5min,失效后异步刷新
    - 热点商品规则预编译到 JVM 常量池
  measurable_via: TC-PERF-007

nfr-acceptance-coverage Validator 守门：nfr 引用的 ACC 必须存在；QA 引用的 NFR 必须存在。

起草技巧：让 AI 推架构包

PD 包就绪后，调 /aiko-pd-to-arch <feature>：

> /aiko-pd-to-arch add-coupon-discount

读取 add-coupon-discount-pd/requirements.md + nfr.md
✓ architecture.md   (6 条 ARCH-* 模块划分图)
✓ adr.md            (3 条 ADR-* 决策骨架,待人评审)
✓ quality-attributes.md (覆盖 nfr.md 全部 REQ-NFR-*)

AI 起完骨架，你审 / 调 / 决策细节。

与上下游的关系

PD 包 (REQ-FN-*, REQ-NFR-*)
   ↓ 引用
你写的架构包 (ARCH-*, ADR-*, QA-*)
   ↓ 引用
开发包 (specs/, design.md, tasks.md)
   ↓ 引用
测试包 (test-cases 引用 QA-* 和 ACC-*)

写完之后

./scripts/aiko-validate.sh

架构包跑通后，开发可以拉 feature/* 分支了。