Jedes Claude Code Tutorial lehrt dieselben 5 Dinge. Keines davon ist in der Produktion relevant.

Sechs Monate. Zwei SaaS-Apps. Etwa 400 Sessions. Und das Zeug, das meinen Code tatsächlich vor dem Absturz bewahrt? Steht in keinem einzigen Tutorial.

Die Tutorial-Checkliste (und warum sie nach Woche zwei ihren Höhepunkt erreicht)

Jeder Guide folgt demselben Muster. Claude Code installieren. CLAUDE.md erstellen. Slash-Commands lernen. Vielleicht noch einen Multi-Worktree-Flow einrichten, wenn der Autor sich ambitioniert fühlt. Die Demo funktioniert. Der Leser fühlt sich mächtig. Das Tutorial endet.

Zwei Wochen später tritt die Realität die Tür ein.

Ich weiß das, weil ich den Bogen selbst durchlebt habe. Mein erster Monat mit Claude Code war die Honeymoon-Phase — alles fühlte sich magisch an, jede generierte Funktion wie kostenlose Arbeitskraft. Dann kam die Convex-Migration.

Ich bat Claude, meine Auth-Middleware von einem Custom-Supabase-Flow auf Clerk umzustellen. Straightforward Task. Klare Anweisungen. Claude produzierte 380 Zeilen sauberen, getypten, gut dokumentierten Code. Es fügte sogar Kommentare hinzu, die erklärten, warum jede Funktion existierte.

Ein Problem: Es importierte von @clerk/nextjs/server statt von @clerk/nextjs/api — ein Unterschied, der wichtig ist, wenn du Convex Server Functions laufen lässt, die keinen Zugang zum Next.js Request Object haben. Der Code kompilierte lokal einwandfrei. Die Tests liefen durch, weil sie den falschen Context mockten. Ich deployete, das Dashboard wurde weiß, und ich verbrachte 4 Stunden damit, einen Import-Pfad zu debuggen.

Kein Tutorial hatte mich darauf vorbereitet. Weil Tutorials Features testen. Production testet Annahmen.

Deine CLAUDE.md ist wahrscheinlich zu lang

Das mit Abstand beliebteste Tutorial-Thema im Claude Code Ökosystem ist "wie man eine gute CLAUDE.md schreibt." Und fast jedes Beispiel, das ich gesehen habe, macht denselben Fehler: Es sind Romane.

Ich verstehe es. Du willst, dass Claude alles über dein Projekt weiß. Deinen Stack, deine Konventionen, deine Testing-Philosophie, dein bevorzugtes Variable-Naming-Schema, deine Meinung zu Tabs vs Spaces (Spaces, offensichtlich — ich bin ja kein Tier).

Meine erste CLAUDE.md hatte 847 Zeilen. Ich war stolz darauf. Dokumentierte jedes Convex Function Pattern. Jeden Clerk Webhook Handler. Jedes Supabase RLS Policy Format. Ich dachte, ich gebe Claude den ultimativen Context.

Was ich tatsächlich tat, war jede Anweisung bis zur Irrelevanz zu verwässern.

Claude liest deine CLAUDE.md jede Session. Komplett. Und wenn du jemals den Token-Counter beobachtet hast, weißt du, dass eine 847-Zeilen-Context-Datei etwa 3.000 Token frisst, bevor Claude ein einziges Zeichen schreibt. Das sind 3.000 Token deines Context-Windows weg. Bei einer komplexen Refactoring-Session erreichst du das Limit 30–40% schneller — was bedeutet, dass Claude deine tatsächliche Unterhaltung früher vergisst, während es sich noch perfekt an deine Meinungen zu Semikolons erinnert.

Meine aktuelle CLAUDE.md hat 127 Zeilen. Ich habe sie um 85% gekürzt.

Was überlebt hat:

• Stack-Deklaration (8 Zeilen) — Convex, Clerk, Supabase, Next.js 15, Tailwind. Keine Erklärungen. Nur Namen und Versionen.
• Harte Grenzen (12 Zeilen) — Dinge, die ein sofortiges git checkout . auslösen, wenn sie verletzt werden. Falscher Auth Provider. Falscher Database Client. Falsches Deployment Target. Das sind keine Präferenzen. Das sind tragende Wände.
• File Structure Rules (15 Zeilen) — wo Dinge hingehören. Convex Functions in /convex, API Routes in /app/api, Shared Types in /lib/types. Claude erfindet gerne neue Verzeichnisse. Das stoppt es.
• Das Contract Template (20 Zeilen) — Goal, Constraints, Output Format, Failure Conditions. Jeder Task beginnt hier. Ich habe einen ganzen Artikel darüber geschrieben, also wiederhole ich es nicht — aber diese einzige Ergänzung senkte meine Revert-Rate von 1-zu-3 auf 1-zu-10.

