Die erste Stunde in fremdem Code mit Claude Code: erst die Karte, dann der Fix

An meinem ersten Übergabetag öffnete ich das Repository eines internen Tools, das mein Vorgänger hinterlassen hatte. Die README hatte drei Zeilen, das letzte Update lag acht Monate zurück. Ich bat Claude Code einfach: „Verschaffe dir einen Überblick über das Projekt und ändere den Text auf dem Login-Bildschirm.” Fünf Minuten später hatte es die Konfigurationsdateien rund um die Authentifizierung „gleich mit aufgeräumt” – und das Deployment-Skript für die Produktion, das seit Monaten niemand angefasst hatte, gleich dazu.

Zum Glück bemerkte ich es über git status und setzte alles zurück. Aber wenn ich es nicht gemerkt und vorher git commit gemacht hätte – mir läuft es noch heute kalt den Rücken hinunter. Das Problem war nicht, wie schlau das Modell ist. Das Problem war: Ich hatte die Arbeit delegiert, ohne selbst zu wissen, wo man anfassen darf und wo nicht.

Die erste Stunde in fremdem Code ist keine Zeit zum Reparieren, sondern zum Kartenzeichnen. In diesem Artikel zeige ich dir, wie du diese Karte zeichnest – als Ablauf, der dir auch in einem völlig unbekannten Repository keinen Unfall beschert.

Das Wichtigste in Kürze

• Die erste Stunde ist nicht zum „Reparieren”, sondern zum „Kartenzeichnen” da. Trenne zuerst die Bereiche, die du anfassen darfst, von denen, die tabu sind.
• Claude Code übernimmt nur das „Lesen und Auflisten”. Was zum Schutzbereich wird, entscheidet der Mensch.
• Lege vor dem ersten Fix immer genau einen Prüfbefehl fest (Build oder Test). Das ist dein Beweis dafür, dass etwas wirklich „repariert” ist.
• Der erste Fix bleibt klein – etwas, das du mit einem einzigen git-Befehl wieder zurückdrehen kannst.
• Halte deine Erkenntnisse auf einer einzigen Notiz fest. Wer als Nächstes in dasselbe Repo einsteigt (auch dein zukünftiges Ich), muss dann nicht dieselbe Recherche wiederholen.

Warum in der ersten Stunde Unfälle passieren

Wer in einem neuen Repository stolpert, scheitert selten an der Schwierigkeit des Codes. Der Grund ist meistens: Man sieht die Form des Repositorys nicht.

Welcher Ordner ist das Frontend, wo liegt die Logik dahinter, welche Datei ist die Produktionskonfiguration? Wer das nicht weiß und trotzdem „mach es mal schön” sagt, bei dem schreibt Claude Code in bester Absicht einen breiten Bereich um. Eine KI behandelt eine Stelle als „darf angefasst werden”, solange niemand ausdrücklich sagt „Finger weg davon”.

Übernahmeprojekte sind besonders heikel. Die ungeschriebenen Regeln des Vorgängers, seine Namens-Eigenheiten, die seltsamen auskommentierten Reste. Dieser Kontext steht nirgends im Code. Selbst ein Mensch versteht am ersten Tag nicht alles. Genau deshalb ist das Erste nicht das Editieren, sondern das Kartenzeichnen.

Die Karte in vier Schritten

Die Reihenfolge ist entscheidend. Leseumfang festlegen, Schutzbereich festlegen, Prüfbefehl festlegen – und erst ganz zum Schluss genau eine kleine Sache reparieren. In dieser Reihenfolge geht es weiter.

Schritt 1: Schreibe das heutige Ziel in einem Satz

„Dieses Projekt verstehen” ist zu weit gefasst. Mit einem so breiten Ziel verlieren Claude Code und Mensch gleichermaßen die Stelle, an der man aufhören sollte.

Schreib es stattdessen so: „Ich ändere an genau einer Stelle den Text auf dem Login-Bildschirm und prüfe, dass der Build durchläuft.” Ein Ziel, das in einen Satz passt, lässt dich auf einen Blick erkennen, ob du fertig bist.

Schritt 2: Trenne Leseumfang und Tabuzone

