Zum Inhalt springen

Wissensbasis

Specs, Tests und Kontext

Die Spec ist die Quelle der Wahrheit, ihre Tests prüfen den Code dagegen. Laufen beide auseinander, entscheidet, wer die Spec verantwortet, welche Seite sich ändert. Dokumentation hat jetzt einen zweiten Leser, den Agenten. Er braucht eine kleine, priorisierte und gepflegte Instruktionsschicht statt einer erschöpfenden.

Verfasst von

Aktualisiert:

Agentic Engineering 5

Unsere Position. Für uns ist die Spec die Quelle der Wahrheit. Aus ihr entstehen die Akzeptanztests, und der Agent, der die Änderung umsetzt, fasst sie nicht an. Weichen Code oder Tests von der Spec ab, entscheidet die Person, die sie verantwortet, welche Seite sich ändert, und hält den Grund fest. Standard ist das Leichteste, das funktioniert (öffnet in einem neuen Tab). Mehr Gewicht bekommt eine Spec erst, wenn die Arbeit es rechtfertigt. Die Instruktionsdateien eines Teams führen wir zu einer AGENTS.md zusammen und geben ihr einen Owner, denn die Datei war nie das Schwierige (öffnet in einem neuen Tab).

Soll die Spec oder sollen die Tests die Quelle der Wahrheit sein?

Wo sich eine Spec lohnt, kehrt spec-getriebene Arbeit das Zeitbudget der Entwicklung um. In Onas Experiment onawalk entstand eine lauffähige 3D-Anwendung aus 30 Minuten Spec-Schreiben und 10 Minuten Agentenlauf. Die Lehre daraus: Ein vager Prompt liefert ein vages Ergebnis. Legt die Spec Shader-Parameter, Kameraverhalten und Ladestrategie fest, liefert der Agent genau das (Ona - Spec-driven design: why planning is the new coding (öffnet in einem neuen Tab)). Berichte aus der Praxis kommen von der anderen Seite zum selben Schluss. Wie gut eine Spec geschrieben ist, bestimmt die Qualität der KI-Ausgabe. Die Arbeit in agentengroße Stücke zu zerlegen, bleibt die zentrale technische Fähigkeit (KI-Produktivitätsstudien).

Specs sind notwendig, aber nicht hinreichend. Die Dark Factory Patterns führen “Big Design Upfront as Source of Truth” als Anti-Pattern. Specs sind unvollständig, beruhen auf Hypothesen und enthalten Fehler. Je selbstbewusster sie formuliert sind, desto gefährlicher wird es, sie ungeprüft umzusetzen. In einer autonomen Software Factory sind deshalb programmatische Tests und Fitness Functions die Quelle der Wahrheit. Die Spec beschreibt die Absicht, die Tests prüfen die Realität, und wo beide auseinandergehen, hat die Realität recht (Dark Factory Patterns). Wir halten an der Spec als Quelle der Wahrheit fest und nehmen die Warnung ernst. Ein fehlschlagender Test geht als Frage an die Person, die die Spec verantwortet. Sie korrigiert die Spec, wo diese falsch war.

Dieselbe Quelle gibt Teams, die mehr Agentenausgabe wollen, eine Reihenfolge vor: zuerst Validierung und Observability, dann Produktionsvolumen. Eine Factory, die gute Ausgabe nicht zuverlässig von schlechter unterscheidet, sollte nicht im Produktionsmaßstab laufen (Dark Factory Patterns). Engineering-Teams investieren also erst in Testsuiten, Akzeptanzkriterien und Fitness Functions und dann in mehr Durchsatz der Agenten. Verifikation zu entwerfen gehört selbst zu den Fähigkeiten, die künftig am wichtigsten werden (KI-Produktivitätsstudien).

Treibt man Specs zu weit, entsteht mehr Verwirrung statt mehr Präzision. Je detaillierter die Instruktionen, desto mehr übersieht der Agent. Dagegen helfen Verifikation und Iteration, nicht mehr Prompting (Modernisierung mit AI (öffnet in einem neuen Tab)). Derselbe Talk nennt die Lücke autogenerated bullshit. Gemeint ist die vierfache Abweichung zwischen dem, was die Anforderungen sagten, was der Agent getan zu haben glaubt, was er nach Ansicht der Nutzer:innen getan hat, und was wirklich geschah. Aus “Implementiere User Authentication” wird so ein Login-Formular ohne Datenbank und ohne Session-Management (Modernisierung mit AI (öffnet in einem neuen Tab)). Deshalb behandeln mehrere Praktiker:innen Tests als unverrückbar. Im Akzeptanztest-Repository von System Initiative gilt eine feste Regel: Die Tests sind die Quelle der Wahrheit und dürfen nicht geändert werden. Jeder Fehlschlag ist damit eine Regression im Binary, nie ein Test zum Anpassen (If humans architect the system, the AI writes the code (YouTube) (öffnet in einem neuen Tab)).

