Projekt vorbereiten: Dateien, Struktur, Kontext

Bevor du den ersten Prompt schreibst, muss dein Projekt vorbereitet sein. Nicht für dich — für die KI. Denn eine KI ohne Kontext ist wie ein neuer Entwickler am ersten Tag: motiviert, schnell, aber völlig orientierungslos. Und genau wie bei einem echten Onboarding entscheidet die Vorbereitung darüber, ob die nächsten Wochen produktiv werden oder eine Katastrophe.

CLAUDE.md — das Onboarding-Dokument für deine KI

Jede KI, die mit deinem Code arbeitet, braucht eine Projektbeschreibung. Bei Claude heißt diese Datei CLAUDE.md, bei anderen Tools gibt es vergleichbare Mechanismen — Cursor hat seine .cursorrules, Copilot liest aus dem Projektkontext. Der Name ist zweitrangig — der Inhalt entscheidet. In diese Datei gehört alles, was du einem neuen Teammitglied am ersten Tag erklären würdest: Projektname, Tech-Stack, Architektur, Coding-Standards, Namenskonventionen. Nicht als Roman, sondern als kompaktes Nachschlagewerk.

Ohne diese Datei rät die KI. Und sie rät falsch. Sie schreibt englische Kommentare in dein deutsches Projekt. Sie verwendet jQuery, obwohl dein Projekt bewusst darauf verzichtet. Sie erzeugt Helper-Klassen, die niemand braucht, und baut Abstraktionen ein, die deine Architektur unterlaufen. Eine gute Projektbeschreibung verhindert 80% der Korrekturschleifen, bevor sie entstehen. Das ist keine Übertreibung — ich habe Projekte mit und ohne CLAUDE.md parallel geführt und den Unterschied gemessen.

Der häufigste Fehler: zu viel reinschreiben. Eine CLAUDE.md mit 200 Zeilen frisst Token-Budget und verwässert die wichtigen Informationen. Drei präzise Sätze über die Architektur schlagen drei Absätze. Vergleich das mal konkret — eine minimale Projektbeschreibung könnte so aussehen:

# Projekt
WordPress Theme für ruhrcoder.de — klassisches PHP-Theme, kein Block-Editor.

# Stack
PHP 8.2, WordPress 6.x, Vanilla JS (kein jQuery), Roboto Flex Variable Font.

# Regeln
Deutsche Kommentare. Kein var_dump. Alle Ausgaben escapen. Max-width: 1200px.

Das sind neun Zeilen. Die KI weiß damit: PHP, kein jQuery, deutsche Sprache, WordPress-Kontext. Das reicht für 90% der Aufgaben. Eine aufgeblähte Version mit Plugin-Beschreibungen, Deployment-Details und der gesamten Projekthistorie bringt keinen Mehrwert — sie kostet nur Token und lenkt ab.

Vergleich das mit einer aufgeblähten Variante, die drei Bildschirmseiten lang ist: Die KI verarbeitet sie zwar, aber sie zieht Informationen aus Abschnitten, die mit deiner Aufgabe nichts zu tun haben. Du fragst nach einem CSS-Fix, und die KI referenziert deine Deployment-Strategie. Du willst eine PHP-Funktion, und sie berücksichtigt deine Datenbank-Migrationsregeln. Fokus schlägt Vollständigkeit — immer.

Verzeichnisstruktur — Kontext von Quellcode trennen

In vielen meiner Projekte nutze ich ein .ai/-Verzeichnis, das alle KI-relevanten Dateien bündelt: Regeln, Status-Tracking, Kontextdateien. Die Trennung von KI-Kontext und Quellcode ist kein Luxus, sondern Hygiene. Dein Projektverzeichnis bleibt sauber, und die KI weiß genau, wo sie nachschauen muss. Wenn ein neuer Entwickler das Repository klont, sieht er sofort: Hier gibt es KI-Unterstützung, und hier sind die Spielregeln.

Ein typisches Setup sieht so aus: Im Projektstamm liegt die CLAUDE.md als Einstiegspunkt. Darunter das .ai/-Verzeichnis mit Unterordnern für rules/ und briefs/. Die Rules definieren, was die KI darf und was nicht — Coding-Standards, verbotene Patterns, Architekturregeln. Die Briefs beschreiben konkrete Aufgaben mit Akzeptanzkriterien. Dazu kommt eine status.md, die den aktuellen Projektstand festhält — damit die KI in der nächsten Session weiß, wo sie aufgehört hat.

projekt/
├── CLAUDE.md              # Einstiegspunkt für die KI
├── .ai/
│   ├── rules/
│   │   ├── code-style.md  # Naming, Typen, Formatierung
│   │   └── architecture.md # Schichten, Patterns, Verbote
│   ├── briefs/
│   │   └── BRIEF-01.md    # Konkrete Aufgabe mit Kriterien
│   └── status.md          # Aktueller Projektstand
├── src/
├── tests/
└── .editorconfig

Das klingt nach Overhead. Ist es aber nicht. Ohne diese Struktur wiederholst du dich in jedem Prompt. Du erklärst jedes Mal neu, welche Architektur du verfolgst, welche Patterns verboten sind, wo die Tests liegen. Mit der Struktur zeigst du einmal auf die Datei, und die KI liest selbstständig nach. Das spart nicht nur Token, sondern auch die mentale Last, bei jedem Prompt den gleichen Kontext zusammenzustellen.

Kontext ist König — aber weniger ist mehr

