sayurinana/agent-aide

Fork 0

Files

sayurinana(vm) 4cacd128ab ✨ feat: 完成文档拆分

2025-12-13 22:22:01 +08:00

8.8 KiB

Raw Blame History

aide-requirements.md 文档拆分方案

一、需求理解

1.1 核心目标

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

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

1.2 用户场景验证

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

二、拆分方案

2.1 核心设计原则

区分设计文档与执行文件
- 设计文档（docs/）：给人类开发者看，包含完整上下文和设计意图
- 执行文件（commands/、skills/）：给 LLM 看，聚焦执行指令
子区块自包含
- 每个子区块文档包含：背景、职责、接口、行为、依赖关系
- 新人看完一个子区块文档，无需阅读其他文档即可理解该组件
导览只做索引
- 导览文档只包含概述和索引
- 详细规格全部放在子区块文档中

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)

# 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)

# 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 命令行工具使用指南 |

子区块文档模板

每个子区块文档应包含：

# [组件名称]

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

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

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

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

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

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

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

三、内容分配

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 步骤

创建目录结构
- aide-marketplace/aide-plugin/docs/commands/
- aide-marketplace/aide-plugin/docs/skill/
- aide-program/docs/commands/
- aide-program/docs/formats/
编写总导览
- 创建 aide-overview.md
编写 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
编写 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
处理原文档
- 将 aide-requirements.md 移动到 archive/ 或删除

4.2 文档数量统计

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

五、待确认事项

总导览位置：放在项目根目录（aide-overview.md）还是其他位置？
原 aide-requirements.md 处理：
- 选项A：移动到 archive/ 目录保留
- 选项B：直接删除
设计文档与执行文件的关系：
- 当前 commands/*.md 和 SKILL.md 是给 LLM 的执行指令
- 新增的 docs/ 是给人类的设计文档
- 两者内容会有重叠，是否可接受？
文档命名：
- 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 个区块：

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

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

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

8.8 KiB Raw Blame History Unescape Escape