Die Reihenfolge zählt. Tests, die nach der Umsetzung entstehen, optimiert der Agent auf den Code, der schon in seinem Kontext steht. Das beabsichtigte Verhalten halten sie dann nicht fest, also kommt der Test zuerst (AI Labs - Three levels of AI UI design (YouTube) (öffnet in einem neuen Tab)). Pläne lassen sich auf dieselbe Weise unter Druck testen. Die Schleife bei System Initiative lässt einen generierenden Agenten gegen einen absichtlich grantigen, adversarialen Reviewer laufen. Dieser muss belegen, dass die Arbeit sicher und architektonisch vollständig ist. Nach höchstens fünf Runden muss ein Mensch als Schiedsrichter:in entscheiden. Das bleibt billig, weil eine verworfene Sitzung etwa zehn Minuten kostet (If humans architect the system, the AI writes the code (YouTube) (öffnet in einem neuen Tab)). Ein guter struktureller Schnitt liefert außerdem die Testpyramide gratis mit. Laut dem Artikel zur Capability-Centric Architecture laufen Essence-Tests für reine Logik in Millisekunden. Realization-Tests mocken die Infrastruktur, und Contract-Tests prüfen, ob jede Capability ihre Zusagen hält (Capability-Centric Architecture (öffnet in einem neuen Tab)).

Die Continuous-Delivery-Community bringt die Spec-Artefakte in eine Rangfolge, damit ein Agent nie raten muss, welches gilt. Ihr Delivery Contract ordnet sechs Artefakte vom verbindlichsten zum am wenigsten verbindlichen:

  1. die menschliche Absicht
  2. das Verhalten für Nutzer:innen als BDD-Szenarien
  3. die Feature-Beschreibung mit ihren Architektur-Constraints
  4. die Akzeptanzkriterien
  5. die organisationsweiten System-Constraints
  6. zuletzt die Implementierung

Widersprechen sich zwei davon, wird das niedrigere geändert. Eine unausgesprochene Rangfolge gilt als eigener Fehler, denn bei einem Konflikt wählt der Agent dann stillschweigend eine Seite (MinimumCD.org and DojoConsortium.org - Agent Delivery Contract (öffnet in einem neuen Tab), Stand September 2026). Die Rangfolge entscheidet, welches Dokument bearbeitet wird. Zum Beweis der Korrektheit macht sie eine Spec nicht, das bleibt wie oben Sache der Tests.

Die Feature-Beschreibung markiert, wo der Ermessensspielraum eines Agenten endet. Neben harten Muss-Vorgaben, ausdrücklichen Verboten und weichen Präferenzen listet sie Eskalations-Trigger auf. Das sind Bedingungen, unter denen der Agent anhält und fragt, statt selbst zu entscheiden, etwa bei einer Änderung, die in die Authentifizierungsschicht reichen würde. Die Akzeptanzkriterien bestehen aus zwei Teilen. Eine Done-Definition nennt Ergebnisse, die Reviewer:innen ohne Blick in den Code bestätigen können. Ein Evaluationsdesign listet Fälle mit bekannt guten Ausgaben, die die Pipeline bei jedem Commit prüft (MinimumCD.org and DojoConsortium.org - Agent Delivery Contract (öffnet in einem neuen Tab), Stand September 2026).

Derselbe Contract stellt zu zwei Zeitpunkten zwei verschiedene Fragen. Die Akzeptanzkriterien fragen bei jedem Commit, ob der Code funktioniert. In der Absicht steht eine testbare Hypothese: Sie nennt die Änderung, das Ergebnis, das sie bewirken soll, und den Grund. Ob die Änderung ihren Zweck erreicht hat, beantworten nach dem Deploy die Produktionsmetriken. Das ausgearbeitete Beispiel ist ein Rate Limiter, der jeden Test besteht und die Tail Latency trotzdem lässt, wo sie war. Missbräuchliche Clients waren nicht die Ursache. Diese widerlegte Hypothese fließt in die nächste Absicht ein. Grüne Tests als bestätigte Hypothese zu lesen, ist genau die Verwechslung, vor der die Quelle warnt (MinimumCD.org and DojoConsortium.org - Agent Delivery Contract (öffnet in einem neuen Tab), Stand September 2026).

