Ich arbeite gerade wie wahrscheinlich auch viele andere Entwickler und Architekten in einer Vielzahl Repositories, und zwar mittlerweile KI-first: Fast jede Änderung entsteht heute mit einem Coding Agent. Das ist schnell. Es hat aber eine Nebenwirkung, die mich zunehmend genervt hat: Ich habe mich ständig wiederholt. In jedem Projekt, oft in jeder Session, dieselben Anweisungen. Schreib keine Behauptung, die du nicht geprüft hast. Bau keine Abstraktion, die niemand braucht. Halt die Doku aktuell. Schreib Tests, die wirklich etwas testen.
Irgendwann habe ich diese Regeln aus meinem Kopf in ein Werkzeug verlagert, meinen eigenen Harness für Coding Agents. In dieser dreiteiligen Serie zeige ich, was darin steckt, warum, und was ich unterwegs wieder verworfen habe. Hier geht es um die Grundregeln. Teil 2 behandelt Architekturdokumentation und ADRs, Teil 3 den Workflow.
Drei Probleme, die mich angetrieben haben
Was ein Agentic Harness grundsätzlich ist, hat Sascha in seiner Serie erklärt, angefangen bei Was ist ein Agentic Harness?. Kurz gesagt: alles rund um das Modell, was nicht das Modell selbst ist. Dieser Beitrag ist die Praxis dazu.
1. Wiederholung. Allgemeine Regeln gehören nicht in einen Prompt, sondern an einen festen Ort, den jeder Agent in jedem Projekt liest. Wenn ich eine Regel verbessere, soll die Verbesserung überall ankommen, nicht nur in dem Repository, in dem ich gerade sitze.
2. Der Abstand zum Projekt. Ein Problem kenne ich aus fast jedem Projekt, lange vor KI: Neue Entwickler, oder auch erfahrene, die ein Projekt nur selten anfassen, fühlen sich vom Stand des Projekts abgehängt. Was ist das Ziel? Was wurde entschieden, und warum? Die Folge ist Zögern. Niemand traut sich, Code anzufassen, den er nicht versteht. Mit Coding Agents wird das schlimmer, denn der Code ändert sich schneller, als jemand die Doku nachziehen kann. Also muss der Agent das selbst erledigen.
3. Entscheidungen, die tragen. Dokumentierte Architekturentscheidungen schaffen Akzeptanz, gerade dann, wenn etwas schiefgeht. Auf einer höheren, auch fürs Management verständlichen Ebene leistet das der Architecture Communication Canvas. Mehr dazu in Teil 2.
Die ersten Antworten darauf sind vier Grundregeln, die jeder Agent bei mir befolgt.
Regel 1: Wissen, nicht vermuten
Die wichtigste Regel heißt Know, do not assume: Ein Agent schreibt nur, was er belegen kann, also mit einer gelesenen Datei, einem ausgeführten Test, einer Aussage von mir oder einer verlinkten Quelle. „Sollte funktionieren“ oder „wahrscheinlich“ sind als Ergebnis verboten, und kein Task gilt als erledigt, bevor seine Verifikation besteht.
Der Unterschied ist im Alltag sofort sichtbar. Ohne die Regel endet eine Aufgabe typischerweise so:
Ich habe den Check erweitert. Commits auf dem Hauptbranch sollten jetzt korrekt geprüft werden.
Mit der Regel steht dasselbe Ergebnis so im QA-Bericht, hier eine echte Zeile aus meinem Harness:
| Scenario | Result | Evidence |
|---|---|---|
| Conventional commit messages: Trunk commit header is not conventional | passed | Test "Conventional commit messages: Trunk commit header is not conventional". node --test 'scripts/*.test.mjs': passed. |
Ich muss nicht glauben, dass es funktioniert. Ich sehe, womit es geprüft wurde, und kann es selbst wiederholen. Was ein Agent nicht belegen kann, landet als offener Punkt in der Doku, statt mit einer plausiblen Annahme überspielt zu werden. Warum sich Agenten nicht selbst benoten sollten, hat Sascha in Verifizierung & Kontrolle beschrieben.
Regel 2: Einfachheit vor Eleganz
Coding Agents neigen zu Overengineering. Sie bauen gern ein Interface für eine einzige Implementierung, eine Factory für ein new oder ziehen ein Paket für eine Aufgabe, die zehn Zeilen braucht. Gleichzeitig ist Einfachheit schon immer meine eigene Haltung als Entwickler. Die Regel macht sie nur explizit:
- Use the simplest solution that meets the spec.
- Add an abstraction only when two or more real uses need it.
- Do not add a dependency if 20 lines of clear code do the same work.
Dazu kommen zwei Klassiker: DRY (jede Information an genau einem Ort, für Code, Konfiguration und Dokumente) und die SOLID-Prinzipien. Auch für sie gilt: nur, wenn es Sinn macht. In der Regel steht deshalb ausdrücklich: Use SOLID to make code easy to change. Do not use it to add layers without need. SOLID und DRY sind Werkzeuge für änderbaren Code, keine Lizenz für Schichten und Abstraktionen. Im Zweifel gewinnt die Einfachheit.
Nach jeder Aufgabe folgt ein kurzer Refactoring-Schritt, aber nur mit grünen Tests davor und danach. Wird das Refactoring groß, macht der Agent es nicht, sondern schreibt es ins Backlog. Das hält Änderungen klein und reviewbar.
Regel 3: Tests, die etwas testen
In Code-Reviews im Zeitalter von Coding Agents habe ich von Tests erzählt, die Assert.True(true) implementieren, nur damit „mehr Tests“ da sind. Dagegen steht eine kurze Liste: Ein guter Test prüft Verhalten über eine öffentliche Schnittstelle, hat genau einen klaren Grund zu scheitern und bildet ein Spec-Szenario ab. Ein schlechter Test mockt die Einheit, die er testen soll, prüft private Zustände oder ist grün, obwohl das Feature kaputt ist.
Der Agent arbeitet testgetrieben und sieht jeden Test erst aus dem richtigen Grund fehlschlagen. Und kein Test wird abgeschaltet oder abgeschwächt, nur damit er besteht.
Regel 4: Simplified Technical English
Dass Anweisungen an Agenten und Dokumente für Menschen knapp und eindeutig sein sollten, ist in der Entwickler-Community inzwischen Konsens. Ich mache daraus eine feste Regel mit einem etablierten Standard: Alle englischen Texte, also Dokumente, Specs, ADRs, Kommentare, Commit-Messages und Berichte, folgen ASD-STE100 Simplified Technical English. Das ist ein kontrolliertes Englisch aus der Luftfahrt, ursprünglich für Wartungshandbücher entwickelt, die auch Nicht-Muttersprachler ohne Missverständnis lesen müssen.
Ein fester Standard statt „schreib bitte kurz“ löst zwei Probleme gleichzeitig:
- LLMs schreiben gern ausschweifend und „poetisch“. Viel Prosa erhöht das Risiko von Widersprüchen und Unklarheiten, gerade in Dokumenten, die später wieder ein Agent als Anweisung liest.
- Menschen sind von zu viel Text schnell überfordert und frustriert. Eine Doku, die niemand liest, ist keine Doku.
Die Regeln sind einfach genug, dass ein Agent sie zuverlässig befolgt: ein Wort für eine Bedeutung, keine Phrasal Verbs und Kurzformen, höchstens 20 Wörter pro Satz in Anleitungen und 25 in Beschreibungen, Aktiv statt Passiv. Zu lange Sätze findet ein Skript automatisch. Das Vokabular kann es nicht prüfen, denn das vollständige STE-Wörterbuch liegt nicht im Repository. Deshalb darf ein Agent auch nicht behaupten, ein Text sei „STE-konform“, sondern nur, dass er „den STE-Regeln folgt“. Das ist die Evidenzregel, angewendet auf sich selbst.
Alle englischen Auszüge in diesem Beitrag sind übrigens in diesem Stil geschrieben.
Was daraus geworden ist: sparc
Aus diesen Regeln ist sparc entstanden. Der Name kommt von spec, von arc (Architektur) und vom Funken (spark) einer Idee, aus dem am Ende funktionierende Software werden soll. sparc ist ein Plugin für Claude Code und baut auf OpenSpec auf, auf das ich über einen Podcast gestoßen bin. Mich hat der schlichte Ansatz überzeugt: Jede Änderung ist ein kleiner Ordner mit Proposal, Specs, Design und Tasks. Wie so oft gilt: Einfachheit ist der Schlüssel.
Neben den Regeln enthält sparc feste Rollen (Product Owner, Architect, UX Designer, Software Engineer, QA Engineer), einen festen Dokumentensatz und ein Skript, das nach jedem Agentenlauf prüft, ob die Doku noch zum Code passt. Jede Regel existiert dabei genau einmal. Rollen und Skills verweisen auf sie, statt sie zu kopieren, und in einem Projekt gibt es nur eine AGENTS.md, keine zweite CLAUDE.md mit leicht abweichendem Inhalt.
sparc ist selbst ein sparc-Projekt und hat in zwei Tagen zwölf Architekturentscheidungen gesammelt. Zwei davon haben etwas wieder entfernt, das anfangs wie gute Architektur aussah. Diese Geschichte erzähle ich in Teil 3.
Zum Mitnehmen: drei Regeln für deine AGENTS.md
Du brauchst keinen eigenen Harness, um damit anzufangen. Diese drei Zeilen stehen fast wörtlich so in jedem meiner Projekte und funktionieren in jeder AGENTS.md oder CLAUDE.md:
- Write only what you know. Get evidence from files, tests or the user.
Do not write "should work" or "probably" as a result.
- Keep it simple. Add an abstraction only when two or more real uses need it.
Keep each fact in one place and link to it from other places.
- Write a test that fails for the right reason before you write the code.
Do not disable, skip or weaken a test to make it pass.
Fazit
Ein eigener Harness ist weniger Aufwand, als es klingt, wenn er sich auf das beschränkt, was man ohnehin in jedem Projekt fordert. Für mich sind das vier Grundregeln: Behauptungen belegen, einfach bauen, echte Tests schreiben, klar formulieren. Neu ist nicht der Inhalt dieser Regeln. Neu ist, dass ich sie nicht mehr wiederholen muss.
Im zweiten Teil geht es um mein Lieblingsthema: Architekturdokumentation, die mit dem Code Schritt hält, und ADRs, die auch nach der Entscheidung ehrlich bleiben.