docs: 大幅更新开发规范和AI协作指导
- 添加绝对强制性规范声明和AI协作流程规范 - 详细完善编程规范，包含违反后果和理由说明 - 新增AI协作指导规范，定义4阶段工作流程 - 完善Memory Bank系统和工具使用原则 - 强化MVP项目特性，明确快速开发要求
This commit is contained in:
parent
a61fdc0437
commit
08a3f414b9
112
CLAUDE.md
112
CLAUDE.md
@ -4,7 +4,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
|
|||||||
|
|
||||||
## 项目概述
|
## 项目概述
|
||||||
|
|
||||||
MedResearcher 是一个给予用户输入的自动实验平台，其会给予用户指定的研究目标，通过mcp访问特定数据集并撰写代码以构建实验。
|
MedResearcher 是一个给予用户输入的自动实验平台，其会给予用户指定的研究目标，通过mcp访问特定数据集并撰写代码以构建实验。该项目现在是一个MVP项目，需要保证快速开发。
|
||||||
|
|
||||||
## 技术栈
|
## 技术栈
|
||||||
1. 后端编程语言：Python
|
1. 后端编程语言：Python
|
||||||
@ -39,62 +39,71 @@ MedResearcher 是一个给予用户输入的自动实验平台，其会给予用
|
|||||||
|
|
||||||
## 开发注意事项
|
## 开发注意事项
|
||||||
|
|
||||||
|
### ⚠️ 绝对强制性规范 - 违反将导致项目失败
|
||||||
|
|
||||||
|
**AI协作流程规范**（绝对不可跳过）：
|
||||||
|
- **强制执行4阶段流程**：任何涉及代码修改的请求必须完成 需求记录→任务规划→计划正式化→实施验证
|
||||||
|
- **讨论优先原则**：禁止在未完成需求分析和计划制定前直接编码
|
||||||
|
- **违反后果**：跳过流程将导致代码质量无法保证、项目架构被破坏、维护成本急剧上升
|
||||||
|
|
||||||
|
**理由**：软件项目80%的失败源于需求理解偏差和无计划修改。规范化流程是项目成功的生命线。
|
||||||
|
|
||||||
### 必须遵循的编程规范
|
### 必须遵循的编程规范
|
||||||
|
|
||||||
1. **注释和文档规范**
|
1. **注释和文档规范**（违反将导致代码无法维护）
|
||||||
- 所有注释使用中文
|
- **绝对强制**所有注释使用中文 - 理由：统一语言避免理解歧义，提高团队协作效率
|
||||||
- 关键代码逻辑必须添加行内注释
|
- **严格要求**关键代码逻辑必须添加行内注释 - 理由：无注释代码在6个月后连作者都无法理解
|
||||||
- 所有函数和类必须添加docstring，说明功能、参数和返回值
|
- **绝对不允许**函数和类缺少docstring - 理由：缺少文档的代码等于技术债务
|
||||||
- 复杂算法需要详细说明思路
|
- **强制执行**复杂算法详细说明思路 - 理由：算法逻辑不清将导致后续无法优化和修复
|
||||||
|
|
||||||
2. **命名规范**
|
2. **命名规范**（违反将导致代码混乱不堪）
|
||||||
- 变量名、函数名：使用 snake_case
|
- **严格执行**变量名、函数名使用snake_case - 理由：命名不一致破坏代码可读性
|
||||||
- 类名：使用 PascalCase
|
- **绝对遵守**类名使用PascalCase - 理由：违反Python社区标准影响代码专业性
|
||||||
- 常量：使用 UPPER_SNAKE_CASE
|
- **强制要求**常量使用UPPER_SNAKE_CASE - 理由：常量不明显将导致误修改引发bug
|
||||||
- 禁止使用中文变量名
|
- **绝对禁止**使用中文变量名 - 理由：中文变量名在不同环境下可能出现编码问题
|
||||||
|
|
||||||
3. **代码修改限制**
|
3. **代码修改限制**（违反将导致系统不稳定）
|
||||||
- 单次修改不超过200行代码
|
- **绝对禁止**单次修改超过200行代码 - 理由：大规模修改导致难以追踪错误源，增加回滚风险
|
||||||
- 单次修改不超过3个文件
|
- **严格限制**单次修改不超过3个文件 - 理由：多文件修改增加依赖复杂度，容易引入连锁错误
|
||||||
- 严格遵循最小修改原则
|
- **强制执行**最小修改原则 - 理由：额外修改增加引入bug的概率，违背单一职责
|
||||||
- 绝对不允许修改与指定任务无关的代码
|
- **绝对不允许**修改与任务无关的代码 - 理由：破坏代码的可追溯性和变更管理
|
||||||
- 每次修改只针对当前任务的必要部分
|
- **严格要求**每次修改只针对当前任务 - 理由：混合修改导致commit历史混乱
|
||||||
- 优先修改而非新建：能通过修改解决的问题不新建文件
|
- **优先原则**修改而非新建文件 - 理由：过度创建文件增加项目复杂度和维护成本
|
||||||
|
|
||||||
4. **代码风格规范**
|
4. **代码风格规范**（违反将导致代码难以阅读）
|
||||||
- 单行代码长度限制：120字符
|
- **严格限制**单行代码120字符 - 理由：超长行代码在review和调试时难以阅读
|
||||||
- 使用类型提示（type hints）提高代码可读性
|
- **强制要求**使用类型提示 - 理由：无类型提示的代码在运行时才暴露类型错误，增加调试成本
|
||||||
- 导入语句按照：标准库 → 第三方库 → 本地模块 的顺序排列
|
- **绝对遵守**导入语句排序规范 - 理由：混乱的导入顺序导致依赖关系不清晰
|
||||||
|
|
||||||
5. **错误处理和日志**
|
5. **错误处理和日志**（违反将导致系统崩溃）
|
||||||
- 必须使用 try-except 进行全面的错误捕获
|
- **绝对强制**使用try-except全面错误捕获 - 理由：未捕获异常导致程序崩溃，影响用户体验
|
||||||
- 使用 logging 模块替代 print 进行日志输出
|
- **严格禁止**使用print进行输出 - 理由：print输出无法控制级别和格式，生产环境下无法管理
|
||||||
- 日志级别：开发时使用DEBUG，生产环境使用INFO
|
- **强制执行**日志级别规范 - 理理：错误的日志级别导致关键信息丢失或日志滚滥
|
||||||
- 绝对不允许填写任何默认值或假设值
|
- **绝对禁止**使用默认值或假设值 - 理由：默认值掩盖真实错误，导致问题被延迟发现
|
||||||
- 出现错误时应抛出明确的异常信息，便于问题排查
|
- **强制要求**抛出明确异常信息 - 理由：模糊错误信息导致问题排查时间成倍增长
|
||||||
- 宁可程序报错，也不要用默认值掩盖潜在问题
|
- **核心原则**宁可程序报错，绝不用默认值掩盖 - 理由：隐藏的错误比明显的崩溃更危险
|
||||||
|
|
||||||
6. **依赖管理**
|
6. **依赖管理**（违反将导致项目臃胀）
|
||||||
- 优先使用标准库
|
- **强制优先**使用标准库 - 理由：标准库稳定性高，减少第三方依赖风险
|
||||||
- 新增第三方依赖时需在注释中说明用途
|
- **绝对强制**新增依赖必须注释说明用途 - 理由：未知用途的依赖增加安全风险和维护成本
|
||||||
- 使用 uv 管理所有依赖
|
- **严格要求**使用uv管理所有依赖 - 理由：不同的包管理器导致依赖冲突和环境不一致
|
||||||
|
|
||||||
7. **资源管理**
|
7. **资源管理**（违反将导致资源泄漏）
|
||||||
- 文件操作必须使用 with 语句
|
- **绝对强制**文件操作使用with语句 - 理由：不使用with导致文件句柄泄漏，系统资源耗尽
|
||||||
- 网络请求设置合理超时（建议30秒）
|
- **严格要求**网络请求设置30秒超时 - 理由：无超时设置导致程序无限等待，资源被占用
|
||||||
- 大文件使用流式处理避免内存溢出
|
- **强制执行**大文件流式处理 - 理由：一次性加载大文件导致内存溢出，系统崩溃
|
||||||
|
|
||||||
8. **Git提交规范**
|
8. **Git提交规范**（违反将导致版本管理混乱）
|
||||||
- commit message 格式：`<类型>: <描述>`
|
- **严格遵守**commit message格式 - 理由：不规范的commit信息导致版本历史无法理解和回滚
|
||||||
- 类型包括：feat(新功能)、fix(修复)、refactor(重构)、docs(文档)、test(测试)
|
- **强制使用**指定类型前缀 - 理由：类型清晰有助于自动化部署和变更追踪
|
||||||
|
|
||||||
9. **测试规范**
|
9. **测试规范**（违反将导致项目无法维护）
|
||||||
- 不允许撰写独立的测试用例文件或测试代码
|
- **绝对禁止**撰写独立测试文件 - 理由：过多测试文件增加项目复杂度，与MVP理念相反
|
||||||
- 通过直接运行对应的主文件（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__":` 块，其他所有工具模块、库文件绝对不允许包含此类测试代码
|
- **绝对禁止**工具模块包含main函数 - 理由：工具模块包含main函数破坏模块化设计原则
|
||||||
- 函数可以被其他模块调用，不一定要在主文件中直接调用
|
- **允许灵活性**函数可被其他模块调用 - 理由：保持代码的可重用性
|
||||||
- 作为MVP项目，重点关注理想情况下的功能实现，而非鲁棒性
|
- **MVP原则**重点关注功能实现而非鲁棒性 - 理由：MVP阶段过度关注鲁棒性影响开发速度
|
||||||
|
|
||||||
**修改前验证**：
|
**修改前验证**：
|
||||||
```bash
|
```bash
|
||||||
@ -112,6 +121,15 @@ MedResearcher 是一个给予用户输入的自动实验平台，其会给予用
|
|||||||
mypy <修改的文件>.py --ignore-missing-imports
|
mypy <修改的文件>.py --ignore-missing-imports
|
||||||
```
|
```
|
||||||
|
|
||||||
|
### ⚠️ 总体声明
|
||||||
|
**这些编程规范是项目成功的基石，违反任何一条都可能导致：**
|
||||||
|
- 代码质量严重下降，技术债务累积
|
||||||
|
- 系统不稳定，生产环境事故
|
||||||
|
- 开发效率大幅降低，维护成本激增
|
||||||
|
- 团队协作困难，项目进度失控
|
||||||
|
|
||||||
|
**所有规范均为硬性要求，无商量余地。遵循规范是专业开发者的基本素养。**
|
||||||
|
|
||||||
### 代码组织原则
|
### 代码组织原则
|
||||||
- 新功能优先集成到现有主文件中
|
- 新功能优先集成到现有主文件中
|
||||||
- 只有在功能独立且复杂时才创建新的模块文件
|
- 只有在功能独立且复杂时才创建新的模块文件
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user