Immutable. This exact content is served forever at /api/v1/blob/556a5d4b12c43a73.
--- name: research-code description: > Implement or strip-down university-lab deep-learning paper prototypes in top-conference GitHub style: few files, readable forward/loss, easy to ablate and reproduce. Use when the user asks to implement a method, 实现算法, 写论文代码, 科研代码, 顶会开源风格, 最小实现, 去工程化, research prototype, or to remove factory/registry/hook/ trainer/audit wrappers. Also use for /research-code. Not for production services, web APIs, Docker/CI/packaging, or building a generic training framework. version: 1.0.0 --- # Research Code You are writing **paper prototype code** for a university deep-learning lab, not a production system and not a framework. Optimize for: the idea is correct; the code is short; a PhD student can read `forward`, the loss, the batch, and the train loop in 10 minutes, then change it, ablate it, and reproduce it. Do not optimize for extensibility, plugins, audit, config platforms, error-recovery frameworks, or future-proof abstractions. ## When to use - Implement a paper method, baseline, or ablation - 写论文代码 / 科研原型 / 顶会开源风格 - Existing code is over-engineered; user wants 去工程化 or a single file - User is fighting factory / registry / hook / trainer / manager / audit code ## When not to use | Request | Do this instead | |---|---| | Web API, service, product backend | Ordinary software engineering | | Docker / CI / packaging / docs site | Only if the user named that deliverable | | MMDetection-style training framework | User must name that goal | | Abstract / idea / novelty / English polish | `awesome-abstract` / `idea-spark` / `scoop-check` / `nature-polishing` | ## Mode | User signal | Mode | |---|---| | 实现 / implement / 按论文写 | `implement` | | 去工程化 / 重构 / 删包装 | `refactor` | | 压成单文件 / one file | `compress` | | 检查是否过度工程化 / review | `review` | | 写进仓库规则 / AGENTS.md / .cursorrules | `repo-rules` | Default: `implement` if there is no code, `refactor` if they point at bloated code. ## Hard rules 1. Correctness of the research idea beats every style rule. 2. Clarity beats abstraction. Prefer functions. A class is allowed only when it is semantically required (`nn.Module`, a real Dataset). 3. Default layout is four files. Do not invent a framework. 4. Only the paper's new module is custom. Everything else is a library call. 5. Map important forward/loss lines to equation numbers and tensor shapes. 6. Expose only experiment knobs (dataset, lr, epochs, seed, hidden, dropout). 7. Reproducibility floor: seed, device, printed metrics, optional best checkpoint. 8. Never add a file, class, or directory "for later". 9. If the plan exceeds the budget, cut first. Do not write the bloated version. 10. After writing, run the checklist. A failed box is a bug; fix it before showing code. ## Complexity budget | Item | Default cap | |---|---| | Project code files | 5: `train.py` `model.py` `data.py` `utils.py` + optional `config.yaml` | | Custom classes | 3 | | Main implementation | 500 lines | | `compress` mode | one `train.py`, 400 lines | | Config surface | experiment knobs only | | Extra abstraction layers | 0 | Exceed a cap only when the algorithm itself is that large. Say so. Still add no wrappers. Every new file / class / function must answer: 1. Which paper part does this implement? 2. If deleted, does the method still run? 3. Can PyTorch / DGL / PyG / Hugging Face / torchvision / timm replace it? If (2) is yes and (1) is "none", delete it. ## Default tree ```text project/ train.py # argparse + train/val/test loop model.py # nn.Module; forward = the method data.py # load, split, batch/collate utils.py # seed, metric, save/load config.yaml # optional; experiment knobs only ``` Entry point: ```bash python train.py --dataset cora --lr 0.01 --epochs 200 ``` Do not create `src/`, `core/`, `engine/`, `runners/`, `modules/`, `builders/`, `tests/`, `docs/`, `.github/`, Docker, `setup.py`, `pyproject.toml`, `Makefile`, or a README — unless the user asked. Pattern names (`registry`, `factory`, `trainer`, …) are banned in the next section. ## Reuse first | Area | Use | Do not rewrite | |---|---|---| | Graphs | DGL or PyG (`dgl.graph` / `heterograph` / `Data`, `GraphConv`/`GATConv`/`GCNConv`, official loaders and samplers) | adjacency multiply, message-passing framework, custom sampler, graph Dataset ABC, graph collator, graph-norm utilities — unless that *is* the contribution | | NLP | Hugging Face Transformers / Datasets | custom tokenizer or Trainer stacks | | CV | torchvision / timm | custom image-pipeline frameworks | | Data | official / OGB / widely used loaders | one-off dataset frameworks | | Train | a plain loop in `train.py` | `Trainer` / `Engine` / `Runner` / `Manager` | | Optim | `torch.optim.Adam` / `AdamW` | optimizer wrappers | | Distributed | only if asked: `torchrun` / DDP / accelerate | homemade launchers | If the repo already imports DGL or PyG, follow that. If neither is present and the user did not name one, pick one, state it, stay consistent. Implement only what the paper actually proposes: a new layer, loss, sampling rule, prompt, or contrastive module. ## Forbidden unless the user names it - `Factory` / `Registry` / `register_module` / `build_from_config` - Plugin / Hook / Callback systems - `AuditLogger` / `ExperimentTracker` / `MetricManager` / `RunManager` - Pydantic / schema / config-validation layers - Custom exception hierarchies and blanket `try/except` - `BaseTrainer` / `BaseRunner` / `BaseModule` / `BaseEngine` and deep inheritance - Dependency injection - Generic `Trainer`, `Engine`, `Runner`, `Manager`, `Builder` - Web / REST / gRPC / servers - Docker, CI, packaging, docs, tests, formatter pipelines - Making every internal variable a CLI flag `print` of loss and metrics is fine. A `logging` package, wandb/MLflow wrapper, or audit trail is not, unless requested. ## Paper mapping On the important forward and loss: ```python # Eq. 3: h = sigma(A_hat @ X @ W) # X: [N, F_in], W: [F_in, F_out], h: [N, F_out] ``` In `data.py`, state the batch contract in one comment (keys, shapes, masks). Keep the loss formula at the call site, not inside a `LossManager`. ## Workflow Execute in order. ### Phase 1 — Min plan (always) Do not create files yet. Write: ```text CONTRIBUTION the 1–3 things that are actually new REUSE what PyTorch / DGL / PyG / HF / timm already provides CUSTOM only the files/functions that implement CONTRIBUTION TREE the ≤5 files and one-line role each BUDGET files / classes / estimated lines RUN python train.py --... CUTS wrappers you refused to add ``` Then: - Over budget, or the only honest plan is a framework → stop. Propose cuts. - User said 先方案 / 等我确认 → wait. - Otherwise continue in the same turn. If a reference repo is given, copy *style* (layout, entry, model/data/hparams), never paste their code. ### Phase 2 — Implement or transform `implement`: write the tree. Train loop stays in `train.py`. Loss and metric are explicit. Open [references/style-canon.md](references/style-canon.md) when you need the GNN sample of this style. `refactor`: delete non-research wrappers; merge tiny modules; keep the algorithm; emit a deletion list (`path — why it was not required`). The result must still run. `compress`: one `train.py` with model + data + train + eval, no wrappers, ≤400 lines, `python train.py` runs. `review`: no edits unless asked. Run the checklist. List concrete deletions. `repo-rules`: write [references/repo-agents-snippet.md](references/repo-agents-snippet.md) into the project `AGENTS.md`. Add `.cursorrules` only if the user uses Cursor and asked for it. Do not invent extra rule files. ### Phase 3 — Self-audit Run the checklist. Any failed box → fix or delete, then re-check. Do not ship a failed audit. ### Phase 4 — Deliver Return, in order: 1. **Tree** — files touched and their roles 2. **Run** — exact command 3. **Deps** — the few libraries 4. **Code** — the files (or the review/deletion list in `review`) 5. **Map** — which functions are CONTRIBUTION vs REUSE 6. **Audit** — checklist, plus deletions or refused wrappers ## Checklist ```text [ ] python train.py ... runs the experiment [ ] Only research-necessary files exist [ ] No factory / registry / hook / callback / audit / manager / engine [ ] Config is argparse or a small YAML of experiment knobs [ ] No extra abstraction layer [ ] Libraries used instead of rewritten utilities [ ] model.forward maps to the paper [ ] Batch contract is obvious [ ] Loss is explicit [ ] Metric is explicit [ ] Important tensors have shapes; important formulas have Eq. numbers [ ] No "for future extension" interfaces [ ] A new PhD student can follow the main path in 10 minutes ``` The last box is the acceptance test.