Harness-Handbuch — 02 Von Hand aufbauen

Ein Verfassungsdokument, eine Agentendatei, eine Skill-Datei, ein Verdrahtungsplan und ein Kontrollposten. Die tatsächliche Reihenfolge für einen minimalen Harness aus fünf Textdateien; übrig bleibt das in neun Werkstätten gemeinsam geprüfte Grundgerüst.

§ 00 · Die erste Datei — sechzig Zeilen Verfassung

Lege im Repository-Wurzelverzeichnis eine Datei namens CLAUDE.md an. Eine Datei dieses Namens wird beim Öffnen jeder Session automatisch geladen—die Konvention, auf der der Harness aufbaut. Schreibe zunächst nur drei Dinge hinein. Fünf Zeilen darüber, was dieses Projekt ist. Einige absolute Verbote, etwa „Nicht ungeprüft fertig melden“ oder „Nicht direkt auf den main-Branch pushen“. Dann die Prüfkommandos: womit Tests laufen und der Build geprüft wird.

Beginne mit ungefähr sechzig Zeilen und bleibe in dieser Nähe. Der Grund ist einfach: Je länger das Regelwerk, desto weniger Aufmerksamkeit erhält jede Regel. Veröffentlichte Messungen sind ernüchternd. Zehn Regeln werden überwiegend eingehalten, bei fünfzig wird die Hälfte ignoriert, bei hundert kann die Maschine Wichtiges nicht mehr unterscheiden. Ab dreihundert Zeilen beginnt sie, Regeln gezielt zu übergehen. Die Bestandsaufnahme bestätigt das. In einer Werkstatt häuften sich Verstöße nach mehr als fünfhundert Zeilen Verfassung; sie wurde auf hundertfünfzig gekürzt, der Rest in einen eigenen Wissensordner verschoben. Die größte Werkstatt hält ihre Verfassung bei dreiundsiebzig Zeilen und hat sogar einen Sensor, der vor dem Commit bei Überschreitung warnt. In die Verfassung gehört die Karte; Details liegen hinter Links.

Vermeide von Anfang an eine Falle: Schreibe keine Bestandszahlen in Dokumente. „Sieben Sensoren“ oder „vierundzwanzig Tests“ beginnen sofort zu veralten, weil Dateien hinzukommen, ohne dass die Dokumentation nachzieht. Zwei Gegenmaßnahmen wurden beobachtet: Statt der Zahl steht der Zählbefehl dort—„Anzahl mit ls ermitteln“—oder ein Skript überschreibt die dokumentierte Zahl unmittelbar vor dem Commit mit dem gemessenen Wert. Das Prinzip ist gleich: Das Dokument soll auf die Realität zeigen, nicht behaupten, wie sie aussieht.

§ 01 · Die zweite Datei — der Agent

Erstelle .claude/agents/ und lege darin pro Arbeiter eine Markdown-Datei ab. Ganz oben stehen im mit drei Bindestrichen (---) begrenzten Frontmatter vier Zeilen. name: der Name, etwa verifier. description: wann er aufgerufen wird, etwa „Bei Prüfung einer Fertigmeldung. Nur beurteilen, keinen Code ändern“. tools: die verfügbaren Werkzeuge, zum Beispiel Read, Bash und Grep; Änderungswerkzeuge werden bewusst weggelassen. model: das verwendete Modell, behandelt in Teil 05.

Das Textgerüst wiederholt sich in den neun Werkstätten fast identisch. Oben steht ein Block absoluter Einschränkungen: Verbote und Pflichten mit den Stufen verpflichtend, empfohlen und optional. Es folgen Rollenbeschreibung und die Liste der verbindlichen Dokumente, die vor der Arbeit zu lesen sind. Ganz unten erneut ein Selbstkontrollpunkt vor der Abgabe: „Ohne Messung fertig behauptet?“ „Originalausgabe beigefügt?“ Dieselben Einschränkungen werden oben und unten doppelt verankert. Das folgt einer in mehreren Werkstätten bestätigten Erfahrungsregel: In langen Dokumenten beachtet die Maschine Anfang und Ende am zuverlässigsten.