Alles andere — der Style Guide, die Testing-Philosophie, die 40 Zeilen über Error Handling Patterns — wurde zu task-spezifischen Prompts verschoben, die ich nur einfüge, wenn relevant. Claude braucht deine Error Handling Meinungen nicht, wenn es eine UI-Komponente schreibt.

Kürzere CLAUDE.md = mehr Platz für die tatsächliche Unterhaltung = weniger Mid-Task-Halluzinationen. Tutorials erzählen dir das nicht, weil "schreib weniger" keine sexy Schlagzeile ist.

Die Checkpoint-Schleife

Ein Task, eine Session. Commit vorher, Commit nachher. Kill die Session, wenn der Task erledigt ist.

Das ist das ganze System. Lass mich erklären, warum jeder Teil wichtig ist.

Claude Code Sessions haben eine Haltbarkeitsdauer. Kein hartes Limit — du kannst technisch stundenlang weitermachen. Aber irgendwo um die 45-Minuten-Marke, oder nach 15–20 Hin-und-Her-Nachrichten, sinkt die Qualität. Nicht dramatisch. Subtil. Claude beginnt, Patterns von früher in der Unterhaltung zu wiederholen. Es referenziert Code, den es vor 30 Nachrichten geschrieben hat und den du seitdem modifiziert hast. Es "erinnert" sich an Constraints vom Anfang der Session, vergisst aber die Verfeinerungen, die du mittendrin hinzugefügt hast.

Ich nenne es Context Decay. Das Context Window ist technisch noch da, aber die Aufmerksamkeit des Models ist dünn über zu viele Nachrichten verteilt, und die neuesten Anweisungen beginnen mit dem angesammelten Müll einer stundenlangen Session zu konkurrieren.

Und hier ist der Teil, für den ich mich schäme: In meinem ersten Monat committete ich einmal pro Feature. Manchmal einmal pro Tag. Ich vertraute Claudes Output genug, um Session für Session darauf aufzubauen, ohne Checkpoints.

Dann, an einem Donnerstagnachmittag, refaktorierte Claude eine Convex Query, die in vier Komponenten kaskadierte, Server-Side Rendering auf drei Seiten brach, und ich hatte keinen sauberen State zum Zurücksetzen. Der letzte Commit war 6 Stunden Arbeit her. Ich verbrachte den Abend damit, git diff Zeile für Zeile zu machen und manuell zu cherry-picken, welche Änderungen ich behalten wollte.

Jetzt sieht der Workflow so aus:

1. git add -A && git commit -m "checkpoint before claude session"
2. Claude Code öffnen. Den Contract für diesen spezifischen Task einfügen.
3. Das Ding machen. Output reviewen. Tests laufen lassen.
4. git add -A && git commit -m "task: clerk webhook handler"
5. Session schließen. Neue für den nächsten Task öffnen.

Nicht "ein Feature." Ein Task. "Den Webhook Handler für Clerk User Creation hinzufügen" ist ein Task. "Den gesamten Auth Flow bauen" ist ein Projekt, das 4–6 Sessions sein sollte.

Mein git log sieht irre aus — 15–20 Commits pro Tag, Nachrichten wie "checkpoint before auth refactor" und "task: add clerk webhook, tests pass." Es ist hässlich. Es ist auch eine Zeitmaschine. Wenn Claude etwas falsch macht und du revertest, startet die nächste Session von einem bekannt guten State mit null übrig gebliebener Verwirrung. Fresh Session + Clean Git = Claude operiert auf der Realität statt auf den Trümmern seines vorherigen Versuchs.

Tutorials zeigen dir eine einzige glorreiche Session, wo alles klickt. Production sind fünfzig kurze Sessions, wo jede sauber startet und committed endet.

Deklariere deine Adjacent Surfaces (oder verliere einen Tag)

