# Vibe Research Coding

> Best practices for writing elegant, readable research code - direct implementations, locality of behavior, fail-fast, strict size limits, clean separation of experiment and plotting code. Use whenever writing or refactoring code in a research project, creating new experiment scripts, or organizing a source tree.

- Skill: `zhangyanbo/vibe-research-coding` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zhangyanbo/vibe-research-coding`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zhangyanbo/vibe-research-coding/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: Zhangyanbo (https://skillmd.com/u/zhangyanbo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/zhangyanbo/vibe-research-coding

---


# Elegant Coding

Best practices for research code: readability over abstraction. Every constraint here shares one premise: **the user reads all of this code**. None of it applies to directories the user never reads (such as `data/` and `tmp/`).

## Base style

- **KISS + YAGNI**: write the most direct implementation; no generic utilities, no future-proofing.
- **Locality of Behavior**: keep related logic together. A 60-line function that clearly mirrors a formula's steps beats a 10-file inheritance chain.
- **Code reads like the algorithm**: the main loop should read like the steps of the math it implements. Someone who knows the method should recognize it in the code at a glance.
- **Plain beats clever**: never use tricks that defeat reading or static analysis (`exec` or dynamic attribute creation, global-state closures, type-sniffing branches), even when the plain version is longer.
- **No dead code**: no commented-out blocks kept "just in case", no leftover debug prints. Delete it; git remembers.
- **Fail-fast**: assert dimensions, check for NaN, crash immediately on bad data. A crash is useful debugging information. No defensive code: no meaningless try/except or if/else fallbacks.
- All code comments in English.

## Structure

- The top level of `src/` holds experiment entry scripts only; reusable components go into semantically named packages.
- **Experiments within a project follow one uniform structure** (entry script → training/compute module → results directory → plotting module): the first experiment that takes shape is the model for all later ones. No freelancing.
- **Keep experiment code and plotting code separate**: the experiment computes and writes its data to disk; plotting is a separate script that reads that data. Changing a figure then never requires re-running the experiment, and the data behind every figure is guaranteed to exist on disk. Entry scripts carry no `--replot`-style switches. Careful: do not git-track very large output files.
- **Keep a clean boundary between evaluation code and the system it evaluates**: a scorer must never be imported by the thing it scores. When judge and judged are entangled, the evaluation cannot be trusted.

## Reproducibility pitfalls

- A fixed random seed does not mean reproducible: on CUDA, `torch.manual_seed` alone is not enough; explicit determinism settings (cudnn deterministic, etc.) are required. Measured fact: the same seed can diverge by ten orders of magnitude within a few hundred steps.

## Size limits (so the user can read a file in one sitting and scan a folder at a glance)

- Keep each file to ~200 lines or fewer; split or abstract beyond that.
  Exception: files that purely enumerate similar items (parameter tables, formula lists) have no limit.
- Keep each folder to ~7 code files or fewer; beyond that, create semantically named subfolders as a Python package.
  The intent of this rule is scannability, not the number itself. It does not apply to folders the user never reads.
- The failure mode to avoid is the god-file: a 1000-plus-line class holding 200-line methods, with plotting, training, and bookkeeping all fused together. One concept per small file; separate concerns instead of fusing them.