Kanji
・Cloud Engineer / Freelance ・Geboren 1993 ・Aus Ehime / Wohnhaft in Shibuya, Tokio ・5 Jahre AWS-Erfahrung Profildetails
Inhaltsverzeichnis
In meinem täglichen Software-Engineering-Workflow orchestriere ich mehrere KI-Coding-Agenten parallel – darunter Google Antigravity, Anthropic Claude Code, Kiro und OpenAI Codex. Der mit Abstand frustrierendste Engpass, auf den ich dabei immer wieder gestoßen bin, war jedoch der „Zusammenbruch von Regeldefinitionen und Prompt-Drift zwischen verschiedenen Agenten-Umgebungen“ .
Anfangs ging ich davon aus, dass es ausreichen würde, umfassende Coding-Richtlinien und Sicherheitsvorgaben in eine einzige AGENTS.md oder CLAUDE.md zu schreiben, damit jedes Tool intelligent arbeitet. Als meine Projekte jedoch zu Enterprise-Multi-Repo-Architekturen heranwuchsen, wurde ich mit gravierenden operativen Fehlermodi konfrontiert:
AGENTS.md
CLAUDE.md
git push origin main
In diesem Deep Dive teile ich die praxiserprobten Architekturmuster, mit denen ich diese Probleme über alle vier großen KI-Agenten hinweg dauerhaft gelöst habe.
Wir ziehen eine klare Grenze zwischen dem universellen Fundament (offene Standards, die überall gelten) und den spezialisierten Superkräften (herstellerspezifische Erweiterungen) – und führen beides in einer produktionserprobten föderierten Regelarchitektur (Federated Rules Architecture) zusammen.
Beim Verfassen von Agenten-Anweisungen tappen Engineering-Teams fast zwangsläufig in drei klassische Fallen.
Der Versuch, Testkonventionen, Commit-Nachrichtenformate, veraltete Bibliotheksversionen und Cloud-IAM-Richtlinien in einer einzigen zentralen Regeldatei im Projektwurzelverzeichnis zu dokumentieren.
Da Agenten dieses gesamte Dokument bei jedem einzelnen Tool-Aufruf erneut in das Prompt-Fenster injizieren, verschlingt ein 1.000-Zeilen-Monolith Ihr Token-Budget und sättigt den Aufmerksamkeitsmechanismus des Modells. Die Wahrscheinlichkeit, dass wichtige Vorgaben ignoriert werden, steigt dadurch exponentiell.
Die getrennte Pflege von CLAUDE.md und AGENTS.md per Copy-and-Paste. Unweigerlich wird bei einer Regeländerung nur eine Datei aktualisiert, während die andere veraltet – was zu widersprüchlichen Anweisungen und destruktiven Code-Regressionen führt.
Sich ausschließlich auf beschreibende natürliche Sprache zu verlassen, um Hochrisiko-Operationen zu verhindern ( „Führe keine gefährlichen Befehle aus“ ). Da LLMs probabilistisch arbeiten, werden Textanweisungen bei komplexen mehrstufigen Schlussfolgerungen übersteuert. Kritische Sicherheitsgrenzen müssen mechanisch über Hooks, Berechtigungen oder Sandboxes erzwungen werden – niemals durch höfliche Prosa.
So verarbeiten und laden die vier führenden Coding-Agenten operative Regeln im Detail:
~/.gemini/config/rules/*.md
<repo>/AGENTS.md
~/.kiro/steering/*.md
.kiro/steering/*.md
~/.claude/rules/*.md
~/.codex/AGENTS.md
AGENTS.override.md
config.toml
glob
model_decision
manual
#[[file:...]]
@pfad/zur/datei
settings.json
Unabhängig davon, welches Tool ich einsetze, gelten drei architektonische Grundprinzipien universell:
Analog zu /etc/ → ~/.config/ → ./ unter UNIX müssen Agenten-Anweisungen von allgemein zu spezifisch kaskadieren, wobei lokale Workspace-Einstellungen globale Konfigurationen strikt überschreiben :
/etc/
~/.config/
./
~/.gemini/config/rules/
~/.claude/rules/
./AGENTS.md
./src/api/AGENTS.md
Halten Sie Ihre zentrale AGENTS.md im Wurzelverzeichnis konsequent unter 150 bis 200 Zeilen . Unterziehen Sie jeden einzelnen Satz diesem Lackmustest: > „Wenn ich diese Zeile streiche, begeht der Agent dann einen katastrophalen oder irreversiblen Fehler?“
Entfernen Sie alles, was Linter, Formatter oder Typechecker automatisch durchsetzen. Behalten Sie ausschließlich nicht-offensichtliche Projekteigenheiten und exakte Build-Befehle bei.
Betten Sie niemals seitenlange Deployment-Runbooks oder mehrstufige Migrationsskripte direkt in Regeldateien ein: - Regeln ( AGENTS.md ) : Unveränderliche Leitplanken, Grenzen und Bewertungskriterien. - Skills ( SKILL.md ) / Runbooks : Operative Schritt-für-Schritt-Prozeduren, die nur bei Bedarf (On-Demand) nachgeladen werden.
SKILL.md
Selbst wenn Teams die 3-stufige Kaskade verinnerlicht haben, scheitert die Praxis oft am Scoping-Grenzdesign : „Welche Anweisungen gehören konkret in die globale Benutzerkonfiguration und welche direkt ins Repository?“
Ich habe anfangs selbst den Fehler gemacht, aus Bequemlichkeit projektspezifische Einstellungen global abzulegen – was prompt zu Fehl-Deployments oder Berechtigungsfehlern in anderen Kunden-Repositories führte – oder lokale Mac-Pfade ins Repository zu committen und damit CI-Pipelines zu sprengen.
Hier ist die produktionserprobte Scoping-Matrix, die ich heute in allen meinen Agenten-Workflows strikt durchsetze:
~/.gemini/...
./.agents/...
features/
components/
/tmp
npm run build
pytest
npm run dev
tsc --noEmit
ruff check
SPONSORED
feat:
fix:
develop
main
Verschwimmen diese Grenzen, schleppen Agenten unweigerlich subtile Fehler und erhebliche Betriebsrisiken ein:
Projektspezifische Bezeichner – etwa AWS_PROFILE=client-prod oder absolute Pfade wie /Users/user01/workspace/client-a/... – werden fest in globale Regeldateien ( ~/.gemini/config/rules/ oder ~/.claude/rules/ ) eingetragen. Wechsle ich später in ein privates Repository oder die Codebasis eines anderen Kunden, versucht der Agent unbewusst, die Zugangsdaten von Kunde A zu nutzen – was zu Berechtigungsfehlern oder im schlimmsten Fall zu einem Fehl-Deployment in fremde Infrastruktur führt .
AWS_PROFILE=client-prod
/Users/user01/workspace/client-a/...
Lokale Maschinenpfade ( file:///Users/kanji/... ), private SSH-Aliase oder persönliche Zugangsdaten werden direkt in die AGENTS.md eines Repositories committet. Sobald CI/CD-Pipelines (GitHub Actions), Docker-Container oder Teammitglieder unter Windows das Repository pullen, brechen automatisierte Builds wegen fehlender Pfade sofort ab, während private Maschinenstrukturen dauerhaft in der Git-Historie landen .
file:///Users/kanji/...
Spezialisierte Best Practices für jede erdenkliche Technologie (Next.js, Python, Terraform, Docker, Go, Rust, Tailwind) werden in globale Regeln gestopft, weil sie „irgendwann nützlich sein könnten“. Dadurch lädt der Agent selbst für ein einzeiliges Shell-Skript direkt zum Sitzungsstart über 10.000 Token irrelevanter Regeln – das Aufmerksamkeitsfenster schnürt sich zu und die Halluzinationsrate steigt drastisch an .
Wann immer ich eine neue Regel formuliere, prüfe ich sie anhand dieser zwei schnellen Fragen:
Wenn eine Regel projektübergreifend gilt, aber nur bei bestimmten Aufgaben relevant ist (z. B. Terraform-Namenskonventionen), nutze ich in Antigravity trigger: glob: "**/*.tf" oder in Kiro Conditional Steering. So liegt die Regel sauber im globalen Bereich, wird aber nur dann in den Kontext geladen, wenn passende Dateien tatsächlich geöffnet sind .
trigger: glob: "**/*.tf"
Sobald das universelle Fundament steht, lassen sich herstellerspezifische Erweiterungen mit maximaler Hebelwirkung einsetzen.
Die herausragende Stärke von Antigravity ist die feingranulare Frontmatter-Steuerung in ~/.gemini/config/rules/*.md :
--- trigger: glob globs: "**/*.tf, **/*.tfvars, infra/**/*.yaml" description: Terraform naming conventions and provider requirements --- # Infrastructure Rules - Resource names must include environment prefixes (prd, stg, dev).
Dank glob und model_decision werden Frontend-Aufgaben niemals durch umfangreiche Infrastruktur- oder Migrationsregeln belastet.
Kiro erlaubt es, dynamische Dateiinhalte ohne Codeduplizierung direkt in Steering-Dokumente einzubetten:
# API Response Contract All error payloads must strictly comply with our central schema: #[[file:src/types/api_errors.ts]]
Sobald sich das zugrunde liegende Schema ändert, synchronisiert sich der Steering-Kontext des Agenten automatisch. Zudem ermöglicht /context show jederzeit eine Echtzeit-Inspektion des aktiven Kontexts.
/context show
Existiert im Repository-Root eine CLAUDE.md , priorisiert Claude Code diese gegenüber AGENTS.md . Während Entwickler unter macOS und Linux häufig zu einem schnellen lokalen Symlink ( CLAUDE.md -> AGENTS.md ) greifen, führt dies in plattformübergreifenden Enterprise-Teams zu einem katastrophalen, lautlosen Fehlermodus.
CLAUDE.md -> AGENTS.md
Unter Windows deaktiviert Git symbolische Links standardmäßig ( core.symlinks = false ). Klont ein Windows-Entwickler ein Repository mit einem solchen Symlink, wird CLAUDE.md nicht als gültige Verknüpfung angelegt, sondern als gewöhnliche 9-Byte-Textdatei mit der bloßen Zeichenkette "AGENTS.md" . Claude Code liest diesen 9-Byte-Stub stillschweigend als kompletten Befehlssatz ein, ohne eine Warnung auszugeben – wodurch sämtliche Sicherheitsregeln und Architekturleitlinien vollkommen unbemerkt ausgelöscht werden.
core.symlinks = false
"AGENTS.md"
Die native @AGENTS.md -Import-Syntax (Empfohlen) Committen Sie CLAUDE.md als schlanke Klartextdatei, die mit einer @ -Importdirektive beginnt:
@AGENTS.md
@
@AGENTS.md # Claude-Specific Directives - (Hier ausschließlich Claude-spezifische Verhaltensweisen oder Subagenten-Rollen ergänzen)
Da es sich um regulären Markdown-Text handelt, funktioniert dieser Ansatz deterministisch unter Windows, macOS, Linux sowie in containerisierten CI-Runnern.
Zero-Config-Fallback ( CLAUDE.md komplett weglassen) Claude Code greift nativ auf AGENTS.md zurück, sobald keine CLAUDE.md vorhanden ist. Benötigt Ihr Projekt keine Claude-exklusiven Prompts, ist eine einzelne AGENTS.md die sauberste, wartungsfreie Lösung.
Setzen Sie darüber hinaus unverhandelbare Sicherheitsgrenzen mechanisch über deterministische PreToolUse-Hooks in .claude/settings.json durch, statt auf höfliche Textbitten zu hoffen:
.claude/settings.json
{ "hooks": { "PreToolUse": [ { "matcher": ".*", "hooks": [ { "type": "command", "command": "python3 scripts/secret_guard.py" } ] } ] } }
Praxis-Stolperfalle 1: Vermeiden Sie die „Selbst-Aussperrungs-Falle“ bei PreToolUse-Hooks Wenn Sie in PreToolUse-Hooks nach Geheimnissen (z. B. OpenAI-/Anthropic-Schlüsseln) suchen, lösen naive Regex-Muster ohne Wortgrenzen (wie sk-[A-Za-z0-9_-]+ ) Fehlalarme bei harmlosem Kebab-Case-Text in Markdown aus (etwa risk-assessment-workflow... ). Beendet sich der Hook bei solchen Fehlalarmen mit Exit-Code 2, blockiert Claude Code alle nachfolgenden Tools – und sperrt den Agenten in einer Endlosschleife aus, in der er nicht einmal mehr Dateien lesen oder bearbeiten kann, um den Fehler zu beheben. Erzwingen Sie daher stets strikte Wortgrenzen ( \b ) und stellen Sie sicher, dass lokale .env -Entwicklungsdateien sowie Test-Mocks in einem Fail-Open-Design sicher ausgenommen werden.
sk-[A-Za-z0-9_-]+
risk-assessment-workflow...
\b
.env
Praxis-Stolperfalle 2: Schutz vor versehentlichem Überschreiben ( install.py ) Beim Ausrollen standardisierter Regelpakete in Engineering-Organisationen überschreiben manuelle cp -Befehle häufig bestehende AGENTS.md - oder CLAUDE.md -Dateien von Teammitgliedern ohne Vorwarnung. Ein automatisiertes Installationsskript ( install.py ), das vorhandene Regeln vor dem Schreiben als .bak sichert, gewährleistet eine reibungslose und konfliktfreie Einführung.
install.py
cp
.bak
In großen Monorepos ermöglicht Codex die gezielte Isolation einzelner Sub-Packages durch eine AGENTS.override.md . Diese Datei stoppt das Durchsuchen übergeordneter Verzeichnisse und verschafft dem Agenten einen schlanken, unbelasteten Kontext. Beachten Sie zudem das Standardlimit von 32 KiB in Codex ( project_doc_max_bytes in config.toml ), um stillschweigendes Abschneiden am Dateiende zu vermeiden.
project_doc_max_bytes
Mit dieser standardisierten Repository-Struktur orchestriere ich alle vier Agenten konfliktfrei im selben Projekt:
my-project/ ├── AGENTS.md # [SSOT] Universelle Kernregeln (< 200 Zeilen) ├── CLAUDE.md # Claude-spezifisch (@AGENTS.md-Import, 100 % Windows-sicher) ├── .kiro/ │ └── steering/ # Kiro-spezifische Dateimuster-Regeln & #[[file:...]] ├── .gemini/ (oder global) │ └── rules/ # Antigravity glob- & model_decision-Regeln ├── .codex/ │ └── config.toml # Codex Byte-Limits & Sandbox-Richtlinien └── .agents/ └── hooks.json # Deterministische PreToolUse- / PostToolUse-Guardrails
Das Management von Richtlinien für KI-Coding-Agenten ist längst über das beiläufige Hineinkopieren von Hinweisen in ein Prompt-Feld hinausgewachsen.
Wer seine Entwicklungsumgebung auf diesen fünf Säulen aufbaut, eliminiert Agenten-Regressionen sowie Prompt-Ermüdung – und erschließt einen verlässlichen, hochproduktiven Multi-Agenten-Workflow.
Umfassender Architekturleitfaden zum Langzeitgedächtnis von KI-Agenten (Gen 3): Wechsel von binären ... [Weiterlesen]
KI-Benchmark-Rangliste (Nov 2026): SWE-bench (86,8%), Terminal-Bench 4.0, ARC-AGI & $2/$10 API-Preis ... [Weiterlesen]
Wenn Sie KI-Assistenten wie Google Antigravity anpassen, können die Regeln und Fähigkeiten zu zahlre ... [Weiterlesen]
Trainieren Sie soziale Fähigkeiten mit realistischen KI-Testanrufen, 5-Achsen-Feedback, 16 interaktiven Lektionen und KI-Porträts.
Belege scannen und blitzschnell mit Gemini AI erfassen. Nahtlose Gruppenabrechnung für Freunde und Reisen.
KI-Persönlichkeiten leiten Spiele und Eisbrecher-Fragen in Echtzeit, um Treffen und Partys unvergesslich zu machen.
Erhalten Sie das vollständige Konfigurationspaket: universelle AGENTS.md, deterministische hooks.json und Git-Sicherheitsleitplanken für Antigravity, Kiro, Claude Code und Codex.