CLAUDE.md, Skills, AGENTS.md: Die Drei-Schichten-Architektur, die Tool-übergreifend skaliert

Schlüsselzahlen auf einen Blick

• 3 Schichten in der modernen Coding-Agent-Architektur 2026: CLAUDE.md (Projekt-Wahrheit), Skills (modulare Best Practices), Custom Commands (wiederholbare Workflows).
• AGENTS.md ist seit Dezember 2025 der offene Standard, gepflegt von der Linux-Foundation-Initiative Agentic AI Foundation, mit Beiträgen von Sourcegraph, OpenAI, Google, Cursor und Factory.
• 29 Prozent der Entwickler vertrauen laut Stack Overflow 2025 KI-Tools, minus 11 Prozentpunkte zum Vorjahr. Vertrauensfrage ist Architektur-Frage.
• 53 Prozent der KI-nutzenden DACH-Unternehmen scheitern laut Bitkom 2026 an fehlender Kompetenz im Team. Skills sind kodifizierte Kompetenz.
• 500 Zeilen ist die Best-Practice-Obergrenze für eine SKILL.md, darüber sinkt die Performance.
• 1 Tool mit nativem CLAUDE.md-Support 2026: Claude Code. Mit AGENTS.md-Support: Cursor, Copilot, Codex, Gemini CLI, Aider, Zed, Warp und weitere. Cross-Tool-Strategie ist 2026 die einzige zukunftssichere Option.

---

Wenn Sie als Engineering-Lead oder CTO 2026 Coding-Agenten produktiv im Team haben und der Output noch immer inkonsistent ist, dann liegt das nicht am Modell und nicht am Prompt. Die Modell-Qualität ist 2026 so gut, dass die Struktur um die Aufgabe herum mehr zählt als die Eleganz der Aufgabenformulierung. Genau das ist der Trend, den Stack Overflow 2025 mit dem 11-Prozentpunkte-Vertrauensverlust angezeigt hat: Teams kippen ihre Coding Standards in einen System-Prompt und wundern sich, dass es nicht skaliert.

Wir bei Sentient Dynamics haben in 2026 in vier DACH-Engagements eine Drei-Schichten-Architektur ausgerollt, die das Vertrauensproblem an der Wurzel anpackt. Die Schichten sind: CLAUDE.md als Projekt-Wahrheit, eigenständige Skills als modulare Best Practices, Custom Commands als wiederholbare Workflows. Ergänzt um den seit 2026 standardisierten AGENTS.md-Layer, der die ganze Architektur Tool-übergreifend macht. Dieser Post liefert die Architektur, das Migrationspfad-Modell und die fünf häufigsten Anti-Pattern, die wir im DACH-Mittelstand sehen.

Wer dieser Post ist und wer nicht

Dieser Post richtet sich an Engineering-Leads und CTOs im DACH-Mittelstand mit 50 bis 2.000 Entwicklern, die Coding-Agenten produktiv im Team haben (Cursor, Copilot, Claude Code, Codex oder Eigenentwicklung) und mit dem Output-Drift kämpfen: ein Senior bekommt sauberen Code, ein Junior bekommt halluzinierte Imports, niemand weiß warum.

Nicht passend ist der Post für Solo-Entwickler oder Greenfield-Teams ohne etablierten Tool-Stack. Für die ist eine schlanke CLAUDE.md ohne Skill-Architektur ausreichend, weil die Komplexität der Drei-Schichten-Lösung erst ab 5 plus Devs und 2 plus Produktionsrepos einen Mehrwert bringt.

Warum Context-Architektur 2026 wichtiger ist als Prompting

Das spannendste Phänomen im KI-Coding-Bereich 2026 ist die Verlagerung der Kompetenz-Achse: Prompting-Technik ist nach wie vor relevant, aber sie ist nicht mehr der entscheidende Faktor für konsistente Outputs. Was zählt, ist die Context-Architektur, also die Art, wie Sie dem Agenten Projekt-Wissen, Konventionen und Workflows strukturiert übergeben.

