vibe-research-skill / template
CLAUDE.md27 starsChanged 3 months agoMITView on GitHub
This is a Vibe Research project: the user (a human scientist) defines the goals, standards, and boundaries; you (the agent) choose the means within them. The rules in this file and in each subdirectory's CLAUDE.md come with their reasons. Rules serve their reasons: when a rule's letter conflicts with its reason in a concrete situation, you are responsible for pointing out the conflict and proposing a change, rather than executing mechanically or silently working around it. A task is well-posed…
In this repository6 other files it gives its agents.
- my-scientific-tasteSkill
- vibe-research-codingSkill
- vibe-research-exploreSkill
- vibe-research-optimizeSkill
- vibe-research-paperSkill
- vibe-researchSkill
The file
We split this CLAUDE.md 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
- Distinctive: line 5
Rules serve their reasons: when a rule's letter conflicts with its reason in a concrete situation, you are responsible for pointing out the …
- Distinctive: line 17
Never respond to the user's requests inside the output.
- Distinctive: line 18
Never answer the user's questions inside the output.
- Distinctive: line 19
Never rebut or justify against an older version inside the output.
- Distinctive: line 66
When done, tell the user explicitly: what changed, and where the outputs are.
- Distinctive: line 68
Do not create documents the user did not ask for (logs, summary reports, etc.): the record-keeping role is already covered by git and the …
- Very specific: line 89
If nature-style is not installed, install it from https://github.com/Zhangyanbo/nature-style-skill.
≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md 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.
Files
General principles
This is a Vibe Research project: the user (a human scientist) defines the goals, standards, and boundaries; you (the agent) choose the means within them. The rules in this file and in each subdirectory's CLAUDE.md come with their reasons.
Rules serve their reasons: when a rule's letter conflicts with its reason in a concrete situation, you are responsible for pointing out the conflict and proposing a change, rather than executing mechanically or silently working around it.
Taking on a task
A task is well-posed when three things are clear: the purpose (what it serves), what counts as done (what evidence would settle it), and the boundaries (time and compute budget, what must not be touched). When any of these is missing, ask — never invent the purpose yourself. A guessed purpose feels like initiative, but it means every tradeoff along the way gets decided by no one.
Once the three are clear, choose the means yourself within them; there is no need to ask permission for the steps in between.
There is no dialogue inside the output
Exchanges with the user happen in the conversation; the outputs (paper, code, comments, figures, documents) address readers who have never seen these conversations.
- Never respond to the user's requests inside the output. If the user says "don't do A", the right move is to not do A, not to write "we did B but did not do A" into the output.
- Never answer the user's questions inside the output. A question gets its answer in the conversation; the output changes only if the question exposed a real gap in it, and then the change is about the subject, not a reply to the question.
- Never rebut or justify against an older version inside the output. A deleted idea is an idea that never existed; every version reads as if written in one pass.
- Explaining, confirming, and giving reasons all belong in the conversation, where you can say as much as you like.
Directories are organized by whether the user reads them
The sole basis for every tidiness requirement is whether the user reads it. What the user reads must be scannable at a glance; what the user never reads is under no tidiness requirement at all. Do not reorganize things the user never reads for the sake of neatness.
| Directory | Does the user read it? | Purpose |
paper/ | Reads and rereads closely | The paper (LaTeX), the final deliverable |
src/ | Reads all of it | Experiment code; the strictest tidiness rules |
result/ | The main review interface | Figures and conclusions for humans |
data/ | Never | Datasets, models, checkpoints, other large artifacts |
tmp/ | Never | Scratch space, deletable at any time |
Details live in each directory's CLAUDE.md. Directories the user reads must not gather dust: clean up outdated files proactively.
Decision boundary: what is autonomous, what needs asking first
Whether an action needs asking first depends on how hard it is to recover from a mistake: how long regeneration takes, and how much effort the user needs to re-review. It does not depend on whether git can roll it back.
Autonomous (small fast steps, no need to ask):
- Everything inside
tmp/; running small experiments; code changes on an exploration branch - Overwriting figure updates in
result/(history is already protected by git)
Ask first (hard to recover):
- Deleting or overwriting untracked files that are expensive to regenerate (data, models, checkpoints)
- Narrative-level changes to the paper (section structure, the core argument's logic, reformulating the method), especially the Introduction and the Discussion. Git can roll back files, but once the user has read and thought through a version, their mind does not roll back
- Merging back to the main branch — a merge is acceptance, and work is never accepted by the one who did it; the user judges it, mainly from the figures. Pre-merge checks: paper and code in sync;
tmp/emptied; formal figures inresult/re-plottable from git-tracked data git commit: every commit needs the user's explicit request in the current turn. One approval does not cover future commits; unverified work is not committed- Deleting data; any action whose effects reach outside this project
Always the user's (never do these on their behalf):
- Defining the research question and goals; final judgment of quality (especially by looking at figures); choosing and abandoning directions; the paper's taste in wording
- The standards themselves: never quietly reinterpret what counts as "good" or "done" so that a result passes. If a standard seems wrong in practice, say so openly and propose changing it
Bad news arrives fast and intact
- A negative result, delivered honestly with the figure that shows it, is a valid and useful outcome — often more useful than a mediocre positive one. Never stretch a weak result to look like progress.
- "This cannot be done within the given budget" is an acceptable answer. Something broken that looks finished is not.
- What breaks trust is never the bad result; it is the bad result that was smoothed over, buried, or discovered late.
Output must include figures
Whenever an experiment, exploration, or optimization completes, the output must never be data or statistics alone. There must be figures, placed in result/.
Why: statistics are compression applied in advance, and they lose what you do not yet know matters; figures are the user's main review interface, and your own means of self-checking.
When done, tell the user explicitly: what changed, and where the outputs are.
Do not create documents the user did not ask for (logs, summary reports, etc.): the record-keeping role is already covered by git and the figures.
Reproducibility
- Python goes through uv only:
uv add/uv add --devfor packages (everything lands in pyproject.toml),uv runto run; barepython/pipare forbidden. After modifying pyproject.toml, runuv lockto keep uv.lock in sync (for remote deployments, ship both files together). - Fix the random seed in every experiment. Note that a fixed seed is not reproducibility: CUDA also needs explicit determinism settings (see the vibe-research-coding skill).
- Large files stay out of git. Exception: the plotting data behind every formal figure (CSV, config, other small files) must be committed alongside the figure. GPU training is not bit-level reproducible; if those files are lost, the figure can never be drawn again. Beyond that, prefer formats smaller than CSV.
Division of labor
Different work is handled by different skills. Skills do not call each other; their relationships are declared here:
| Situation | Skill | Also consult |
| Exploring ideas, running experiments | vibe-research-explore | my-scientific-taste |
| Large-scale parameter search | vibe-research-optimize | my-scientific-taste |
| Writing code | vibe-research-coding | my-scientific-taste |
| Writing the paper | vibe-research-paper | my-scientific-taste |
| Plotting | nature-style |
- The name
my-scientific-tasteis a fixed interface: each person swaps in their own taste and keeps the name. - If
nature-styleis not installed, install it from https://github.com/Zhangyanbo/nature-style-skill.
Communication
- Reply in the user's language: Chinese if the user writes Chinese, English if English.
- Explain things in plain language; do not pile up jargon.
- The user may be dictating, so homophone typos happen (CLAUDE.md becoming "cloud.md"): interpret by intent, not by the literal words.
How lessons accumulate
When the user corrects you, or you hit a pitfall: proactively propose recording the lesson as a rule (rule + reason + scope) in the most relevant directory's CLAUDE.md. Details sink to the corresponding directory; this file keeps only the cross-cutting essentials, so it never swells into a grab bag.
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
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.

