Eine kuratierte Basisdatei für dein Projekt — CLAUDE.md, AGENTS.md oder GEMINI.md, mit dem Warum zu jedem Baustein. Alles läuft im Browser; nichts verlässt die Seite.
Ein Primer ist die Datei, die dein Coding-Agent zu Beginn jeder Sitzung liest. Wähle unten die Bausteine, ersetze die [KLAMMERN] mit deinen Angaben, und kopiere das Ergebnis. Jeder Baustein erklärt, warum er funktioniert — das Lernen ist der Punkt, die Datei ist das Nebenprodukt. Die Bausteine selbst sind bewusst Englisch: Basisdateien werden üblicherweise Englisch geschrieben.
Hintergrund und Pflege-Regeln: A CLAUDE.md that actually gets followed (Englisch).
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.
# [Project name] [What it is and who uses it, in two sentences.] [The one architectural fact that explains everything else.]
Warum: The agent starts every session knowing nothing about your project. Two oriented sentences beat ten minutes of file exploration, every single session.
Anpassen: Replace both brackets. Resist writing more than three sentences — history and philosophy belong in linked docs, not here.
CLAUDE.md: great AGENTS.md: great GEMINI.md: great
## Layout - `[src/]` — [what lives here] - `[tests/]` — [what lives here] - `[the directory people always get wrong]` — [what it actually is]
Warum: 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.
Anpassen: List only directories whose purpose is not obvious from the name. Three to six lines; a full tree is noise.
CLAUDE.md: great AGENTS.md: great GEMINI.md: great
## More - Architecture: `[docs/architecture.md]` - Contributing: `[CONTRIBUTING.md]` - [The doc people actually need but never find]
Warum: 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.
Anpassen: 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: great AGENTS.md: great GEMINI.md: great
## Commands - Build: `[command]` - Test (all): `[command]` - Test (one file): `[command path/to/file]` - Lint / format: `[command]`
Warum: 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.
Anpassen: Exact commands, copy-pasteable. Include the single-file test form — it is the one agents need most and guess worst.
CLAUDE.md: great AGENTS.md: great GEMINI.md: great
## Style Match the surrounding code: naming, comment density, error handling. [The one or two conventions that are non-obvious in this codebase.]
Warum: 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.
Anpassen: 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: great AGENTS.md: great GEMINI.md: great
## Commits [Message format, e.g. conventional commits or plain imperative.] [Whether the agent may commit at all, or only stage and report.]
Warum: 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.
Anpassen: 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: great AGENTS.md: great GEMINI.md: great
## Never modify - `[.env, secrets, credentials]` - `[generated files / lockfiles, if hand-editing breaks them]` - `[migrations that already ran]`
Warum: 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).
Anpassen: 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: great AGENTS.md: great GEMINI.md: great
## Ask first Before: deleting files, schema or data migrations, force-pushes, publishing packages, or anything touching `[production-like systems]`.
Warum: 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.
Anpassen: Adapt to what is actually destructive in your world. A data team's list differs from a frontend team's.
CLAUDE.md: great AGENTS.md: great GEMINI.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.
Warum: 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.
Anpassen: 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: great AGENTS.md: great GEMINI.md: great
## Workflow For changes touching more than [two] files: outline the plan first, wait for a go-ahead, then implement.
Warum: 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.
Anpassen: 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: great AGENTS.md: great GEMINI.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.
Warum: 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.
Anpassen: 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: great AGENTS.md: great GEMINI.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.
Warum: 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.
Anpassen: 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: great AGENTS.md: great GEMINI.md: great
<!-- 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. -->
Warum: 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.
Anpassen: Optional block. Drop it if your team already has the discipline; keep it if the file has ever hit 200 lines.
CLAUDE.md: great AGENTS.md: great GEMINI.md: great
→ CLAUDE.md
Ersetze alle [KLAMMERN], bevor du die Datei eincheckst — sie markieren, was nur du weißt.