Drei Beobachtungen aus unseren Engagements 2026:

Single-Prompt-Skalierung scheitert ab 200 Zeilen. Teams, die ihre Coding Standards in einen System-Prompt packen, sehen ab etwa 200 Zeilen Prompt-Länge eine Performance-Erosion: der Agent ignoriert frühere Anweisungen, weil die Aufmerksamkeit auf den frischen Token liegt. Das ist konsistent mit Anthropics offizieller Best Practice für SKILL.md (Obergrenze 500 Zeilen) und der Empfehlung, CLAUDE.md schlank zu halten.

Hooks sind deterministisch, CLAUDE.md ist beratend. Wenn eine Aktion immer ohne Ausnahme passieren muss (z.B. Tests vor Commit), gehört sie in einen Hook, nicht in CLAUDE.md. CLAUDE.md ist Empfehlung, Hook ist Befehl. Teams, die diese Trennung verstehen, haben deutlich weniger Compliance-Drift in Code-Reviews.

Skills laden on-demand und entlasten Tokens. Domain-Wissen, das nur manchmal relevant ist (Migration-Patterns, Test-Generierungs-Templates, Bug-Reproduktions-Workflows), gehört in eigenständige Skills im .claude/skills/-Verzeichnis, nicht in CLAUDE.md. Der Agent lädt sie automatisch, wenn die Trigger-Beschreibung passt, oder explizit per /skill-name-Slash-Command.

Die drei Schichten im Detail

Schicht 1: CLAUDE.md als Projekt-Wahrheit. Die CLAUDE.md ist die immer-geladene Projekt-Konstante. Sie enthält drei Sachen: Stack-Überblick (welche Sprachen, Frameworks, Build-Tools), die zwei bis vier wichtigsten Konventionen (z.B. "alle DB-Calls über Repository-Layer", "kein direktes console.log"), und Verweise auf wichtige Skills oder Custom Commands. Best Practice: pro Zeile fragen "würde Claude Fehler machen, wenn ich das streiche?". Wenn nicht, raus damit.

Schicht 2: Skills als modulare Best Practices. Skills leben im .claude/skills/-Verzeichnis, jede mit einer SKILL.md, die unter 500 Zeilen bleibt. Beispiele aus unseren Engagements: ein Test-Generation-Skill, der Pytest-Patterns für eine bestimmte Domäne kodifiziert; ein Doc-Generation-Skill, der README-Stubs nach Team-Standard erzeugt; ein Bug-Reproduktion-Skill, der eine Issue-Beschreibung in einen reproducible test case übersetzt. Skills tragen eine klare Trigger-Beschreibung, sodass der Agent sie autonom lädt, oder werden per Slash-Command explizit gerufen.

Schicht 3: Custom Commands als wiederholbare Workflows. Custom Commands sind in .claude/commands/ definiert und kapseln einen mehrstufigen Workflow als Single-Slash-Befehl. Beispiel: /release-prep führt automatisch Tests aus, baut Changelog-Entries aus den letzten Commits, aktualisiert die Version-Datei, öffnet einen Release-PR. Custom Commands sind die operative Ausprägung der Skills: wo Skills das Wissen tragen, tragen Commands den Workflow.

Die drei Schichten arbeiten zusammen, ohne sich zu überlappen. CLAUDE.md liefert Kontext, Skills liefern Wissen, Commands liefern Aktion. Wenn eine der Schichten fehlt, kompensieren Teams typischerweise mit Bloat in den anderen Schichten. Häufiges Anti-Pattern: ein 800-Zeilen-CLAUDE.md, das eigentlich Skills sein sollte.

Der AGENTS.md-Standard und was er für DACH-Teams bedeutet

