你会接触到的几个关键概念
用 Aiko IDE 之前先认 8 个词，省得文档里到处看不懂
Aiko IDE 把研发的每一步都规范化了，所以你会反复看到几个词。一页讲清，遇到时不用现查。
1. change
你提的每一次变更都叫一个 change。
无论是新功能、修 bug、重构，统一在 openspec/changes/<change-name>/ 下管理。一个 change = 一组要一起 merge 的制品 + 代码。
你会在 IDE 里看到：
- Workbench 全景树按 change 分组
- Aiko Chat 在某个 change 的 worktree 里跑
- CI 按 change 跑 validate
2. change 档位（5 档：xs / s / tech / m / l）
改一行文案和改全公司架构不该走同一套流程。
每个 change 起手时要选一个档位，档位决定要写哪些文档、走哪些门禁：
| 档位 | 适用 | 你需要写 |
|---|---|---|
| xs | 1 天内的小改 | 简单 dev 包 |
| s（默认） | 单功能小改 | PD + Dev + Test |
| tech | 重构 / 引擎升级 | 架构 + Dev |
| m | 跨模块 / 调 NFR | 全套 |
| l | 跨业务线 / 战略级 | 全套 + 全员评审 |
不会选？看 怎么给你的 change 选档。
3. 四角色 × 19 标准制品
每个角色有固定的"主笔文档"，别越界写。
| 角色 | 主笔文档 | 写什么 |
|---|---|---|
| PD（产品/BA） | 10 件 | 业务价值、用户场景、验收标准 |
| 架构师 | 3 件 | 系统边界、关键决策、NFR 实现策略 |
| 开发 | 4 件 | capability 行为契约、内部实现、任务清单 |
| 测试 | 2 件 | 测试用例、测试证据 |
具体文档怎么写见 每件文档怎么写。
4. SSoT（一处定义，别复制粘贴）
同一条事实只能在一个文档里写。 其他文档只通过 ID 引用：
- 功能需求只写在
requirements.md→ 用REQ-FN-007这种 ID - 验收标准只写在
acceptance.md→ 用ACC-012 - 架构决策只写在
adr.md→ 用ADR-003
下游文档（test / spec / design）想引用，直接写 ID，不要把段落复制一份。
为什么要这样做？看 为什么不要复制粘贴。
5. group（把相关文档绑在一起）
同一能力的 PD / 架构 / 测试 / 开发四个包，挂同一个 group: 字段。
# .openspec.yaml
group: coupon-discount挂上后，add-coupon-discount-pd / add-coupon-discount-arch / add-coupon-discount-test / add-coupon-discount 四包会一起 resolve、一起 ready、一起 archive。
任何一包没就绪，整个 group 不能归档。
6. aiko.pipeline（开发节点链）
开发包按"流水线"推进，AI 不能跳步。
DoR → §1 impl → §2 tdd → §3 e2e_gen → §4 e2e_run → §5 evidence → ready每一步对应 tasks.md 的一段。只有 advance-node.sh 脚本能推进节点，让 Aiko Chat 替你跑：
./scripts/pipeline/advance-node.sh --change my-change --to impl不熟悉？看 怎么推进开发任务到 ready。
7. L1-L4 测试分层
测试不是一锅跑，分四层在不同时机跑。
| 层 | 你什么时候关心 |
|---|---|
| L1 单测 | 开发本地写代码时（§2 阶段） |
| L2 本 change E2E | 你的 feature 合 develop 之前 |
| L3 集成回归 | 多人合完后 develop / release CI |
| L4 正式发布证据 | release 合 main 前的正式签收 |
如果你的 PR 合不进 develop，多半是 L2 没跑过。
8. Validator（机器化守门员）
14 个 Validator 是自动跑的，违规直接拒提交。
最常遇到的报错：
| 错误 | 啥意思 | 怎么办 |
|---|---|---|
matrix.required_missing | 这个档位要求的文档你没写 | 补上 or 降档 |
trace.broken_ref | 你引用了一个不存在的 ID | 改 ID 或者把那条 ID 补上 |
ssot.duplicate_requirement | 同一条需求写了两遍 | 删一份，另一份用 ID 引 |
pipeline-gate.tasks_mismatch | tasks 勾选状态和 pipeline 节点对不上 | 跑 advance-node 推进，或回退节点 |
具体怎么处理？看 校验报错了怎么办。
9. AI Skill（让 AI 替你起草）
起草文档不用从空白开始，让 AI 替你起骨架，你再改：
| 我想做什么 | 调哪个 Skill |
|---|---|
| 起一个新 change | aiko-new-change |
| 让 AI 起草 PD 10 件 | aiko-pd-package |
| 从 PD 推架构包 | aiko-pd-to-arch |
| 从 PD 推测试包 | aiko-pd-to-test |
| 从 PD 推开发包 | aiko-pd-to-dev |
| 让 AI 真正写代码 | aiko-apply-dev |
| 校验报错自动修 | aiko-validate-and-fix |
在 Aiko Chat 里输入 / 看完整列表，或者打 /aiko- 触发模糊匹配。
接下来
- 先跑通一遍 → 30 分钟快速体验
- 在 IDE 里看到的界面 → Workbench 总览
- 让 AI 真正写代码 → Aiko Chat 总览