Harness Bootstrap
Verwandeln Sie ein Repository in eines, in dem jede neue Agentensitzung auf jedem Entwicklerrechner allein aus dem Repository fünf Fragen beantworten kann: Was ist das, wie ist es organisiert, wie führe ich es aus, wie verifiziere ich es und wo haben wir aufgehört. Dann machen Sie aus „erledigt“ etwas, das ein Skript entscheidet, nicht der Agent.
Dieses Skill wird einmal pro Repository ausgeführt. Es installiert einen Vertrag, den das Team committed, und Lebenszyklus-Skills (harness-start, harness-handoff, harness-cleanup, harness-evaluate), die im Repository leben, sodass jeder Teammitglied sie beim Klonen erhält, unabhängig vom verwendeten Coding-Agenten.
Pfade in dieser Datei (scripts/, references/, assets/) sind relativ zu dem Verzeichnis, das diese SKILL.md enthält. Wo sich dieses Verzeichnis befindet, hängt vom Agenten und davon ab, wie das Skill installiert wurde. Lösen Sie es daher vom Speicherort aus auf, von dem Sie diese Datei geladen haben; nehmen Sie niemals einen festen Pfad wie ~/.claude/skills/ an.
Lesen Sie references/principles.md, wenn Sie die Begründung hinter einem Artefakt benötigen (z. B. um es dem Benutzer zu erklären oder an ein ungewöhnliches Repository anzupassen).
Das Modell, das Sie installieren
| Schicht | Wo | Committed? | Zweck |
|---|---|---|---|
| Einstiegsdatei | CLAUDE.md und/oder AGENTS.md | ja | Kurze Karte: Was, wie ausführen, wie verifizieren, harte Regeln, Links |
| Dokumentation | docs/ARCHITECTURE.md, PRODUCT.md, RELIABILITY.md, docs/decisions/ | ja | Wissen, das der Agent nicht aus dem Code ableiten kann |
| Vertrag | harness/ (Konfiguration, Regeln, Checkliste, Rubrik, Qualitätsdokument, Vorlagen, README) | ja | Gleiche Regeln für alle, nur durch PR änderbar |
| Verifikation | scripts/harness/ | ja | init.sh, verify.sh, feature.py, check_architecture.py, cleanup-scan.sh |
| Lebenszyklus | .agents/skills/harness-*, gespiegelt für Agenten, die einen anderen Ordner lesen | ja | Starten, Übergeben, Aufräumen, Auswerten |
| Adapter | Pro Agent, z. B. .claude/agents/, .claude/hooks/ für Claude Code | ja | Optionale Extras: Subagent, Hooks |
| Aufgabenstatus | .harness/tasks/<TASK-ID>/ | nein | Feature-Liste, Vertrag, Fortschritt, Übergabe, Ausführungsprotokolle für eine Aufgabe |
Der Aufgabenstatus ist lokal, weil er sich in jeder Sitzung ändert und zu einer Person Branch gehört. Ihn zu committen verursacht Merge-Konflikte und lässt den veralteten Status eines Entwicklers den Agenten eines anderen in die Irre führen. Es ist ein Cache: Alles Dauerhafte wird vor Aufgabenende in Code, Tests, Dokumentation, den PR oder das Issue-Tracker überführt. harness/README.md erklärt dies dem Team.
Arbeitsablauf
1. Ziel bestätigen
Führen Sie git rev-parse --show-toplevel in dem Verzeichnis aus, das der Benutzer meint. Wenn es kein Git-Repository ist, stoppen Sie und teilen Sie dies mit: Worktree-Isolation und die Base-Branch-Prüfungen hängen von Git ab. Notieren Sie, ob der Working Tree schmutzig ist; schlagen Sie vor, das Bootstrap auf einem eigenen Branch durchzuführen, damit es als ein PR überprüft werden kann.
2. Bestand ermitteln
Schauen Sie, bevor Sie schreiben. Finden und lesen Sie:
- Anweisungsdateien:
AGENTS.md,CLAUDE.md,.claude/CLAUDE.md,CLAUDE.local.md,GEMINI.md,.cursorrules,.cursor/rules/,.github/copilot-instructions.md,.windsurfrules - Dokumentation:
README*,docs/, ADR-Ordner,CONTRIBUTING* - Vorhandene Harness-Teile:
feature_list.json,progress.md,init.sh,Makefile,harness/,scripts/harness/,.harness/ - Agentenkonfiguration und Skills:
.agents/skills/,.claude/(settings.json,skills/,agents/,hooks/),.devin/,.cursor/,.github/,.worktreeinclude .gitignore
Vorhandener Inhalt hat Vorrang. Sie erweitern ihn; Sie ersetzen niemals eine vom Team geschriebene Datei ohne Rückfrage.
3. Herausfinden, wie das Projekt läuft
Folgen Sie references/discovery.md. Das Ziel ist eine verifizierte Liste von Befehlen für jede Verifikationsebene, jeweils mit dem Ort, an dem Sie ihn gefunden haben (CI-Konfiguration ist der stärkste Beleg, weil sie das ist, dem das Team tatsächlich vertraut). Identifizieren Sie auch die Ebenen oder Module des Codes und die Abhängigkeitsrichtungen zwischen ihnen; diese werden zu Architekturregeln.
4. Nur nach Lücken fragen
Fassen Sie die Fragen, die Sie nicht aus dem Repository beantworten konnten, in einem strukturierten Frageaufruf zusammen, wenn Ihre Umgebung einen hat, andernfalls in einer einzigen Nachricht. Typische Lücken:
- Architekturgrenzen, die Sie abgeleitet haben, aber nicht sicher sind („darf
ui/db/importieren?“) - Der End-to-End- oder Smoke-Befehl, falls keiner existiert
- Base Branch und Branch-Namenskonvention, falls nicht dokumentiert
- Welche Coding-Agenten das Team verwendet (Claude Code, Codex, Cursor, Copilot, Devin, Pi, andere). Dies bestimmt die Einstiegsdatei und welche Agentenadapter installiert werden.
- Wenn das Team Claude Code verwendet: Ob dessen Hooks installiert werden sollen (empfohlen; sie zeigen den Aufgabenstatus zu Sitzungsbeginn an und blockieren manuelle Änderungen des Aufgabenstatus, bevor sie passieren)
Fragen Sie nicht nach Dingen mit einem konventionellen Standard; wählen Sie ihn und erwähnen Sie ihn im Abschlussbericht.
5. Das Grundgerüst kopieren
bash <Verzeichnis dieses Skills>/scripts/install.sh <Repo-Wurzel> --agents <IDs>
--agents nimmt die Agenten des Teams aus Schritt 4 als kommagetrennte IDs, dieselben IDs, die die npx skills CLI verwendet (claude-code, codex, cursor, github-copilot, gemini-cli,
opencode, pi, devin, windsurf, kiro-cli, ...; --help listet sie auf).
Das Skript kopiert assets/project/ in das Repository, einschließlich der Lebenszyklus-Skills in .agents/skills/, die die meisten Agenten direkt lesen. Für Agenten, die einen anderen Ordner lesen (claude-code, devin, windsurf, kiro-cli) fügt es relative Symlinks zu diesen Skills hinzu, und für Agenten mit einem Adapter in assets/adapters/<id>/ kopiert es die Adapterdateien. Übergeben Sie --copy für Kopien anstelle von Symlinks, wenn das Team Windows-Checkouts ohne Symlink-Unterstützung hat; init.sh meldet dann Kopien, die abweichen. Das Skript überschreibt niemals einen vorhandenen Pfad, markiert Skripte als ausführbar und gibt CREATED / LINKED / SKIPPED pro Pfad aus. Verwenden Sie zuerst --dry-run, wenn das Repository bereits Harness-Teile enthält. Lesen Sie für jeden SKIPPED-Pfad die vorhandene Datei und fügen Sie die fehlenden Ideen manuell ein, anstatt die Vorlage zu erzwingen.
Wenn das Skript FAILED-Pfade meldet, schützt die Sandbox Ihres Agenten wahrscheinlich einen Ordner wie .agents/ oder .claude/ (Codex tut dies standardmäßig für .agents/). Führen Sie denselben Befehl mit der Berechtigung erneut aus, die Ihre Umgebung dafür bietet, oder bitten Sie den Benutzer, ihn auszuführen. Verlagern Sie die Skills niemals in einen anderen Ordner, um dies zu umgehen: Agenten entdecken Skills nur in den Ordnern, die sie lesen, daher funktionieren verlagerte Skills stillschweigend nicht mehr.
6. Projektspezifische Details ausfüllen
Alles, was das Grundgerüst nicht wissen kann, müssen Sie schreiben, basierend auf dem, was Sie in den Schritten 2-4 gelesen haben:
harness/config.sh: ein Befehl pro Zeile für jede Ebene (Setup, Statisch, Test, Smoke, E2E), die Base-Branch und die Debug-Muster für den Stack. Lassen Sie eine Ebene nur leer, wenn sie wirklich nicht existiert;verify.shmeldet leere erforderliche Ebenen als UNVERIFIED anstatt als bestanden. Füllen Sie eine Ebene niemals mit einem Befehl, den eine andere Ebene bereits ausführt (z. B. die Integrationstests als „e2e“): Jede Ebene muss Beweise hinzufügen, die die anderen nicht haben. Siehereferences/discovery.md.harness/architecture-rules.json: eine Regel pro Grenze, gemäßreferences/architecture-rules.md. Jede Regel benötigtwhyundfix, die für einen Agenten geschrieben sind, denn die Fehlermeldung ist die Feedbackschleife.- Dokumentation: Erstellen Sie
docs/ARCHITECTURE.md,docs/PRODUCT.md,docs/RELIABILITY.mdnur dort, wo das Repository kein Äquivalent hat, ausgehend vonassets/docs-skeletons/. Schreiben Sie aus dem Code, den Sie gelesen haben, halten Sie jede unter ~150 Zeilen und markieren Sie alles, was Sie nicht bestätigen konnten, alsTODO(confirm): ...anstatt zu raten. Wenn anderswo Äquivalente existieren, verlinken Sie darauf anstatt zu duplizieren. - Entscheidungsaufzeichnungen: Das Grundgerüst fügt
docs/decisions/hinzu. Wenn das Repository bereits ADRs anderswo führt (doc/adr/,docs/adr/), entfernen Sie den neuen Ordner und verweisen Sie inharness/README.md, den Handoff- und Cleanup-Skills und den Vorlagen auf das bestehende. harness/quality-document.md: Listen Sie die tatsächlichen Module mit einer ehrlichen Anfangsnote auf, oderunknown, wenn Sie keine Belege haben. Bewerten Sie niemals nach Bauchgefühl.
7. Einstiegsdatei verdrahten
Fügen Sie den Abschnitt aus assets/snippets/entry-section.md in die Einstiegsdatei ein, nahe dem Anfang oder dem Ende (Modelle erinnern sich besser an die Ränder langer Dateien als an die Mitte). Halten Sie die Einstiegsdatei als Router: Wenn sie über ~200 Zeilen hinauswächst, verschieben Sie Details in docs/ und verlinken Sie darauf.
AGENTS.md ist die kanonische Einstiegsdatei: Die meisten Coding-Agenten lesen sie direkt. Andere Agenten erhalten einen dünnen Zeiger darauf, niemals eine zweite Kopie der Regeln, damit die Dateien nicht auseinanderdriften können.
| Situation | Tun Sie dies |
|---|---|
Weder AGENTS.md noch CLAUDE.md existieren | Erstellen Sie AGENTS.md aus dem Gelernten, plus dem Abschnitt. |
Nur AGENTS.md existiert | Fügen Sie den Abschnitt zu AGENTS.md hinzu. |
Nur CLAUDE.md existiert, das Team verwendet nur Claude Code | Fügen Sie den Abschnitt zu CLAUDE.md hinzu. |
Nur CLAUDE.md existiert, das Team verwendet auch andere Agenten | Fragen Sie vor dem Verschieben: Schlagen Sie vor, den Inhalt nach AGENTS.md zu verschieben und @AGENTS.md in CLAUDE.md zu belassen. Wenn das Team ablehnt, fügen Sie den Abschnitt zu CLAUDE.md hinzu und erstellen Sie AGENTS.md mit dem Abschnitt und einem Link zu CLAUDE.md. |
| Beide existieren | Fügen Sie den Abschnitt zu AGENTS.md hinzu und stellen Sie sicher, dass CLAUDE.md es mit @AGENTS.md importiert. |
Fügen Sie dann den Zeiger für jeden Agenten hinzu, den das Team verwendet und der AGENTS.md nicht standardmäßig liest:
| Agent | Zeiger |
|---|---|
| Claude Code | CLAUDE.md mit @AGENTS.md. Standardmäßig liest Claude Code AGENTS.md nur, wenn keine CLAUDE.md oder CLAUDE.local.md existiert. Ein Repository mit beiden lässt AGENTS.md ohne den Import stillschweigend fallen. |
| Gemini CLI | GEMINI.md mit @AGENTS.md, oder "contextFileName": "AGENTS.md" in .gemini/settings.json. |
Jeder Agent mit eigener Regeldatei bereits im Repository (.github/copilot-instructions.md, .cursor/rules/, .windsurfrules) | Eine Zeile in dieser Datei, die besagt, dass AGENTS.md gelesen werden soll, welches die Regeln enthält. |
Überprüfen Sie das aktuelle Verhalten eines Agenten, bei dem Sie unsicher sind, in seiner eigenen Dokumentation, anstatt zu raten; Agenten ändern, welche Dateien sie lesen.
8. Konfiguration zusammenführen
.gitignore: Fügen Sie die Zeilen ausassets/snippets/gitignore.txtan, die fehlen.- Nur Claude Code,
.claude/settings.json: Führen Sie die Hooks ausassets/adapters/claude-code/settings-hooks.jsonzusammen. Lesen Sie die vorhandene Datei, fügen Sie an vorhandenehooks.SessionStart/hooks.PreToolUse-Arrays an, anstatt sie zu ersetzen, und halten Sie das JSON gültig. Wenn das Team Hooks abgelehnt hat, überspringen Sie dies und löschen Sie die.claude/hooks/, die der Adapter kopiert hat. Das Harness hängt nicht von Hooks ab:feature.pyversiegelt den Aufgabenstatus und weigert sich zu arbeiten, nachdem eine manuelle Bearbeitung stattgefunden hat, und die Einstiegsdatei weist jeden Agenten an, zu Sitzungsbeginninit.shauszuführen. - Nur Claude Code,
.worktreeinclude: Wenn das Projekt git-ignorierte Dateien wie.envzum Ausführen benötigt, listen Sie sie auf, damit jeder von Claude Code erstellte Worktree eine Kopie erhält. Für einfachesgit worktree adderwähnen Sie diese Dateien inharness/README.md, damit Leute sie kopieren.
9. Einmalig beweisen
Führen Sie bash scripts/harness/init.sh und python3 scripts/harness/check_architecture.py aus und berichten Sie das tatsächliche Ergebnis. Wenn etwas aufgrund des Projekts (nicht des Harness) fehlschlägt, sagen Sie dies deutlich und lassen Sie es als ersten Eintrag im Bericht; lockern Sie keine Regel oder löschen Sie keinen Befehl, um es grün zu machen. Führen Sie dann den Frischsitzungs-Test aus references/principles.md durch: Beantworten Sie die fünf Fragen nur mit den Dateien und korrigieren Sie alles, was Sie nicht beantworten können.
10. Berichten
Teilen Sie dem Benutzer kurz mit:
- Was erstellt, was zusammengeführt und was übersprungen wurde, weil es bereits existierte
- Die Befehle pro Ebene und woher jeder stammt
- Jedes
TODO(confirm)und jede Annahme, die Sie getroffen haben - Das Init-/Verifikationsergebnis, einschließlich Fehlschläge
- Wenn dieses Skill selbst im Repository installiert wurde (
.agents/skills/harness-bootstrap/oder ein anderer Skill-Ordner des Agenten, plusskills-lock.json), sagen Sie dies: Das Team benötigt es nach dem Bootstrap nicht mehr, und es kann entfernt oder für eine spätere erneute Ausführung behalten werden. Entfernen Sie es nicht selbst. - Nächster Schritt: Überprüfen und committen Sie das Bootstrap auf einem Branch, starten Sie dann eine Aufgabe mit dem
harness-startSkill (bei Agenten mit Slash-Befehlen/harness-start <TASK-ID>)
Committen oder pushen Sie nicht, es sei denn, der Benutzer fordert es an.
Entwurfsregeln zur Anpassung des Grundgerüsts
- Bevorzugen Sie die vorhandenen Werkzeuge des Projekts. Wenn das Repository ein
Makefilemitmake checkhat, setzen Siemake checkinconfig.shein, anstatt seine Teile neu aufzulisten. - Halten Sie die Laufzeitabhängigkeiten auf
bash,gitundpython3(nur Standardbibliothek). Fügen Sie keine Pakete zum Projekt für das Harness hinzu. - Fehlermeldungen eines jeden Harness-Skripts sagen, was fehlgeschlagen ist, warum und wie es zu beheben ist.
- Nichts Zerstörerisches in Skripten. Cleanup berichtet nur; Menschen oder Agenten handeln aufgrund des Berichts.
- Machen Sie das Harness kleiner, wenn Sie können. Eine Komponente, die das Agentenverhalten in diesem Repository nicht ändert, ist Overhead; sagen Sie dies anstatt sie der Vollständigkeit halber zu installieren.