Im Dezember 2025 hat die Linux-Foundation-Initiative Agentic AI Foundation die Pflege des AGENTS.md-Standards übernommen (der schon im Laufe von 2025 aktiv von verschiedenen Vendoren genutzt wurde), mit Beiträgen von Sourcegraph, OpenAI, Google, Cursor und Factory. AGENTS.md ist tool-agnostisch und wird nativ unterstützt von Cursor, Copilot, Codex, Gemini CLI, Windsurf, Aider, Zed, Warp, RooCode und einer wachsenden Liste weiterer Agenten.

Stand April 2026 unterstützt Claude Code AGENTS.md noch nicht nativ. Der pragmatische Workaround, den wir in unseren Engagements einsetzen: AGENTS.md als Single-Source-of-Truth schreiben, dann symlinken nach CLAUDE.md (ln -s AGENTS.md CLAUDE.md). Damit funktioniert die Datei sowohl in Claude Code als auch in Cursor und Copilot, ohne Duplikation.

Was bedeutet das für DACH-Engineering-Teams strategisch? Drei Punkte:

Tool-Lock-in vermeiden. Wer 2026 ausschließlich auf CLAUDE.md setzt, baut sich in Claude Code fest. Wenn Anthropic später Pricing ändert, EU-Hosting verändert oder das Tool aus dem Markt nimmt, ist die Skill-Architektur nicht portabel. AGENTS.md macht den Tool-Wechsel zur Drei-Tage-Aufgabe statt zur Drei-Monats-Migration.

Multi-Tool-Engagements abdecken. In Engagements mit 100 plus Devs sehen wir 2026 routinemäßig Multi-Tool-Setups: Senior-Devs auf Claude Code, Mainstream-Engineers auf Copilot, Greenfield-Teams auf Cursor. Eine einheitliche AGENTS.md sorgt dafür, dass die Konventionen gleich sind, unabhängig vom Tool.

Vendor-Konsolidierung in der Pipeline berücksichtigen. Die KI-Coding-Agent-Landschaft konsolidiert sich gerade. AGENTS.md ist die Versicherung gegen die nächste Marktbereinigung, weil die Konvention an dem offenen Standard hängt, nicht am Vendor.

Welches Tool für welches Setup? Lesen Sie unseren Vergleich Cursor vs Copilot vs Claude Code →

Beispiel-Architektur aus einem Sentient-Engagement

Q1 2026 haben wir bei einem deutschen Maschinenbauer mit 80 Engineering-FTE die Drei-Schichten-Architektur ausgerollt. Vorher: ein 1.200-Zeilen-System-Prompt, der über Cursor-Rules und CLAUDE.md doppelt geführt wurde, mit 30 Prozent Drift zwischen den beiden Files. Nachher: eine AGENTS.md mit 280 Zeilen, sieben Skills im .claude/skills/-Verzeichnis, drei Custom Commands für Release, Bugfix und Refactoring.

Die Skill-Library im Detail:

1. test-generation-pytest: Pytest-Test-Cases nach internem Domänen-Standard, mit fixture-Patterns für die Hauptmodule.
2. doc-generation-readme: README-Stubs in Team-Standard, mit Sektionen für Setup, Usage, Architecture, Troubleshooting.
3. bug-repro-from-issue: Issue-Beschreibung in reproducible test case übersetzen, inkl. Mock-Daten-Template.
4. migration-postgres-version: PostgreSQL-Schema-Migrations-Patterns inkl. Backwards-Compatibility-Checks.
5. legacy-cobol-bridge: Wrapper-Patterns für eine COBOL-Mainframe-Integration im Brownfield-Setup.
6. compliance-audit-trail: Logging-Patterns für AI-Act-konforme Audit-Trails (siehe unseren Post zum AI Act).
7. frontend-component-test: Component-Test-Patterns mit Mock-Strategien für die React-Codebase.

Die drei Custom Commands:

• /release-prep: Tests, Changelog, Version-Bump, Release-PR.
• /bug-fix: Issue lesen, Bug-Repro-Skill ziehen, Fix-PR erstellen, Tests schreiben.
• /refactor-module: Modul-Refactoring nach Pattern-Library, mit Pre- und Post-Test-Verifikation.

