A curated base file for your project — CLAUDE.md, AGENTS.md or GEMINI.md, with the why behind every block. Runs entirely in your browser; nothing leaves the page.
A primer is the file your coding agent reads at the start of every session. Pick blocks below, replace the [BRACKETS] with your project's specifics, and copy the result. Every block explains why it works — the learning is the point; the file is the by-product.
Facts and commands first (the agent needs them every session), then boundaries (cheap to write, expensive to lack), then the two workflow habits with the best cost-benefit in current tools: plan-first and evidence-over-assertion. Commit conventions, doc pointers and the maintenance note are worth adding once the basics have survived a week of real use.
facts
# [Project name]
[What it is and who uses it, in two sentences.]
[The one architectural fact that explains everything else.]
Why this works, and what to customize
Why: The agent starts every session knowing nothing about your project. Two oriented sentences beat ten minutes of file exploration, every single session.
Customize: Replace both brackets. Resist writing more than three sentences — history and philosophy belong in linked docs, not here.
CLAUDE.md: greatAGENTS.md: greatGEMINI.md: great
## Layout
- `[src/]` — [what lives here]
- `[tests/]` — [what lives here]
- `[the directory people always get wrong]` — [what it actually is]
Why this works, and what to customize
Why: Agents rediscover your layout by searching, which costs time and context window. A five-line map is cheaper than the search, and it steers the agent away from the directory everyone misreads.
Customize: List only directories whose purpose is not obvious from the name. Three to six lines; a full tree is noise.
CLAUDE.md: greatAGENTS.md: greatGEMINI.md: great
## More
- Architecture: `[docs/architecture.md]`
- Contributing: `[CONTRIBUTING.md]`
- [The doc people actually need but never find]
Why this works, and what to customize
Why: The base file should stay lean, so depth lives elsewhere and gets pointed at. An agent told where the architecture doc is reads it when relevant; one pasted into the base file costs its full length every session.
Customize: Only docs that exist and are current. A pointer to a stale doc is worse than no pointer — the agent will trust it.
CLAUDE.md: greatAGENTS.md: greatGEMINI.md: great
commands
## Commands
- Build: `[command]`
- Test (all): `[command]`
- Test (one file): `[command path/to/file]`
- Lint / format: `[command]`
Why this works, and what to customize
Why: The single highest-value section in any base file. Without it the agent guesses commands from package files, sometimes wrongly, and the single-file test variant is what keeps verification cheap enough to actually run.
Customize: Exact commands, copy-pasteable. Include the single-file test form — it is the one agents need most and guess worst.
CLAUDE.md: greatAGENTS.md: greatGEMINI.md: great
conventions
## Style
Match the surrounding code: naming, comment density, error handling.
[The one or two conventions that are non-obvious in this codebase.]
Why this works, and what to customize
Why: Models default to their own average style. One instruction to match what is already there prevents most of it, and naming your genuinely unusual conventions covers the rest — the agent cannot infer a rule your code applies inconsistently.
Customize: Name only conventions a newcomer would get wrong. A full style guide belongs in a linter config, which enforces it better than prose can.
CLAUDE.md: greatAGENTS.md: greatGEMINI.md: great
## Commits
[Message format, e.g. conventional commits or plain imperative.]
[Whether the agent may commit at all, or only stage and report.]
Why this works, and what to customize
Why: Unstated, every tool applies its own default commit style — and some add attribution footers you may not want. One block settles message format, attribution, and whether committing is even the agent's job.
Customize: State the attribution rule explicitly, whichever way you want it. Teams that forbid AI attribution in commits need to say so here, once.
CLAUDE.md: greatAGENTS.md: greatGEMINI.md: great
boundaries
## Never modify
- `[.env, secrets, credentials]`
- `[generated files / lockfiles, if hand-editing breaks them]`
- `[migrations that already ran]`
Why this works, and what to customize
Why: A written boundary is honored far more reliably than an assumed one — but prose is still a request, not a guarantee. For rules where a single violation is unacceptable, add an enforcing mechanism on top (Claude Code: a PreToolUse hook or a permission deny).
Customize: Your real protected paths. Keep the list short enough that every entry is genuinely never-touch; a long list of soft preferences dilutes the hard ones.
CLAUDE.md: greatAGENTS.md: greatGEMINI.md: great
## Ask first
Before: deleting files, schema or data migrations, force-pushes,
publishing packages, or anything touching `[production-like systems]`.
Why this works, and what to customize
Why: Agents inherit your authority for the whole session. Naming the irreversible actions turns 'the agent did something surprising' into 'the agent asked' — the difference between an incident and a question.
Customize: Adapt to what is actually destructive in your world. A data team's list differs from a frontend team's.
CLAUDE.md: greatAGENTS.md: greatGEMINI.md: great
## Tests
Tests are the specification. Never modify, weaken or delete a test to
make it pass — report the failure instead. Placeholder implementations
that return expected values count as failures, not passes.
Why this works, and what to customize
Why: An agent optimises for the finish line it is given; if that is 'tests green', editing the test or stubbing the return value are valid paths to it. This is a recorded failure mode of test-driven agents, not a hypothetical. Naming the rule closes the cheapest cheat; a hook blocking edits to test paths closes it hard.
Customize: Point at your test paths if they are non-obvious. Teams with hard requirements should pair this with an enforcing hook rather than relying on the prose alone.
CLAUDE.md: greatAGENTS.md: greatGEMINI.md: great
workflow
## Workflow
For changes touching more than [two] files: outline the plan first,
wait for a go-ahead, then implement.
Why this works, and what to customize
Why: Separating planning from implementation is the cheapest quality lever there is: a wrong plan costs one message to correct, a wrong implementation costs a review and a revert.
Customize: Tune the threshold to your risk tolerance. Some teams want plans only for schema or API changes; some want them for everything non-trivial.
CLAUDE.md: greatAGENTS.md: greatGEMINI.md: great
## Verification
After changes, run the relevant tests and show the output.
Claims like "done" or "fixed" come with the command run and its result.
Why this works, and what to customize
Why: Models assert success fluently whether or not it happened. Requiring the test output converts 'trust me' into something you can read — and trains your own review habit onto evidence instead of confidence.
Customize: Point at your actual verification command from the Commands block. If your project has no tests, name the smoke check that exists instead.
CLAUDE.md: greatAGENTS.md: greatGEMINI.md: great
## Handover
Before ending a work block or when context runs low: write a short
handover to `HANDOVER.md` — what was done (with the why), what is in
progress, next steps, open questions. The next session starts from it.
Why this works, and what to customize
Why: Sessions do not share memory, and the expensive part of every restart is re-deriving state. A handover note written while the context still exists converts that cost into thirty seconds of writing. Capturing the *why* matters most — a next-steps list without reasons gets re-litigated.
Customize: Rename the file to your convention. Solo users can keep one rolling file; teams may want dated files so handovers double as a work log.
CLAUDE.md: greatAGENTS.md: greatGEMINI.md: great
meta
<!-- Keep this file lean: it is read every session, so every line is a
recurring cost. Facts and commands belong here; procedures and history
belong in linked docs. Delete lines that stop being true. -->
Why this works, and what to customize
Why: Base files rot in one direction: they grow. A maintenance note at the top gives the next editor (human or agent) the pruning rule, and as a comment it costs nothing in most renderers while still being read by the model.
Customize: Optional block. Drop it if your team already has the discipline; keep it if the file has ever hit 200 lines.
CLAUDE.md: greatAGENTS.md: greatGEMINI.md: great
Result
→ CLAUDE.md
Replace every [BRACKET] before committing the file — they mark what only you know.