Claude Code Praxisanleitung: Sicher im Projekt arbeiten

Diese Claude Code Anleitung führt vom sicheren Start im Repository bis zu einem überprüften Patch. Das Ziel ist nicht, möglichst schnell „irgendetwas mit KI“ zu erzeugen. Du baust stattdessen einen Ablauf auf, in dem Claude Code den relevanten Code untersucht, Änderungen nachvollziehbar umsetzt, Tests ausführt und offenlegt, was nicht geprüft wurde.

Die Schritte eignen sich für Creator mit eigenen Websites oder Tools, Selbstständige, kleine Produktteams und technisch interessierte Einsteiger. Grundkenntnisse im Terminal helfen, sind aber weniger wichtig als ein sauberer Git-Workflow. Arbeite zum Einstieg nie direkt auf einem produktiven Server und beginne mit einer kleinen, reversiblen Aufgabe.

Claude Code vorbereiten: Repository, Git und Definition of Done

Claude Code arbeitet nicht in einem abstrakten Chatfenster, sondern kann Dateien lesen, bearbeiten und Befehle im Projekt ausführen. Anthropic beschreibt es als agentisches Coding-Werkzeug für Terminal, IDE, Desktop und Browser.^[1] Genau diese Handlungsfähigkeit ist der Nutzen – und das Risiko. Richte deshalb zuerst einen sicheren Arbeitsbereich ein.

1. Repository prüfen: Öffne den Projektordner und führe git status aus. Unklare lokale Änderungen solltest du sichern oder bewusst dokumentieren.
2. Branch anlegen: Erstelle für die Aufgabe einen eigenen Branch, zum Beispiel git switch -c fix/kontaktformular-validierung.
3. Tests kennen: Notiere die Befehle für Tests, Linter, Build und gegebenenfalls Typprüfung.
4. Grenzen definieren: Benenne Dateien oder Bereiche, die nicht verändert werden dürfen – etwa Deploy-Konfiguration, Migrationen oder Abrechnungslogik.
5. Erfolg messbar machen: Formuliere zwei bis fünf Akzeptanzkriterien. „Formular verbessern“ ist zu offen; „leere E-Mail blockieren, Fehlermeldung anzeigen und bestehenden Test ergänzen“ ist prüfbar.

Wenn das Projekt noch keine Tests besitzt, wähle als ersten Task keine tiefgreifende Umstrukturierung. Bitte Claude Code zunächst, den Ist-Zustand zu erklären, eine minimale Reproduktion zu erstellen oder einen kleinen Test für vorhandenes Verhalten vorzuschlagen. Ein Coding-Agent ist am zuverlässigsten, wenn er seine Änderung gegen ein beobachtbares Signal prüfen kann.

Claude Code installieren und im richtigen Ordner starten

Die offizielle Schnellstart-Dokumentation nennt für macOS, Linux und WSL einen nativen Installer. Da Installationswege und Voraussetzungen sich ändern können, kopiere den aktuellen Befehl direkt aus der Claude-Code-Schnellstartseite und prüfe anschließend die Installation mit claude --version.^[2] Für Windows stehen dort gesonderte Wege bereit.

Wechsle danach in das Repository und starte den Agenten:

cd /pfad/zu/deinem-projekt
claude

Beim ersten Start folgt die Anmeldung über eine aktuell unterstützte Methode. Abonnements, API-Nutzung, Limits und verfügbare Funktionen können sich ändern. Verlasse dich daher nicht auf ältere Screenshots oder Preisangaben aus Tutorials, sondern prüfe die aktuellen Informationen beim Anbieter.

Der erste sinnvolle Auftrag ist lesend:

Untersuche dieses Repository. Erkläre Architektur, Startbefehl, Tests und die fünf wichtigsten Risiken für Änderungen. Verändere noch keine Datei und führe keine Installation aus.