Ergebnisse nach 90 Tagen Produktivbetrieb: 1,8x Cycle-Time-Beschleunigung in den Modulen, in denen die Skills griffen, gemessen über DORA-Lead-Time. Pull-Request-Compliance mit Team-Konventionen stieg von 62 Prozent (gemessen vor Rollout) auf 91 Prozent (gemessen 90 Tage nach Rollout). Senior-Dev-Skepsis, die anfangs hoch war, kippte nach Tag 14, als die ersten zwei Custom Commands das Refactoring-Backlog spürbar abgebaut haben.

Fünf häufige Anti-Pattern, die wir 2026 in DACH sehen

Anti-Pattern 1: Der 1.200-Zeilen-CLAUDE.md. Teams, die alle Konventionen, Standards und Prozesse in eine CLAUDE.md packen. Folge: Performance-Erosion, der Agent ignoriert ältere Anweisungen, der Output wird inkonsistent. Fix: alles, was nicht in jedem Projekt-Touch relevant ist, in Skills migrieren.

Anti-Pattern 2: Skills ohne Trigger-Beschreibung. Teams legen Skills im .claude/skills/-Verzeichnis ab, vergessen aber die descriptive Header, die der Agent zum auto-Loading braucht. Folge: Skills sind nur per Slash-Command nutzbar, der Wert entfaltet sich nicht. Fix: jede SKILL.md startet mit klarer "Wann benutzen"-Beschreibung im Frontmatter.

Anti-Pattern 3: Hooks vermisst. Teams behandeln deterministische Anforderungen (z.B. Tests vor Commit, Lint-Check vor Push) als CLAUDE.md-Empfehlung. Folge: Drift in den Pull Requests, Compliance-Berater im Q2-Audit findet die Lücke. Fix: alles, was zu 100 Prozent passieren muss, in Hooks ziehen.

Anti-Pattern 4: Tool-spezifischer Lock-in. Teams schreiben CLAUDE.md ohne AGENTS.md-Symlink, sind 2026 in Claude Code festgenagelt. Folge: Tool-Wechsel ist Drei-Monats-Migration. Fix: AGENTS.md als Single-Source-of-Truth, Symlink nach CLAUDE.md.

Anti-Pattern 5: Credentials in Skill-Files. API-Keys, Tokens, Secrets im SKILL.md-Body, mit dem Argument "der Agent muss es ja kennen". Folge: Credentials in Git-History, Compliance-Audit-Findings, Rotation-Aufwand sechsstellig. Fix: Credentials nur über Environment-Variablen oder Secret-Manager referenzieren.

Pre-Production-Checkliste

Bevor Sie eine Drei-Schichten-Architektur in den Produktivbetrieb übernehmen, sollten diese fünf Punkte schriftlich abgehakt sein:

1. CLAUDE.md / AGENTS.md unter 300 Zeilen, mit klarem Stack-Überblick, 2 bis 4 Top-Konventionen und Verweisen auf Skills.
2. Skills mit Trigger-Beschreibung im Frontmatter, jede unter 500 Zeilen, klare Verantwortungsgrenze.
3. Custom Commands mit Workflow-Doku, Erfolgs- und Fehlerfall benannt, Tests integriert.
4. Hooks für deterministische Anforderungen (Tests, Lint, Type-Check) konfiguriert und getestet.
5. Credentials-Isolation über Environment-Variablen oder Secret-Manager, kein einziges Secret im Skill-Body.

Wenn einer der fünf Punkte nicht abgehakt ist, geht die Architektur zurück in die Überarbeitung. Die Inkonsistenz, die danach kommt, kostet mehr als die zwei Tage zusätzlicher Polish.

CLAUDE.md-Template + 3 Beispiel-Skills gefällig? 30-Minuten-Discovery-Call buchen, wir zeigen das Kit live →

Häufige Fragen

