Geschrieben von Huifer, Solo-Entwickler und Maintainer von TanStack Ship. Ich habe Claude Code zwischen Januar und Juni 2026 in 8 TanStack Start Projekten eingesetzt. Die Muster in diesem Beitrag sind jene, die den Review-Prozess überstanden haben und in die Produktion gegangen sind – nicht diejenigen, die nur in einem Tweet gut aussahen.
Verifizierte Quellen: TanStack Ship GitHub · TanStack Start Docs Zuletzt aktualisiert: 22. Juli 2026 · Changelog
TL;DR: Claude Code transformiert die TanStack Start Entwicklung, wenn Sie ihm den richtigen Kontext geben. Eine gut durchdachte CLAUDE.md Datei ist die Investition mit dem höchsten ROI, die Sie tätigen können. Dieser Beitrag enthält ein in der Produktion getestetes CLAUDE.md Template und 10 Prompts, die tatsächlich funktionieren.
Warum CLAUDE.md für TanStack Projekte wichtig ist
Wenn Sie ein neues TanStack Start Projekt mit Claude Code beginnen, weiß die KI nichts über Ihren Tech-Stack. Sie sieht TypeScript, React und generische Muster. Ohne expliziten Kontext generiert sie Code, der gegen Ihre Konventionen ankämpft, anstatt sie zu nutzen. Der Code sieht richtig aus, funktioniert aber nicht mit den spezifischen Mustern von TanStack Start.
Eine CLAUDE.md Datei teilt Claude Code alles mit, was er wissen muss: Ihre Routing-Konventionen, Server-Function-Muster, den Authentifizierungsablauf und das Deployment-Ziel. Es ist der Unterschied zwischen Code, der 30 Minuten Überarbeitung benötigt, und Code, der direkt in die Produktion gehen kann.
Ich habe seit Januar 2026 bereits 8 TanStack Start Projekte mit Claude Code ausgeliefert. Die Prompts, die funktionieren, haben eine konsistente Struktur. Diejenigen, die fehlschlagen, weisen vorhersehbare Muster auf. Dieser Leitfaden teilt mit, was funktioniert, und hilft Ihnen, die Fehlermuster zu vermeiden, die mich Stunden an Überarbeitung gekostet haben.
Der Setup-Prozess
Bevor Sie Prompts schreiben, sollten Sie Claude Code richtig einrichten. Das Setup dauert fünf Minuten und spart später Stunden.
Installieren Sie Claude Code global auf Ihrem System mit npm. Navigieren Sie in Ihr Projektverzeichnis und starten Sie Claude Code im Terminal. Erstellen Sie eine CLAUDE.md Datei im Stammverzeichnis Ihres Projekts. Die CLAUDE.md Datei wird beim Start von Claude Code automatisch geladen. Wenn Sie also eine neue Unterhaltung beginnen, liest Claude diese Datei und verwendet sie als Kontext für all Ihre Anfragen.
Dieses automatische Laden ist enorm wirkungsvoll. Jede Unterhaltung beginnt mit demselben Kontext, ohne dass Sie sich wiederholen müssen. Sie können auch projektspezifische Anweisungen verwenden, die CLAUDE.md für bestimmte Unterhaltungen überschreiben, falls Sie für spezifische Aufgaben ein abweichendes Verhalten benötigen.
Aufbau einer effektiven CLAUDE.md
Eine CLAUDE.md für TanStack Start besteht aus vier wesentlichen Abschnitten. Jeder erfüllt einen bestimmten Zweck, und zusammen geben sie Claude Code den Kontext, den er benötigt, um Code zu generieren, der Ihren Konventionen entspricht.
Projektübersicht
Beginnen Sie mit den Grundlagen – Framework-Versionen, Deployment-Ziel und den wichtigsten Abhängigkeiten. Dieser Abschnitt teilt Claude Code mit, mit welcher Art von Anwendung er arbeitet und welche Technologien im Einsatz sind. Seien Sie bei den Versionen präzise, da sich das Verhalten zwischen Versionen ändert und das Wissen über die exakte Version Claude hilft, kompatiblen Code zu generieren.
# TanStack Ship Project
This is a TanStack Start application deployed on Cloudflare Workers.
- Framework: TanStack Start 1.x
- Router: TanStack Router with type-safe routes
- Database: D1 (SQLite) with Drizzle ORM
- Auth: Better Auth with edge-compatible sessions
- Payments: Stripe subscriptions
- Deployment: Cloudflare Workers (edge)
## Package Versions
- @tanstack/react-router: ^1.x
- @tanstack/start: ^1.x
- drizzle-orm: ^0.30.x
- better-auth: ^1.x
Wichtige Konventionen
Dokumentieren Sie die Muster, die sich vom Standard-React unterscheiden. Hier sparen die meisten Entwickler Zeit, da Claude Ihre spezifischen Muster lernt, anstatt generischen Code zu generieren, der nicht zu Ihrer Architektur passt.
TanStack Start verwendet Serverfunktionen für Mutationen, die ausschließlich auf dem Server laufen und nicht auf den Client-State zugreifen können. Die Authentifizierung erfolgt in beforeLoad Hooks anstatt in Komponenten, wodurch die Auth-Logik serverseitig bleibt, wo sie hingehört. Routenparameter sind durch den Router typsicher, nicht durch den generischen useParams Hook. Das Verständnis dieser Muster ist essenziell für das Schreiben einer CLAUDE.md, die tatsächlich weiterhilft.
## Routing
Routes live in `src/routes/`. Each route file exports:
- `route` — the route configuration
- `component` — the page component
- `loader` — server-side data fetching
- `beforeLoad` — authentication guards
Never use `useParams()` for typed route params.
Use `route.useParams()` instead.
## Server Functions
Mutations use `createServerFn()`:
- Server functions run on the server only
- Import from `@tanstack/start/server`
- Return typed responses
- Handle errors with Result types
## Authentication
All protected routes use `beforeLoad`:
```typescript
beforeLoad: ({ context, location }) => {
if (!context.session) {
return redirect('/login');
}
}
### Dateibenennungskonventionen
TanStack Start hat spezifische Erwartungen an die Benennung, die Claude kennen muss. Ein Bruch dieser Konventionen führt zu stillen Fehlern, die schwer zu debuggen sind, weil der Code zwar richtig aussieht, aber nicht funktioniert. Routendateien müssen das Routen-Präfix verwenden. Index-Routen verwenden das Index-Schlüsselwort. Layout-Routen verwenden das Layout-Schlüsselwort. API-Routen befinden sich im `api` Unterverzeichnis. Diese Konventionen zu verstehen, hilft Ihnen dabei, eine CLAUDE.md zu schreiben, die Fehler verhindert.
### Zu vermeidende Anti-Patterns
Dieser Abschnitt verhindert die häufigsten Fehler von Claude Code. Ohne ihn generiert Claude Muster, die zwar korrekt aussehen, in der Architektur von TanStack Start jedoch nicht funktionieren. Diese Anti-Patterns tauchen am häufigsten auf, wenn ich von Claude generierten Code überprüfe.
```markdown
## Don't Do These
1. Don't use `fetch()` directly in components—use loaders
2. Don't create client-side-only mutations—use server functions
3. Don't use React Router directly—use TanStack Router APIs
4. Don't hardcode URLs—use `to` from route components
5. Don't put auth logic in components—use beforeLoad guards
6. Don't use environment variables directly—use `runtimeConfig`
10 Prompts, die tatsächlich funktionieren
Diese Prompts wurden projektübergreifend in der Produktion eingesetzt. Kopieren Sie sie in Ihre Claude Code Unterhaltungen und passen Sie die Details für Ihr Projekt an. Jeder Prompt wurde stark verfeinert, basierend darauf, was funktionierenden Code generierte im Vergleich zu dem, was überarbeitet werden musste.
1. Routengenerierung
Wenn Sie eine neue Route benötigen, seien Sie präzise darüber, was die Route tun soll und welche Daten sie benötigt. Schließen Sie den URL-Pfad, die Authentifizierungsanforderungen sowie jegliches Datenabrufen (Data Fetching) oder Mutationen ein. Je spezifischer Sie sind, desto besser generiert Claude Code, der Ihren Erwartungen entspricht.
Prompt: "Erstelle eine neue Route unter /dashboard/settings mit:
- Geschützt durch Auth (Redirect zu
/login, falls nicht authentifiziert) - Loader, der Benutzereinstellungen aus D1 abruft
- Einer Einstellungen-Formularkomponente mit Feldern für Name, E-Mail und Zeitzone
- Serverfunktion, um die Einstellungen zu aktualisieren
- Verwende die TanStack Start Konventionen aus CLAUDE.md"
Nachdem Claude die Route generiert hat, überprüfen Sie, ob beforeLoad die Authentifizierung korrekt handhabt, der Loader typisierte Daten zurückgibt und die Serverfunktion createServerFn verwendet. Dies sind die häufigsten Fehler, die Sie im Code-Review frühzeitig erkennen sollten.
2. Drizzle Schema
Das Hinzufügen von Datenbanktabellen ist unkompliziert, wenn Sie Claude das exakte Schema vorgeben, das Sie benötigen. Fügen Sie Feldnamen, Typen und jegliche Constraints hinzu. Seien Sie bei Fremdschlüsseln und Indizes explizit, da Drizzle eine explizite Definition vorschreibt und Beziehungen nicht automatisch ableitet.
Prompt: "Füge dem bestehenden Drizzle Schema eine subscriptions Tabelle hinzu, mit Feldern für id (cuid2 Primary Key), userId (Foreign Key zur users Tabelle), stripeCustomerId, plan mit den Enum-Werten 'free' | 'pro' | 'enterprise', status mit den Werten 'active' | 'canceled' | 'past_due', currentPeriodEnd als Unix-Timestamp-Integer und createdAt als Unix-Timestamp mit dem Standardwert now. Ergänze korrekte Indizes für userId und status, und füge die Relation zur users Tabelle hinzu."
3. Stripe Webhook Handler
Stripe Webhooks erfordern eine sorgfältige Handhabung, da dabei Geld im Spiel ist. Claude kann die Struktur generieren, aber Sie müssen die Event-Handling-Logik auf ihre Richtigkeit überprüfen. Webhook-Handler müssen idempotent, schnell und sicher sein.
Prompt: "Erstelle einen Stripe Webhook-Handler in /src/routes/api/stripe-webhooks.ts, der die Stripe-Signatur mit der Umgebungsvariablen STRIPE_WEBHOOK_SECRET verifiziert, Subscription-Lifecycle-Events behandelt (created, updated, deleted), die Datenbank aktualisiert, die Idempotenz unter Verwendung der Event-ID korrekt handhabt, unmittelbar 200 zurückgibt, um Stripe-Timeouts zu verhindern, alle Events mit Timestamps loggt und ein angemessenes Error Handling verwendet, das bei unerwarteten Fehlern 500 zurückgibt."
4. R2 File Upload
Datei-Uploads auf Cloudflare Workers erfordern aufgrund der Einschränkungen der Edge-Runtime eine spezifische Handhabung für R2. Geben Sie Claude die Einschränkungen vor, und er generiert die Serverfunktion mit eingebauter, angemessener Validierung und Sicherheitsvorkehrungen.
Prompt: "Erstelle eine Serverfunktion für Datei-Uploads, die Dateien bis zu 10MB akzeptiert, diese in Cloudflare R2 unter Verwendung des konfigurierten R2_BUCKET Bindings speichert, Dateitypen dahingehend validiert, dass nur Bilder (jpg, png, webp) und Dokumente (pdf) erlaubt sind, einen eindeutigen Dateinamen unter Beibehaltung der ursprünglichen Dateiendung generiert, die öffentliche R2 URL zurückgibt, Fehler elegant mit passenden Statuscodes und Nachrichten abfängt und Dateinamen bereinigt, um Sicherheitsprobleme zu verhindern."
5. Paraglide Messages
Das Hinzufügen von Schlüsseln für die Internationalisierung ist mühsam, wenn Sie viele Sprachen und viele Features haben. Claude kann die Keys generieren und sie in all Ihren Übersetzungsdateien entsprechend der bestehenden Struktur einfügen, ohne dass Sie jede Datei manuell aktualisieren müssen.
Prompt: "Füge Übersetzungen für ein neues Feature namens 'billing' hinzu, mit Schlüsseln für Subscription-Statusnachrichten. Binde folgende Keys ein: billing.subscription.active mit dem Text 'Your subscription is active', billing.subscription.canceled mit dem Text 'Your subscription has been canceled', billing.subscription.past_due mit dem Text 'Payment failed. Please update your payment method', und billing.invoice.paid mit dem Text 'Payment received. Thank you!'. Füge diese sowohl in die englischen als auch in die deutschen Übersetzungen ein und folge dabei der Struktur der bestehenden Nachrichtendateien im Verzeichnis messages/."
Häufige Fehlerquellen
Mit einem guten Kontext hat Claude Code zu 70% Erfolg. Die restlichen 30% schlagen auf vorhersehbare Weise fehl. Das Wissen um diese Fehlermuster spart Stunden an Debugging und hilft Ihnen, bessere Prompts zu schreiben, die diese Probleme vermeiden.
Falsches Auth Pattern
Claude generiert manchmal clientseitige Auth-Prüfungen, weil die meisten React-Tutorials so funktionieren. TanStack Start verlangt eine serverseitige Authentifizierung im beforeLoad, da clientseitige Prüfungen umgangen werden können und Sicherheitslücken schaffen. Verifizieren Sie immer, dass sich Auth im beforeLoad befindet, und nicht in useEffect oder in der Komponentenlogik.
// Falsch (nur clientseitig)
useEffect(() => {
if (!user) router.navigate('/login');
}, [user]);
// Richtig (serverseitig)
beforeLoad: ({ context }) => {
if (!context.user) return redirect('/login');
}
Falscher Speicherort der Dateien
Claude platziert Dateien in falschen Verzeichnissen, weil er Ihre exakte Projektstruktur nicht kennt. Überprüfen Sie nach der Generierung immer den Speicherort. API-Routen gehören nach src/routes/api/, Komponenten nach src/components/, Utilities nach src/lib/ und Datenbankschemata nach src/db/. Falsche Speicherorte verursachen Importfehler und ein defektes Routing.
Fehlende Typ-Importe
Beim Hinzufügen neuer Routen vergisst Claude manchmal, Typen aus Ihrem Projekt zu importieren. Stellen Sie sicher, dass der generierte Code Routentypen und jegliche benutzerdefinierten Typen importiert, die Ihr Projekt verwendet. Fehlende Importe verursachen TypeScript-Fehler, die unübersichtlich zu debuggen sind, weil der Code syntaktisch korrekt aussieht.
TanStack Intent Skills im Vergleich zu CLAUDE.md
TanStack Intent liefert Skills aus, die CLAUDE.md erweitern. Die Skills bieten Typdefinitionen für TanStack-Pakete, beispielhafte Code-Muster aus den offiziellen Docs, Dokumentations-Links als Referenz und Werkzeugbeschreibungen, die Claude bei der Codegenerierung nutzt. Diese Skills werden vom TanStack-Team gepflegt und bleiben bei Paketänderungen stets aktuell.
Die Skills werden automatisch geladen, wenn Sie TanStack-Pakete über npm installieren. Sie ergänzen CLAUDE.md, aber sie ersetzen es nicht. Ihre CLAUDE.md sollte sich auf Ihre projektspezifischen Konventionen konzentrieren, während die Skills paketspezifische Muster abdecken. Diese Trennung hält die CLAUDE.md wartbar und auf Ihr Projekt fokussiert.
Legen Sie heute noch los
Die Investition beträgt 30 Minuten, um eine gute CLAUDE.md zu schreiben. Der Ertrag sind 30 eingesparte Minuten bei jedem Feature, das Sie bauen. Über ein Jahr der Entwicklung hinweg sind das hunderte von Stunden, die Sie zurückgewinnen.
Der Schlüssel liegt darin, simpel anzufangen. Versuchen Sie nicht, alles auf einmal zu dokumentieren. Beginnen Sie mit der Projektübersicht und den wichtigsten Konventionen. Fügen Sie Anti-Patterns hinzu, wenn Sie Fehler entdecken. Im Laufe der Zeit wird Ihre CLAUDE.md zu einem umfassenden Leitfaden, der jeden Entwickler in Ihrem Team produktiver macht.
Kopieren Sie das CLAUDE.md Template von TanStack Ship, passen Sie es für Ihr Projekt an und beginnen Sie heute noch damit, schneller auszuliefern.
Wenn Sie neu bei Claude Code sind, empfehle ich, mit dem Prompt zur Routengenerierung zu beginnen. Er ist unkompliziert zu verifizieren, und Sie werden sofort sehen, wie viel schneller die Feature-Entwicklung mit dem richtigen Kontext wird. Sobald Sie sich sicher fühlen, fügen Sie weitere Prompts hinzu, wenn Sie Muster entdecken, bei denen Claude Schwierigkeiten hat.
Das Ziel ist es nicht, Claude Ihren gesamten Code schreiben zu lassen. Es geht vielmehr darum, Claude Code schreiben zu lassen, der minimale Überarbeitung benötigt. Mit einem guten Kontext wird das zur Norm und nicht zur Ausnahme.
Ich habe festgestellt, dass die größten Produktivitätssteigerungen dadurch entstehen, dass Claude Boilerplate-Code korrekt abhandelt. Serverfunktionen, Routendefinitionen und Datenbankschemata sind vorhersehbare Muster, die Claude gut erlernt. Die Zeitersparnisse summieren sich bei jedem Feature, das Sie erstellen.
Über die Produktivitätssteigerungen hinaus sorgen gute CLAUDE.md Dateien insgesamt für schnellere Code-Reviews. Wenn Claude Code generiert, der Konventionen folgt, verbringen Reviewer weniger Zeit mit stilistischen Kleinigkeiten und mehr Zeit mit echten Logikproblemen. Das Ergebnis sind bessere Code-Reviews und schnellere Iterationszyklen für das gesamte Team.