你会接触到的几个关键概念
用 Aiko Studio IDE 之前先认 8 个词，省得文档里到处看不懂
Aiko Studio IDE 把研发的每一步都规范化了，所以你会反复看到几个词。一页讲清，遇到时不用现查。
1. change
你提的每一次变更都叫一个 change。
无论是新功能、修 bug、重构，统一在 openspec/changes/<change-name>/ 下管理。一个 change = 一组要一起 merge 的制品 + 代码。
你会在 IDE 里看到：
- Workbench 全景树按 change 分组
- Aiko Chat 在某个 change 的 worktree 里跑
- CI 按 change 跑 validate
2. SDD 面板变更类型
改一行日志和做一个完整新能力不该走同一套流程。
每个 change 起手时要在 SDD 面板里选择一种类型，类型决定要生成哪些设计、任务和证据：
| 类型 | 适用 | SDD 面板会组织什么 |
|---|---|---|
| 新功能 | 从 Studio 需求文档启动一条标准开发链路 | 开发任务、测试材料、必要设计与 evidence |
| hotfix | 线上缺陷或紧急修复 | 复现、最小修复任务、验证步骤、发布证据 |
| 日志与小调整 | 低风险文案、日志、配置、小 UI 调整 | 轻量任务清单、变更说明、自测证据 |
| full 完整流程 | 复杂需求、跨模块能力、需要评审的方案 | 设计、详细设计、开发任务、测试与归档证据 |
不会选？看 Workbench / SDD 面板怎么用。
3. 任务、设计与证据
SDD 面板不是自由聊天框，而是把一次变更拆成可追踪的任务、设计和证据。
| 材料 | 写什么 | 什么时候出现 |
|---|---|---|
| 需求输入 | Studio 已确认的 BRD / PRD、验收标准、资源引用 | 所有类型 |
| 设计 | 方案边界、关键决策、接口和数据影响 | 新功能、full |
| 详细设计 | 模块拆解、实现步骤、边界条件、回滚策略 | full 完整流程 |
| 开发任务 | 可执行 task、关联文件、完成条件 | 所有类型 |
| 测试证据 | 测试用例、执行结果、发布证据 | 所有类型 |
具体结构见 SDD 制品矩阵。
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 总览