Welcher Arbeiter kommt zuerst? Die Bestandsaufnahme antwortet eindeutig: der Prüfer. Vor einem guten Implementierer brauchst du jemanden, der für dich misst, ob die Implementierung tatsächlich erfolgt ist. Sobald ein reiner Prüfer ohne Änderungswerkzeuge existiert, wird aus „Alles fertig“ die Meldung „Vom Prüfer freigegeben“. Dieser Unterschied ist der Anfang eines Harness.

§ 02 · Die dritte Datei — der Skill

Lege unter .claude/skills/ einen Ordner mit einer SKILL.md an. Für den Anfang genügen zwei Frontmatter-Zeilen: name und description. In description steht die konkrete Auslösebedingung. Manche Werkstätten ergänzen ein Array mit etwa zwanzig Ausdrücken wie „Fertig“, „Alles bestanden“ und „Keine Probleme“, damit der Skill unmittelbar vor solchen Formulierungen eingreift.

Der erste Skill steht praktisch fest: das Fertigmeldungs-Gate. Schreibe in den Text: Vor der Fertigmeldung werden tatsächlich ① Typprüfung, ② Tests und ③ Build ausgeführt. Die Originalausgabe jedes Befehls kommt in den Bericht. Dann drei Verbote: keine Fertigmeldung ohne Messung; nicht nach einer Teilprüfung behaupten, alles sei bestanden; Ergebnisse der vorherigen Session nicht als aktuelle Belege ausgeben. Diese drei Sätze wurden nach wirklichen Vorfällen in mehreren Werkstätten festgeschrieben. Ihre Wirkung ist auch messbar: Beim zuvor beschriebenen Benchmark-Aufstieg leistete genau dieses Muster der Selbstkontrolle vor Abgabe den größten Beitrag.

Füge zuletzt eine Berichtsvorlage in den Skill ein. Vier Felder reichen: Urteil, ausgeführte Befehle, Originalausgaben und offene Probleme. Ein festes Berichtsformat erschwert Ausflüchte. Eine Lücke wird entweder ausgefüllt oder als Lücke sichtbar.

§ 03 · Die vierte und fünfte Datei — Verdrahtungsplan und Kontrollposten

Die vierte Datei ist .claude/settings.json, der Verdrahtungsplan. Er verbindet Ausführungszeitpunkte mit Skripten. Die häufigste beobachtete Minimalverdrahtung hat drei Stränge. Session-Start: prüfen, ob das Gedächtnis aktuell ist. Direkt nach einer Dateiänderung: still die Typprüfung ausführen. Session-Ende: warnen, wenn es heute Commits, aber keinen Eintrag gibt. Die Skripte selbst liegen in .claude/scripts/; lass sie nach Teil 03 von der Maschine schreiben.

Eine Verdrahtungsregel: Hooks blockieren möglichst nicht. Die überwältigende Mehrheit der untersuchten Hook-Skripte endet mit „in jedem Fall passieren lassen“, also exit 0. Ein Defekt im Hook selbst darf nicht die gesamte Arbeit stoppen. Ihr eigentlicher Wert liegt anderswo. „Tu das nicht“ im Chat ist die schwächste Einschränkung, die die Maschine ignorieren kann. Ein Hook arbeitet unabhängig von ihrer Absicht und ist deshalb die verlässlichste Einschränkung. Gewöhnliche Hooks flüstern. Das Beißen übernimmt die fünfte Datei.

Die fünfte Datei ist der eigentliche Kontrollposten. Erstelle in .githooks/ ein Shellskript namens pre-push. Das ist die Git-Konvention für automatische Ausführung unmittelbar vor dem Push ins entfernte Repository. Das Skript führt nacheinander Typprüfung, Tests und Build aus und verweigert bei einem Fehler den Push mit Exit-Code 1. Aktiviert wird es mit einer einzigen Terminalzeile: git config core.hooksPath .githooks. Diese führt der Nutzer einmal selbst aus. Ab dann ist ein Deployment mit kaputten Tests strukturell unmöglich. Es liegt nicht an der Faulheit der Maschine, sondern daran, dass die Tür verschlossen ist.

Beitrag lesen: sass.studio.