Claude Code in fremden Repos: die erste Änderung sicher machen

In einem gerade übernommenen internen Repo habe ich es am ersten Tag verbockt.

“Lies dir das Ganze mal durch und bring die Stellen in Ordnung, die dir auffallen” — das war mein Auftrag an Claude Code. 30 Minuten später waren 23 Dateien umgeschrieben. Inhaltlich gar nicht schlecht. Aber “ganz nebenbei” hatte der Agent auch die Produktions-Deployment-Konfiguration und die Bezahl-Dateien aufgeräumt, die niemand anfassen darf. Der Diff war so riesig, dass nicht einmal ich noch wusste, welche Änderung wirklich nötig war. Am Ende habe ich alles weggeworfen und neu angefangen.

Dass eine clevere KI Unfälle baut, ist kein Fähigkeitsproblem. Es lag schlicht daran, dass vor dem Einstieg niemand festgelegt hatte, wie weit sie gehen darf. Heute baue ich diesen ersten Tag so um, dass er rückgängig zu machen, prüfbar und tatsächlich abschließbar ist.

Das Wichtigste in Kürze

• An dem Tag, an dem du zum ersten Mal in fremden Code einsteigst, schreibst du zuerst auf eine Seite: Was darf gelesen werden, was ist tabu, welchen Prüfbefehl lässt du am Ende laufen.
• Überlass Claude Code nicht von Anfang an den großen Umbau. Fang mit einer kleinen, rückgängig machbaren Änderung an (Testnamen aufräumen, Kommentare ergänzen).
• Bevor die Meldung “fertig” kommt, lass immer einen Prüfbefehl laufen und sichere das Ergebnis.
• Löschen, Produktions-DB, Abrechnung und Force-Push bleiben am ersten Tag fest auf “Mensch bestätigt”. Nur was sich als sicher erweist, automatisierst du später.
• Wenn der Diff zu wachsen beginnt, schraub nicht zuerst am Auftragstext, sondern reduziere die Dateien, die angefasst werden dürfen.

Warum du den Rahmen am ersten Tag festlegst

Ein neues Repo ist eine Stadt ohne Karte. Welche Datei das Herzstück ist und welche kaputtgeht, wenn man sie anfasst, sieht am Anfang niemand.

Wenn du Claude Code jetzt bittest “Sieh dir alles an und bessere aus”, greift die KI aus reiner Hilfsbereitschaft breit ein. Nicht die KI ist schuld. Die Ursache liegt beim Menschen, der ihr keinen Rahmen mitgegeben hat. Wenn du einer neuen Aushilfe sagst “Mach den Laden mal schön” und sie dir die Kasseneinstellungen umstellt, dann liegt das Problem bei dir, der den Auftrag gegeben hat, oder?

Deshalb besteht der erste Schritt nicht darin, einen cleveren Prompt zu schreiben, sondern eine Karte zu zeichnen. Welche Regale du durchsehen darfst, welche Schublade verschlossen bleibt, was du vor dem Gehen kontrollierst. Wenn du nur diese drei Dinge auf einen Zettel schreibst, verschwinden die Unfälle des ersten Tages fast vollständig.

Die drei Grenzen, die du zuerst festlegst

Die Reihenfolge ist wichtig. Wir legen sie von oben nach unten fest.

Was festlegen	Beispiel	Warum zuerst festlegen
Was gelesen werden darf	src/, docs/, Testdateien	Lässt man alles lesen, kommen oft Vorschläge zu Unrelevantem
Was tabu ist	.env, Bezahlung, Authentifizierung, DB-Migrationen, Produktions-Deployment	Geht das kaputt, ist es nicht mehr zu retten
Prüfung am Ende	npm run build, ein Test	Um jedes Mal einen “Beweis, dass es läuft” zu sichern

Diesen Zettel mit den drei Punkten (Text reicht) lege ich als ONBOARDING.md in den Arbeitsordner. Es ist auch die erste Datei, die ich Claude Code lesen lasse. Erst die Karte teilen, dann durch die Stadt laufen lassen — diese Reihenfolge.

