From 7b258f4d904c1b01394be394809371e29e9ecb07 Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Tue, 9 Jun 2026 12:40:35 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README=20=E5=92=8C?= =?UTF-8?q?=20DEVELOPMENT=EF=BC=8C=E8=A1=A5=E5=85=85=E8=AE=BE=E8=AE=A1?= =?UTF-8?q?=E5=86=B3=E7=AD=96=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- DEVELOPMENT.md | 32 +++++++++++++++++++++++ README.md | 70 +++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 87 insertions(+), 15 deletions(-) diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md index 5c7ee58..3bcb7b7 100644 --- a/DEVELOPMENT.md +++ b/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 ` 对比已注入的命令/skill 文件内容与内置版本，不一致则覆盖，不存在则新建。用于升级 Rune 后更新编辑器配置。 + +### 其他决策 + +- 无跨变更依赖，变更之间完全独立 +- 无并发锁，同一变更可被多个 agent 同时操作 +- 无需变更废弃命令，手动删除目录即可 +- 同一变更名同天多次归档不处理冲突（日期+名称去重） +- plan skill 应引导 AI 先通过 `rune status` 获取文档列表 + ## 测试策略 ### Level 1 — 纯单元/集成测试（当前） diff --git a/README.md b/README.md index 26717fb..abfabcf 100644 --- a/README.md +++ b/README.md @@ -13,38 +13,64 @@ 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` — 自由讨论需求 -2. `/rune-plan <变更名> <文档名>` — 生成指定规划文档（如 `design`、`task`），支持文档间依赖 -3. `/rune-build <变更名>` — 按任务顺序编码实现 -4. `/rune-archive <变更名>` — 归档并清理 +SDD 工作流包含固定的四个阶段，不可自定义增删： + +1. **讨论阶段** — `/rune-discuss`：与 AI 自由讨论需求和方案。讨论结果保留在 AI 会话上下文中传递到后续阶段，不持久化到文件。结束前会引导是否进入规划阶段。 +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 # 显示全局帮助 -rune help # 显示指定命令的详细帮助 -rune version # 显示版本号 +rune help # 显示全局帮助 +rune help # 显示指定命令的详细帮助 +rune version # 显示版本号 ``` +| 命令 | 说明 | +|------|------| +| `rune init ` | 初始化项目，注入编辑器配置 | +| `rune update ` | 更新编辑器的命令和 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