diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index a024ccd..ea50988 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -13,6 +13,10 @@
 ```
 src/
 ├── cli.ts              # CLI 入口
+├── cli/
+│   ├── errors.ts       # CLI 错误定义（CliError 层级）
+│   ├── output.ts       # 格式化输出（错误/用法/提示）
+│   └── help.ts         # 帮助文本生成
 ├── types.ts            # 类型定义
 ├── commands/
 │   └── init.ts         # init 命令
@@ -36,8 +40,29 @@ tests/                   # 测试目录（镜像 src 结构）
 bun test                      # 运行全部测试
 bun test tests/core/          # 运行指定目录测试
 bun src/cli.ts init opencode  # 测试 init 命令
+bun src/cli.ts help           # 查看全局帮助
+bun src/cli.ts help init      # 查看 init 命令帮助
+bun src/cli.ts version        # 查看版本号
 ```
 
+## CLI 交互架构
+
+### 子命令
+
+CLI 通过子命令提供帮助和版本信息，不使用 `--help`/`--version` 标志：
+
+- `rune help` — 显示全局帮助（可用命令列表）
+- `rune help <command>` — 显示指定命令的详细用法
+- `rune version` — 显示版本号
+
+### 错误处理
+
+错误消息采用结构化格式，相关代码位于：
+
+- `src/cli/errors.ts` — `CliError` 错误层级（未知命令、缺少参数等）
+- `src/cli/output.ts` — 格式化输出（`错误:`、`用法:`、`提示:` 三段式）
+- `src/cli/help.ts` — 帮助文本生成
+
 ## 测试策略
 
 ### Level 1 — 纯单元/集成测试（当前）
diff --git a/README.md b/README.md
index 2dd1096..dd4b972 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,14 @@ bunx rune init opencode
 rune status
 ```
 
+### 帮助与版本
+
+```bash
+rune help              # 显示全局帮助
+rune help <command>    # 显示指定命令的详细帮助
+rune version           # 显示版本号
+```
+
 ### 自定义配置
 
 编辑 `.rune/config.yaml` 自定义提示词和文档模板。配置文件默认为空，使用内置默认策略；仅覆盖需要自定义的阶段，未配置的阶段使用内置默认配置。