Was die KI übernimmt und was der Mensch entscheidet

Vermischst du das hier, baust du Unfälle. Die Grenze muss klar sein.

Arbeit, die du Claude Code überlassen darfst

• Das ganze Repo überfliegen und die Struktur zusammenfassen
• Suchen, “in welcher Datei diese Funktion liegt”
• Entwürfe für rückgängig machbare kleine Verbesserungen: Testnamen aufräumen, Kommentare ergänzen, Typen vervollständigen
• Prüfbefehle ausführen, Fehlerlogs lesen und die Ursache eingrenzen

Arbeit, die der Mensch immer entscheidet

• Ob eine Änderung in eine Tabuzone hinein erlaubt wird
• Dateien löschen, Operationen auf der Produktions-DB, Abrechnungslogik, Force-Push
• Die letzte Entscheidung, ob eine große Designänderung gemergt werden darf
• Ob gestoppt wird, wenn der Diff breiter wird als erwartet

Mein Maßstab ist einfach. Was sich bei einem Fehler mit git zurückholen lässt, überlasse ich der KI. Was nicht rückholbar ist, da drückt der Mensch den Knopf. Hältst du nur diese eine Linie ein, bricht am ersten Tag nichts groß zusammen.

Copy-Paste-Vorlage für den Prompt

Bevor ich in die erste Änderung gehe, werfe ich Folgendes hinein. Der Trick: nicht sofort schreiben lassen, sondern zuerst einen Plan zurückgeben lassen.

Das ist ein bestehendes Repo, das ich zum ersten Mal anfasse. Halte dich an folgende Regeln.

[Lesen erlaubt] nur src/ und docs/ und Testdateien
[Nicht anfassen] .env / Authentifizierung / Bezahlung / DB-Migrationen / Produktions-Deployment
[Ziel diesmal] genau eine kleine, rückgängig machbare Verbesserung (z. B. Testnamen aufräumen)
[Prüfung] nach der Änderung immer `npm run build` laufen lassen und das Ergebnis einfügen

Ändere noch keinen Code.
Gib mir zuerst einen Plan zurück, welche Datei du wie ändern willst,
und formuliere die obigen Regeln mit deinen eigenen Worten neu.

Wenn der zurückgegebene Plan unsere Einschränkungen korrekt in eigenen Worten wiederholt, ist er bestanden. Versucht er, den Rahmen auszuweiten, stoppe ich sofort. Ist der Plan gut, geht es weiter mit “Dann setz das genau so um und führe bis zum build aus”.

Die Grenzen auch im Code festhalten

Regeln auf Papier vergisst man. Deshalb halte ich den Onboarding-Plan auch in maschinenlesbarer Form fest. Das folgende Skript läuft direkt. Tausch den Inhalt für dein eigenes Repo aus.

#!/usr/bin/env bash
# Fasst den Onboarding-Plan fuer ein bestehendes Repo in einer JSON zusammen
set -euo pipefail

cat > onboarding-plan.json <<'JSON'
{
  "goal": "Die erste Aenderung im bestehenden Repo sicher abschliessen",
  "readOnlyCommands": [
    "git status --short",
    "git ls-files | head -50",
    "grep -rn \"TODO\\|FIXME\" src | head -20"
  ],
  "protectedAreas": [".env", "billing", "auth", "db/migrations", "deploy/prod"],
  "firstTask": "Eine rueckgaengig machbare kleine Verbesserung an Doku oder Test",
  "proofCommand": "npm run build",
  "rollback": "git diff -- path/to/changed-file && git checkout -- path/to/changed-file"
}
JSON

echo "=== Onboarding-Plan ==="
cat onboarding-plan.json

echo ""
echo "=== Aktueller Diff (leer = noch nicht bearbeitet) ==="
git status --short

