enforced as code is written ML / DL research repos

Code that stays in spec, not just reviewed after.

A coding-standard enforcer for AI agents working inside a research codebase. It enforces two standards: a steady project framework that stays consistent, and healthy code — clear comments, sensible APIs, thorough modularization.

Get the skill → Read the install spec

§01 · 能力

What it does.

🏗️Project level: establish a clear, predictable structure and keep it that way.
🧩Models decoupled from systems, self-contained, fixed method order.
⚙️All experiment params in config files; code only reads config, no hardcoding.
🔁Reproducible: config, data version, code tag bound together, results regenerate.
🚦Mandatory gates (black / isort / ruff / mypy / pytest) pass before accept.
💬Code level: comments explain the thinking, sensible APIs, clean modularization.
🏛️Named architectures & pluggability: timm tiers, OpenMMLab, no if model=="...".
📦Ships as a package; CI runs style+type checks; small reviews, docs don't drift.
🧠Behavior discipline: think first, keep simple, surgical edits, goal-driven.
🔧Automaintained .gitignore: syncs with layout, keeps hand-written rules.
📂Run artifacts funnel into .cache/; nothing litters the repo root.
🤝Key principle: never deletes/rewrites your code — only moves or renames it.
📏Every rule is checkable, applied live as work proceeds, not just cited.

§02 · 场景

Two scenario examples.

A · build from zero

“Create a new research project here and add a model trained on CIFAR.”

The agent scaffolds the structure, then writes src/, configs/, and Hydra _target_ per the standard.

Agent 从骨架建结构，再按规范写 src/、configs/、Hydra _target_。

B · tidy an existing repo

“Tidy this repo: move code into the right dirs, turn training params into config, unify naming.”

The agent audits drift, then refactors/rename into compliance and re-runs the gates.

§03 · 参考

Reference projects.

Concern	关注领域	Basis	依据
Project structure & style	项目结构与写法	Lightning-Hydra-Template, Hydra, Google Python Style	Lightning-Hydra-Template、Hydra、Google Python Style
Model & component design	模型与组件设计	PyTorch Lightning Style, timm, OpenMMLab	PyTorch Lightning Style、timm、OpenMMLab
Reproducible experiments	可复现实验	Hydra, FAIR, SemVer, Git Flow, Meta Research	Hydra、FAIR、SemVer、Git Flow、Meta Research
Engineering habits & interfaces	工程习惯与接口	Software Engineering at Google, Scientific Python, research-code commenting standard	Software Engineering at Google、Scientific Python、科研代码注释规范
LLM coding discipline	LLM 编码纪律	Karpathy Skills	Karpathy Skills

§04 · 快速开始

Quick start.

Clone to a stable path (don't develop inside this copy); point the agent at SKILL.md:

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

~/ai-skills — bash

# clone the skill to a stable path# 克隆 skill 到稳定路径
git clone https://github.com/SaltGardenia/research-code-skill.git \
  ~/ai-skills/research-code-skill

# Claude Code — load the main file as a subagent# 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

Other agents (Kilo, Codex, etc.) keep the full folder: create a subagent / slash command / custom prompt pointing at the main file. Update: cd ~/ai-skills/research-code-skill && git pull.

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

Run the checker locally: first python -m pip install -r requirements.txt, then python scripts/audit_style.py ., python scripts/sync_gitignore.py ., bash scripts/run_gate.sh.

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

Code that stays in spec, not just reviewed after.

代码始终符合规范，而非事后才审查。

What it does.

能力列表。

Two scenario examples.

两个场景示例。

Reference projects.

参考项目。

Quick start.

快速开始。