Jedes KI-Modell hat ein Token-Budget. Das ist die Gesamtmenge an Text, die es in einer Konversation verarbeiten kann — Eingabe und Ausgabe zusammen. Bei Claude sind das je nach Modell zwischen 200.000 und über einer Million Token. Klingt viel, ist es auch — aber wenn du dein gesamtes Projekt als Kontext reinlädst, bleibt wenig Raum für präzise Antworten. Schlimmer noch: die KI verliert den Fokus und zieht irrelevante Informationen aus Dateien, die mit deiner Frage nichts zu tun haben.

Die 80/20-Regel gilt hier besonders hart. 20% des Kontexts liefern 80% der Qualität. Ein präziser Verweis auf die relevante Datei und die betroffene Funktion bringt mehr als das gesamte Repository im Kontext. Statt die komplette Klasse zu pasten, zeigst du auf die Methode, die du ändern willst, und erklärst in einem Satz, was sie tut. Die KI kann in den meisten modernen Tools die Datei selbst öffnen — du musst ihr nur sagen, wo sie schauen soll.

Ich habe das in der Praxis oft erlebt: Ein Prompt mit 50 Zeilen Kontext liefert bessere Ergebnisse als einer mit 500. Nicht weil die KI weniger kann, sondern weil sie bei weniger Kontext gezwungen ist, sich auf das Wesentliche zu konzentrieren. Genau wie ein menschlicher Entwickler, der ein klares Ticket bekommt statt eines Confluence-Romans. Die Versuchung ist groß, alles reinzupacken, „damit die KI den vollen Überblick hat“. Widerstehe ihr. Gib der KI genau die Information, die sie für diese eine Aufgabe braucht — nicht mehr.

Was vor dem ersten Prompt existieren muss

Bevor du die KI zum ersten Mal ansprichst, sollten bestimmte Dateien in deinem Projekt vorhanden sein. Nicht weil die KI sie zwingend braucht, sondern weil ihr Fehlen zu Raten und Improvisieren führt — und das willst du nicht.

Die CLAUDE.md (oder ein vergleichbares Kontextdokument) steht an erster Stelle: Projektname, Stack, Architekturentscheidungen, die wichtigsten Regeln. Dann eine .editorconfig, damit die KI weiß, ob du Tabs oder Spaces verwendest, welche Zeilenlänge gilt und wie Zeilenumbrüche aussehen. Ohne sie rät die KI nach Trainingsdata-Mehrheit — und die Mehrheit nutzt andere Einstellungen als du.

Eine .gitignore gehört dazu, damit generierter Code nicht versehentlich Dateien ins Repository einschleust, die dort nicht hingehören — vendor/, node_modules/, .env-Dateien. Viele KI-Tools lesen die .gitignore und respektieren die Ausschlüsse. Wenn sie fehlt, kann die KI Dateien als Kontext verwenden, die Secrets enthalten oder schlicht irrelevant sind.

Dazu gehören Coding-Rules in einer Form, die die KI lesen kann. Das kann eine Markdown-Datei im .ai/rules/-Verzeichnis sein, das kann die CLAUDE.md selbst sein. Konkret, nicht vage: Nicht „sauberer Code“ sondern „declare(strict_types=1) in jeder PHP-Datei, finale Klassen als Standard, keine Magic Numbers“. Und schließlich eine README, die das Projekt in fünf Sätzen erklärt — nicht für die KI, sondern für jeden, der das Repository zum ersten Mal öffnet. Die KI profitiert davon genauso.

Ein reales Beispiel: WordPress-Theme mit und ohne Vorbereitung

Ohne Vorbereitung: „Erstelle mir eine WordPress-Template-Datei für die Startseite.“ Die KI liefert ein Template mit get_header(), get_footer(), einer WP_Query-Schleife und Bootstrap-Klassen. Nichts davon passt — dein Theme hat ein eigenes CSS-Framework, die Query-Logik gehört in eine separate Klasse, und die Template-Hierarchie deines Themes folgt einem anderen Pattern als der WordPress-Standard.

Mit Vorbereitung: Die CLAUDE.md definiert Stack, Layout-Breite, CSS-Methodik und Template-Struktur. Die KI generiert ein Template, das zu deinem Projekt passt — mit den richtigen CSS-Klassen, der richtigen Query-Strategie und der richtigen Einordnung in deine Template-Hierarchie. Der Unterschied ist nicht die Qualität der KI, sondern die Qualität der Vorbereitung.

All das dauert keine Stunde. Aber diese Stunde spart dir Tage, die du sonst mit dem Korrigieren von KI-Output verbringst, der am Projekt vorbei generiert wurde. Vorbereitung ist nicht optional — sie ist die Grundlage für alles, was danach kommt. In den nächsten Teilen dieser Serie schauen wir uns an, wie du die Regeln formulierst und was einen guten Prompt von einem schlechten unterscheidet.

Alle Teile dieser Serie

Teil 1: Projekt vorbereiten — Dateien, Struktur, Kontext
Teil 2: Gute Regeln schreiben — der KI Grenzen setzen
Teil 3: Saubere Prompts — präzise formulieren, Token sparen
Teil 4: Modelle und Tools — Stärken, Schwächen, Einsatzgebiete
Teil 5: Sicherheit — was nicht in den Prompt gehört
Teil 6: Reviews — warum der Mensch das letzte Wort haben muss
Teil 7: Wann KI nicht nutzen — die Grenzen kennen
Glossar: Begriffe für Entwickler