cf-research-pipeline

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 时必须同步记录。