agent-aide/discuss/05-文档拆分方案.md

# aide-requirements.md 文档拆分方案

## 一、需求理解

### 1.1 核心目标

将完整的 `aide-requirements.md` 拆分为**总导览 + 多个子区块文档**，实现：

1. **子区块信息完整独立**：新人仅依赖子区块文档即可完全了解该区块
2. **修改范围最小化**：调整某功能只需更新相关子区块和导览，无需了解全部内容
3. **导览轻量化**：导览远比全部完整信息轻量

### 1.2 用户场景验证

| 场景 | 阅读路径 | 修改范围 |
|------|----------|----------|
| 调整 commands/init 业务细节 | 总导览 → plugin导览 → init设计文档 | init设计文档 + 对应command文件 |
| 调整 aide env 子命令功能 | 总导览 → program导览 → env设计文档 | env设计文档 + 对应代码 |
| 新增一个 command | 总导览 → plugin导览 → 参考现有command文档 | 新建command设计文档 + command文件 + 更新导览 |

---

## 二、拆分方案

### 2.1 核心设计原则

1. **区分设计文档与执行文件**
   - 设计文档（docs/）：给人类开发者看，包含完整上下文和设计意图
   - 执行文件（commands/、skills/）：给 LLM 看，聚焦执行指令

2. **子区块自包含**
   - 每个子区块文档包含：背景、职责、接口、行为、依赖关系
   - 新人看完一个子区块文档，无需阅读其他文档即可理解该组件

3. **导览只做索引**
   - 导览文档只包含概述和索引
   - 详细规格全部放在子区块文档中

### 2.2 目录结构

```
项目根目录/
├── aide-overview.md              # 总导览（系统概述 + 子区块索引）
│
├── aide-marketplace/
│   └── aide-plugin/
│       ├── docs/                 # plugin 设计文档区块
│       │   ├── README.md         # plugin 导览
│       │   ├── commands/
│       │   │   ├── init.md       # init 命令设计文档
│       │   │   ├── prep.md       # prep 命令设计文档
│       │   │   └── exec.md       # exec 命令设计文档
│       │   └── skill/
│       │       └── aide.md       # aide skill 设计文档
│       ├── commands/             # 实际 command 文件（给 LLM）
│       │   ├── init.md
│       │   ├── prep.md
│       │   └── exec.md
│       └── skills/               # 实际 skill 文件（给 LLM）
│           └── aide/
│               └── SKILL.md
│
└── aide-program/
    ├── docs/                     # program 设计文档区块
    │   ├── README.md             # program 导览
    │   ├── commands/
    │   │   ├── env.md            # env 子命令设计
    │   │   ├── flow.md           # flow 子命令设计
    │   │   ├── decide.md         # decide 子命令设计
    │   │   └── init.md           # init 子命令设计
    │   └── formats/
    │       ├── config.md         # 配置文件格式规范
    │       └── data.md           # 数据格式规范（待定项、流程状态等）
    └── aide/                     # 实际代码
```

### 2.3 文档内容规划

#### 总导览 (aide-overview.md)

```markdown
# Aide 系统概述

## 系统简介
[1-2段话描述 aide 是什么、解决什么问题]

## 核心设计原则
- 渐进式披露
- 确定性封装
- 信息隔离
- 核心与形式分离

## 系统架构
[简图：plugin ↔ program 关系]

## 子区块索引

| 区块 | 位置 | 职责 |
|------|------|------|
| aide-plugin | aide-marketplace/aide-plugin/docs/ | Commands 和 Skill 定义 |
| aide-program | aide-program/docs/ | 命令行工具实现 |

## 快速导航
- 想了解/修改 commands → [aide-plugin 导览](...)
- 想了解/修改 aide 程序 → [aide-program 导览](...)
```

#### plugin 导览 (aide-plugin/docs/README.md)

```markdown
# Aide Plugin 设计文档

## 概述
aide-plugin 是 Claude Code 插件，提供 Aide 工作流的 Commands 和 Skill。

## 组件关系
- Commands：定义流程（init/prep/exec）
- Skill：定义工具使用方法（aide 命令）

## Commands 索引

| Command | 文档 | 职责 |
|---------|------|------|
| /aide:init | [init.md](commands/init.md) | 项目认知与环境初始化 |
| /aide:prep | [prep.md](commands/prep.md) | 任务准备流程 |
| /aide:exec | [exec.md](commands/exec.md) | 任务执行流程 |

## Skill 索引

| Skill | 文档 | 职责 |
|-------|------|------|
| aide | [aide.md](skill/aide.md) | aide 命令行工具使用指南 |
```

#### 子区块文档模板

每个子区块文档应包含：

