# 原有设计分析与问题识别

## 一、分析范围

本文档基于以下材料进行分析：
- `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程序体系