Hier liegt das Herz der Karte. Bevor du Claude Code mit „du darfst alles lesen” loslässt, bringst du zuerst in Worte, was nicht angefasst werden darf.

Was ich jedes Mal in den Schutzbereich packe: Authentifizierung, Abrechnung, die Datei mit den Umgebungsvariablen (.env) und die Deployment-Skripte für die Produktion. Fehler hier richten großen Schaden an und sind obendrein schwer rückgängig zu machen. Deshalb sage ich am Anfang ausdrücklich: „Lesen ja, schreiben nein.”

Schritt 3: Lege zuerst den Prüfbefehl fest

Wenn es heißt „ist repariert” – woran genau erkennt man, dass es repariert ist? Das legst du vorab fest.

In vielen Projekten dient ein Build- oder Test-Befehl als Prüfung. npm run build läuft durch, npm test wird grün. Legst du diesen einen Befehl vor dem Fix fest, musst du Claude Codes „fertig” nicht blind glauben, sondern entscheidest nach dem maschinellen Bestanden/Durchgefallen.

Schritt 4: Genau ein rücksetzbarer Mini-Fix

Wenn die Karte steht, sei beim ersten Fix nicht gierig. Wähle genau eine Sache, die du mit einem einzigen git checkout zurückdrehen kannst: eine Textänderung, ein hinzugefügter Kommentar, ein offensichtlicher Tippfehler.

Widersteh dem „und das hier gleich mit”. Ein großes Diff kann niemand reviewen, und wenn etwas schiefgeht, wird das Zurücksetzen zur Qual.

Was Claude Code übernimmt und was der Mensch entscheidet

Was du beim Kartenzeichnen delegierst und was du selbst in der Hand behältst – wenn du das vermischst, passiert genau der Unfall vom Anfang.

Aufgabe	Zuständig	Grund
Dateiliste und Ordnerstruktur erfassen	Claude Code	Mechanisches Lesen ist schnell und genau
„Wo ist diese Funktion?” recherchieren	Claude Code	Suchen und Zusammenfassen ist seine Stärke
Was zum Schutzbereich wird	Mensch	Die Schadenshöhe hängt vom Kontext ab. Die KI kennt ihn nicht
Endgültige Wahl des Prüfbefehls	Mensch	Projektspezifische Umstände kennt nur der Mensch
Änderungen an Produktion, Abrechnung, Auth	Mensch	Schwer rücksetzbare Eingriffe genehmigt der Mensch

Das Prinzip ist einfach. Lesen und Auflisten delegierst du. Schwer rücksetzbare Entscheidungen behältst du in der Hand. Nur Operationen, deren Sicherheit du bestätigt hast, stufst du Claude Code später schrittweise hoch.

Den feineren Entwurf der Berechtigungen habe ich in einem eigenen Artikel zusammengefasst. Wenn du am Anfang unsicher bist, was du sperren sollst, wirf einen Blick in den Berechtigungs-Leitfaden.

Der Kartenzeichen-Prompt zum Kopieren

Das ist der Prompt, den ich in der ersten Stunde tatsächlich abschicke. Füge ihn direkt ein und ändere nur den Repository-Namen auf deinen eigenen.

Ich fasse dieses Repository zum ersten Mal an. Editiere noch nichts.
Untersuche der Reihe nach das Folgende und berichte das Ergebnis als Stichpunkte.

1. Die Ordnerstruktur auf oberster Ebene und die Rolle jedes Ordners
   (Vermutungen sind erlaubt, aber als Vermutung kennzeichnen)
2. Die Befehle für Build, Test und Start (aus package.json oder README)
3. Den Ort der Dateien rund um Authentifizierung, Abrechnung,
   Umgebungsvariablen und Produktions-Deployment
4. In welcher Datei der „Text des Login-Bildschirms" steht

Nach dem Bericht gilt: Die Dateien aus Punkt 3 sind diesmal
„nur lesen, Editieren verboten".
Editiert werden darf ausschließlich die eine Datei aus Punkt 4.

Der Knackpunkt: Schon in der ersten Zeile „editiere noch nichts” einnageln. Ohne das gibt es KIs, die bei der Recherche gleich anfangen zu reparieren.

Das Prüfskript zum direkt Ausführen