Dieses Skript ist nicht spektakulär. Sein Wert liegt darin, dass du vor Arbeitsbeginn die Tabuzonen und den Beweis-Befehl in einer Datei fixierst. Du musst nur protectedAreas durch die gefährlichen Stellen deines Repos ersetzen, schon hast du die Karte für den ersten Tag.

Es beruhigt, auch einen Prüfbefehl bereitzuhalten. Bei einem Node.js-Projekt prüfst du mit so einem minimalen Check maschinell, “ob etwas kaputt ist”.

// check.mjs : Minimal-Skript, das nur prueft, ob der Build durchlaeuft
import { execSync } from "node:child_process";

try {
  // Durch den Pruefbefehl deines eigenen Projekts ersetzen
  execSync("npm run build", { stdio: "inherit" });
  console.log("Pruefung OK: Build laeuft durch. Bitte den Diff reviewen.");
} catch (e) {
  console.error("Pruefung NICHT OK: Build ist gefallen. Nicht mergen, Ursache pruefen.");
  process.exit(1);
}

Ist node check.mjs grün, geht der Diff ins Review, ist er rot, wird gestoppt. Allein mit dieser einen Datei verschwindet der Unfall, bei dem man im Glauben “müsste laufen” einfach mergt.

So nutzt du das in drei Situationen

Wenn eine ähnliche Lage zu deiner passt, bau die Schritte nicht neu, sondern tausch nur die Namen gegen deine Situation aus.

1. Übernahme einer Content-Website Lass zuerst den Ablageort der Artikeldaten, den Bilderordner, den Build-Befehl und die Produktseiten lesen und erfassen. Die erste Änderung ist nur “ein kaputter Link wird repariert”. Läuft der Build durch, geht es ins Review. Das große Umschreiben von Fließtext kommt erst, wenn klar ist, dass es sicher ist.

2. Eine SaaS-Codebasis Schreib Authentifizierung, Abrechnung und DB-Migrationen klar als Tabuzone fest. Beschränke die erste Aufgabe auf etwas wie “die Beschreibungstexte der Tests verständlicher machen” und geh erst weiter, nachdem ein Mensch zugestimmt hat. Lässt du hier locker, schleicht sich eine “freundliche Verbesserung” in die Zahlungslogik ein und dir wird ganz anders.

3. Ein altes Legacy-Repo “Modernisiere das Ganze” ist ein Tabuwort. Der Diff wird so groß, dass man ihn nicht mehr lesen kann. Geh stattdessen einen kleinen Schritt, der sich per Build prüfen lässt: einen Tippfehler im Funktionsnamen beheben, Testnamen aufräumen. Klappt es einmal, gehst du nach demselben Muster den nächsten Schritt.

Jedes Beispiel hat einen Haltepunkt. Weil es einen Haltepunkt gibt, breitet sich die Arbeit nicht endlos aus.

Fehlerbeispiele und wie du sie behebst

Ich schreibe es ehrlich. Die ersten paar Male habe ich alles verbockt.

Ohne Tabuzonen beauftragt → Der Diff wurde zu groß zum Reviewen, ich musste alles wegwerfen. Die Lösung ist simpel: bevor du den Auftragstext überarbeitest, reduziere zuerst die Dateien, die gelesen werden dürfen. Je enger der Rahmen, desto kleiner der Spielraum für Ausbrüche der KI.

Erst nach allen Änderungen gebaut → Ich wusste nicht mehr, welche Änderung etwas kaputtgemacht hatte. Heute lasse ich nach jeder einzelnen geänderten Datei die Prüfung laufen. Der Moment des Bruchs bleibt im Protokoll, also ist die Ursache sofort klar.

Mich allein auf meine Augen verlassen → An einem stressigen Tag übersieht man garantiert etwas. Heute überlasse ich buchstäblich “was die Maschine wissen kann” der Maschine: ob der Build durchläuft, das Testergebnis, kaputte Links. Das menschliche Auge nutze ich nur noch für Designentscheidungen, die keine Maschine erfassen kann. Damit sind meine nächtlichen Reviews deutlich seltener geworden.

