Wie wir Claude Code in unseren Engineering-Workflow integriert haben

Seit Januar nutzt unsere Engineering-Crew Claude Code in der täglichen Arbeit. Dieser Beitrag dokumentiert, wie das Setup bei uns aussieht — keine Marketing-Geschichte, sondern die konkreten Configs und Erkenntnisse aus drei Monaten Produktiveinsatz.

Setup pro Projekt

Wir committen für jedes Projekt eine .claude/-Struktur mit:

.claude/
├── settings.json          # Tool-Permissions, Hooks
├── skills/
│   ├── deploy.md          # Custom Skill für Deployments
│   ├── add-migration.md   # DB-Migration mit Audit-Trail
│   └── review-pr.md       # Code-Review-Checkliste
└── memory/                # Projekt-spezifisches Wissen
    └── CLAUDE.md

Die settings.json ist der Hebel, an dem die meisten Teams zu lange warten:

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Edit(src/**/*.ts)",
      "Read(**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push:*)",
      "Bash(npm publish:*)",
      "Edit(.env*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash(git commit:*)", "command": "./bin/check-secrets.sh" }
    ],
    "Stop": [
      { "command": "./bin/notify-slack.sh" }
    ]
  }
}

Die Permissions-Trennung ist kein bürokratischer Overhead. Sie ist das, was den Unterschied macht zwischen “Agent läuft autonom, ich trinke Kaffee” und “Agent fragt bei jedem Schritt nach”. Wer eine sinnvolle Allowlist pflegt, dem fällt der Übergang in produktive Arbeit deutlich leichter.

Skills statt Prompts

Vor sechs Monaten hatten wir noch lange Prompt-Bausteine in einer Notion-Seite. Heute liegen sie als Skills im Projekt:

---
name: add-migration
description: Erzeugt eine neue Datenbank-Migration mit Audit-Trail
when_to_use: |
  Bei Schema-Änderungen, die in den Migrations-Ordner gehören.
  Niemals für reine Daten-Updates.
---

## Schritte

1. Prüfe `migrations/` auf höchste Versionsnummer
2. Erstelle neue Datei mit `YYYYMMDDHHMMSS_kurzname.sql`
3. Füge UP- und DOWN-Block ein
4. Hänge Eintrag in `audit/SCHEMA_CHANGES.md` an
5. Lass den Linter laufen (`./bin/lint-migrations`)

## Beispiel

[...konkretes Beispiel hier...]

Vorteil: Die Skills werden vom Agenten bei Bedarf geladen, nicht jedes Mal vorab. Das spart Token-Kontext und macht die Skills versionierbar — eine Migration-Skill von Anfang Q1 kann sich von der Q2-Version unterscheiden, weil zwischendurch das Schema-Tooling gewechselt hat.

Hooks für die unangenehmen Wahrheiten

Hooks haben uns drei Klassen von Problemen gelöst:

• Secret-Detection: Vor jedem git commit läuft ein Hook, der nach API-Keys, AWS-Credentials und privaten SSH-Keys scannt. Hat in den ersten 6 Wochen drei Versehen abgefangen.
• Test-Gate: Stop-Hook ruft npm test auf. Wenn rot, bekommt der Agent das Resultat zurück und macht weiter, bis grün.
• Slack-Audit: Jeder abgeschlossene Agenten-Task landet als Nachricht im #engineering-bot-Channel. Schafft Transparenz im Team und macht später Forensik leicht.

“Die spannendste Erkenntnis war nicht, dass Hooks Bugs fangen — sondern dass sie die psychologische Hürde abbauen, einen Agenten autonom laufen zu lassen.”

Was nicht funktioniert hat

Drei Sackgassen, in die wir gelaufen sind:

1. Generische Skills

Wir haben anfangs versucht, projektübergreifende Skills zu schreiben (general-code-review.md). Das Resultat: zu vage Anweisungen, zu wenig konkret. Heute schreiben wir projektspezifische Skills. Das wirkt redundant, ist aber in der Praxis schneller und liefert besseren Output.

2. Zu viele Tools

Wir hatten anfangs 23 erlaubte Bash-Kommandos. Der Agent verlor sich. Wir haben runter-iteriert auf 8. Output-Qualität gestiegen, Token-Verbrauch gesunken.

3. Memory ohne Pflege

Wir haben in .claude/memory/ Informationen abgelegt und vergessen, sie zu aktualisieren. Nach 4 Wochen war die Hälfte veraltet. Inzwischen läuft ein wöchentlicher Skill cleanup-memory, der zusammen mit dem Engineering-Lead die Memory-Einträge auditiert.

Empfehlungen für den Einstieg

Für Teams, die nächste Woche starten:

1. Klein anfangen: Ein Projekt, eine Person, zwei Wochen. Erst dann ausrollen.
2. Permissions früh definieren: Eine settings.json mit minimaler allow-Liste, alles andere fragt nach. Sicher und gleichzeitig informativ — man sieht, wonach der Agent fragt.
3. Skills aus echten Tasks ableiten: Nicht ausdenken — den Agenten dreimal eine Sache machen lassen, dann den gemeinsamen Pfad als Skill festhalten.
4. Hooks setzen, bevor man autonomer wird: Test-Gate und Secret-Detection als erstes. Den Rest später.
5. Wöchentliches Retro: 30 Minuten, was hat funktioniert, was nicht. Das Setup verändert sich in den ersten 6 Wochen stark.

Fazit

Claude Code ist kein “Werkzeug, das man installiert”. Es ist eine kleine Plattform, an die sich der Engineering-Prozess anpasst. Wer mit derselben Mentalität rangeht wie an CI/CD vor 10 Jahren — schrittweises Investment, Hooks, Conventions, Disziplin — bekommt eine spürbar bessere Engineering-Geschwindigkeit ohne Qualitätsverlust.

Wer es als magische Black-Box behandelt, bekommt frustrierte Engineers und merkwürdig formatierten Code.