Vergleiche die Antwort mit README, Paketdateien und CI-Konfiguration. Korrigiere Missverständnisse sofort. Erst wenn das Projektbild stimmt, gibst du eine Schreibaufgabe frei. Dieser Schritt kostet wenige Minuten und verhindert, dass eine falsche Annahme durch viele Dateien getragen wird.

Mit CLAUDE.md dauerhaften Projektkontext schaffen

Jede Sitzung beginnt mit einem frischen Kontext. Anthropic dokumentiert CLAUDE.md als eine Möglichkeit, dauerhafte Projektanweisungen bereitzustellen; Claude Code liest solche Dateien zu Beginn einer Sitzung.^[3] Die Datei sollte das wiederholte Briefing verkürzen, nicht das gesamte Handbuch duplizieren.

Ein kompakter Ausgangspunkt kann so aussehen:

# Projektregeln

## Architektur
- Frontend liegt in src/frontend, API in src/api.
- Öffentliche Schnittstellen dürfen nicht ohne Freigabe geändert werden.

## Prüfbefehle
- Tests: npm test
- Lint: npm run lint
- Build: npm run build

## Arbeitsweise
- Erstelle vor Änderungen einen kurzen Plan.
- Ändere nur Dateien, die für den Task nötig sind.
- Keine neuen Produktionsabhängigkeiten ohne Freigabe.
- Berichte übersprungene oder fehlgeschlagene Prüfungen ausdrücklich.

Prüfe jede Zeile auf Wahrheit. Ein veralteter Testbefehl ist schlimmer als gar keiner, weil er falsche Sicherheit erzeugt. Gute Regeln sind konkret und überprüfbar. Schwache Regeln wie „Schreibe sauberen Code“ lassen zu viel Interpretationsspielraum. Besser: „Bestehende öffentliche Funktionssignaturen beibehalten“ oder „Für jeden behobenen Fehler einen Regressionstest ergänzen“.

Du kannst die Datei gemeinsam mit dem Team versionieren. Persönliche, maschinenspezifische oder sensible Angaben gehören nicht hinein. Für größere Projekte lassen sich Regeln nach Bereichen strukturieren; die offizielle Dokumentation erklärt die aktuell unterstützten Geltungsbereiche und zusätzliche Regeldateien.

Der Praxis-Workflow: verstehen, planen, ändern, testen, reviewen

Ein guter Prompt beschreibt Ergebnis und Grenzen, nicht jeden Tastendruck. Verwende für den ersten echten Task dieses Muster:

Fehler: Das Kontaktformular akzeptiert eine leere E-Mail-Adresse. Reproduziere das Verhalten zuerst. Erkläre dann kurz die Ursache und nenne die Dateien, die du ändern willst. Implementiere die kleinste passende Korrektur, ergänze einen Regressionstest und führe die relevanten Tests sowie den Linter aus. Ändere keine Abhängigkeiten und keine Deployment-Dateien. Zeige zum Schluss Diff-Zusammenfassung, Testausgabe und offene Risiken.

Der Ablauf sollte fünf erkennbare Phasen haben:

1. Verstehen: Claude Code sucht Einstiegspunkte, Tests und angrenzende Logik. Achte darauf, ob es Annahmen als Fakten ausgibt.
2. Planen: Bei mehr als einer kleinen Datei sollte ein kurzer Plan vor der Änderung stehen. Korrigiere den Scope, bevor Code entsteht.
3. Implementieren: Genehmige nur Befehle und Änderungen, die zum Plan passen. Eine unerwartete Paketinstallation ist ein Stoppsignal.
4. Verifizieren: Bestehe auf dem konkreten Testbefehl. „Sollte funktionieren“ ist kein Prüfergebnis.
5. Reviewen: Lies git diff selbst. Suche nach entferntem Verhalten, stillen API-Änderungen, unklaren Fehlermeldungen und unnötiger Komplexität.

Wenn ein Test fehlschlägt, soll der Agent nicht automatisch die Erwartung so lange anpassen, bis alles grün ist. Frage zuerst: Ist der neue Code falsch, ist der Test veraltet oder war die Anforderung missverständlich? Diese Trennung schützt vor „grünen“ Tests, die den eigentlichen Fehler nicht mehr prüfen.