Ich halte die Fallstricke im Artikel fest, weil Leser allein an Erfolgsbeispielen nicht merken, wann sie selbst in einer gefährlichen Lage sind. Notier dir kurz, welcher Auftrag zu breit wurde und welche Prüfung gefehlt hat — dann tappst du beim nächsten Mal nicht in dasselbe Loch.

Häufige Fragen

F. Was soll ich als erste Änderung wählen? A. Wähle etwas, das sich “bei einem Fehler mit git checkout zurückholen lässt”. Testnamen aufräumen, Kommentare ergänzen, Tippfehler korrigieren — das ist sicher. Neue Features oder Konfigurationsänderungen eignen sich nicht für den ersten Tag.

F. Wie detailliert sollte ich die Tabuzonen aufschreiben? A. Nur die “Stellen, die bei einem Bruch nicht mehr zu retten sind”, reichen. .env, Authentifizierung, Abrechnung, Produktions-Deployment, DB-Migrationen. Hast du anfangs diese fünf im Griff, verhinderst du fast alle fatalen Unfälle.

F. Kann ich mir den Umweg sparen, Claude Code erst einen Plan zurückgeben zu lassen? A. Ich empfehle, ihn nicht zu sparen. Der kleine Aufwand, den Plan neu formulieren zu lassen, deckt Abweichungen im Rahmen schon vor der Änderung auf. Das ist weit billiger, als es erst zu merken, nachdem der Code geschrieben ist.

F. Reicht der Build als einziger Prüfbefehl? A. Am ersten Tag reicht der Build allein. Wenn du Routine bekommst, leg einen passenden Test dazu. Willst du von Anfang an alle Tests laufen lassen, wird es zu schwerfällig, um durchzuhalten. Klein anfangen und erst erweitern, wenn sich Erfolgslogs angesammelt haben.

F. Worauf muss ich bei der Einführung im Team achten? A. Schreib die Grenzen in eine gemeinsame Datei wie ONBOARDING.md, damit alle dieselbe Karte nutzen. Sind die Tabuzonen je nach Person verschieden, schwankt auch der Maßstab im Review.

Verwandte Artikel

Die gedankliche Grundlage findest du in Wie auch Nicht-Entwickler Claude Code nutzen und Claude Code: der erste Schritt. Wie du dem Projekt seine Regeln beibringst, steht in CLAUDE.md Best Practices, und wie du gezieltere Anweisungen formulierst, in Prompt-Design in der Praxis. Die Details rund um Berechtigungen prüfst du am besten zusätzlich in der offiziellen Anthropic-Dokumentation.

Was ich tatsächlich ausprobiert habe

Nach dem “23-Dateien-Unfall” vom Anfang habe ich die Reihenfolge des Onboardings geändert. Ich habe aufgehört, nach dem cleveren Prompt zu suchen, und fixiere stattdessen zuerst die Tabuzonen und den Prüfbefehl in onboarding-plan.json. Allein damit ist der Unfall, bei dem Bezahlung oder Produktionskonfiguration angefasst werden, auf null gegangen.

An dem Tag, an dem ich die erste Änderung auf “Testnamen aufräumen” beschränkt habe, passte der Diff in 8 Zeilen, und der Build lief auf Anhieb durch. Das Review dauert keine zwei Minuten. Umgekehrt ist der Diff an einem anderen Tag, an dem ich ohne festgelegten Rahmen beauftragt habe, wieder aufgebläht, und ich habe alles weggeworfen. Der Unterschied lag nicht in der Klugheit des Modells, sondern darin, ob ich vor dem Einstieg eine Karte gezeichnet habe.

Wer das Muster, fremden Code sicher anzufassen, am echten Beispiel des eigenen Teams festigen will: In Schulung und Beratung bauen wir die auf deinen Arbeitsalltag zugeschnittene Einführung gemeinsam auf. Fang am besten noch heute damit an, fünf Tabuzonen deines eigenen Repos aufzuschreiben.