Können wir AGENTS.md und CLAUDE.md parallel pflegen? Technisch ja, organisatorisch eine Drift-Falle. Wir empfehlen Single-Source-of-Truth in AGENTS.md, Symlink nach CLAUDE.md. Damit pflegt das Team eine Datei, beide Tools sehen die gleiche Konvention.

Wie lange dauert eine Skill-Library-Erst-Aufstellung für ein 50-FTE-Team? In unseren Engagements typisch zwei bis drei Wochen für die ersten fünf Skills, Custom Commands und Hooks. Skill-Library wächst danach iterativ pro Sprint, mit Refinement-Sessions alle 14 Tage.

Was ist mit Cursor-Rules, brauchen wir die noch zusätzlich? Stand April 2026: Cursor unterstützt AGENTS.md nativ, Cursor-Rules werden parallel als Tool-spezifische Erweiterung gepflegt. Wenn Sie nur Cursor einsetzen, reichen .cursorrules plus AGENTS.md. Wenn Sie Multi-Tool fahren, AGENTS.md plus Tool-spezifische Erweiterungen wo nötig.

Wie messen wir den Erfolg der Drei-Schichten-Architektur? Drei KPIs aus unserer Engagement-Praxis: DORA-Lead-Time pro Größeneinheit (siehe unseren Post zum KPI-Framework), Pull-Request-Compliance-Rate mit Team-Konventionen, und Time-to-Productive für neue Devs. Letztere fällt nach unserer Erfahrung um 30 bis 50 Prozent, wenn die Skill-Library steht.

Brauchen wir Subagenten zusätzlich zu Skills? Subagenten in .claude/agents/ sind ein Spezial-Pattern für isolierte Tasks, die viele Files lesen oder einen eigenen Kontext brauchen. Beispiel: ein "code-reviewer"-Subagent, der einen PR isoliert reviewed ohne den Hauptkontext zu fluten. Wir setzen Subagenten ab Team-Größe 100 plus Devs ein, drunter reichen Skills.

Wie passt das zur AI-Act-Compliance? Skills sind kodifizierte Engineering-Kompetenz, die im AI-Act-Audit nachweisbar dokumentiert ist. Compliance-Audit-Trails als Skill plus Audit-Logging-Hook ergeben einen sauberen, prüfbaren Stack. Details in unserem AI-Act-90-Tage-Plan.

Was bringt der Drei-Schichten-Stack einem 5-Dev-Team? Begrenzten Mehrwert. Bei 5 Devs reicht eine schlanke AGENTS.md mit zwei bis drei Skills. Die Komplexität der vollen Architektur lohnt sich ab 15 plus Devs, mehreren Repos oder Multi-Tool-Setup.

Quellen

• Claude Code Best Practices (Anthropic)
• Skill authoring best practices (Anthropic)
• Writing a good CLAUDE.md (HumanLayer)
• .cursorrules vs CLAUDE.md vs AGENTS.md 2026 (The Prompt Shelf)
• AGENTS.md vs CLAUDE.md Cross-Tool Standard (Hivetrail)
• Complete Guide CLAUDE.md AGENTS.md 2026 (Data Science Collective)
• Claude Code Skills vs Cursor Rules vs Codex Skills (Agensi)
• 12 Patterns Agentic Engineers Use (Level Up Coding)
• Stack Overflow Developer Survey 2025: KI-Vertrauen
• Bitkom KI-Studie 2026 (PDF)

---

Über den Autor

Sebastian Lang ist Co-Founder von Sentient Dynamics und leitet das Agentic-University-Programm. Vor Sentient war er bei SAP in der Strategy-Practice für KI-Workforce-Programme verantwortlich, mit 15 plus Jahren Engineering-Leadership-Erfahrung. Sentient Dynamics arbeitet mit erfolgsbasierter Vergütung und ist im SHD- sowie Bregal-Portfolio im Einsatz.

Newsletter abonnieren | Sebastian auf LinkedIn