Optimal mit KI arbeiten – Teil 3: Coden mit KI

KI-Agenten sind keine Suchmaschinen, die man einmalig befrägt — sie sind Pair-Programming-Partner, die am effektivsten arbeiten, wenn sie den Kontext deines Projekts wirklich verstehen. Dieser dritte und abschließende Teil der Reihe zeigt dir, wie du mit einem KI-Agenten wie Claude Code produktiv an echten Codebases arbeitest: von der Kontextvorbereitung über den iterativen Arbeitsloop bis hin zu Review und Qualitätssicherung.

Voraussetzungen

Du hast die ersten beiden Teile dieser Reihe gelesen:

• Teil 1 — Grundlagen: Wie KI-Sprachmodelle funktionieren, Prompting-Techniken, Kontext und Token-Limits.
• Teil 2 — Workflows: Effektive Nutzung von KI im Alltag, Recherche-Aufgaben, Texte und Konzepte.

Für diesen Teil brauchst du Grundkenntnisse in Git und einer Programmiersprache deiner Wahl. Die Beispiele nutzen Bash, TypeScript/Next.js und SQL — die Prinzipien gelten aber für jede Technologie.

---

Den Agenten orientieren: die Projekt-Regeldatei

Wenn du einem Kollegen eine neue Codebase zeigst, erklärst du ihm zuerst die wichtigsten Konventionen: Branching-Strategie, Deployment-Prozess, Besonderheiten der Infrastruktur. Genau dasselbe brauchst du für deinen KI-Agenten.

CLAUDE.md — Kontext on-demand

Claude Code liest beim Start automatisch eine Datei namens CLAUDE.md im Repo-Root. Das ist dein Ort für alles, was der Agent wissen muss, bevor er die erste Zeile Code anfasst.

Eine gute CLAUDE.md enthält:

• Workflow-Regeln (Commit-Konventionen, Branch-Strategie, Auto-Deploy-Verhalten)
• Infrastruktur-Details (Hosts, SSH-Zugang, Docker-Container-Namen)
• Einschränkungen (was nicht geht — z.B. "Kein Supabase-CLI verfügbar")
• Env-Dateien und ihre Bedeutung
• Verweise auf Subsysteme (z.B. "Frontend-Regeln in frontend/CLAUDE.md")

# CLAUDE.md — Mein Projekt

## Commits & Deployment
- Conventional Commits, kein Co-Author-Trailer
- `git push origin main` triggert automatischen Coolify-Rebuild

## Infrastruktur
- DB-Migrations NICHT via CLI, sondern per scp + docker exec:
  scp migrations/file.sql user@host:/tmp/
  ssh user@host 'docker exec -i $(docker ps --filter name=db -q) psql -U postgres < /tmp/file.sql'

## Verbotene Befehle
- `supabase db push` — CLI nicht vorhanden
- `npm run build` direkt — immer über CI

Tipp: Halte die CLAUDE.md aktuell. Ein veralteter Kontext ist schlimmer als keiner — der Agent trifft dann falsche Annahmen mit Selbstvertrauen.

Code-Konventionen explizit machen

Neben der Regeldatei helfen kurze Konvention-Snippets direkt im Prompt, wenn du an einem spezifischen Modul arbeitest:

Wir nutzen im Frontend:
- TypeScript strict mode
- Zod für Schema-Validierung (nie manuelle type-casts)
- React Query für alle API-Calls
- Tailwind CSS, keine inline-styles

Passe deine Ausgaben daran an.

Je präziser du diese Rahmenbedingungen setzt, desto weniger Zeit verbringst du damit, KI-Output nachzubessern.

---

Der Wissensgraph: den Agenten die Codebase navigieren lassen

Bei mittelgroßen bis großen Projekten reicht es nicht, den Agenten einfach auf den Code loszulassen — er liest dann zu viele irrelevante Dateien und verliert den Faden. Ein Wissensgraph oder ein strukturierter Index löst dieses Problem.

Tools wie graphify bauen einen statischen Graphen aus dem AST deines Projekts: Knoten sind Dateien/Module, Kanten sind Imports, Aufrufe und Abhängigkeiten. Der Agent kann diesen Graphen traversieren, statt blind alle Dateien zu öffnen.

# Einmalig: Wissensgraph erstellen
graphify init .

# Nach Code-Änderungen aktualisieren (AST-only, kein API-Cost)
graphify update .

# Im Agenten-Prompt dann:
# "Lies zuerst graphify-out/GRAPH_REPORT.md, dann beantworte..."

Schreib in deine CLAUDE.md explizit, dass der Agent den Graphen zuerst lesen soll:

## Wissensgraph
- IMMER `graphify-out/GRAPH_REPORT.md` lesen, bevor du Quelldateien öffnest.
- Für "wie hängt X mit Y zusammen"-Fragen: `graphify query "<frage>"` statt grep.

Das Ergebnis: Der Agent findet das relevante Modul in Sekunden, statt 30 Dateien zu lesen und dabei Token zu verbrauchen.

