agentleFS
ZhangyanboZhangyanbo/vibe-research-skill/skills/vibe-research-coding/SKILL.md

vibe-research-coding

Skill27 starsChanged 3 months agoMITView on GitHub

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.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 6 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈6

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    KISS + YAGNI: write the most direct implementation.

    line 12
  2. Distinctive:

    Locality of Behavior: keep related logic together.

    line 13
  3. Very specific:

    Plain beats clever: never use tricks that defeat reading or static analysis (exec or dynamic attribute creation, global-state closures, …

    line 15
  4. Distinctive:

    No dead code: no commented-out blocks kept "just in case", no leftover debug prints.

    line 16
  5. Distinctive:

    All code comments in English.

    line 18
  6. Distinctive:

    Keep each file to ~200 lines or fewer.

    line 33
  7. Distinctive:

    Keep each folder to ~7 code files or fewer.

    line 35

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.