MedResearcher/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

项目概述

MedResearcher 是一个给予用户输入的自动实验平台，其会给予用户指定的研究目标，通过mcp访问特定数据集并撰写代码以构建实验。该项目现在是一个MVP项目，需要保证快速开发。

技术栈

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 # 配置变量参考

开发注意事项

⚠️ 绝对强制性规范 - 违反将导致项目失败

AI协作流程规范（绝对不可跳过）：

• 强制执行4阶段流程：任何涉及代码修改的请求必须完成 需求记录→任务规划→计划正式化→实施验证
• 讨论优先原则：禁止在未完成需求分析和计划制定前直接编码
• 违反后果：跳过流程将导致代码质量无法保证、项目架构被破坏、维护成本急剧上升

理由：软件项目80%的失败源于需求理解偏差和无计划修改。规范化流程是项目成功的生命线。

必须遵循的编程规范

1. 注释和文档规范（违反将导致代码无法维护）

   • 绝对强制所有注释使用中文 - 理由：统一语言避免理解歧义，提高团队协作效率
   • 严格要求关键代码逻辑必须添加行内注释 - 理由：无注释代码在6个月后连作者都无法理解
   • 绝对不允许函数和类缺少docstring - 理由：缺少文档的代码等于技术债务
   • 强制执行复杂算法详细说明思路 - 理由：算法逻辑不清将导致后续无法优化和修复

2. 命名规范（违反将导致代码混乱不堪）

   • 严格执行变量名、函数名使用snake_case - 理由：命名不一致破坏代码可读性
   • 绝对遵守类名使用PascalCase - 理由：违反Python社区标准影响代码专业性
   • 强制要求常量使用UPPER_SNAKE_CASE - 理由：常量不明显将导致误修改引发bug
   • 绝对禁止使用中文变量名 - 理由：中文变量名在不同环境下可能出现编码问题

3. 代码修改限制（违反将导致系统不稳定）

   • 绝对禁止单次修改超过200行代码 - 理由：大规模修改导致难以追踪错误源，增加回滚风险
   • 严格限制单次修改不超过3个文件 - 理由：多文件修改增加依赖复杂度，容易引入连锁错误
   • 强制执行最小修改原则 - 理由：额外修改增加引入bug的概率，违背单一职责
   • 绝对不允许修改与任务无关的代码 - 理由：破坏代码的可追溯性和变更管理
   • 严格要求每次修改只针对当前任务 - 理由：混合修改导致commit历史混乱
   • 优先原则修改而非新建文件 - 理由：过度创建文件增加项目复杂度和维护成本

4. 代码风格规范（违反将导致代码难以阅读）

   • 严格限制单行代码120字符 - 理由：超长行代码在review和调试时难以阅读
   • 强制要求使用类型提示 - 理由：无类型提示的代码在运行时才暴露类型错误，增加调试成本
   • 绝对遵守导入语句排序规范 - 理由：混乱的导入顺序导致依赖关系不清晰

5. 错误处理和日志（违反将导致系统崩溃）

   • 绝对强制使用try-except全面错误捕获 - 理由：未捕获异常导致程序崩溃，影响用户体验
   • 严格禁止使用print进行输出 - 理由：print输出无法控制级别和格式，生产环境下无法管理
   • 强制执行日志级别规范 - 理理：错误的日志级别导致关键信息丢失或日志滚滥
   • 绝对禁止使用默认值或假设值 - 理由：默认值掩盖真实错误，导致问题被延迟发现
   • 强制要求抛出明确异常信息 - 理由：模糊错误信息导致问题排查时间成倍增长
   • 核心原则宁可程序报错，绝不用默认值掩盖 - 理由：隐藏的错误比明显的崩溃更危险

6. 依赖管理（违反将导致项目臃胀）

   • 强制优先使用标准库 - 理由：标准库稳定性高，减少第三方依赖风险
   • 绝对强制新增依赖必须注释说明用途 - 理由：未知用途的依赖增加安全风险和维护成本
   • 严格要求使用uv管理所有依赖 - 理由：不同的包管理器导致依赖冲突和环境不一致

7. 资源管理（违反将导致资源泄漏）

   • 绝对强制文件操作使用with语句 - 理由：不使用with导致文件句柄泄漏，系统资源耗尽
   • 严格要求网络请求设置30秒超时 - 理由：无超时设置导致程序无限等待，资源被占用
   • 强制执行大文件流式处理 - 理由：一次性加载大文件导致内存溢出，系统崩溃

8. Git提交规范（违反将导致版本管理混乱）

   • 严格遵守commit message格式 - 理由：不规范的commit信息导致版本历史无法理解和回滚
   • 强制使用指定类型前缀 - 理由：类型清晰有助于自动化部署和变更追踪

9. 测试规范（违反将导致项目无法维护）

   • 绝对禁止撰写独立测试文件 - 理由：过多测试文件增加项目复杂度，与MVP理念相反
   • 强制要求通过主文件进行功能测试 - 理由：集中式测试简化操作流程
   • 严格规定主文件必须包含功能示例 - 理由：无示例的代码无法快速验证功能
   • 绝对禁止工具模块包含main函数 - 理由：工具模块包含main函数破坏模块化设计原则
   • 允许灵活性函数可被其他模块调用 - 理由：保持代码的可重用性
   • MVP原则重点关注功能实现而非鲁棒性 - 理由：MVP阶段过度关注鲁棒性影响开发速度

   修改前验证：

   # 确保现有功能正常
   uv run <主文件>.py --test-mode
   

   修改后验证：

   # 功能测试
   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指导规范定义"怎么理解和修改代码"
• 发生冲突时，编程规范优先