---

Der richtige Arbeitsloop

Effektives KI-Pair-Programming folgt einem klaren Rhythmus. Wenn du diesen Loop verinnerlicht hast, arbeitest du deutlich produktiver als jemand, der den Agenten einfach "mach das Feature" sagen lässt.

1. Recherchieren

Lass den Agenten zuerst die Codebase verstehen, bevor er schreibt:

Lies die Datei src/lib/auth.ts und erkläre mir, wie die Session-Validierung aktuell funktioniert. Noch keine Code-Änderungen.

Dieser Schritt verhindert, dass der Agent blindlings Code schreibt, der mit dem bestehenden System kollidiert.

2. Planen

Lass dir einen konkreten Plan vorlegen, bevor Code entsteht:

Ich möchte eine Rate-Limiting-Middleware für die /api/send-email Route hinzufügen.
Entwirf einen Plan: welche Dateien werden geändert, was wird neu erstellt,
welche Tests sind nötig? Noch kein Code.

Ein guter Agent nennt dir:

• Betroffene Dateien
• Neue Abhängigkeiten (und ob sie sicher sind)
• Potenzielle Konflikte mit bestehendem Code
• Testszenarien

3. Umsetzen — in kleinen Schritten

Hier ist der häufigste Fehler: einen riesigen Diff auf einmal zu verlangen. Stattdessen:

Schritt 1 von 3: Erstelle nur die Middleware-Funktion in src/lib/rateLimit.ts.
Noch keine Integration in die Route.

Kleine, überprüfbare Schritte bedeuten:

• Du kannst jeden Schritt reviewen, bevor der nächste kommt
• Fehler werden früh erkannt, nicht nach 500 geänderten Zeilen
• Der Agent verliert bei kleinen Kontexten seltener den Faden

4. Testen und verifizieren

Fordere Tests aktiv ein — sie kommen nicht automatisch:

Schreibe jetzt Unit-Tests für rateLimit.ts.
Decke ab: normaler Request, Rate-Limit überschritten, IP-Whitelist.
Nutze Vitest, keine externen Dependencies.

Und lasse den Agenten auch die Tests ausführen:

Führe `npx vitest run src/lib/rateLimit.test.ts` aus und zeige mir die Ausgabe.

5. Reviewen

Niemals blind committen. Geh den Diff durch:

git diff --stat        # Übersicht welche Dateien betroffen sind
git diff src/lib/      # Detaillierter Blick auf kritische Module

Frag den Agenten nach dem Reviewen explizit:

Gibt es in diesem Diff etwas, das du als riskant oder unvollständig einstufst?
Übersehe ich Edge-Cases?

---

Was KI gut kann — und wo du aufpassen musst

Die ehrliche Einschätzung ist entscheidend für realistische Erwartungen. Hier eine Übersicht aus der Praxis:

Aufgabe	KI-Eignung	Hinweis
Boilerplate generieren	Sehr gut	CRUD-Routes, Migrations, Test-Stubs
Refactoring (lokale Umbenennungen)	Gut	Bei großen Cross-File-Refactors Diff sorgfältig prüfen
Reguläre Ausdrücke schreiben	Gut	Output immer testen
SQL-Abfragen schreiben	Gut	Indizes und Performance-Implikationen prüfen
Dokumentation/Kommentare	Sehr gut	Gelegentlich zu ausführlich
Debugging mit Fehlermeldung	Gut	Kontextreiche Fehlermeldung mitgeben
Architekturentscheidungen	Vorsicht	Kennt deinen Deployment-Kontext nicht vollständig
Sicherheitskritischer Code	Vorsicht	Kryptographie, Auth-Flows immer manuell reviewen
Komplexe Businesslogik	Vorsicht	Domänenwissen fehlt, ungetestete Annahmen möglich
Versteckte Systemabhängigkeiten	Schlecht	KI kennt nur was im Kontext ist

Modellwahl für Code-Aufgaben

Wenn du Claude Code nutzt, hast du Zugriff auf verschiedene Modelle. Für Code-Aufgaben gilt als Faustregel:

• claude-opus-4-8 — Stärkstes Modell, ideal für komplexe Architektur-Fragen, mehrstufige Refactorings und Code-Reviews, bei denen kein Detail verloren gehen darf.
• claude-sonnet-4-6 — Sehr gutes Preis-Leistungs-Verhältnis für den täglichen Coding-Loop. Schnell genug für iteratives Arbeiten, stark genug für anspruchsvolle Aufgaben.
• claude-haiku-4-5 — Für einfache, repetitive Aufgaben: Kommentare schreiben, einfache Typ-Annotationen ergänzen, kurze Test-Stubs. Günstig und sehr schnell.

---

Sicherheit und Qualität nicht delegieren

Ein KI-Agent kann sicherheitskritische Muster aus Trainingsdaten replizieren — inklusive bekannter Schwachstellen. Drei Grundregeln:

1. Secrets niemals im Kontext

# Falsch: .env direkt referenzieren lassen
"Lies meine .env und erstelle den DB-Connection-String"

