Claude Code Existing-Codebase-Map: sicherer 45-Minuten-Workflow

Wenn du Claude Code in eine bestehende Codebasis bringst, sollte das erste Ergebnis kein Diff sein. Es sollte eine Karte sein. Eine Repo-Map zeigt, wo die Anwendung startet, welche Ordner wichtig sind, welche Bereiche heute tabu bleiben, wie ein Change geprüft wird und was die nächste Person wissen muss. Ohne diese Karte kann eine hilfreiche Session schnell in breite Aufräumarbeiten, Neben-Refactorings oder schwer reviewbare Änderungen abdriften.

Dieser Leitfaden zeigt einen einsteigerfreundlichen 45-Minuten-Workflow, um ein Repository vor dem Editieren zu kartieren. Die offizielle Claude Code overview erklärt, dass Claude Code Codebasen lesen, Dateien bearbeiten und Befehle ausführen kann. Genau deshalb müssen die Grenzen vorher klar sein.

Passende Vertiefungen sind die ersten Prompts für bestehende Codebases, der Claude Code Permission Guide und das CLAUDE.md Starter Template.

Die 45-Minuten-Repo-Map

Plane 25 Minuten für Read-only-Erkundung, 10 Minuten für die Karte, 5 Minuten für die erste sichere Aufgabe und 5 Minuten für Review. Ziel ist kein perfektes Architekturpapier, sondern eine Arbeitskarte für eine kleine, umkehrbare und prüfbare Änderung.

flowchart TD
  A["Read-only Inventar"] --> B["Einstiegspunkte finden"]
  B --> C["Sichere und riskante Bereiche trennen"]
  C --> D["Ersten Patch wählen"]
  D --> E["Prüfkommandos festlegen"]
  E --> F["repo-map.md schreiben"]

Ein Einstiegspunkt ist dort, wo die App beginnt: Route, API-Handler, Server-Bootstrap, CLI-Befehl, geplanter Job oder Content-Loader. Ein riskanter Bereich ist alles, wo ein kleiner Fehler Vertrauen oder Umsatz berührt: Authentifizierung, Billing, Löschung, Produktionskonfiguration, Secrets, Deploy-Skripte, Analytics und Ads.

Schritt 1: Read-only-Inventar

Starte mit Befehlen, die das Repo beschreiben, ohne es zu verändern. Unter Windows PowerShell reicht dieser Block für den ersten Überblick.

git status --short
Get-ChildItem -Force | Select-Object Name, Mode, Length
Get-ChildItem -Recurse -File -Include package.json,astro.config.*,next.config.*,vite.config.*,README*,CLAUDE.md,AGENTS.md | Select-Object -ExpandProperty FullName
rg --files | Select-Object -First 120

Suche nach Stack, Dokumentation, generierten Ordnern, Caches und uncommitted Changes. Wenn der Working Tree dirty ist, kläre zuerst, wem diese Änderungen gehören. So vermeidest du, dass Claude Code fremde Arbeit überschreibt.

Der erste Prompt sollte die Read-only-Grenze deutlich machen.

Read this repository as an existing codebase. Do not edit files yet.

Goal:
- Create a first repo map in 45 minutes
- Pick exactly one safe starter task
- Identify areas that should not be touched today

Return:
1. Up to 8 important directories
2. Up to 5 runtime or content entry points
3. Risky areas with reasons
4. Three safe starter task candidates
5. Candidate proof commands

If something is uncertain, write "unverified" instead of guessing.

Do not edit files yet hält die Session im Analysemodus, bis ein reviewbarer Plan existiert.

Schritt 2: repo-map.md schreiben

Lass die Erkenntnisse nicht nur im Chat stehen. Schreibe eine kurze repo-map.md, die die nächste Session wiederverwenden kann. Die offizielle Memory-Dokumentation zeigt, wie CLAUDE.md persistente Projektanweisungen hält. Die erste Erkundung bleibt aber meist besser getrennt; stabile Regeln wandern später nach CLAUDE.md.

# repo-map.md

## Purpose
- First working map for using Claude Code safely in this repository

## Entry points
| Type | File | Role | Proof |
| --- | --- | --- | --- |
| Web | site/src/pages/index.astro | Home page | npm run build |
| Content | site/src/content/blog | Article source | Open article URL |

## Safe candidates
- docs/
- site/src/content/blog/
- Small display copy

## Do not touch today
- .env and secrets
- Auth, billing, deletion flows
- Deploy scripts
- Generated dist and cache folders

## First safe task
- Improve one article CTA
- Change one file only
- Verify with build and preview

## Remaining risks
- Production data flow is unverified
- External service integrations need a separate pass

Das ist keine vollständige Architektur. Es ist ein Geländer für die erste nützliche Änderung.

Schritt 3: Grenzen mit Permissions absichern

Anweisungen helfen, sind aber keine Durchsetzung. Die Permissions-Dokumentation beschreibt allow, ask und deny. In der ersten Session eines bestehenden Repos solltest du Lesen und sichere Checks erlauben, bei Build oder Edit fragen lassen und Push, destruktive Befehle sowie Secrets blockieren.

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(rg *)",
      "Bash(npm run test *)",
      "Read"
    ],
    "ask": [
      "Bash(npm run build *)",
      "Edit(site/src/content/blog/**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)",
      "Edit(scripts/deploy*)"
    ]
  }
}

