你会接触到的几个关键概念
用 Aiko IDE 之前先认 8 个词，省得文档里到处看不懂
Aiko IDE 把研发的每一步都规范化了，所以你会反复看到几个词。一页讲清，遇到时不用现查。
1. change（OpenSpec change）
你提的每一次开发任务都叫一个 change。
新功能、修 bug、小调整，统一在 openspec/changes/<change-name>/ 下管理：proposal.md（为什么做）、design.md（怎么做）、tasks.md（业务任务清单）、specs/（行为规格 delta）。一个 change = 一组要一起验证、一起归档的规格 + 代码。
2. 工作流预设（workflow）
改一行配置和做一个完整新能力不该走同一套流程。
每个 change 起手时选一种预设，预设决定要多少设计、多少决策点：
| 预设 | 设计落点 | 适用 |
|---|---|---|
| full | Superpowers Design Doc + plan，五字段全决策 | 复杂功能、架构决策 |
| spec | OpenSpec design.md（可选详细设计），TDD/审查可选 | 需求清晰的中型功能 |
| hotfix | 精简 design.md，直接构建轻量验证 | 行为修复 |
| tweak | 最轻路径 | 小调整 |
对比细节见 四种工作流怎么选。
3. 产物（artifacts）
每个阶段写什么，门禁就查什么。
- open：proposal.md / design.md / tasks.md / specs/（tasks 只写业务任务，实现细节进 design.md）
- design（仅 full）：Superpowers Design Doc（
docs/superpowers/specs/）+ plan（docs/superpowers/plans/）+ brainstorm 检查点（.aiko/handoff/brainstorm-summary.md） - build：源码 + tasks.md 逐项勾选
- verify：
.aiko/verify-report.md - archive：change 目录移入
openspec/changes/archive/，delta spec 合并进主 spec
4. .aiko.yaml
change 的唯一权威状态文件，就放在 change 目录里：workflow、phase、requirement（需求归属）、design_doc/plan、build/tdd/review/verify 各模式字段。
- 写入只走
aiko-state.sh（init/set/transition），每次写入后过 schema 校验，坏文件当场失败 - 面板严格镜像它，不做文件存在性推断
5. phase-guard（写门禁）
"现在这个阶段能写什么文件"由 phase-guard 说了算。
按 .aiko.yaml 的 phase: 执行白名单：open/design 只许写规格产物，build 起才放行源码（full 要五字段决策齐备），archive 封笔。Claude / Codex / opencode 三种宿主共享同一套判定；vibe（自由编程）会话全阶段放行。
6. 五阶段（lifecycle）
open（需求）→ design（设计）→ build（构建）→ verify（验证）→ archive（归档）spec/hotfix/tweak 跳过 design 阶段（open→build→verify→archive）。aiko-guard.sh <change> <phase> --apply 推进，每步都有校验。
7. SDD 面板
IDE 侧的结构化进度视图：需求列表（Studio 文档分组 + chat 组）、阶段条、步骤进度（设计 2/2、任务 N/M、验证归档 2/2）、活动日志。面板只读 .aiko.yaml 和 change 目录。
8. 两层验证
- 确定性 e2e（
test/manual/sdd-e2e/run-all.sh）：无 LLM，驱动真实门禁/状态机/面板推导，跑全工作流×模式矩阵 - 真实 e2e（
sddRealSdk.integrationTest.ts）：真模型走完各流程，手动开启