AI-Coding-Agenten konfigurieren: Das 4-Schichten-Modell für Claude Code und Codex

Heute gibt es dafür ein System. Damals, beim ersten CLAUDE.md, nicht – und das Ergebnis war vorhersehbar: zunächst übersichtlich, nach ein paar Wochen zwanzig Abschnitte: Astro-Architektur, Tailwind-Regeln, Testing-Standards, Commit-Konventionen, Accessibility-Checkliste, bevorzugter Paketmanager, Erklärungen für das Monorepo-Setup. Alles in einer Datei, die bei jedem Projekt vollständig mitgeladen wird – egal ob das Projekt Tailwind nutzt oder nicht.

Das Problem ist nicht das Tool – es ist die fehlende Schichtenstruktur. Die Qualität der Antworten sinkt, weil irrelevantes Wissen das relevante verdrängt. Wenn ein Projekt andere Regeln braucht, ist unklar, was jetzt gilt.

Es gibt einen besseren Weg.

Das 4-Schichten-Modell

Das Grundprinzip ist einfach – jede Schicht hat genau das, was auf sie gehört. Keine Schicht trägt Wissen der anderen.

Schicht 1: Was global reingehört

Die globale Konfiguration sollte kurz sein – nicht weil Kürze ein Selbstzweck ist, sondern weil alles, was hier steht, bei jedem Projekt mitgeladen wird. Das gilt unabhängig vom Tool:

Tool	Konfigurationsdatei	Quelle
Claude Code	~/.claude/CLAUDE.md	Symlink auf GLOBAL.md
Codex	~/.codex/AGENTS.md	Symlink auf GLOBAL.md

Der entscheidende Punkt im ai-agent-config-Repo: Es gibt keine separate claude/CLAUDE.md und codex/AGENTS.md. Stattdessen liegt eine einzige GLOBAL.md im Root, die per Symlink unter beiden Tool-Pfaden erreichbar ist. Einmal bearbeiten, beide Tools sehen es sofort.

Die Faustregel gilt für beide Tools: Wenn ein Satz in einem anderen Projekt wahrscheinlich anders wäre, gehört er nicht global.

Was fast immer global passt:

## Core principles
- Do exactly what is asked — no more, no less.
- Prefer modifying existing code over adding new files.
- Minimize surface area of changes.

## Working style
- Start non-trivial tasks with a brief plan before making changes.
- Break work into small, reviewable steps.
- State assumptions explicitly when requirements are unclear.

## Scope control
- Do not fix unrelated issues.
- Do not reformat unrelated code.
- Do not refactor outside the task scope.

## Validation
- Run targeted checks first: typecheck, lint, focused tests.
- Mention what was validated and what was not.

Etwa vierzig Zeilen – inklusive der neuen Sections „Core principles” und „Scope control”, die die häufigsten LLM-Fehler adressieren: ungebetene Refactorings, stille Umstrukturierungen, überschießende Fixes.

Was nicht global gehört: „Nutze Astro mit Tailwind und shadcn/ui.” Das ist Stack-Wissen, kein Arbeitsstil.

Schicht 2: Skills statt Riesendatei

Skills sind Markdown-Dateien mit YAML-Header, die bei Bedarf geladen werden. Claude Code und Codex unterstützen dieses Prinzip direkt: Stack-Wissen aktiviert sich selektiv, nicht dauerhaft.

~/.claude/skills/
├─ astro-architecture/
│  └─ SKILL.md
├─ tailwind-ui/
│  └─ SKILL.md
└─ accessibility-audit/
   └─ SKILL.md

Ein Skill für Astro-Architektur enthält Regeln wie: src/pages für Routen, Islands sparsam einsetzen, Hydration vermeiden wo möglich, SEO-Metadaten bei jeder Seite prüfen. Alles, was spezifisch für Astro ist – und nichts darüber hinaus.

---
name: astro-architecture
description: Guidance for Astro projects — rendering strategy, route structure,
  content modeling, and component boundaries.