Dieses JSON ist ein Startpunkt. Dein Projekt hat vielleicht kein npm run test, oder ein anderer Edit-Pfad ist richtig. Wichtig ist, zuerst zu entscheiden, was verboten bleibt.

Schritt 4: Den ersten sicheren Patch wählen

Sobald die Karte steht, wähle eine Aufgabe, die klein, umkehrbar und leicht prüfbar ist. Drei Praxisfälle funktionieren besonders gut.

Erstens: Content-CTA verbessern. Ein beliebter Artikel sollte natürlich zu Produkten und Training führen. Meist ändert sich nur eine Content-Datei, geprüft mit Build und Preview.

Zweitens: Prüfkommandos in README oder CLAUDE.md dokumentieren. Build, Test, Lint und Preview kurz festzuhalten spart in künftigen Sessions Zeit, ohne App-Verhalten zu ändern.

Drittens: Text oder Datumsformat in einer einzelnen Ansicht korrigieren. Begrenze den Patch auf ein bis zwei Dateien und prüfe mit Test, Screenshot oder lokaler Preview. Auth, Billing, Permissions und Delete-Flows bleiben außen vor.

Using repo-map.md, implement only the first safe task.

Target:
- site/src/content/blog/example.mdx

Requirements:
- Make the final CTA more natural
- Keep internal links to /products/ and /training/
- Do not change pubDate, category, tags, author, or heroImage
- Change this one file only

After finishing, report:
1. Changed files
2. Why they changed
3. Proof commands run
4. Remaining risks

So wird aus einer breiten Bitte ein reviewbarer Patch.

Schritt 5: Die Karte prüfen

Eine Repo-Map ist Text, aber Mindestabschnitte lassen sich prüfen. Speichere dies als check-repo-map.js.

const fs = require("node:fs");

const file = process.argv[2] || "repo-map.md";
const text = fs.readFileSync(file, "utf8");
const required = ["Entry points", "Safe candidates", "Do not touch today", "First safe task", "Remaining risks"];
const missing = required.filter((heading) => !text.includes(heading));

if (missing.length > 0) {
  console.error(`Missing repo-map sections: ${missing.join(", ")}`);
  process.exit(1);
}

console.log(`OK: ${file} has the minimum repo-map sections.`);

node check-repo-map.js repo-map.md

Das Skript ist simpel, erzwingt aber einen konsistenten Handoff.

Häufige Fehler

Fehler eins ist eine zu breite Anfrage wie “refactor the app” oder “improve quality”. Besser: Read-only-Erkundung, maximale Dateianzahl, Tabu-Bereiche und Prüfkommandos vor jedem Edit festlegen.

Fehler zwei ist das Einbeziehen generierter Artefakte. dist, .astro, .next, coverage und node_modules machen das Repo groß, helfen aber selten beim ersten Verständnis. Schließe sie aus, außer sie sind tatsächlich das Deployment-Ziel.

Fehler drei ist, externe Services zu unterschätzen. E-Mail, Payment-Webhooks, Ads, Analytics und CRM können wenig Code, aber hohen Business-Impact haben. Erst lesen, später separat ändern.

Fehler vier ist, nach dem Build aufzuhören. Mobile Layouts, Codeblöcke, CTAs oder interne Links können trotz Build kaputt sein. Für Content-Seiten öffnest du die Preview und prüfst Body, Codeblöcke, /products/ und /training/.

Review-Checklist

Blickwinkel	Prüfen	Warnsignal
Diff	Nur angefragte Dateien geändert	Viel Nebenformatierung
Einstieg	Ladepfad verstanden	Geänderte Datei wird nie genutzt
Risiko	Auth, Billing, Delete, Prod unberührt	Secrets oder Deploy geändert
Beweis	Command oder manueller Check vorhanden	Nur “probably fine”
Funnel	CTA und Links passen	Produktlinks wirken angeklebt
Handoff	Restrisiken notiert	Nächste Session recherchiert erneut

Diese Checkliste misstraut Claude Code nicht. Sie macht die Arbeit wiederholbar.

Umsatzpfade mit kartieren

Bei einer Site wie ClaudeCodeLab gehört Monetarisierung in die Karte. Welche Artikel bringen Suchtraffic? Wo sieht der Leser Download, Produkt oder Beratung? Vorlagen findest du in der Produktbibliothek. Für Team-Rollout, Permissions und Content-Operations ist Claude Code Training sinnvoll.

Wenn Umsatzpfade in der Karte stehen, ist ein kleiner CTA-Patch mehr als Textarbeit. Du prüfst auch interne Links, Produktseiten, Formulare, Analytics und Anzeigen. Korrekter Code erzeugt keinen Umsatz, wenn der nächste Schritt für Leser unklar bleibt.

Zusammenfassung

Nutze die ersten 45 Minuten mit Claude Code zum Kartieren, nicht zum Umschreiben. Inventar aufnehmen, Einstiegspunkte finden, Risiken markieren, eine sichere Aufgabe wählen, Prüfkommandos festlegen und repo-map.md hinterlassen. Danach folgt ein kleiner Patch in ein oder zwei Dateien.