# AI指导规范构建任务 - 深度分析

## 任务理解
用户希望为MedResearcher项目构建一套完整的AI协作指导规范，核心思想是"充分讨论后再修改"，以避免代码难以维护。

## 核心设计理念
1. **讨论优先**：任何修改前必须充分讨论，达成共识
2. **上下文明确**：不仅指出需要什么，更要具体到哪个文件的哪个函数
3. **渐进式实施**：通过子任务分解，逐步完成复杂需求
4. **可追溯性**：所有决策和修改都有明确记录

## 详细工作流程设计

### 阶段1：需求理解与记录（必须执行）
**触发条件**：用户提出任何代码修改需求

**具体步骤**：
1. **立即**在CLAUDE-temp.md中撰写：
   ```markdown
   ## 任务理解
   原始需求：[用户的原话]
   我的理解：[用我的话重述一遍]
   
   ## 收集的上下文
   ### 相关文件和函数
   - `papers_crawler.py::line_45-67::fetch_papers()` - 当前的爬取实现
   - `config.py::line_12-15::RETRY_CONFIG` - 现有重试配置
   
   ### 现有代码分析
   [贴出关键代码片段并分析]
   
   ### 潜在影响
   - 影响文件：papers_crawler.py, test_crawler.py
   - 影响功能：论文爬取的稳定性
   - 风险评估：可能影响爬取速度
   
   ## 任务复杂度判断
   - [ ] 单一功能修改，影响1-2个函数 → 简单任务
   - [x] 需要修改3个以上函数或添加新模块 → 复杂任务
   ```

2. **等待用户反馈**：
   - "理解正确" → 继续阶段2
   - "理解有偏差" → 修正理解，重新记录
   - "补充需求" → 更新CLAUDE-temp.md

### 阶段2：任务规划（根据复杂度差异化）

**简单任务处理**：
- **判断标准**：
  - 修改不超过2个函数
  - 不需要新建文件
  - 逻辑改动在50行以内
- **严格要求**：绝对不允许拆分子任务
- **直接输出**：一个完整的执行计划

**复杂任务处理**：
- **判断标准**：
  - 修改3个以上函数
  - 需要新建模块或文件
  - 涉及多个功能模块交互
- **拆分原则**：
  - 必须拆分为3-5个子任务（不能少于3个，不能多于5个）
  - 每个子任务可独立验证
  - 子任务之间有清晰的依赖关系
- **拆分示例**：
  ```
  子任务1：创建重试机制基础设施
  子任务2：集成重试机制到爬虫
  子任务3：添加重试相关配置
  子任务4：更新错误处理逻辑
  子任务5：添加重试日志记录
  ```

### 阶段3：计划确认与正式化（用户确认后执行）

**创建CLAUDE-plan.md，严格按照以下格式**：

#### 简单任务格式：
```markdown
## 任务：[具体任务名称]
创建时间：2025-08-22 10:30

### 目标
[30-50字描述要实现的功能，必须具体且可验证]

### 所需上下文
- `papers_crawler.py::45-67行::fetch_papers()` - 需要添加异常处理
- `papers_crawler.py::120-135行::parse_response()` - 需要理解返回格式
- `config.py::全文` - 了解现有配置结构

### 拟修改内容
1. 修改 `papers_crawler.py::fetch_papers()` 第50-55行 - 添加try-except块
2. 修改 `papers_crawler.py::fetch_papers()` 第65行 - 添加重试逻辑
3. 修改 `config.py` 末尾 - 添加RETRY_TIMES常量

### 测试指令
```bash
# 主功能测试
uv run papers_crawler.py --keyword "machine learning" --limit 5

# 异常情况测试（模拟网络错误）
uv run papers_crawler.py --test-mode --simulate-error
```

### 验收标准
- [ ] 正常爬取功能不受影响
- [ ] 网络异常时能正确重试
- [ ] 日志正确记录重试次数
```

#### 复杂任务格式：
```markdown
## 任务：[具体任务名称]
创建时间：2025-08-22 10:30

### 总体目标
[50-100字描述整体要实现的功能]

### 子任务分解

#### 子任务1：[名称]
**目标**：[20-30字描述]

**所需上下文**：
- `papers_crawler.py::45-67行::fetch_papers()` - 理解当前实现
- `utils/__init__.py::全文` - 确认工具模块结构

**拟修改内容**：
- 新建 `utils/retry.py` - 创建RetryDecorator类
- 修改 `utils/__init__.py` - 导出retry装饰器

**测试指令**：
```bash
# 单元测试
python -c "from utils.retry import retry; print('导入成功')"
```

#### 子任务2：[名称]
[格式同上]

### 整体验收标准
- [ ] 所有子任务独立测试通过
- [ ] 集成测试：完整流程测试通过
- [ ] 性能测试：重试不影响正常爬取速度
```