---

## Goals
- Keep projects server-first and static-friendly where possible.
- Minimize shipped client-side JavaScript.
- Use islands intentionally, not by default.

## Structure
- src/pages for route entry points
- src/layouts for page shells
- src/components for reusable UI
- src/content for structured editorial content

Das wird nur geladen, wenn du an einem Astro-Projekt arbeitest – oder wenn du den Skill explizit aufrufst. Es bläht nicht den Kontext von Node-Projekten oder Rust-Bibliotheken auf.

Das öffentliche Template enthält bereits 18 kurierte Skills: Astro, Tailwind, Biome, SEO, Accessibility, Playwright, Dark Mode, Svelte 5, Web Performance, i18n und mehr. Ich nutze davon im Schnitt zwanzig aktiv – kurz nachdem Claude Code Skills einführte war das die erste Struktur, die sich über mehrere Projekte hinweg als stabil erwiesen hat. Jeder Skill ist eine eigenständige Datei, die nur dann in den Kontext geladen wird, wenn sie relevant ist.

Schicht 3: Was ins Repo gehört

Projektbezogene Regeln gehören in CLAUDE.md im jeweiligen Repo – nicht global. Der Unterschied ist entscheidend: Globales gilt immer, Repo-spezifisches gilt hier.

# Project rules

## Stack
- Astro, Tailwind CSS, TypeScript

## Commands
- pnpm dev / pnpm lint / pnpm check / pnpm build

## Architecture
- Keep route files slim
- No direct cross-imports between page files
- Preserve canonical URLs – no URL structure changes without discussion

## Constraints
- No new runtime dependencies without explicit reason
- Avoid client-side hydration where server rendering works

Das ist alles, was dieses Projekt besonders macht. Die Skills und die globale Basis kommen aus der zentralen Konfiguration.

Für private Abweichungen, die nicht ins Team-Repo sollen, gibt es CLAUDE.local.md – von Claude Code separat geladen, nicht eingecheckt.

Schicht 4: Agents als Rollen

Agents sind keine Wissensbehälter. Die häufigste Falle: einen Agent definieren, der Astro kennt und Tailwind kann und Accessibility prüft und Reviews macht. Das ist ein Wissenssilobau, kein Rollenmodell.

Agents sind Rollen. Das Wissen steckt in Skills.

Das Template enthält fünf spezialisierte Rollen:

planner – analysiert, zerlegt, benennt Risiken. Definiert Trigger-Regeln, erwartete Inputs und ein strukturiertes Output-Format.

implementer – setzt gezielt um. Kleiner Diff, bestehende Architektur erhalten, keine stillen Refactorings.

reviewer – prüft Korrektheit, Regressionen, Wartbarkeit. Ergebnis nach Severity gruppiert (Critical / Warning / Suggestion).

explorer – durchsucht den Codebase kontextisoliert. Gibt eine direkte Antwort mit file:line-Referenzen zurück, ohne rohen Dateiinhalt in den Hauptagenten-Kontext zu laden.

security-auditor – prüft defensiv auf Injection, Authn/Authz, Secret-Handling, Input-Validierung. Schreibt keine Exploits, unterscheidet Critical / Warning / Hardening.

Wo Agents abgelegt werden, hängt vom Tool ab – das Format aber nicht:

Tool	Agents-Pfad	Format
Claude Code	~/.claude/agents/	Markdown (Quelldateien in agents/)
Codex	~/.codex/agents/	TOML – automatisch generiert aus den Markdown-Quelldateien