Wie wird Dokumentation zum Kontext für Agenten?

Dokumentation hat jetzt zwei Zielgruppen, und die Hälfte für Agenten wird zu einer eigenen, gezielt gebauten Schicht. Ein Framework stuft diesen “agentic layer” ab: von einer nackten CLAUDE.md über Spec-Verzeichnisse, Subagents und Koordinationsdateien bis zu Closed-Loop-Prompts. Seine These: Ist die Schicht mächtig genug, bedienen Agenten die Codebase wirksamer als jede:r einzelne Engineer (The Codebase Singularity (öffnet in einem neuen Tab); siehe Agentic Engineer Maturity Model). Entsprechend gilt Context Engineering als eigenes Architekturthema. Gemeint ist der Entwurf des gesamten Modell-Inputs, mit Prompts, abgerufenen Daten, Memory und Tools. Die Empfehlung lautet, Prompts als vollwertigen Code selbst zu verantworten, statt sie an Black Boxes eines Frameworks abzugeben (AOE - AI Technology Radar: Context Engineering (öffnet in einem neuen Tab)).

Auf die Größe kommt es an. Der Erfinder von Claude Code hält seine CLAUDE.md bei rund 2.500 Tokens. Die Initiative zur Standardisierung von agents.md empfiehlt etwa 70 Zeilen. Laut einer Studie der ETH Zürich steigern Kontextdateien wie AGENTS.md die Erfolgsquote von Coding Agents im Allgemeinen nicht gegenüber gar keiner Kontextdatei, erhöhen aber die Inferenzkosten im Schnitt um über 20 % (Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? (öffnet in einem neuen Tab)). Als Lösung zeichnet sich Progressive Disclosure ab: minimaler Basiskontext, und Details laden bei Bedarf über Skills. Die optimale Balance ist allerdings noch nicht geklärt (KI-Produktivitätsstudien).

Statische Dokumentation weicht unterdessen der laufenden Generierung. Googles Code Wiki scannt ein Repository nach jeder Änderung neu. Es erzeugt strukturierte Docs sowie Architektur-, Klassen- und Sequenzdiagramme neu, dazu einen Chat-Agenten, der auf dem stets aktuellen Wiki aufsetzt (Google - Introducing Code Wiki (öffnet in einem neuen Tab)). Jeder Wiki-Abschnitt und jede Chat-Antwort verlinkt direkt auf die zugrunde liegenden Dateien. Lesen und Navigieren werden so ein einziger Arbeitsablauf. Google zielt damit klar auf Legacy- und private Repositories, deren ursprüngliche Autor:innen vielleicht nicht mehr da sind. Eine lokale Gemini-CLI-Erweiterung hält den internen Code dabei on-premises (Google - Introducing Code Wiki (öffnet in einem neuen Tab)). Das Dark-Factory-Pattern “Living Portfolio” überträgt dieselbe Idee auf ein ganzes Portfolio. Jede Lösung wird bei ihrer Entstehung katalogisiert und dokumentiert. Maintenance-Agenten erzeugen Dokumentation und Changelogs aus Code und Änderungshistorie, damit das Portfolio sich selbst gesund hält (Dark Factory Patterns).

Hinter der Größendisziplin steckt die Aufmerksamkeit. In sehr großen Kontextfenstern erkennt das Modell nicht, welche früheren Tokens zählen. Wer Agenten entwirft, muss deshalb aktiv steuern, was dauerhaft im Kontext bleibt (BRAID: bounded reasoning for agents (YouTube) (öffnet in einem neuen Tab)). Ein hilfreiches Denkmodell behandelt den Kontext als festes Allokations-Array. Die ersten Slots belegen der Harness-Prompt und die stets geladene AGENTS.md. Eine übergroße Instruktionsdatei stiehlt dauerhaft Arbeitsraum und drängt den Agenten in eine Zone geringerer Qualität. Das ist das konkrete Argument, sie bei rund siebzig Zeilen zu halten (Ralph and AGENTS.md tuning (YouTube) (öffnet in einem neuen Tab)). Die Kunst besteht darin, gerade genug zu schreiben, um das latente Wissen des Modells auszulösen, statt jeden Schritt auszubuchstabieren. Wer journalctl nennt, bringt das Modell dazu, von selbst zu systemctl zu greifen. Überspezifikation schadet also (Ralph and AGENTS.md tuning (YouTube) (öffnet in einem neuen Tab)).

