Kontext-Engineering: Warum dein Prompt das kleinste Problem ist

Ich stand neulich in einem Kundenprojekt vor einer Situation, die ich inzwischen gut kenne. Neue Codebasis, keine AI-Unterstützung eingerichtet, und der Entwickler im Team fragt mich: "Wie kriegst du die AI dazu, so gute Ergebnisse zu liefern?" Ich habe auf seinen Bildschirm geschaut. Er hatte Claude offen – im Browser, ohne Projektkontext, mit einem frischen Chat für jeden Task.

Da liegt das Problem. Nicht beim Tool, nicht beim Modell, nicht beim Prompt. Bei der fehlenden Struktur.

Nach einem Jahr, in dem ich AI täglich in echten Projekten einsetze, bin ich überzeugt: Der Unterschied zwischen "AI ist ganz okay" und "AI hat meinen Workflow fundamental verändert" liegt nicht im perfekten Prompt. Er liegt im Kontext, den du der AI gibst – bevor sie die erste Frage beantwortet.

Die CLAUDE.md ist der Anfang von allem

Wenn ich in einem neuen Projekt mit Claude Code starte, ist das erste, was ich erstelle, die CLAUDE.md. Nicht die erste Komponente, nicht das erste Feature – die Kontext-Datei.

Was steht drin? Alles, was ein neuer Entwickler am ersten Tag wissen müsste:

• Tech Stack und Versionen
• Projektstruktur und warum sie so ist
• Design System – Farben, Typografie, Abstände – konkret, mit Werten
• Coding-Regeln: was immer gilt, was nie gilt
• Externe Links, API-Endpunkte, wichtige Accounts

Das klingt nach Aufwand. Ist es auch – einmalig. Aber danach spare ich mir in jeder einzelnen AI-Session den Aufbau dieses Kontexts. Ich erkläre nicht mehr "wir nutzen Tailwind, nicht Styled Components" oder "alle Texte müssen durch i18n". Das steht in der Datei. Claude liest sie, hält sich daran.

Der praktische Unterschied: Wenn ich sage "erstelle eine neue Sektion für die Services-Seite", bekomme ich Code, der mein Design System verwendet, meine Komponenten nutzt, TypeScript strict ist und keine hardcodierten Texte enthält. Nicht weil Claude zaubern kann – sondern weil er die Regeln kennt.

PRODUCT_SPEC.md – die Produktvision auf Papier

Die CLAUDE.md beschreibt wie gebaut wird. Die PRODUCT_SPEC.md beschreibt was und warum.

Ich habe sie zum ersten Mal erstellt, weil ich merkte: Wenn ich drei Wochen nicht an einem Projekt war und dann weitermache, brauche ich selbst eine Weile, um wieder im richtigen Frame zu sein. Die AI braucht das erst recht.

In meiner PRODUCT_SPEC.md stehen Dinge wie:

• Was ist das Kernversprechen des Produkts?
• Wer sind die Nutzer und was wollen sie?
• Welche Features gibt es, und welche Design-Entscheidungen stecken dahinter?
• Was wurde bewusst nicht gebaut – und warum?

Der letzte Punkt ist unterschätzt. "Was wir nicht bauen" ist genauso wichtig wie "was wir bauen". Wenn ich der AI nicht erkläre, dass wir bewusst auf ein bestimmtes Feature verzichten, wird sie es beim nächsten passenden Moment vorschlagen oder sogar implementieren.

Coding-Regeln auslagern – nicht im Prompt erklären

Ich habe beobachtet, dass viele Leute ihre Regeln im Prompt mitgeben. "Schreib keinen Inline-CSS. Nutze keine any-Types in TypeScript. Erstelle immer eine deutsche und englische Version." Und dann schreiben sie das beim nächsten Task wieder.

Das ist ermüdend – und fehleranfällig. Irgendwann vergisst man es, oder man formuliert es leicht anders, und die AI interpretiert es leicht anders.

Meine Lösung: Ein ausführlicher Abschnitt in der CLAUDE.md. Alles, was immer gilt, steht dort. Jede Regel, jede Konvention, jede "tu das nie"-Anweisung.

Ein paar Beispiele aus echten Projekten:

• ESLint muss vor jedem Commit ohne Fehler laufen
• Keine eslint-disable-Kommentare ohne explizite Genehmigung
• Jeder neue Text muss in i18n/de.json und i18n/en.json erscheinen
• Typografie: Halbgeviertstrich mit geschützten Leerzeichen, kein englischer Gedankenstrich

Die letzte Regel kennt jeder, der schon mal vergessen hat, sie zu formulieren. Ich habe sie gelernt, als ich eine Stunde damit verbracht habe, falsche Gedankenstriche durch das ganze Projekt zu korrigieren.

