Warum in diesem Repo SKILL.md und CLAUDE.md wichtig sind, AGENTS.md aber fehlt
Ein Coding-Agent startet jede Session ohne Wissen über das Projekt, also werden die Dateien, die er liest, zum wichtigsten Code. Am Beispiel ParkEase zeigt sich, wie SKILL.md und CLAUDE.md Regeln wie verbotene Floats für Geldbeträge oder den Einsatz von Fastify übermitteln.
Ein KI-Coding-Agent startet jede Session mit null Wissen ueber dein Projekt. Keine Erinnerung an gestern, keine Ahnung, dass du Floats fuer Geld verboten hast, kein Hinweis darauf, dass die API auf Fastify laeuft und nicht auf Express.
Alles, was er wissen muss, muss er lesen. Die Dateien, die er liest, wurden dadurch zum wichtigsten Code in ParkEase, der kein Code ist.
Claude Code laedt automatisch eine Datei namens CLAUDE.md aus dem Repo-Root in jede Session. Meine ist kurz im Prosaanteil und lang bei den Regeln. Den Kern bildet ein Abschnitt namens "The ten rules that matter most":
1. Geld ist ein Integer in Paise, und das Ledger ist die Wahrheit. 2. Controller autorisieren und delegieren. Nichts weiter. 3. Eine Transaktion pro Schreibvorgang, mit dem Outbox darin. 4. Rufe niemals einen externen Service innerhalb einer Transaktion auf. 5. Die Datenbank erzwingt Invarianten, denen die Anwendung man nicht vertrauen darf.... 10. Loading, Error und Empty auf jedem Bildschirm. Enter fullscreen mode Exit fullscreen mode Dazu kommen der Stack (und was er nicht ist: "Drizzle ORM, NOT TypeORM", "NestJS on Fastify, NOT Express"), das Code-Layout, eine "Don't"-Liste und die Befehle.
Die "NOT"-Zeilen sind wichtiger, als sie aussehen. Das Vorwissen eines Modells ist der Durchschnitt des Internets. Fragt man nach einer NestJS-Validierungsschicht, ohne etwas anderes zu sagen, erhaelt man class-validator, weil das in den meisten Tutorials verwendet wird. Eine Zeile in CLAUDE.md verschiebt den Default.
Die Datei legt auch die Rangfolge der Autoritaet fest: Die Architecture Decision Records uebersteuern die Regeln, und diese uebersteuern die Produkt-Spec. Widerspricht der Rat eines Tools einem Decision Record, gewinnt der Record, und die KI muss das offen aussprechen.
Man kann nicht alles in CLAUDE.md unterbringen; die Datei wuerde enorm gross, und das meiste waere fuer eine einzelne Aufgabe irrelevant. Skills loesen das Problem.
Ein Skill ist ein Ordner mit einer SKILL.md darin. Der obere Teil der Datei besteht aus einem Namen und einer Beschreibung:
--- name: flow description: "Use when working on ParkEase — any of its 22 tasks, or any" feature, bugfix, refactor, review, UI or motion work... --- Enter fullscreen mode Exit fullscreen mode Der Agent sieht nur die Beschreibungen, bis eine Aufgabe zu einer passt; dann laedt er die gesamte Datei. Die Beschreibung ist damit faktisch ein Trigger, und eine gute zu schreiben ("use when...", mit Nennung der Situationen) ist wichtiger als der Inhalt.
ParkEase nutzte zwei Ebenen: allgemeine Skills, die fuer jedes Projekt installiert sind (brainstorming, test-driven-development, systematic-debugging, verification-before-completion, die Design-Skills), und projektlokale Skills in.claude/skills/, die nur in diesem Repo existieren, etwa ein Delivery Gate und eine kuratierte Sammlung stackspezifischer Skills (Postgres, Redis, Docker, Error Handling). Darueber lag flow, ein Routing-Skill, der festlegt, welche Skills in welcher Phase fuer welchen Teil des Stacks gelten.
In.claude/agents/ liegen Subagent-Definitionen: einen Security Reviewer, einen TypeScript Reviewer, einen Database Reviewer, einen Test-Coverage Analyzer und meinen Favoriten, einen "silent failure hunter", der ausschliesslich nach verschluckten Fehlern, leeren Catch-Bloecken und verlorenen Stack Traces sucht. Jeder ist eine Markdown-Datei mit einem fokussierten Prompt und einem eingeschraenkten Werkzeugset.
Sie machen aus "reviewe den Code" mehrere schmale Reviews. Dazu mehr, einschliesslich der Rechnung, spaeter in der Serie.
AGENTS.md wird zu einer tooluebergreifenden Konvention fuer genau das, was CLAUDE.md tut. Ich habe eine hinzugefuegt und mich gegen diesen Plan schriftlich entschieden, damit die KI nicht staendig wieder darauf zurueckkommt:
CLAUDE.md ist die einzige Source of Truth fuer dieses Projekt. Eine zweite Kontextdatei mit derselben Governance-Kette ist der Weg, wie die beiden auseinanderdriften, und eine teilweise Kopie ist schlimmer als keine.
Zwei Dateien, die dasselbe sagen, sagen irgendwann zwei verschiedene Dinge, und ein Agent, der die veraltete liest, befolgt sie zuversichtlich. Wer mehrere Tools nutzt, sollte eine kanonische Datei waehlen und die anderen darauf verweisen. Pflege keine zwei Kopien deiner Regeln.
Behandle diese Dateien wie Code. Pruefe Aenderungen daran. Loesche Regeln, die nicht mehr gelten. Wenn die KI denselben Fehler zweimal macht, gehoert die Korrektur in eine dieser Dateien, nicht in deinen naechsten Prompt. Ein Prompt haelt eine Session; eine Regel haelt das Projekt.
Als Naechstes: der Skill, den ich ofter von Hand getippt habe als jeden anderen, und der mit dem lustigsten Namen: ponytail, der faule Senior Developer, der mehr Code geloescht als geschrieben hat.
ParkEase ist ein Peer-to-Peer-Parkplatz-Marktplatz fuer Indien, solo gebaut mit Claude Code. Code: https://github.com/Deonkar/parkease
Automatisch übersetzt. Das Original auf Englisch ist unten aufklappbar.
Original (Englisch) anzeigen
An AI coding agent starts every session knowing nothing about your project. No memory of yesterday, no idea that you banned floats for money, no clue the API runs on Fastify and not Express.
Whatever it needs to know, it has to read. So the files it reads became the most important code in ParkEase that isn't code.
Claude Code loads a file called CLAUDE.md from the repo root into every session automatically. Mine is short on prose and long on rules. The core of it is a section called "The ten rules that matter most":
1. Money is integer paise, and the ledger is the truth. 2. Controllers authorise and delegate. Nothing more. 3. One transaction per write, with the outbox inside it. 4. Never call an external service inside a transaction. 5. The database enforces invariants the application cannot be trusted with.... 10. Loading, error, and empty on every screen. Enter fullscreen mode Exit fullscreen mode Plus the stack (and what it's not: "Drizzle ORM, NOT TypeORM", "NestJS on Fastify, NOT Express"), the code layout, a "Don't" list, and the commands.
The "NOT" lines matter more than they look. A model's prior is the average of the internet. Ask for a NestJS validation layer without saying otherwise and you'll get class-validator, because that's what most tutorials use. One line in CLAUDE.md moves the default.
The file also sets the order of authority: the architecture decision records override the rules, which override the product spec. When a tool's advice contradicts a decision record, the decision wins, and the AI has to say so out loud.
You can't put everything in CLAUDE.md; it would be enormous, and most of it irrelevant to any one task. Skills solve that.
A skill is a folder with a SKILL.md inside. The top of the file is a name and a description:
--- name: flow description: "Use when working on ParkEase — any of its 22 tasks, or any" feature, bugfix, refactor, review, UI or motion work... --- Enter fullscreen mode Exit fullscreen mode The agent sees only the descriptions until a task matches one; then it loads the whole file. So the description is effectively a trigger, and writing a good one ("use when…", naming the situations) matters more than the body.
ParkEase used two layers: general skills installed for every project ( brainstorming, test-driven-development, systematic-debugging, verification-before-completion, the design skills), and project-local skills in.claude/skills/ that only exist inside this repo, like a delivery gate and a curated set of stack-specific skills (Postgres, Redis, Docker, error handling). On top sat flow, a routing skill that says which skills apply at which phase for which part of the stack.
.claude/agents/ holds subagent definitions: a security reviewer, a TypeScript reviewer, a database reviewer, a test-coverage analyzer, and my favourite, a "silent failure hunter" that only looks for swallowed errors, empty catch blocks and lost stack traces. Each is a markdown file with a focused prompt and a restricted toolset.
They turn "review the code" into several narrow reviews. More on how that went, including the bill, later in the series.
AGENTS.md is becoming a cross-tool convention for exactly what CLAUDE.md does. I considered adding one, and decided against it, in writing, so the AI wouldn't keep re-proposing it:
CLAUDE.md is the single source of truth for this project. A second context file carrying the same governance chain is how the two drift apart, and a partial copy is worse than none.
Two files saying the same thing will eventually say two different things, and an agent that reads the stale one will follow it confidently. If you use several tools, pick one canonical file and point the others at it. Don't maintain two copies of your rules.
Treat these files like code. Review changes to them. Delete rules that no longer apply. When the AI makes the same mistake twice, the fix belongs in one of these files, not in your next prompt. A prompt lasts one session; a rule lasts the project.
Next: the skill I typed by hand more than any other, and the one with the funniest name: ponytail, the lazy senior developer who deleted more code than he wrote.
ParkEase is a peer-to-peer parking marketplace for India, built solo with Claude Code. Code: https://github.com/Deonkar/parkease