Vor jedem Claude Code Task schreibe drei Zeilen wie diese:

## Adjacent Code
- /convex/payments.ts → handled Stripe webhook, schreibt in "payments" table
- /app/dashboard/revenue.tsx → liest von "payments" table, gruppiert nach Monat
- /convex/notifications.ts → triggert bei payment insert via Convex scheduled function

Das war's. File Paths und ein One-Liner darüber, was sie interessiert. Zwei Minuten. Füge es in deinen Prompt Contract unter "Adjacent Code" ein.

Warum? Weil jedes Tutorial Claude Code an isolierten Features demonstriert. "Lass uns eine Todo-App bauen!" "Lass uns Authentication hinzufügen!" In der Production ist nichts isoliert. Dein Clerk Webhook spricht mit deiner Convex Mutation, die eine Supabase Edge Function triggert, die eine E-Mail via Resend sendet, die in deine Dashboard-Komponente loggt. Berühre eins, und drei andere zucken zusammen.

Ich lernte das auf die teure Art. Claude machte ein korrektes Refactoring meines Payment Flows — sauberer Code, alle Tests bestanden — das stillschweigend das Revenue Chart des Dashboards brach. Weil es nicht wusste (und ich es ihm nicht sagte), dass das Dashboard von derselben Convex Table mit einem anderen Query Pattern las. Der Fix dauerte 20 Minuten. Den Bug zu finden dauerte anderthalb Tage.

Claude muss adjacent Files nicht lesen. Es muss nur wissen, dass sie existieren. Das reicht, damit es "das Ändern dieses Table Schemas wird diese 3 Files betreffen" flaggt, statt stillschweigend dein Dashboard zu planieren.

Error Recovery ist, wo du tatsächlich Zeit verlierst

Tutorials zeigen den Happy Path. Feature Request → Claude generiert Code → Tests bestehen → ship it. Die unausgesprochene Annahme ist, dass dieser Flow die Norm ist.

Meiner Erfahrung nach funktioniert der Flow vielleicht 60% der Zeit sauber. Die anderen 40% sind Error Recovery — Claude generiert Code, etwas bricht, und jetzt debuggst du mit Claude, was eine fundamental andere Fähigkeit ist als mit Claude zu bauen.

Das Problem mit Debugging Sessions: Claude wird entschuldigend und über-korrektiv. Sag ihm "der Webhook Handler wirft eine 500 beim Clerk user.created Event" und es wird den gesamten Handler neu schreiben, statt die eine falsche Zeile zu fixen. Ich habe Claude öfter funktionierenden Code löschen sehen, um "fresh zu starten", als ich zählen kann, weil sein Error-Recovery-Instinkt ist, aus dem Orbit zu nuken.

Mein Workaround ist hässlich, aber effektiv. Wenn etwas bricht:

1. Beschreibe den Error nicht in derselben Session. Kill die Session. Starte eine neue.
2. Füge die Error Message und die spezifische Datei ein, nicht die Task Description. "Diese Funktion in /convex/webhooks.ts wirft TypeError: Cannot read properties of undefined (reading 'email_addresses') beim Empfangen eines Clerk user.created Events. Die eingehende Payload sieht so aus: [paste payload]. Fixe nur diese Funktion. Modifiziere keine anderen Files."
3. Sperre alles andere. Füge "MODIFIZIERE KEINE Datei außer /convex/webhooks.ts" zum Constraint hinzu. Claude im Fix-Modus ist trigger-happy.

Der Unterschied zwischen "hey Claude, die Auth ist kaputt, kannst du es fixen" und einem scoped, single-file, error-spezifischen Prompt ist der Unterschied zwischen einem 5-Minuten-Fix und einem einstündigen Rabbit Hole, wo Claude deine Auth von Grund auf neu schreibt.

Tutorials lehren Error Recovery nicht, weil es nicht fotogen ist. Aber dort geht mindestens ein Drittel deiner Claude Code Zeit tatsächlich hin.

Was ich ausprobiert und verworfen habe

Nicht alles hat überlebt. Einiges, wovon ich überzeugt war, dass es funktionieren würde, wofür ich echte Zeit aufwendete und schließlich aufgab. Wert zu dokumentieren, damit du das Experiment nicht wiederholst.

