docs: 更新 README 和 DEVELOPMENT，补充设计决策说明

DEVELOPMENT.md

@@ -65,6 +65,38 @@ CLI 通过子命令提供帮助和版本信息，不使用 `--help`/`--version`
 - `src/cli/output.ts` — 格式化输出（`错误:`、`用法:`、`提示:` 三段式）
 - `src/cli/help.ts` — 帮助文本生成
 
+## 设计决策
+
+### 阶段与配置
+
+- **四阶段固定**：discuss → plan → build → archive，不可自定义增删
+- **配置覆盖策略**：阶段级别全量覆盖，不支持字段级合并。自定义 plan 时需完整重写所有 documents
+- **配置文件名**：`.rune/config.yaml`，不是 `rune.yml`
+- **模板变量**：仅支持 `{{change-name}}`，不需要其他变量（信息已在上下文中）
+
+### 各阶段行为
+
+- **discuss**：不持久化讨论结果，完全依赖 AI 会话上下文传递；不设强制门控，通过提示词引导
+- **plan**：命令只输出提示词，不写入文件；AI 负责根据提示词生成文档内容并写入。重复调用同一文档的 plan 会追加已有内容用于增量修订。依赖未满足时有友好提示（非报错）
+- **build**：按 task.md 的 checkbox 顺序执行；任务间无结构化依赖；可多次执行直到全部完成
+- **archive**：归档前命令行校验 task 完成状态，未完成时在提示词中注入警告并引导 AI 询问用户
+
+### 变更名校验
+
+变更名仅支持中文、英文、短横线（`-`），不支持空格、下划线等其他符号。
+
+### update 命令
+
+`rune update <tool>` 对比已注入的命令/skill 文件内容与内置版本，不一致则覆盖，不存在则新建。用于升级 Rune 后更新编辑器配置。
+
+### 其他决策
+
+- 无跨变更依赖，变更之间完全独立
+- 无并发锁，同一变更可被多个 agent 同时操作
+- 无需变更废弃命令，手动删除目录即可
+- 同一变更名同天多次归档不处理冲突（日期+名称去重）
+- plan skill 应引导 AI 先通过 `rune status` 获取文档列表
+
 ## 测试策略
 
 ### Level 1 — 纯单元/集成测试（当前）

README.md

@@ -13,28 +13,44 @@ bunx rune init opencode
 ### 初始化
 
 ```bash
-bunx rune init opencode
+bunx rune init opencode          # OpenCode 编辑器
+bunx rune init claude-code       # Claude Code 编辑器
 ```
 
 会在项目中创建：
 - `.rune/` 目录（配置、变更文档、归档）
-- `.opencode/commands/` 和 `.opencode/skills/`（注入的 AI 工具配置）
+- 编辑器对应的 command 和 skill 文件（如 `.opencode/commands/`、`.opencode/skills/`）
+
+### 更新编辑器配置
+
+当 Rune 版本升级后，需要更新已注入的命令和 skill 文件：
+
+```bash
+bunx rune update opencode        # 更新 OpenCode 的命令和 skill
+bunx rune update claude-code     # 更新 Claude Code 的命令
+```
+
+更新策略：对比文件内容，不一致则用内置版本覆盖；不存在则新建。
 
 ### SDD 流程
 
