iomgaa 8213ae9a55 feat: 初始化MedResearcher项目

- 添加项目配置文件（pyproject.toml）
- 添加Python版本配置（.python-version）
- 添加项目文档（README.md, CLAUDE.md）
- 添加Git配置（.gitignore）

2025-08-23 00:20:41 +08:00

8.3 KiB

Raw Blame History

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

任务理解

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

核心设计理念

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

详细工作流程设计

阶段1：需求理解与记录（必须执行）

触发条件：用户提出任何代码修改需求

具体步骤：

立即在CLAUDE-temp.md中撰写：

## 任务理解
原始需求：[用户的原话]
我的理解：[用我的话重述一遍]

## 收集的上下文
### 相关文件和函数
- `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
- "理解有偏差" → 修正理解，重新记录
- "补充需求" → 更新CLAUDE-temp.md

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

简单任务处理：

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

复杂任务处理：

判断标准：
- 修改3个以上函数
- 需要新建模块或文件
- 涉及多个功能模块交互
拆分原则：
- 必须拆分为3-5个子任务（不能少于3个，不能多于5个）
- 每个子任务可独立验证
- 子任务之间有清晰的依赖关系

拆分示例：

子任务1：创建重试机制基础设施
子任务2：集成重试机制到爬虫
子任务3：添加重试相关配置
子任务4：更新错误处理逻辑
子任务5：添加重试日志记录

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

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

简单任务格式：

## 任务：[具体任务名称]
创建时间：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文件：

CLAUDE-activeContext.md - 标记任务完成，记录最终状态
CLAUDE-patterns.md - 如有新的代码模式，记录下来
CLAUDE-decisions.md - 记录本次任务的关键决策
CLAUDE-troubleshooting.md - 如遇到问题，记录解决方案
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. 文件操作最佳实践

读取顺序：

先读CLAUDE-activeContext.md（如果存在）了解当前状态
读取主文件了解整体结构
读取相关依赖文件

修改原则：

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

与现有编程规范的协同

层次关系

编程规范（已在CLAUDE.md中定义）：
- 定义"怎么写代码"
- 包括：命名、注释、代码风格等
AI指导规范（本规范）：
- 定义"怎么理解和修改代码"
- 包括：工作流程、沟通方式、工具使用等

执行优先级

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

规范更新机制

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

8.3 KiB Raw Blame History Unescape Escape