Das ist ein weiteres Kernprinzip des Repos: agents/*.md ist die einzige Quelle. Ein Python-Script (scripts/render-codex-agents.py) konvertiert sie automatisch in TOML für Codex – ausgelöst durch einen Pre-commit-Hook. Wer einen Agent bearbeitet, muss nicht daran denken, das TOML manuell zu synchronisieren.

Derselbe Hook läuft außerdem nosecrets gegen alle gestagten Dateien. Wenn Secrets im Commit wären, bricht der Hook ab – bevor etwas in die Versionsgeschichte gelangt.

Das zentrale Config-Repo

Wenn dieselbe Konfiguration auf mehreren Rechnern laufen soll, ist ein privates GitHub-Repo die sauberste Lösung. Kein Kopieren, kein Vergessen, kein Abgleichen.

ai-agent-config/
├─ GLOBAL.md               ← Eine Datei für Claude Code & Codex
├─ agents/                 ← Quelldateien (Markdown + YAML-Frontmatter)
│  ├─ planner.md
│  ├─ implementer.md
│  ├─ reviewer.md
│  ├─ explorer.md
│  └─ security-auditor.md
├─ codex-agents/           ← Generiert aus agents/ – nicht manuell bearbeiten
│  ├─ planner.toml
│  ├─ implementer.toml
│  └─ reviewer.toml
├─ codex-config.toml       ← Codex-Profile: default / deep / fast
├─ skills/                 ← 18 kurierte Domain-Skills
│  ├─ astro-architecture/SKILL.md
│  ├─ tailwind-ui/SKILL.md
│  └─ ...
├─ scripts/
│  └─ render-codex-agents.py
└─ install/
   ├─ link-claude.sh
   ├─ link-codex.sh
   └─ link-all.sh

Die Symlinks verbinden das Repo mit den Tool-Konfigurationspfaden:

# Claude Code
ln -sfn ~/ai-agent-config/GLOBAL.md        ~/.claude/CLAUDE.md
ln -sfn ~/ai-agent-config/agents           ~/.claude/agents
ln -sfn ~/ai-agent-config/skills           ~/.claude/skills

# Codex
ln -sfn ~/ai-agent-config/GLOBAL.md        ~/.codex/AGENTS.md
ln -sfn ~/ai-agent-config/codex-agents     ~/.codex/agents
ln -sfn ~/ai-agent-config/codex-config.toml ~/.codex/config.toml
ln -sfn ~/ai-agent-config/skills           ~/.codex/skills

Update auf einem neuen Rechner: git clone + Symlink-Skript ausführen. Änderungen am Config-Repo: git pull, direkt wirksam.

Das Repo hat zwei Varianten: ein öffentliches Template als Ausgangspunkt, ein privates Fork mit den eigenen Spezifika. Das öffentliche Template ist auf GitHub verfügbar und unter ai-agent-config.casoon.dev dokumentiert.

Was beim Start zählt

Nicht alles auf einmal einrichten. Wer mit einer kleinen, funktionierenden Basis startet, hat mehr als jemand, der ein aufwändiges System baut und dann kaum pflegt.

Minimaler Start:

• 1 globale Konfigurationsdatei (CLAUDE.md / AGENTS.md) – zwanzig bis vierzig Zeilen
• 2-3 Skills: ein Stack, den du täglich nutzt
• 2 Agents: planner und reviewer

Das reicht, um projektübergreifend sauber zu arbeiten. Skills und Agents können bei Bedarf ergänzt werden. Das System skaliert – aber es muss nicht von Anfang an vollständig sein.

Am stärksten zahlt sich die Struktur bei drei Dingen aus: bei Deployment-Prozessen, wo der reviewer-Agent Änderungen bewertet, bevor etwas live geht. Bei Debugging, wo explorer isoliert nach Ursachen sucht, ohne den Hauptkontext zu belasten. Und bei Entscheidungen zum Code-Design – wo ein Planner-Agent erst Risiken benennt, bevor implementiert wird. Für Webprojekte kommt noch hinzu, dass jede Site ihre eigenen Constraints hat; die Trennung zwischen globalem Verhalten und projekt-spezifischen Regeln verhindert, dass diese Constraints sich gegenseitig überschreiben.

Die eine Faustregel für alle Entscheidungen:

Wenn dieser Satz in einem anderen Projekt wahrscheinlich anders wäre, gehört er nicht global.