Die Migrationsarbeit von TNG kam über Fehlschläge zum selben Schluss. Überlädt man das Modell mit irrelevanten Details, hält es sich schon bei grundlegenden Aufgaben schlechter an die Vorgaben. Startet also nur mit dem nötigen Kontext und ergänzt mehr nur dort, wo Ergebnisse scheitern (TNG - AI-assisted PL/I to Java migration (öffnet in einem neuen Tab)). Wann die Datei ein Update braucht, zeigt das Verhalten: Scheitern Tool Calls wiederholt, müssen die Instruktionen nachjustiert werden, nicht der Agent (Ralph and AGENTS.md tuning (YouTube) (öffnet in einem neuen Tab)).

Die Instruktionsdatei wandert von Prosa Richtung Code. Das Team von System Initiative behandelt die CLAUDE.md als ausführbaren Vertrag und Schwerpunkt des Systems. Darin stehen knappe Constraints statt Dokumentation: TypeScript strict, nur Named Exports, keine Fire-and-forget-Promises (If humans architect the system, the AI writes the code (YouTube) (öffnet in einem neuen Tab)). Eine Quelle spricht sich gegen eine einzige Instruktionsdatei für alle Modelle aus. Ein Ton, der einem Modell hilft, schadet einem anderen. Manche Modelle werden bei nachdrücklichen Instruktionen in Großbuchstaben schlechter, andere sind gerade darauf abgestimmt. Eine gemeinsame Datei bricht deshalb, und Dateien pro Modell werden sinnvoll (Ralph and AGENTS.md tuning (YouTube) (öffnet in einem neuen Tab)).

Mehrere Teams machen die Datei selbstverbessernd:

Auch Prompts können strukturierte Artefakte sein. Kodiert man einen System-Prompt als Mermaid-Flowchart, bekommt der Agent explizite Verzweigungen statt einer linearen Textwand, die er erst deuten muss. Das Signal-Rausch-Verhältnis steigt so weit, dass ein kleines, billiges Modell mit einem Spitzenmodell mithalten kann (BRAID: bounded reasoning for agents (YouTube) (öffnet in einem neuen Tab)).

Zwei Folgeeffekte verdienen einen Namen. Erstens ist oft der Agent der Grund, warum Dokumentation endlich entsteht. Konventionen, die niemand für Kolleg:innen aufschreiben wollte, landen für den Assistenten auf Papier, und die Menschen finden sich dadurch besser in der Codebase zurecht (INNOQ - Softwaremodernisierung mit GenAI (YouTube) (öffnet in einem neuen Tab)). Lesbarer Code bedient jetzt auch den Agenten als vollwertigen Konsumenten, denn klare Absicht macht es dem nächsten Agenten leichter, darauf aufzubauen (Modern Software Engineering (YouTube) (öffnet in einem neuen Tab)). Zweitens ist diese Schicht ein Asset, das man baut und nicht installiert. Das Tool steht in Minuten. Architektonisches Gedächtnis, Qualitätschecks und Governance darum herum entstehen über Quartale (Into the Wind: an architecture for AI transformation (öffnet in einem neuen Tab), 11. Juni 2026).

Subagents werden zu einem eigenen portablen Format. Sie folgen einer festen Vorlage aus Frontmatter, Identität und Memory, Mission, Domänenregeln, Deliverables mit Beispielen, Workflow und Erfolgsmetriken. Aus einer einzigen Markdown-Definition lassen sie sich in ein Dutzend agentischer Tools konvertieren (agency-agents (öffnet in einem neuen Tab)). Ein paralleler Ansatz packt diese Portabilität in eine Hülle im Stil von Kubernetes. AgentSpec (öffnet in einem neuen Tab) (Version 0.3.0, Stand Juli 2026) definiert YAML-Dokumente mit apiVersion, kind, metadata und spec in vier Arten: Agent, Skill, MultiAgent und Workflow. Das spec enthält:

  • die Absicht mit Problem, Ergebnissen, Standard Operating Procedures, Constraints und Annahmen
  • Kontext-Bindings an Eingabedaten
  • Aktionen mit Freigaberegeln und Fehlerbehandlung
  • Capabilities
  • Evaluationskriterien mit Szenarien und Edge Cases
  • eine targets-Liste, die eine Definition für mehrere Agenten-Runtimes baut

Die Wette dahinter: Absicht und Evaluation gehören in dasselbe Artefakt wie der Prompt. Eine Definition kommt dann gleich mit den Kriterien, die sie bewerten, statt sie später nachzurüsten.

Verwandte Seiten

Quellen

Spec-Praxis