```markdown
# [组件名称]

## 背景
[为什么需要这个组件，解决什么问题]

## 职责
[这个组件做什么、不做什么]

## 接口
[输入、输出、参数]

## 行为
[详细的执行逻辑/流程]

## 依赖
[依赖哪些其他组件，简要说明]

## 被依赖
[被哪些组件使用]

## 修改指南
[修改此组件时需要同步更新的内容]
```

---

## 三、内容分配

### 3.1 从 aide-requirements.md 提取的内容分配

| 原章节 | 目标位置 |
|--------|----------|
| 一、项目背景 | aide-overview.md（精简版） |
| 二、核心设计原则 | aide-overview.md（列表形式） |
| 三、组件职责定义 | aide-plugin/docs/README.md |
| 四、命令清单 | aide-plugin/docs/commands/*.md |
| 五、技能清单 | aide-plugin/docs/skill/aide.md + aide-program/docs/commands/*.md |
| 六、信息流设计 | aide-program/docs/formats/data.md |
| 七、LLM 自由发挥边界 | aide-plugin/docs/README.md |
| 八、数据格式规范 | aide-program/docs/formats/data.md |
| 九、数据存储 | aide-program/docs/formats/config.md |
| 十、实施结构 | aide-overview.md（架构部分） |

### 3.2 新增内容

| 文档 | 新增内容 |
|------|----------|
| aide-program/docs/README.md | program 整体介绍、目录结构、开发指南 |
| aide-program/docs/commands/flow.md | flow 子命令完整设计（当前未实现） |
| aide-program/docs/commands/decide.md | decide 子命令完整设计（当前未实现） |

---

## 四、实施计划

### 4.1 步骤

1. **创建目录结构**
   - aide-marketplace/aide-plugin/docs/commands/
   - aide-marketplace/aide-plugin/docs/skill/
   - aide-program/docs/commands/
   - aide-program/docs/formats/

2. **编写总导览**
   - 创建 aide-overview.md

3. **编写 aide-plugin 文档**
   - aide-plugin/docs/README.md
   - aide-plugin/docs/commands/init.md
   - aide-plugin/docs/commands/prep.md
   - aide-plugin/docs/commands/exec.md
   - aide-plugin/docs/skill/aide.md

4. **编写 aide-program 文档**
   - aide-program/docs/README.md
   - aide-program/docs/commands/env.md
   - aide-program/docs/commands/flow.md
   - aide-program/docs/commands/decide.md
   - aide-program/docs/commands/init.md
   - aide-program/docs/formats/config.md
   - aide-program/docs/formats/data.md

5. **处理原文档**
   - 将 aide-requirements.md 移动到 archive/ 或删除

### 4.2 文档数量统计

| 区块 | 文档数量 |
|------|----------|
| 总导览 | 1 |
| aide-plugin | 5 |
| aide-program | 7 |
| **合计** | **13** |

---

## 五、待确认事项

1. **总导览位置**：放在项目根目录（aide-overview.md）还是其他位置？

2. **原 aide-requirements.md 处理**：
   - 选项A：移动到 archive/ 目录保留
   - 选项B：直接删除

3. **设计文档与执行文件的关系**：
   - 当前 commands/*.md 和 SKILL.md 是给 LLM 的执行指令
   - 新增的 docs/ 是给人类的设计文档
   - 两者内容会有重叠，是否可接受？

4. **文档命名**：
   - aide-program/docs/commands/ 下的文档是否用 "env.md" 还是 "aide-env.md"？

---

## 六、预期效果

### 6.1 新人上手流程

```
想了解 aide 系统
    ↓
阅读 aide-overview.md（5分钟）
    ↓
确定要修改的区块
    ↓
阅读对应区块导览（5分钟）
    ↓
阅读具体组件文档（10分钟）
    ↓
开始修改
```

### 6.2 修改影响范围

| 修改类型 | 影响文档 |
|----------|----------|
| 调整 init 命令流程 | init设计文档 + init.md执行文件 |
| 新增 aide 子命令 | program导览 + 新子命令设计文档 + SKILL.md + 代码 |
| 修改数据格式 | formats/data.md + 相关代码 |
| 调整设计原则 | aide-overview.md |

---

## 七、总结

本方案将 aide-requirements.md 拆分为 13 个文档，分布在 3 个区块：

1. **总导览**：系统概述和索引
2. **aide-plugin 区块**：Commands 和 Skill 的设计文档
3. **aide-program 区块**：程序子命令和数据格式的设计文档

每个子区块文档自包含，新人可以仅通过导览找到相关文档，完全掌握该区块信息后进行修改，无需了解整个系统的全部细节。

请审阅此方案，如有调整意见请在 reply/ 目录创建回复文档。