✨ feat: 完成文档拆分
This commit is contained in:
293
discuss/05-文档拆分方案.md
Normal file
293
discuss/05-文档拆分方案.md
Normal file
@@ -0,0 +1,293 @@
|
||||
# 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/ 目录创建回复文档。
|
||||
Reference in New Issue
Block a user