Wenn die Karte steht, beruhigt es ungemein, vor und nach dem Fix dieselbe Prüfung laufen lassen zu können. Das folgende Skript prüft, ob der Build vor und nach der Änderung durchläuft und ob das Diff nicht zu breit geworden ist. Es läuft mit Node.js.

// verify-edit.mjs
// Prüft, ob der Build vor/nach dem Fix durchläuft und das Diff nicht zu groß ist
import { execSync } from "node:child_process";

// Obergrenze der geänderten Dateien festlegen – noch mit einem Befehl rücksetzbar
const MAX_CHANGED_FILES = 3;

function run(cmd) {
  return execSync(cmd, { encoding: "utf8" }).trim();
}

try {
  // Anzahl der geänderten Dateien zählen
  const changed = run("git diff --name-only")
    .split("\n")
    .filter(Boolean);

  console.log(`Geänderte Dateien: ${changed.length}`);
  changed.forEach((f) => console.log(`  - ${f}`));

  if (changed.length > MAX_CHANGED_FILES) {
    console.error(
      `Das Diff ist zu breit (${changed.length} > ${MAX_CHANGED_FILES}).`,
    );
    console.error("Mit git checkout zurücksetzen und den Fix kleiner aufteilen.");
    process.exit(1);
  }

  // Prüfen, ob in den Schutzbereich eingegriffen wurde
  const protectedHits = changed.filter((f) =>
    /(^|\/)\.env|auth|billing|deploy/i.test(f),
  );
  if (protectedHits.length > 0) {
    console.error("Es wurde in den Schutzbereich geändert:");
    protectedHits.forEach((f) => console.error(`  - ${f}`));
    process.exit(1);
  }

  // Prüfen, ob der Build durchläuft (an dein Projekt anpassen)
  console.log("Build wird geprüft ...");
  run("npm run build");
  console.log("Build OK. Der Fix bleibt im sicheren Bereich.");
} catch (err) {
  console.error("Die Prüfung ist fehlgeschlagen:", err.message);
  process.exit(1);
}

Ausführen mit node verify-edit.mjs. Sind es zu viele geänderte Dateien oder wurde in den Schutzbereich eingegriffen, hält es sofort an. Der Unfall vom Anfang – „bis hin zur Auth-Datei aufgeräumt” – wäre durch dieses Skript im Voraus gestoppt worden.

Drei Situationen, in denen es greift

Konkret, in welchen Repositories das funktioniert – drei Muster, die ich selbst ausprobiert habe.

1. Ein übernommenes internes Tool Wenn du in eine Codebasis ohne Dokumentation einsteigst. Lass dir zuerst Ordnerstruktur und Start-Befehle auflisten und fixiere Auth- und Konfigurationsdateien als Schutzbereich. Der erste Fix sollte etwas Sichtbares sein, etwa eine Label-Änderung im Admin-Bereich, deren Ergebnis du mit den Augen erkennst.

2. Der erste Beitrag zu einem öffentlichen Repository Wenn du zum ersten Mal einen Pull Request für ein fremdes Open-Source-Projekt einreichst. Lass zuerst den Test-Befehl identifizieren und reiche genau einen kleinen Fix ein, während npm test grün bleibt. Ein rücksetzbarer Ein-Datei-Fix wird eher übernommen als ein breiter Verbesserungsvorschlag.

3. Der Neustart eines alten Projekts Wenn du Code wieder aufnimmst, der ein halbes Jahr brachlag. Lass Claude Code untersuchen, „wie weit es noch läuft”, und kartiere die kaputten Einstiegspunkte. Repariere zuerst die Stelle, die am leichtesten rücksetzbar ist.

Fallstricke und wie du sie behebst

Fallstrick 1: Alles auf einmal reparieren wollen Wenn aus „das Refactoring gleich mit” ein Diff über 50 Dateien wird, kann es niemand mehr reviewen. Die Lösung: Mit dem obigen Prüfskript eine Obergrenze für die Anzahl geänderter Dateien setzen. Wird sie überschritten, einmal zurücksetzen und aufteilen.

Fallstrick 2: Erfolgreichen Build mit „fertig” gleichsetzen Auch wenn der Build lokal durchläuft, sieht der Bildschirm noch lange nicht so aus wie gedacht. Bei einer Textänderung gehört es zum Set dazu, den betreffenden Bildschirm tatsächlich zu öffnen und den Text mit eigenen Augen zu prüfen.

