🧪 科研代码 Skill

让科研代码库整洁、一致。Agent 边写边改，边应用标准。不做事后审查。 English →

✨ 能力列表

• 🚦 强制质量门（black / isort / ruff / mypy / pytest），变更接受前必须通过。
• ⚙️ 实验参数一律走配置文件，代码只从配置读取，杜绝硬编码。
• 🔁 实验可复现：配置、数据版本、代码 tag 三者绑定，结果可重生。
• 🏗️ 项目层面，建立一套清晰、可预期的结构并长期保持。
• 🧩 模型与系统分离，模型自包含，遵循固定方法顺序。
• 🏛️ 命名架构加可插拔：timm 分层、OpenMMLab 注册即用，拒绝 if model == "..." 分支。
• 💬 代码层面，注释讲清思路、API 设计合理、模块化完善。
• 📦 以可安装包交付，CI 跑风格与类型检查，小步评审、接口文档不漂移。
• 🧠 行为纪律：先想后写、保持简单、外科手术式改动、目标驱动执行。
• 📏 每条规范编码为可检查的规则，随工作实时应用与校验，而非仅引用文档。
• 🤝 关键原则：Agent 不会随意删除或重写你的代码，只移动、重命名以保持行为不变。
• 🔧 自动维护的 .gitignore：随目录结构变化同步忽略规则，不破坏手写规则。
• 📂 运行产物收口到 .cache/，仓库根不散落缓存文件。

🎯 两个场景示例

A. 从零搭建

“在这里新建一个科研项目，并添加一个在 CIFAR 上训练的模型。” Agent 从骨架建结构，再按规范写 src/、configs/、Hydra _target_。

B. 整理已有仓库

“整理这个仓库：代码归位，训练参数改配置，命名统一。” Agent 先审计偏离，再重构重命名至合规，重跑校验门确认。

📂 生成的项目结构（Lightning-Hydra-Template）

<project>/
├── .github                   <- Github Actions workflows
│
├── configs                   <- Hydra configs
│   ├── callbacks                <- Callbacks configs
│   ├── data                     <- Data configs
│   ├── debug                    <- Debugging configs
│   ├── experiment               <- Experiment configs
│   ├── extras                   <- Extra utilities configs
│   ├── hparams_search           <- Hyperparameter search configs
│   ├── hydra                    <- Hydra configs
│   ├── local                    <- Local configs
│   ├── logger                   <- Logger configs
│   ├── model                    <- Model configs
│   ├── paths                    <- Project paths configs
│   ├── trainer                  <- Trainer configs
│   │
│   ├── eval.yaml             <- Main config for evaluation
│   └── train.yaml            <- Main config for training
│
├── data                   <- Project data
│
├── logs                   <- Logs generated by hydra and lightning loggers
│
├── notebooks              <- Jupyter notebooks. Naming convention is a number (for ordering),
│                             the creator's initials, and a short `-` delimited description,
│                             e.g. `1.0-jqp-initial-data-exploration.ipynb`.
│
├── scripts                <- Shell scripts
│
├── src                    <- Source code
│   ├── data                     <- Data scripts
│   ├── models                   <- Model scripts
│   ├── utils                    <- Utility scripts
│   │
│   ├── eval.py                  <- Run evaluation
│   └── train.py                 <- Run training
│
├── tests                  <- Tests of any kind
│
├── .env.example              <- Example of file for storing private environment variables
├── .gitignore                <- List of files ignored by git
├── .pre-commit-config.yaml   <- Configuration of pre-commit hooks for code formatting
├── .project-root             <- File for inferring the position of project root directory
├── environment.yaml          <- File for installing conda environment
├── Makefile                  <- Makefile with commands like `make train` or `make test`
├── pyproject.toml            <- Configuration options for testing and linting
├── requirements.txt          <- File for installing python dependencies
├── setup.py                  <- File for installing project as a package
└── README.md

📚 参考项目

🚀 快速开始

克隆到稳定路径（不要在此副本内开发），让 Agent 指向 SKILL.md：

git clone https://github.com/SaltGardenia/research-code-skill.git ~/ai-skills/research-code-skill

Claude Code 用 subagent 加载主文件：

mkdir -p ~/.claude/agents
cat > ~/.claude/agents/research-code-skill.md <<'EOF'
---
name: research-code-skill
description: 用于以固定结构、统一规范搭建或整理科研（ML/DL）代码库。
---
When invoked, first read `~/ai-skills/research-code-skill/SKILL.md` and follow it as the governing workflow.
Read supporting files from `~/ai-skills/research-code-skill/` only when needed.
Do not replace this skill with a generic coding response.
EOF

其他 Agent（Kilo、Codex 等）同样保留完整文件夹，创建指向主文件的 subagent / slash command / 自定义 prompt。更新：cd ~/ai-skills/research-code-skill && git pull。

本地运行检查器：先 python -m pip install -r requirements.txt，再依次运行 python scripts/audit_style.py .、python scripts/sync_gitignore.py .、bash scripts/run_gate.sh。