Briefing-First mit KI – Spezifikation vor Code

Datum: 2026-03-01

Spezifikation schlägt Chat-Gedächtnis

Ohne schriftliche Spezifikation halluziniert das Modell Architektur: falsche Namespaces, Orchestrator im Legacy-Ordner, Translation-Keys die es nie gab. Das passiert nicht aus Bosheit – sondern weil das Kontextfenster kein Vertrag ist.

Briefing-First bedeutet: Jede Änderung beginnt unter `briefing/` – Screen, Orchestrator, Service, Model, CLI. Erst wenn das Briefing stimmt, folgt PHP, Twig, CSS und Tests.

Das Problem

Du optimierst gegen Chat-Gedächtnis, nicht gegen Projektrealität.

Das Pattern

Briefing-First ist keine Formalität, sondern API zwischen Mensch, Team und KI:

001. Briefing beschreibt was und in welcher Schicht.

002. Quellcode implementiert das Briefing 1:1.

003. Subagents prüfen Abweichungen (Briefing ↔ PHP ↔ Tests).

Die KI hat eine verbindliche Quelle – nicht nur die letzten zehn Chat-Nachrichten.

Struktur bei uns

briefing/
├── screens/           # UI-Screens, Blogposts
├── orchestrator-services/
├── CLIOrchestrator/   # start-vendor-* Workflows
├── services/
├── models/
├── database/          # optional SQL-Quellen
└── ui-tests/

Jede PHP-Datei unter `src/` und jedes `start-vendor-*.php` verweist im Kopfkommentar auf sein Briefing. Änderungsprotokoll in PHPDoc bei jeder Code-Änderung (`@skill-change-provenance`).

Ablauf: Feature von Briefing bis grün

Subagents wie `subagent-briefing-first` und `subagent-check-orchestrator` fangen Drift früh ab.

Briefing-Qualität: Was rein muss

Screen-Briefing: Route, Script-Pfad, Orchestrator, Parameter, UI-Aufbau, SEO, Fehlerfälle.

Orchestrator-Briefing: Steps 001…00N mit Fließtext und Return; Adjazenz zwischen Steps.

Service-Briefing: Eine Hauptmethode pro Step, ABLAUF-SCHRITTE, keine Array-Returns.

CLI-Briefing: Terminal-Bootstrap, Logs, Ralph-Loop-Anbindung.

Vage Formulierungen („etc.“, „wie üblich“) sind verboten – die KI füllt Lücken zufällig.

Anti-Patterns

001. Code zuerst, Briefing „später“ – Später kommt nie; Drift ist sofort da.

002. Briefing als Kommentar im Chat – Nicht versioniert, nicht prüfbar.

003. Ein Riesen-briefing.md für alles – Unübersichtlich; Ordnerstruktur nutzen.

004. Briefing ohne Step-Nummern – Orchestrator-Checks schlagen fehl.

005. Vendor-Briefing im Host spiegeln – `subagent-check-vendor-duplicates` bereinigt das.

KI-Prompt vs. Briefing

Regel: Wenn es morgen noch gelten soll → `briefing/`.

Häufige Fragen

Verlangsamt Briefing-First?

Kurzfristig minimal, langfristig massiv schneller – weniger 500er und Rewrite-Schleifen.

Muss jedes Mini-Refactoring ein Briefing?

Schichten-, API- oder Verhaltensänderung: ja. Reiner Tippfehler im Template: oft nein.

Wer pflegt Briefings?

Wer den Code ändert – gleicher PR.

Verwandte Beiträge

Takeaway

Ohne Spezifikation optimiert das Modell gegen sein eigenes Gedächtnis. Briefing-First macht `briefing/` zur Single Source of Truth – für Menschen, für Reviews und für Agents. Wer das einmal gewöhnt ist, will nicht mehr zurück zum „Bau mal schnell im Chat“.