### 阶段4：实施与验证（严格按计划执行）

**执行要求**：
1. **开始前确认**：
   - 再次阅读CLAUDE-plan.md
   - 确认所有依赖文件存在
   - 确认测试环境就绪

2. **执行中记录**：
   - 在CLAUDE-activeContext.md实时更新进度
   - 遇到计划外情况立即停止并讨论

3. **完成后验证**：
   - 运行所有测试指令
   - 检查验收标准
   - 记录任何偏差或问题

## Memory Bank系统设计

### 文件结构
```
/docs/
├── CLAUDE-temp.md          # 临时讨论和分析
├── CLAUDE-plan.md          # 当前任务的正式计划
├── CLAUDE-activeContext.md # 会话状态和进度跟踪
├── CLAUDE-patterns.md      # 项目代码模式记录
├── CLAUDE-decisions.md     # 重要决策和理由记录
├── CLAUDE-troubleshooting.md # 问题和解决方案库
└── CLAUDE-config-variables.md # 配置变量参考
```

### 使用原则
1. **docs/CLAUDE-temp.md**：
   - 每次新任务开始时清空或归档
   - 用于快速记录和思考
   - 不需要结构化

2. **docs/CLAUDE-plan.md**：
   - 结构化的任务计划
   - 用户确认后才写入
   - 作为实施的指导文档

3. **docs/CLAUDE-activeContext.md**：
   - 记录当前进度
   - 标记已完成/进行中/待完成
   - 会话恢复时的参考

### Memory Bank更新机制

**使用专门的SubAgent管理**：
```
Task: memory-bank-updater
Description: "更新Memory Bank文件"
Prompt: "任务已完成，请更新以下Memory Bank文件：
1. CLAUDE-activeContext.md - 标记任务完成，记录最终状态
2. CLAUDE-patterns.md - 如有新的代码模式，记录下来
3. CLAUDE-decisions.md - 记录本次任务的关键决策
4. CLAUDE-troubleshooting.md - 如遇到问题，记录解决方案
5. CLAUDE-config-variables.md - 如有新配置，更新文档

具体完成内容：[任务摘要]
遇到的问题：[如有]
采用的解决方案：[如有]"
```

**调用时机**：
- 每个任务完成后必须调用
- 遇到重要决策时调用
- 发现新的最佳实践时调用

## 工具使用优化原则

### 1. 批量操作原则
**场景**：需要读取多个文件或执行多个独立搜索时
**做法**：
```python
# 同时执行多个工具调用
parallel_calls = [
    Read("papers_crawler.py"),
    Read("pdf_parser.py"),
    Grep("retry", "*.py"),
    LS("./utils/")
]
```
**禁止**：顺序执行可并行的操作

### 2. 上下文管理策略
**主上下文保留**：
- 用户对话
- 关键决策点
- 当前任务计划

**委托给subagent**：
- 大规模代码搜索："搜索所有使用requests库的地方"
- 代码模式分析："分析项目中的错误处理模式"
- 依赖关系梳理："找出papers_crawler.py的所有依赖"

**subagent使用示例**：
```
Task: code-searcher
Prompt: "在整个项目中搜索所有异常处理相关的代码，
        重点关注papers_crawler.py和pdf_parser.py，
        总结当前的错误处理模式和改进建议"
```

### 3. 文件操作最佳实践
**读取顺序**：
1. 先读CLAUDE-activeContext.md（如果存在）了解当前状态
2. 读取主文件了解整体结构
3. 读取相关依赖文件

**修改原则**：
- 优先使用Edit而非Write
- 使用MultiEdit处理同文件多处修改
- 新文件创建需明确理由

## 与现有编程规范的协同

### 层次关系
1. **编程规范**（已在CLAUDE.md中定义）：
   - 定义"怎么写代码"
   - 包括：命名、注释、代码风格等

2. **AI指导规范**（本规范）：
   - 定义"怎么理解和修改代码"
   - 包括：工作流程、沟通方式、工具使用等

### 执行优先级
1. 遵守编程规范的硬性要求（如单次修改限制）
2. 按AI指导流程进行任务
3. 发生冲突时，编程规范优先

## 规范更新机制
- 每次遇到新的最佳实践，记录到CLAUDE-patterns.md
- 定期回顾CLAUDE-troubleshooting.md，提炼通用规则
- 用户可随时提出规范优化建议