Fallstrick 3: Den Schutzbereich nur mündlich mitteilen Auch wenn du im Prompt „fass die Auth nicht an” sagst, kann das mitten in einer langen Arbeit vergessen werden. Die Lösung: Mit dem Prüfskript Änderungen am Schutzbereich maschinell abweisen. Geschützt wird per Befehl, nicht per menschlichem Gedächtnis.

Fallstrick 4: Die erstellte Karte nicht festhalten Auch wenn du eine Stunde lang alles erfasst hast – ohne Notiz machst du beim nächsten Mal dieselbe Recherche. Schreibst du Ordnerstruktur, Prüfbefehl und Schutzbereich auf eine einzige Notiz, hilft das deinem zukünftigen Ich.

Diese Kartennotiz wirkt noch stärker, wenn du sie als Projektregel in eine CLAUDE.md schreibst. Wie das geht, habe ich in den CLAUDE.md-Best-Practices zusammengefasst.

Häufige Fragen

F. Muss ich in der ersten Stunde wirklich gar nichts reparieren? A. Reparieren ist erlaubt, aber nur „eine kleine, rücksetzbare Stelle”. Die übrige Zeit ins Kartenzeichnen zu stecken, senkt unterm Strich die Unfälle und ist am Ende schneller.

F. Ist es gefährlich, Claude Code mit „du darfst alles lesen” loszulassen? A. Nur Lesen ist nicht gefährlich. Gefährlich ist die Berechtigung zum „Schreiben”. Lesen breit, Schreiben eng – das ist die Grundaufteilung.

F. Was tue ich bei einem Projekt, dessen Prüfbefehl ich nicht kenne? A. Lass Claude Code zuerst aus package.json oder README Kandidaten nennen. Bleibt es trotzdem unklar, nimm vorerst als minimale Prüfung, dass git status kein Diff zeigt.

F. Geht das Gleiche auch mit PowerShell? A. Ja. Die Logik, das Ergebnis von git diff --name-only zu zählen und mit einer Obergrenze zu vergleichen, lässt sich auch in PowerShell genauso schreiben. Passe das Prüfskript an deine Umgebung an.

F. Können auch Anfänger diesen Ablauf durchziehen? A. Ja. Bei Anfängern wirkt er sogar besonders gut. Auch ohne den Code vollständig zu verstehen, lassen sich große Unfälle vermeiden, wenn du vorab die „Stellen, die du anfassen darfst” festlegst. Wer von Grund auf einsteigen will, liest am besten zuerst den Einsteiger-Leitfaden.

Was beim Ausprobieren herauskam

Diesen Ablauf habe ich mir nach dem Unfall vom Anfang für mich selbst gebaut. Am stärksten wirkte beim Ausprobieren, dass ich im Prüfskript die „Obergrenze der geänderten Dateien” und die „automatische Prüfung des Schutzbereichs” eingebaut habe.

Tatsächlich: Als ich es in dem übernommenen Repository etwa dreimal laufen ließ, stoppte es einmal, weil die Zahl der geänderten Dateien die Obergrenze überschritt. Beim Reinschauen hatte Claude Code bei der Textänderung gleich eine gemeinsame Komponente mit umgeschrieben – wäre das durchgegangen, hätte das ein Diff mit unkalkulierbarem Wirkungsbereich ergeben. Weil es angehalten hat, konnte ich den Fix in zwei Teile aufteilen und einreichen.

Nicht „der schlauen KI vertrauen, dann wird’s schon”, sondern „im rücksetzbaren Rahmen delegieren”. Allein dadurch, dass ich zuerst die Karte zeichne, fühlt sich die erste Stunde völlig anders an. Wer als Nicht-Entwickler diese Aufteilung im Team teilen möchte, dem hilft auch der Einstieg für Nicht-Entwickler.

Die offizielle Nutzung von Claude Code kannst du auch in der offiziellen Anthropic-Dokumentation nachlesen. Wer seine Betriebsregeln festzurren und im Team reproduzierbar machen will: In Schulung und Beratung kartieren wir gemeinsam ein konkretes Repository.