Wiederkehrende Tasks als Skills

Das ist der Teil, über den am wenigsten geredet wird – und der mir am meisten gebracht hat.

Jedes Projekt hat Tasks, die immer gleich ablaufen. Nach einem neuen Feature: Linter ausführen, Browser-Screenshot machen, das Ticket mit dem Ergebnis kommentieren. Bei einem neuen Blog-Post: Frontmatter prüfen, Typografie-Check laufen lassen, deutsche und englische Version erstellen.

Früher habe ich das immer wieder im Prompt beschrieben. "Vergiss nicht, danach den Linter zu starten" – jedes Mal. Jetzt lagere ich solche Workflows in Skill-Dateien aus. Eine Markdown-Datei, die Schritt für Schritt beschreibt, was in einem bestimmten Kontext zu tun ist. Die AI referenziert sie, ich erwähne sie kurz im Prompt: "Nutze den publish-blog-post-Skill."

Das klingt nach Kleinigkeit. In der Praxis ist es das, was den Unterschied zwischen einer AI, die ich korrigieren muss, und einer AI, die einfach das Richtige tut, ausmacht.

Bei größeren Projekten: spezialisierte Agents

Das Kontext-Prinzip lässt sich skalieren. Wenn ein Projekt wächst, bekommt jeder Agent seine eigene Kontext-Datei – mit genau dem Wissen, das er braucht, und nichts, das ihn ablenkt. Der Tester muss nicht wissen, wie Tailwind-Klassen aufgebaut sind. Der Builder muss nicht wissen, wie Tickets strukturiert sind.

Wie das konkret aussieht und was ein solcher Multi-Agent-Workflow im Alltag leistet, habe ich in Mein Agent-Workflow – von der Idee bis zum Deployment in Minuten beschrieben.

Datenmodelle vor dem Code definieren

Das ist eine Lektion, die ich auf die harte Tour gelernt habe.

Ich hatte einer AI den Auftrag gegeben, ein neues Feature mit mehreren Datenbank-Tabellen zu implementieren. Das Ergebnis war technisch funktionierend – aber das Datenmodell war falsch. Nicht falsch im Sinne von "Syntax-Fehler", sondern falsch im Sinne von "das wird in drei Monaten zum Problem". Fehlende Constraints, eine N:M-Relation, die eigentlich eine 1:N sein sollte, und ein Feld, das semantisch zu einer anderen Tabelle gehört hätte.

Seitdem mache ich das anders: Bevor ich die AI auf Datenbankarbeit loslasse, schreibe ich eine kurze Model-Spec. In Prosa, keine besondere Syntax:

Tabelle: orders
- id: UUID, Primary Key
- user_id: FK → users.id, NOT NULL
- status: ENUM (pending, processing, shipped, cancelled), NOT NULL
- total_cents: INTEGER, NOT NULL (kein DECIMAL – wir rechnen in Cent)
- created_at: TIMESTAMP WITH TIME ZONE, NOT NULL, DEFAULT now()

Relationen:
- Ein Order hat viele OrderItems (1:N)
- Ein Order gehört zu genau einem User

Das dauert 15 Minuten. Es spart eine Stunde Refactoring.

Kontext-Engineering statt Prompt-Engineering

Ich merke, dass "Prompt-Engineering" als Begriff gerade überall auftaucht. Workshops, Kurse, LinkedIn-Posts über die perfekte Formulierung.

Ich glaube, das ist der falsche Fokus.

Der Prompt ist der letzte Schritt. Das System drumherum – CLAUDE.md, PRODUCT_SPEC.md, Coding-Rules, Skills, Datenmodelle – ist das, was tatsächlich die Qualität bestimmt. Die AI ist nur so gut wie der Kontext, den sie bekommt. Und diesen Kontext kann man systematisch aufbauen, versionieren und verbessern.

Ein guter Prompt in einem schlecht vorbereiteten Projekt liefert mittelmäßige Ergebnisse. Ein mittelmäßiger Prompt in einem gut vorbereiteten Projekt liefert gute Ergebnisse.

Ich nenne es Kontext-Engineering. Wer das versteht, hat einen echten Vorteil – nicht nur mit Claude, sondern mit jedem AI-Tool. Im nächsten Post zeige ich, wie dieses Prinzip weitergedacht wird: mit Tickets, die das gleiche für einzelne Tasks leisten, was die CLAUDE.md fürs Gesamtprojekt tut.

Je besser die Struktur rund um die AI, desto besser die Ergebnisse. Das ist keine Theorie – das ist die Erfahrung aus einem Jahr täglichem Einsatz in echten Projekten.