# Richtig: Platzhalter nutzen
"Der Connection-String hat dieses Format: postgresql://USER:PASS@HOST/DB
Erstelle eine Funktion, die ihn aus process.env liest."

2. Abhängigkeiten prüfen, bevor sie installiert werden

Wenn der Agent npm install some-package vorschlägt, prüfe zuerst:

npm info some-package | grep -E '(version|downloads|maintainers)'
# Und: https://snyk.io/advisor/ für Security-Score

3. Auth- und Kryptographie-Code manuell reviewen

KI-generierter Auth-Code ist oft funktional, aber subtil fehlerhaft — falsche Token-Expiry-Logik, fehlende CSRF-Protection, unsichere Vergleiche. Lass hier immer einen zweiten Blick laufen, am besten mit einem spezialisierten Review-Prompt:

Reviewe diesen Auth-Code ausschließlich unter Sicherheitsgesichtspunkten.
Suche nach: Token-Handling-Fehlern, fehlenden Validierungen,
Timing-Attacken, unsicheren Defaults.

---

Häufige Fehler

1. Den Kontext nicht setzen und sich über schlechte Ergebnisse wundern

Wenn du dem Agenten keine Projektregeln gibst, erfindet er welche — basierend auf dem, was er am häufigsten in Trainingsdaten gesehen hat. Das ist für dein Projekt oft falsch.

Lösung: CLAUDE.md im Repo, Konventionen im Prompt, spezifische Constraints explizit nennen.

2. Riesige Änderungen auf einmal verlangen

"Baue das gesamte Authentifizierungssystem neu" erzeugt einen 800-Zeilen-Diff, den niemand sinnvoll reviewen kann — und in dem sich Fehler verstecken.

Lösung: Aufgaben in überprüfbare Schritte aufteilen. Lieber fünf kleine PRs als ein Monster-Commit.

3. Tests nicht einfordern

KI-Agenten schreiben standardmäßig nur dann Tests, wenn du sie explizit verlangst. Ohne Tests weißt du nicht, ob der generierte Code tatsächlich das tut, was er soll.

Lösung: Tests als fester Bestandteil jedes Feature-Loops. Nicht optional.

4. Den Agenten als Orakel behandeln

"Ist dieser Ansatz richtig?" — Der Agent antwortet immer mit Selbstvertrauen, auch wenn er falsch liegt. Das liegt in der Natur der Modelle: Sie sagen das Wahrscheinlichste, nicht das Richtige.

Lösung: Vertrau keiner einzelnen Aussage bei architekturrelevanten Entscheidungen. Lass den Agenten Gegenargumente nennen: "Welche Nachteile hat dieser Ansatz?"

5. Env-Secrets im Kontext lassen

Wenn du dem Agenten ein ganzes Verzeichnis zum Lesen gibst und dort .env-Dateien liegen, sind deine Secrets im Kontext — und werden in Logs, Tool-Calls oder UI-Ausgaben sichtbar.

Lösung: .env* in .gitignore und auch aus Agent-Kontexten explizit ausschließen. Agenten brauchen keine echten Credentials — sie brauchen das Format.

6. Veraltete CLAUDE.md ignorieren

Eine CLAUDE.md, die beschreibt wie das Deployment vor sechs Monaten funktionierte, ist aktiv schädlich. Der Agent befolgt veraltete Anweisungen mit Konsequenz.

Lösung: CLAUDE.md bei jedem Infra-Change aktualisieren — genauso wie ein README.

---

Nächste Schritte

Mit diesem dritten Teil ist die Reihe "Optimal mit KI arbeiten" vollständig:

• Teil 1 hat dir gezeigt, wie KI-Sprachmodelle intern funktionieren, was Token und Kontext bedeuten und wie du Prompts strukturierst, die zuverlässig gute Ergebnisse liefern.
• Teil 2 hat erfolgreiche Workflows für den Alltag gebracht: Recherche, Texterstellung, Brainstorming und das richtige Mindset für KI als Werkzeug — nicht als Entscheider.
• Teil 3 — dieser Beitrag — hat gezeigt, wie du KI als echten Coding-Partner einsetzt: mit Kontext-Setup, einem strukturierten Loop, klarer Aufgabenteilung und dem nötigen kritischen Blick auf den Output.

Das Wichtigste zum Mitnehmen: Ein KI-Agent ist so gut wie der Kontext, den du ihm gibst, und so zuverlässig wie die Reviews, die du auf seinen Output anwendest. Wer diese beiden Stellschrauben beherrscht, multipliziert seine Produktivität — ohne Qualität zu opfern.

Wenn du diese Prinzipien in deinem Projekt umsetzen möchtest, von der Infra-Automatisierung über den Coding-Loop bis zur richtigen Tool-Auswahl, melde dich gerne. Ich helfe dir dabei, einen KI-Workflow aufzubauen, der tatsächlich zu deiner Codebase und deinem Team passt.

Lass uns zusammenarbeiten →