| name | cf-research-pipeline |
| description | 当需要从零规划、搭建或推进单人科研代码项目 pipeline 时触发。适用于明确项目目标、确认 CPU/GPU/内存/存储资源、记录资源约束、查找 common_functions 中可复用函数、创建 Python 文件骨架、梳理函数调用关系、按依赖顺序实现函数、做 shape/smoke test、补 README。 |
CF Research Pipeline
触发后按固定顺序执行：意图确认、骨架搭建、分步实现、文档生成。新增较大功能、从零搭项目、重排 pipeline 时都必须走完该流程；只允许跳过已明确完成且有记录的子项。
1. 意图确认
写代码前必须确认并记录以下信息：
- 项目目标。
- 输入、输出、核心指标或需要复现的结果。
- 当前机器或目标机器的 CPU、GPU、内存、存储资源；若项目文件已有当前记录，只核对不重复询问。
- 用户给本项目设定的内存上限和存储上限；或本轮推进希望占用的存储上限。
common_functions、common_func 或当前项目共享工具目录中可复用的函数；记录函数名、路径和用途。
把资源信息、资源上限、可复用函数写入项目文件夹内已有的记录文件；若没有记录文件，写入 README.md。目标、输入输出、资源上限任一项不清楚时，不写完整实现，只写骨架和明确 TODO。
2. 骨架搭建
写函数体前必须先固定文件结构和调用关系：
- 创建必要文件夹和
.py 文件，沿用当前仓库或项目已有目录习惯。
- 确立模块调用关系：入口脚本只组织流程；工具函数负责核心计算、I/O、分析或绘图。
- 先定义函数名和函数签名，再补函数体。
- 函数名必须自解释；docstring 只写输入、输出、shape 和关键假设。
- 输入输出关系在骨架阶段写定；路径、随机种子、设备、批大小、任务 id、dtype 必须通过参数或配置传入。
- 确认虚拟环境依赖已安装，并验证模块间 import 能通过。
- 已有参数文件、配置文件或路径 helper 时必须复用；禁止在多个脚本中重复硬编码同一类路径。
骨架阶段只固定文件位置、函数边界和调用方向，不写复杂内部逻辑。
3. 分步实现
按依赖顺序补全函数体：
- 先实现数据读取、预处理、核心计算、保存结果。
- 再实现分析、绘图、批处理、参数扫描。
- 需要大幅修改文件结构或函数边界时，停止实现，回到骨架搭建步骤。
- 每完成一个
.py 文件，立刻做轻量测试。
- 测试只覆盖科研项目核心约束：shape、dtype、device、索引长度、随机种子、保存路径、结果可重新读取。
- 长任务必须先用小规模参数做 smoke test，通过后再运行完整参数。
- 输出大结果前必须检查预计目录大小和单文件大小；超出存储上限时必须分块保存、减少默认输出或停止并询问。
检查代码只临时存在，检查完成后立即删除，不留在正式文件中。
assert x.shape == expected_shape
assert y.dtype == expected_dtype
assert np.isfinite(loss_value)
4. 文档生成
最小 pipeline 跑通后必须更新 README，内容只保留复现所需信息：
- 项目一句话目标。
- 主要入口脚本和运行顺序。
- 关键输入、输出和结果目录。
- 关键依赖或虚拟环境名称。
- CPU/GPU/内存/存储相关约束或建议。
- 已复用的 common functions 或重要 helper 文件。
- 已通过的最小测试或 smoke test 命令。
项目有 memory.md 或 storage.md 时必须同步记录。