Bei Frontend-Aufgaben reicht ein Unit-Test oft nicht. Ergänze – je nach Projekt – Build, Screenshot, Browserprüfung oder einen kleinen manuellen Testplan. Bei Datenbankänderungen brauchst du zusätzlich Rollback-Überlegungen. Bei Authentifizierung, Zahlungen und personenbezogenen Daten gehört eine menschliche Sicherheitsprüfung dazu.

Berechtigungen, Hooks und Automatisierung ohne Kontrollverlust

Im manuellen Modus beginnt Claude Code laut Sicherheitsdokumentation mit Lesezugriff und fragt vor Dateiänderungen oder verändernden Bash-Befehlen nach Zustimmung.^[4] Nutze diese Rückfragen als Review-Punkte. Dauerfreigaben sind nur für eng begrenzte, bekannte Befehle sinnvoll – zum Beispiel einen lokalen Test, nicht einen beliebigen Shell-Aufruf.

• Keine Zugangsdaten in Prompts oder CLAUDE.md schreiben.
• Netzwerkzugriff nicht pauschal freigeben.
• Installations- und Migrationsbefehle einzeln prüfen.
• Produktive Deployments aus dem Agenten-Task ausschließen.
• Vor breiten Refactorings einen Commit oder anderen Wiederherstellungspunkt setzen.

Für wiederkehrende Abläufe unterstützt Claude Code Hooks an Ereignissen seines Lebenszyklus.^[5] Damit lassen sich beispielsweise Formatierung oder Prüfungen nach einer Änderung anstoßen. Beginne aber nicht mit einem komplexen Hook-System. Stabilisiere zuerst den manuellen Ablauf, protokolliere Fehler sauber und automatisiere anschließend genau einen Schritt. Ein Hook, der automatisch Dateien verändert, kann einen Diff schwerer verständlich machen; ein nur prüfender Hook ist für den Einstieg meist leichter zu kontrollieren.

Für echte Hintergrundagenten auf eigener Infrastruktur gelten zusätzliche Regeln zu Isolation, Updates, Secrets und Monitoring. Dazu passt der Leitfaden OpenClaw auf dem VPS installieren. Wenn du statt Code eher Apps und Dienste visuell verbinden willst, lies den OttoKit-Schnellstart zu Workflow-Grundlagen.

Methodik, Grenzen und der sinnvolle nächste Schritt

Diese Praxisanleitung basiert auf der offiziellen Claude-Code-Dokumentation und auf etablierten, toolunabhängigen Praktiken wie Git-Branches, kleinen Diffs, Regressionstests und menschlichem Review. Sie gibt keine erfundene persönliche Projekterfahrung vor und verspricht keine Erfolgsquote. Die Beispielbefehle wurden aus der dokumentierten Bedienlogik abgeleitet; Installer, Oberflächen, Modelle, Limits und Preise können sich verändern. Prüfe aktuelle technische und kommerzielle Details immer direkt bei Anthropic.

Starte nicht mit einem kompletten Neubau. Wähle einen Fehler oder eine kleine Verbesserung, deren korrektes Verhalten du beschreiben kannst. Miss danach: Wie viele unnötige Dateien wurden geändert? Waren die Tests relevant? Wurden Unsicherheiten offengelegt? Konntest du den Diff verstehen? Diese Fragen zeigen, ob dein Workflow reif für größere Aufgaben ist.

Für die Werkzeugwahl hilft der Pillar-Artikel Claude Code vs. OpenAI Codex im Vergleich. Möchtest du denselben Prozess mit OpenAIs Werkzeug aufbauen, nutze die OpenAI Codex Praxisanleitung. So kannst du beide Ansätze mit identischen Akzeptanzkriterien im eigenen Repository vergleichen.

FAQ zur Claude Code Anleitung