237 lines
8.1 KiB
Markdown
237 lines
8.1 KiB
Markdown
# CLAUDE.md
|
||
|
||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
||
## 项目概述
|
||
|
||
MedResearcher 是一个给予用户输入的自动实验平台，其会给予用户指定的研究目标，通过mcp访问特定数据集并撰写代码以构建实验。
|
||
|
||
## 技术栈
|
||
1. 后端编程语言：Python
|
||
2. python管理器：uv
|
||
3. 爬虫工具：Crawl4AI
|
||
|
||
## 各个模块的主文件
|
||
1. 论文爬取主文件: papers_crawler.py
|
||
2. pdf解析主文件: pdf_parser.py
|
||
3. 实验运行主文件: experiment_runner.py
|
||
|
||
## 文件结构
|
||
```
|
||
/
|
||
├── dataset/ # 数据存放目录
|
||
│ └── mimic.csv # 存放所有需要处理的与mimic相关论文的基础信息
|
||
├── papers_crawler.py # 论文爬取主文件
|
||
├── pdf_parser.py # pdf解析主文件
|
||
├── experiment_runner.py # 实验运行主文件
|
||
├── src/ # 源代码目录
|
||
│ └── utils/ # 工具函数目录
|
||
│ └── csv_utils.py # CSV文件操作工具函数
|
||
└── docs/ # Memory Bank系统文件
|
||
├── CLAUDE-temp.md # 临时讨论和分析
|
||
├── CLAUDE-plan.md # 当前任务计划
|
||
├── CLAUDE-activeContext.md # 会话状态跟踪
|
||
├── CLAUDE-patterns.md # 代码模式记录
|
||
├── CLAUDE-decisions.md # 决策记录
|
||
├── CLAUDE-troubleshooting.md # 问题解决方案
|
||
└── CLAUDE-config-variables.md # 配置变量参考
|
||
```
|
||
|
||
## 开发注意事项
|
||
|
||
### 必须遵循的编程规范
|
||
|
||
1. **注释和文档规范**
|
||
- 所有注释使用中文
|
||
- 关键代码逻辑必须添加行内注释
|
||
- 所有函数和类必须添加docstring，说明功能、参数和返回值
|
||
- 复杂算法需要详细说明思路
|
||
|
||
2. **命名规范**
|
||
- 变量名、函数名：使用 snake_case
|
||
- 类名：使用 PascalCase
|
||
- 常量：使用 UPPER_SNAKE_CASE
|
||
- 禁止使用中文变量名
|
||
|
||
3. **代码修改限制**
|
||
- 单次修改不超过200行代码
|
||
- 单次修改不超过3个文件
|
||
- 严格遵循最小修改原则
|
||
- 绝对不允许修改与指定任务无关的代码
|
||
- 每次修改只针对当前任务的必要部分
|
||
- 优先修改而非新建：能通过修改解决的问题不新建文件
|
||
|
||
4. **代码风格规范**
|
||
- 单行代码长度限制：120字符
|
||
- 使用类型提示（type hints）提高代码可读性
|
||
- 导入语句按照：标准库 → 第三方库 → 本地模块 的顺序排列
|
||
|
||
5. **错误处理和日志**
|
||
- 必须使用 try-except 进行全面的错误捕获
|
||
- 使用 logging 模块替代 print 进行日志输出
|
||
- 日志级别：开发时使用DEBUG，生产环境使用INFO
|
||
- 绝对不允许填写任何默认值或假设值
|
||
- 出现错误时应抛出明确的异常信息，便于问题排查
|
||
- 宁可程序报错，也不要用默认值掩盖潜在问题
|
||
|
||
6. **依赖管理**
|
||
- 优先使用标准库
|
||
- 新增第三方依赖时需在注释中说明用途
|
||
- 使用 uv 管理所有依赖
|
||
|
||
7. **资源管理**
|
||
- 文件操作必须使用 with 语句
|
||
- 网络请求设置合理超时（建议30秒）
|
||
- 大文件使用流式处理避免内存溢出
|
||
|
||
8. **Git提交规范**
|
||
- commit message 格式：`<类型>: <描述>`
|
||
- 类型包括：feat(新功能)、fix(修复)、refactor(重构)、docs(文档)、test(测试)
|
||
|
||
9. **测试规范**
|
||
- 不允许撰写独立的测试用例文件或测试代码
|
||
- 通过直接运行对应的主文件（papers_crawler.py、pdf_parser.py 或 experiment_runner.py）进行功能测试
|
||
- 主文件的 `if __name__ == "__main__":` 块中应包含基本的功能调用示例
|
||
- **严格限制main函数使用**：只有主文件（papers_crawler.py、pdf_parser.py、experiment_runner.py）允许包含 `if __name__ == "__main__":` 块，其他所有工具模块、库文件绝对不允许包含此类测试代码
|
||
- 函数可以被其他模块调用，不一定要在主文件中直接调用
|
||
- 作为MVP项目，重点关注理想情况下的功能实现，而非鲁棒性
|
||
|
||
**修改前验证**：
|
||
```bash
|
||
# 确保现有功能正常
|
||
uv run <主文件>.py --test-mode
|
||
```
|
||
|
||
**修改后验证**：
|
||
```bash
|
||
# 功能测试
|
||
uv run <主文件>.py --test-mode
|
||
# 语法检查
|
||
python -m py_compile <修改的文件>.py
|
||
# 如有类型提示，运行类型检查
|
||
mypy <修改的文件>.py --ignore-missing-imports
|
||
```
|
||
|
||
### 代码组织原则
|
||
- 新功能优先集成到现有主文件中
|
||
- 只有在功能独立且复杂时才创建新的模块文件
|
||
- 保持代码结构简洁，避免过度模块化
|
||
|
||
## uv常用指令
|
||
1. 初始化项目
|
||
```
|
||
uv init
|
||
```
|
||
2. 安装依赖
|
||
```
|
||
uv add <package-name>
|
||
```
|
||
3. 运行项目
|
||
```
|
||
uv run <script-name>
|
||
```
|
||
4. 打包项目
|
||
```
|
||
uv build
|
||
```
|
||
|
||
## AI协作指导规范
|
||
|
||
### 核心理念
|
||
- **讨论优先**：任何修改前必须充分讨论，达成共识
|
||
- **上下文明确**：具体到文件、行号和函数名
|
||
- **渐进式实施**：通过子任务分解，逐步完成复杂需求
|
||
- **可追溯性**：所有决策和修改都有明确记录
|
||
- **深度思考**：除非任务不涉及代码的修改，不然默认使用ultrathink模式
|
||
|
||
### 工作流程
|
||
|
||
#### 阶段1：需求理解与记录（必须执行）
|
||
用户提出需求后，立即在`docs/CLAUDE-temp.md`中记录：
|
||
- 原始需求和我的理解
|
||
- 相关文件和函数（具体到行号）
|
||
- 现有代码分析
|
||
- 潜在影响评估
|
||
- 任务复杂度判断（简单/复杂）
|
||
|
||
#### 阶段2：任务规划
|
||
**简单任务**（修改≤2个函数，≤50行）：
|
||
- 严禁拆分子任务
|
||
- 直接形成单一执行计划
|
||
|
||
**复杂任务**（修改≥3个函数或需新建文件）：
|
||
- 必须拆分为3-5个子任务
|
||
- 每个子任务可独立验证
|
||
- 按依赖关系排序
|
||
|
||
#### 阶段3：计划正式化
|
||
用户确认后，在`docs/CLAUDE-plan.md`中记录详细计划：
|
||
- 任务目标（30-50字）
|
||
- 所需上下文（文件::行号::函数名）
|
||
- 拟修改内容（具体到行）
|
||
- 测试指令
|
||
- 验收标准
|
||
|
||
#### 阶段4：实施与验证
|
||
- 严格按计划执行
|
||
- 在`docs/CLAUDE-activeContext.md`实时更新进度
|
||
- 遇到计划外情况立即停止并讨论
|
||
- 完成后运行所有测试指令
|
||
|
||
### Memory Bank系统
|
||
|
||
#### 更新机制
|
||
每个任务完成后，使用专门的SubAgent更新Memory Bank， SubAgent为memory-bank-synchronizer：
|
||
```
|
||
Task: memory-bank-synchronizer
|
||
功能: 更新所有Memory Bank文件，记录任务成果、决策和经验
|
||
```
|
||
|
||
### 工具使用原则与智能协作
|
||
|
||
#### 1. 基本操作策略
|
||
- **批量操作**：多个独立操作必须同时执行，提高效率
|
||
- **文件操作**：优先Edit而非Write，同文件多处修改用MultiEdit，新文件需明确理由
|
||
- **上下文管理**：合理分配主上下文和SubAgent的职责
|
||
|
||
#### 2. 上下文分层管理
|
||
- **主上下文**：负责用户对话、核心决策、当前计划制定
|
||
- **SubAgent**：承担大规模搜索、模式分析、依赖梳理等专门任务
|
||
- **协作原则**：主上下文保持聚焦，复杂分析任务交给专门SubAgent
|
||
|
||
#### 3. MCP工具集成策略
|
||
- **Context7 MCP**：遇到不熟悉或新版本第三方库时的首选工具
|
||
- 使用场景：库文档查询、API使用示例、版本兼容性确认
|
||
- 触发条件：代码中涉及未知库调用或需要确认具体用法
|
||
- **其他MCP工具**：根据具体需求选择合适的MCP服务
|
||
- 数据集访问、外部API调用、特定领域知识查询
|
||
|
||
#### 4. SubAgent选择策略
|
||
- **代码搜索类**：使用code-searcher进行深度代码分析
|
||
- **记忆银行更新**：任务完成后使用memory-bank-synchronizer
|
||
- **通用复杂任务**：使用general-purpose处理多步骤综合任务
|
||
|
||
### TodoWrite工具使用
|
||
**强制使用场景**：
|
||
- 任务包含3个以上步骤
|
||
- 复杂任务的子任务追踪
|
||
- 用户明确要求
|
||
|
||
**状态管理**：
|
||
- 同时只能有1个in_progress
|
||
- 完成立即标记completed
|
||
- 遇阻标记pending并说明
|
||
|
||
### 与编程规范的关系
|
||
- 编程规范定义"怎么写代码"
|
||
- AI指导规范定义"怎么理解和修改代码"
|
||
- 发生冲突时，编程规范优先
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|
||
|