iomgaa 8213ae9a55 feat: 初始化MedResearcher项目

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

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

6.3 KiB

Raw Blame History

CLAUDE.md

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

项目概述

MedResearcher 是一个给予用户输入的自动实验平台，其会给予用户指定的研究目标，通过mcp访问特定数据集并撰写代码以构建实验。

技术栈

后端编程语言：Python
python管理器：uv
爬虫工具：Crawl4AI

各个模块的主文件

论文爬取主文件: papers_crawler.py
pdf解析主文件: pdf_parser.py
实验运行主文件: experiment_runner.py

开发注意事项

必须遵循的编程规范

注释和文档规范
- 所有注释使用中文
- 关键代码逻辑必须添加行内注释
- 所有函数和类必须添加docstring，说明功能、参数和返回值
- 复杂算法需要详细说明思路
命名规范
- 变量名、函数名：使用 snake_case
- 类名：使用 PascalCase
- 常量：使用 UPPER_SNAKE_CASE
- 禁止使用中文变量名
代码修改限制
- 单次修改不超过200行代码
- 单次修改不超过3个文件
- 严格遵循最小修改原则
- 绝对不允许修改与指定任务无关的代码
- 每次修改只针对当前任务的必要部分
- 优先修改而非新建：能通过修改解决的问题不新建文件
代码风格规范
- 单行代码长度限制：120字符
- 使用类型提示（type hints）提高代码可读性
- 导入语句按照：标准库 → 第三方库 → 本地模块的顺序排列
错误处理和日志
- 必须使用 try-except 进行全面的错误捕获
- 使用 logging 模块替代 print 进行日志输出
- 日志级别：开发时使用DEBUG，生产环境使用INFO
- 绝对不允许填写任何默认值或假设值
- 出现错误时应抛出明确的异常信息，便于问题排查
- 宁可程序报错，也不要用默认值掩盖潜在问题
依赖管理
- 优先使用标准库
- 新增第三方依赖时需在注释中说明用途
- 使用 uv 管理所有依赖
资源管理
- 文件操作必须使用 with 语句
- 网络请求设置合理超时（建议30秒）
- 大文件使用流式处理避免内存溢出
Git提交规范
- commit message 格式：<类型>: <描述>
- 类型包括：feat(新功能)、fix(修复)、refactor(重构)、docs(文档)、test(测试)
测试规范
- 不允许撰写独立的测试用例文件或测试代码
- 通过直接运行对应的主文件（papers_crawler.py、pdf_parser.py 或 experiment_runner.py）进行功能测试
- 主文件的 if __name__ == "__main__": 块中应包含基本的功能调用示例
- 函数可以被其他模块调用，不一定要在主文件中直接调用
- 作为MVP项目，重点关注理想情况下的功能实现，而非鲁棒性
修改前验证：
```
# 确保现有功能正常
uv run <主文件>.py --test-mode
```
修改后验证：
```
# 功能测试
uv run <主文件>.py --test-mode
# 语法检查
python -m py_compile <修改的文件>.py
# 如有类型提示，运行类型检查
mypy <修改的文件>.py --ignore-missing-imports
```

代码组织原则

新功能优先集成到现有主文件中
只有在功能独立且复杂时才创建新的模块文件
保持代码结构简洁，避免过度模块化

uv常用指令

初始化项目
```
uv init
```
安装依赖
```
uv add <package-name>
```
运行项目
```
uv run <script-name>
```
打包项目
```
uv build
```

AI协作指导规范

核心理念

讨论优先：任何修改前必须充分讨论，达成共识
上下文明确：具体到文件、行号和函数名
渐进式实施：通过子任务分解，逐步完成复杂需求
可追溯性：所有决策和修改都有明确记录

工作流程

阶段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系统

文件结构

/docs/
├── CLAUDE-temp.md          # 临时讨论和分析
├── CLAUDE-plan.md          # 当前任务计划
├── CLAUDE-activeContext.md # 会话状态跟踪
├── CLAUDE-patterns.md      # 代码模式记录
├── CLAUDE-decisions.md     # 决策记录
├── CLAUDE-troubleshooting.md # 问题解决方案
└── CLAUDE-config-variables.md # 配置变量参考

更新机制

每个任务完成后，使用专门的SubAgent更新Memory Bank， SubAgent为memory-bank-synchronizer：

Task: memory-bank-synchronizer
功能: 更新所有Memory Bank文件，记录任务成果、决策和经验

工具使用原则

批量操作：多个独立操作必须同时执行
上下文管理：
- 主上下文：用户对话、决策、当前计划
- SubAgent：大规模搜索、模式分析、依赖梳理
文件操作：
- 优先Edit而非Write
- 同文件多处修改用MultiEdit
- 新文件需明确理由

TodoWrite工具使用

强制使用场景：

任务包含3个以上步骤
复杂任务的子任务追踪
用户明确要求

状态管理：

同时只能有1个in_progress
完成立即标记completed
遇阻标记pending并说明

与编程规范的关系

编程规范定义"怎么写代码"
AI指导规范定义"怎么理解和修改代码"
发生冲突时，编程规范优先

6.3 KiB Raw Blame History Unescape Escape