188 lines
5.2 KiB
Markdown
188 lines
5.2 KiB
Markdown
|
# 原有设计分析与问题识别
|
|||
|
|
|
|||
|
|
## 一、分析范围
|
|||
|
|
|
|||
|
|
本文档基于以下材料进行分析：
|
|||
|
|
- `aide-requirements.md` - 原有需求规格
|
|||
|
|
- `ai-agent-memory/` - 原始提示词指令体系
|
|||
|
|
- `docs/` - Claude Code扩展机制指南
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、原有设计的优点
|
|||
|
|
|
|||
|
|
### 2.1 核心理念清晰
|
|||
|
|
|
|||
|
|
原有设计提出的四个核心原则是正确的：
|
|||
|
|
|
|||
|
|
| 原则 | 价值 |
|
|||
|
|
|------|------|
|
|||
|
|
| 渐进式披露 | 解决信息过载，按需加载 |
|
|||
|
|
| 确定性封装 | 消除自然语言歧义 |
|
|||
|
|
| 信息隔离 | 减少token污染 |
|
|||
|
|
| 核心与形式分离 | LLM专注思考，程序处理格式 |
|
|||
|
|
|
|||
|
|
这些原则应当保留。
|
|||
|
|
|
|||
|
|
### 2.2 职责划分合理
|
|||
|
|
|
|||
|
|
Command负责"方法论指导"，Skill负责"工具使用说明"的划分是合理的：
|
|||
|
|
- Command：告诉LLM**怎么思考**
|
|||
|
|
- Skill：告诉LLM**有什么工具可用**
|
|||
|
|
|
|||
|
|
### 2.3 三命令结构简洁
|
|||
|
|
|
|||
|
|
`/aide:init`、`/aide:prep`、`/aide:exec` 的三命令结构覆盖了完整的任务生命周期，入口清晰。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、识别出的问题
|
|||
|
|
|
|||
|
|
### 3.1 过度设计：命令粒度过细
|
|||
|
|
|
|||
|
|
**问题描述**：
|
|||
|
|
|
|||
|
|
原设计中 `aide env check`、`aide env ensure`、`aide progress init`、`aide progress update` 等命令粒度过细。
|
|||
|
|
|
|||
|
|
**分析**：
|
|||
|
|
|
|||
|
|
以 `aide env` 为例：
|
|||
|
|
- `aide env check` - 只检测不修复
|
|||
|
|
- `aide env ensure` - 检测并修复
|
|||
|
|
|
|||
|
|
这种拆分的假设是"用户有时只想检测不想修复"，但实际场景中：
|
|||
|
|
- 如果环境有问题，用户几乎总是希望修复
|
|||
|
|
- 如果环境没问题，check和ensure的输出相同
|
|||
|
|
|
|||
|
|
**结论**：这是一个**伪需求**，应合并为单一命令。
|
|||
|
|
|
|||
|
|
### 3.2 过度设计：状态记录的必要性存疑
|
|||
|
|
|
|||
|
|
**问题描述**：
|
|||
|
|
|
|||
|
|
原设计保留了 `aide-progress` 用于记录任务执行状态（CSV文件），这继承自原ai-agent-memory体系。
|
|||
|
|
|
|||
|
|
**分析**：
|
|||
|
|
|
|||
|
|
状态记录的原始目的是：
|
|||
|
|
1. 追踪任务进度
|
|||
|
|
2. 支持中断恢复
|
|||
|
|
3. 提供执行历史
|
|||
|
|
|
|||
|
|
但在Claude Code环境下：
|
|||
|
|
- 对话本身就是状态记录
|
|||
|
|
- Claude Code有自己的TodoWrite工具
|
|||
|
|
- CSV状态文件增加了维护负担
|
|||
|
|
|
|||
|
|
**需要讨论**：状态记录是否仍然必要？如果必要，是否需要独立的aide命令？
|
|||
|
|
|
|||
|
|
### 3.3 职责边界模糊：aide-version
|
|||
|
|
|
|||
|
|
**问题描述**：
|
|||
|
|
|
|||
|
|
`aide-version` 封装了Git操作和CHANGELOG管理，但这些操作：
|
|||
|
|
- Git操作：Claude Code本身就能很好地执行
|
|||
|
|
- CHANGELOG：格式相对固定，但内容需要LLM理解变更语义
|
|||
|
|
|
|||
|
|
**分析**：
|
|||
|
|
|
|||
|
|
封装Git操作的价值有限：
|
|||
|
|
- `git add . && git commit -m "xxx"` 并不复杂
|
|||
|
|
- 封装后反而隐藏了实际操作，调试困难
|
|||
|
|
|
|||
|
|
CHANGELOG管理可能有价值：
|
|||
|
|
- 格式固定（版本号、日期、分类）
|
|||
|
|
- 但内容生成仍需LLM参与
|
|||
|
|
|
|||
|
|
**结论**：Git操作封装是**伪需求**，CHANGELOG管理**待讨论**。
|
|||
|
|
|
|||
|
|
### 3.4 技术复杂度：待定项Web界面
|
|||
|
|
|
|||
|
|
**问题描述**：
|
|||
|
|
|
|||
|
|
你提出用 ts+react+nextjs 实现待定项的Web交互界面。
|
|||
|
|
|
|||
|
|
**分析**：
|
|||
|
|
|
|||
|
|
优点：
|
|||
|
|
- 用户体验好
|
|||
|
|
- 可视化操作直观
|
|||
|
|
- 技术栈成熟
|
|||
|
|
|
|||
|
|
潜在问题：
|
|||
|
|
- 引入了Node.js依赖（除了Python）
|
|||
|
|
- 需要启动HTTP服务
|
|||
|
|
- 开发和维护成本增加
|
|||
|
|
- 对于简单的待定项确认，可能过重
|
|||
|
|
|
|||
|
|
**需要讨论**：
|
|||
|
|
1. 待定项的典型数量和复杂度是多少？
|
|||
|
|
2. 是否有更轻量的替代方案？
|
|||
|
|
3. Web界面是否应该作为可选增强而非必需？
|
|||
|
|
|
|||
|
|
### 3.5 缺失：错误恢复机制
|
|||
|
|
|
|||
|
|
**问题描述**：
|
|||
|
|
|
|||
|
|
原设计定义了输出前缀（✓/⚠/✗），但没有定义：
|
|||
|
|
- 错误发生后LLM应该如何响应
|
|||
|
|
- 是否需要重试机制
|
|||
|
|
- 如何处理部分成功的情况
|
|||
|
|
|
|||
|
|
### 3.6 缺失：配置的默认值与覆盖机制
|
|||
|
|
|
|||
|
|
**问题描述**：
|
|||
|
|
|
|||
|
|
`aide.toml` 定义了配置结构，但没有说明：
|
|||
|
|
- 配置文件不存在时的默认行为
|
|||
|
|
- 用户如何覆盖默认配置
|
|||
|
|
- 配置验证和错误提示
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、伪需求清单
|
|||
|
|
|
|||
|
|
基于上述分析，以下功能可能是伪需求：
|
|||
|
|
|
|||
|
|
| 功能 | 判断依据 | 建议 |
|
|||
|
|
|------|----------|------|
|
|||
|
|
| `aide env check` vs `aide env ensure` 拆分 | 实际场景中几乎总是需要ensure | 合并为单一命令 |
|
|||
|
|
| Git操作封装 | Claude Code本身能力足够 | 删除，或仅保留极简封装 |
|
|||
|
|
| 细粒度的progress命令 | 与Claude Code的TodoWrite重复 | 重新评估必要性 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、待讨论问题
|
|||
|
|
|
|||
|
|
请在 `reply/` 目录回复以下问题：
|
|||
|
|
|
|||
|
|
### Q1：状态记录的必要性
|
|||
|
|
|
|||
|
|
原ai-agent-memory体系使用CSV记录任务状态。在新体系中：
|
|||
|
|
- 你是否仍然需要独立的状态记录文件？
|
|||
|
|
- 还是可以依赖Claude Code的对话历史和TodoWrite？
|
|||
|
|
|
|||
|
|
### Q2：待定项的典型场景
|
|||
|
|
|
|||
|
|
为了评估Web界面的必要性：
|
|||
|
|
- 一个典型任务通常有多少个待定项？
|
|||
|
|
- 待定项的选项通常有多复杂？（简单二选一 vs 多选+自定义输入）
|
|||
|
|
- 是否有需要展示大量上下文信息的场景？
|
|||
|
|
|
|||
|
|
### Q3：CHANGELOG管理的价值
|
|||
|
|
|
|||
|
|
- 你的项目是否都需要维护CHANGELOG？
|
|||
|
|
- 如果需要，aide封装的价值在哪里？（格式化？自动生成版本号？）
|
|||
|
|
|
|||
|
|
### Q4：最小可用版本的范围
|
|||
|
|
|
|||
|
|
如果要先实现一个最小可用版本，你认为哪些功能是必须的？
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 六、下一步
|
|||
|
|
|
|||
|
|
根据你的回复，我将：
|
|||
|
|
1. 更新 `aide-requirements.md`，删除伪需求，保留核心原则
|
|||
|
|
2. 创建新的设计文档，重新定义aide程序体系
|