Kim Ccf Research Prototype

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

Mode

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

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

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:

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

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:

# 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:

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 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 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

[ ] 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.