"Think hard" bei jedem Prompt. Eine Zeit lang fügte ich "think hard" oder "think step by step" zu jedem einzelnen Claude Code Prompt hinzu, weil irgendein Reddit-Thread sagte, es verbessere die Output-Qualität. Tut es — bei komplexen architektonischen Entscheidungen. Bei "füge einen Loading Spinner zu diesem Button hinzu"? Es bringt Claude nur dazu, einen 400-Wort-Plan für eine 3-Zeilen-Änderung zu schreiben. Jetzt verwende ich es nur für Tasks mit echter Ambiguität. Vielleicht 1 von 5 Prompts.

Multi-Worktree Parallel Sessions. Das Konzept ist schön — drei Claude Instanzen arbeiten an drei Features gleichzeitig, jede in ihrem eigenen Git Worktree. Ich richtete das ein, brachte es zum Laufen und verwendete es für genau einen Nachmittag. Das Problem ist nicht technisch, es ist kognitiv. Drei gleichzeitige Outputs zu reviewen, im Blick zu behalten, welcher Worktree voraus ist, ohne Konflikte zurückzumergen — es ist Projektmanagement-Overhead, verkleidet als Produktivität. Wenn du ein Team hast, vielleicht. Solo? Du generierst nur schneller Merge-Konflikte. Aber ich schweife ab — ich benannte die Worktrees etwa 48 Stunden lang nach Pokémon, und ehrlich gesagt war dieser Teil spaßig.

Claude verwenden, um seinen eigenen Code zu reviewen. Y Combinators CEO hat einen ganzen Prompt dafür — vierstufiges Review-System, Architecture Check, Code Quality Pass, das ganze Programm. Ich ließ es zwei Tage laufen. Der Output war gründlich und ich lernte tatsächlich etwas vom strukturierten Format. Aber die Mathematik funktionierte nicht: 30–45 Minuten Review-Dialog pro Feature, zusätzlich zur Generierungszeit. Ich verbrachte mehr Zeit damit, den Reviewer zu überwachen, als ich gebraucht hätte, den Code selbst zu reviewen. Claude seine eigenen Fehler fangen zu lassen klingt elegant. In der Praxis wirst du ein QA-Manager für einen Roboter, der sich das Review in der nächsten Session sowieso nicht merkt.

Personality Instructions in CLAUDE.md. "Du bist ein Senior TypeScript Engineer, der saubere Architektur schätzt." "Antworte prägnant." "Sei meinungsstark." Ich hatte 15 Zeilen von diesem Zeug. Entfernte alles, nachdem ich realisierte, dass es null messbaren Einfluss auf die Code-Qualität hatte. Claude codet nicht anders, weil du ihm gesagt hast, senior zu sein. Es codet anders, wenn du ihm die richtigen Constraints und Context gibst. Spare diese Token.

Jedes davon fühlte sich zur Zeit smart an. Das ist die Falle — das Claude Code Ökosystem ist voller Ratschläge, die in einem Blog-Post vernünftig klingen und bei Session 200 auseinanderfallen.

🔄 Update: Es gibt tatsächlich eine 6. Sache, die kein Tutorial abdeckt, und sie ist wohl die wichtigste: Security. Claude Code hat seit August 2025 einen /security-review Slash-Command. Du tippst ihn, es scannt deinen Code nach Vulnerabilities. Zwölf Wörter zu erklären. Null Tutorials erwähnen es. Anthropic hat gerade ein ganzes Enterprise-Produkt darum gebaut und dabei $15 Milliarden in Cybersecurity-Aktien gecrasht. Die Tutorials bringen dir immer noch bei, wie man CLAUDE.md einrichtet.

Tutorials verkaufen die Magie. Production berechnet das Aufräumen.

---

Ich schreibe über Claude Code, AI Automation und die unsexy Teile des Shippens echter Produkte mit AI Tools. Als nächstes: warum ich mein gesamtes OpenClaw Setup für $15 neu gebaut habe nachdem Anthropic das alte gekillt hat — und die Architektur, die tatsächlich funktioniert. Hit subscribe (nicht nur follow — die E-Mail bringt dir den Artikel, der Follow-Button ist im Grunde eine Teilnahme-Trophäe), wenn du das in deiner Inbox willst.

---

Produktions-Code ist mehr als ein Tutorial: Lerne, wie echte AI-Agents ohne Stolperfallen deployt werden.

→ Newsletter abonnieren und Willkommens-Kit sichern