-1. `/rune-discuss` — 自由讨论需求
+SDD 工作流包含固定的四个阶段，不可自定义增删：
-2. `/rune-plan <变更名> <文档名>` — 生成指定规划文档（如 `design`、`task`），支持文档间依赖
+
-3. `/rune-build <变更名>` — 按任务顺序编码实现
+1. **讨论阶段** — `/rune-discuss`：与 AI 自由讨论需求和方案。讨论结果保留在 AI 会话上下文中传递到后续阶段，不持久化到文件。结束前会引导是否进入规划阶段。
-4. `/rune-archive <变更名>` — 归档并清理
+2. **规划阶段** — `/rune-plan <变更名> <文档名>`：按配置的文档模板生成规划文档。变更名仅支持中文、英文和短横线（`-`）。默认包含 `design`（设计文档）和 `task`（任务清单，依赖 design）两个文档。文档间支持 `depend` 字段声明前置依赖，依赖未满足时有友好提示。plan 命令自身不写入文件，只输出提示词供 AI 消费。
+3. **构建阶段** — `/rune-build <变更名>`：按 task.md 中的任务顺序逐个实现。每个任务完成后更新对应的 checkbox 为 `[x]`。可多次执行直到所有任务完成。
+4. **归档阶段** — `/rune-archive <变更名>`：将变更目录移至 `archive/`。归档前自动检查 task.md 的完成状态，如有未完成任务会注入警告提示词，引导 AI 询问用户是否确认归档。
 
 ### 状态查看
 
 ```bash
-rune status              # 查看所有变更
+rune status              # 查看所有变更（含各阶段文档完成状态、下一步建议）
-rune status <变更名>     # 查看指定变更的详细状态（文档完成情况、依赖状态、下一步建议）
+rune status <变更名>     # 查看指定变更的详细状态
 ```
 
-### 帮助与版本
+规划阶段应引导 AI 先通过 `rune status` 获取当前有哪些文档需要编写。
+
+### 命令参考
 
 ```bash
 rune help                # 显示全局帮助
@@ -42,9 +58,19 @@ rune help <command>    # 显示指定命令的详细帮助
 rune version             # 显示版本号
 ```
 
+| 命令 | 说明 |
+|------|------|
+| `rune init <tool>` | 初始化项目，注入编辑器配置 |
+| `rune update <tool>` | 更新编辑器的命令和 skill 文件 |
+| `rune discuss` | 输出讨论阶段提示词 |
+| `rune plan <变更名> <文档名>` | 输出规划阶段提示词 |
+| `rune build <变更名>` | 输出构建阶段提示词 |
+| `rune archive <变更名>` | 输出归档阶段提示词，同时移动变更目录到 archive/ |
+| `rune status [变更名]` | 显示变更状态和下一步建议 |
+
 ### 自定义配置
 
-编辑 `.rune/config.yaml` 自定义提示词和文档模板。配置文件默认为空，使用内置默认策略；仅覆盖需要自定义的阶段，未配置的阶段使用内置默认配置。
+编辑 `.rune/config.yaml` 自定义各阶段的提示词和文档模板。配置合并采用阶段级别全量覆盖策略：自定义某个阶段时需完整重写该阶段的配置，未配置的阶段使用内置默认配置。
 
 规划阶段的文档支持 `depend` 字段声明前置依赖，如 `task` 依赖 `design`：
 
@@ -53,12 +79,26 @@ stages:
   plan:
     documents:
       - name: design
-        prompt: 生成设计文档
+        prompt: 生成设计文档，包含背景、目标、方案、接口和注意事项
       - name: task
-        prompt: 生成任务清单
+        prompt: 生成任务清单，将设计拆分为可独立执行的小任务
         depend: [design]
 ```
 
+计划阶段文档模板支持 `{{change-name}}` 变量，运行时会替换为实际变更名。
+
+## 设计决策
+
+- **四阶段固定**：discuss → plan → build → archive 不可自定义增删
+- **配置覆盖策略**：阶段级别全量覆盖，不支持字段级合并
+- **讨论结果不持久化**：完全依赖 AI 会话上下文传递
+- **plan 不写文件**：plan 命令只输出提示词，由 AI 负责写入文档
+- **变更名限制**：仅支持中文、英文、短横线（`-`）
+- **同一变更名同天多次归档**：依靠日期+变更名去重，不做冲突处理
+- **无跨变更依赖**：变更之间完全独立
+- **无并发锁**：同一变更可被多个 AI agent 同时操作
+- **无变更废弃命令**：用户手动删除 `.rune/changes/<变更名>/` 目录即可
+
 ## 开发
 
 ```bash