KI-Agenten-Optimierung: Audit des V2-Systems (2026-07)¶

Stand: Runde 1 (PR #2799, gemerged) setzte die risikoarmen Quick Wins um. Runde 2 ergänzt Production-Guards, den automatisierten V1-Schema-Guardrail und den Fix des Format-Hooks — siehe Abschnitt A.2.

Ergebnis eines systematischen Multi-Agent-Audits des V2-Systems (laravel/, frontend-v2/, Tooling, CI, Agent-Dokumentation) mit dem Ziel, KI-gestützte, agentische Code-Assistenten schneller, sicherer und zuverlässiger arbeiten zu lassen — nachhaltig und mit minimaler Störung der laufenden Entwicklung.

8 Audit-Dimensionen, 63 Rohbefunde, davon 19 adversarial verifiziert bestätigt. Dieses Dokument listet (A) die bereits umgesetzten Maßnahmen und (B) die priorisierten offenen Empfehlungen.

A. Umgesetzt (dieser PR)¶

Feedback-Loop-Geschwindigkeit¶

Maßnahme	Effekt
Paratest installiert, `composer test`/`test:unit`/`test:feature` laufen parallel (`test:sequential` als Fallback)	Volle Suite ~90s → ~20s
`ReportCertificateServiceTest` nutzt isolierten Storage-Pfad	Beseitigt Parallel-Race auf `storage/app/certificates`
49 stale `markTestSkipped('route not yet registered')` entfernt (Auth-Funktionstests, Repair, Result, Standard, TestStep, Inventory) — alle Routen existieren, alle 93 Tests bestehen	Verdeckte API-Coverage reaktiviert
Schnelle Einzeltest-Iteration in `laravel/CLAUDE.md` dokumentiert (`php artisan test <datei>` ~3s, `--filter` ~1s)	Agenten iterieren nicht mehr mit der vollen Suite
`postinstall: nuxt prepare` in `frontend-v2/package.json`	`typecheck` funktioniert direkt nach `npm install`

Falsche Signale beseitigt¶

Maßnahme	Effekt
Erste Vitest-Unit-Tests geseedet (`utils/tm-tree.test.ts` als kopierbare Vorlage), `passWithNoTests: false`	`npm run test`, CI-Gate und Pre-Push waren zuvor grüne No-Ops ohne einen einzigen Test
`laravel/CLAUDE.md`: falsche Behauptungen korrigiert („parallel" war nicht installiert, Timings, `composer fresh` ist docker-only)	Agenten handeln nicht mehr auf Basis falscher Doku

Doku-Drift korrigiert (CLAUDE.md-Hierarchie)¶

Field-Mapping: HasDynamicFields + FieldDefinitionService als aktueller Mechanismus dokumentiert; HasFieldMapping explizit als Legacy markiert (nur noch FieldConfiguration). Vorher zeigte die Doku Agenten auf das Legacy-System.
FormRequest/Resource-Regel an die tatsächliche Konvention angepasst (Pflicht für Haupt-Ressourcen, inline validate() für kleine Admin-Endpoints).
thermo_-Widerspruch zwischen Root- und laravel-CLAUDE.md aufgelöst (kein Präfix; DB_PREFIX nur für Legacy-Installationen).
Versionsangaben korrigiert (Laravel 13, Yii 1.1.32).
Pre-Commit-/Pre-Push-Gates vollständig dokumentiert (Prettier, Build, composer audit), inkl. Verbot von git commit --no-verify.
Extract-on-touch-Regel (>500-Zeilen-Dateien) und Verbot unbedingter markTestSkipped-Aufrufe ergänzt.
Verzeichnis-Landkarte im Root-CLAUDE.md (Zweck von yii/, doc/, docs-v2/, calserver-sync/, report-runner/ …) und Hinweis auf historische Root-Analyse-Dokumente.
frontend-v2/CLAUDE.md: bisher nur PrimeVue-Regeln — jetzt mit Projekt-Architektur, kanonischem Grid-Muster (TableMaster + useDataTable), Typing-Konventionen, Test-Anleitung und Kommando-Referenz.
.claude_code_rules als Legacy-V1-Dokument gebannert (CLAUDE.md ist maßgeblich).

Kontext-Ökonomie & Hygiene¶

Root-.ignore (ripgrep & Co.): blendet committete Third-Party-Masse aus — httpdocs/protected/vendor|vendors|extensions, yii/, docs/calServer_manual/ (~425 MB, ~78 % der durchsuchbaren Dateien). Suchtreffer zeigen jetzt V2-/V1-Anwendungscode statt Vendor-Rauschen.
frontend-v2/.gitignore: test-results/, playwright-report/, coverage/.

A.2 Umgesetzt (Runde 2)¶

Maßnahme	Effekt
Production-Guards für `db:clear`, `db:install --clean`, `demo:data seed/remove`, `v1:sync --fresh` (`GuardsProductionDatabase`-Trait): in Produktion Verweigerung auch mit `--force`; nur das explizite `--allow-production` schaltet frei. Mit Feature- und Unit-Tests.	Ein Agent (oder Skript) kann eine Produktions-DB nicht mehr per Routine-`--force` wipen
V1-Schema-Guardrail (`scripts/check-v1-migration-pairing.sh` + Pre-Commit + CI-Workflow `v1-schema-guardrail.yml`): Neue Laravel-Migration, die eine V1-Tabelle ALTERt, erfordert im selben Changeset eine Yii-Migration — oder den bewussten Marker `// @v2-only-schema-change: <Begründung>`. V1-Tabellenliste wird live aus `httpdocs/protected/migrations/` extrahiert (kann nicht veralten).	Die wichtigste Prosa-Regel des Repos ist jetzt maschinell durchgesetzt
PreToolUse-Format-Hook gefixt: formatiert und re-staged nur noch die tatsächlich gestagten Dateien statt repo-weit + `git add -u`.	Keine still ausgeweiteten Commits mehr

A.3 Umgesetzt (Runde 3)¶

Maßnahme Effekt

.claude/settings.json um Permissions erweitert (auf ausdrückliche Freigabe): allow für read-only/geprüfte Kommandos (composer check/test/analyse/format/audit/fix, php artisan test/route:list, npm run lint/typecheck/test/format); deny für destruktive/gefährliche (git commit --no-verify, git push --force[-with-lease], php artisan db:clear/db:wipe/migrate:fresh, demo:data remove). Zusätzlich "env": {"COMPOSER_ALLOW_SUPERUSER": "1"}. Agenten prompten nicht mehr bei sicheren Standard-Checks; destruktive Befehle sind hart blockiert (zweite Schicht neben den Production-Guards)

B. Offene Empfehlungen (priorisiert)¶

Hoch (geringes Risiko, hoher Nutzen)¶

PHPStan-Blanket-Ignore entfernen: argument.type-Ignore über alle V2-Controller durch Builder<TModel>-Generics in FilterService, FormulaService, ExportService, AggregationService ersetzen.

Mittel¶

Pre-Commit-Hook verschlanken: Voller nuxt build (~45s) und volle Laravel-Testsuite laufen vor Merge bis zu 4× (Pre-Commit, Pre-Push, CI push+PR). Vorschlag: Build nur in CI; Pre-Commit auf lint + format + typecheck + betroffene Tests begrenzen; CI-Doppellauf über branches-ignore/concurrency beseitigen. (Gate-Änderung — sollte als Team-Entscheidung separat beschlossen werden.)
Monster-Dateien beim nächsten Anfassen zerlegen: pages/admin/reports.vue (1 395 Zeilen), settings.vue (1 183), demo-data.vue (932); Backend: AuthController (911) u. a. — Extract-on-touch-Regel ist jetzt dokumentiert.
Vitest-Coverage ausbauen: Stores (auth, i18n) und useDataTable-Filterlogik (dafür reine Funktionen nach utils/ extrahieren). @vitest/coverage-v8 ergänzen.
Attribut-Interfaces je Ressource in frontend-v2/types/ inkrementell einführen (mit [key: string]: unknown-Index-Signatur für Custom-Fields).

Niedrig¶

Historische Root-MD-Dateien (~600 KB: GRID_OVERVIEW.md, PHASE1_SPRINT_PLAN.md, plan-*.md, …) nach docs/analysis/ archivieren oder mit Status-Banner versehen.
timeout-minutes für alle CI-Jobs setzen (hängende Deploys blockieren PR-Watching).
PR-Template mit develop-Base-Hinweis; Branch-Protection für master.
[AUTO]-Version-Bump-Commits reduzieren (z. B. Bump erst beim Release statt je Merge) — aktuell >25 % der Historie.
Docker-Default-Credentials in docker/.env durch Platzhalter ersetzen.

Methodik¶

Audit über 8 parallele Analyse-Agenten (Backend-Architektur, Backend-Testing, Frontend-Architektur, Frontend-Testing, Doku-Genauigkeit, CI/Hooks, Repo-Hygiene, Safety-Rails), jeweils mit Pflicht zu gemessener Evidenz (Dateipfade, Zeilen, Sekunden, Kommando-Output). Befunde mit Severity hoch/mittel wurden anschließend von unabhängigen Verifikations-Agenten adversarial geprüft; nur bestätigte Befunde wurden umgesetzt.