CommunityCodierung & Entwicklunggithub.com

Harness-Bootstrap

Installieren Sie ein vollständiges, teamreifes Agenten-Harness in ein beliebiges Git-Repository: eine kurze Eintragsdatei (CLAUDE.md / AGENTS.md), Architektur- und Zuverlässigkeitsdokumente, mehrschichtige Verifikationsskripte, ausführbare Architekturregeln, eine aufgabenbezogene Feature-Liste, deren Status nur ein Verifizierer ändern kann, Sitzungsübergabe- und Fortschrittsdateien (lokal, gitignoriert), eine Checkliste für saubere Zustände, einen unabhängigen Evaluator und Integritätsprüfungen, die alles durchsetzen.

Was ist Harness-Bootstrap?

Dieses Skill richtet ein **Harness** in einem Git-Repository ein – ein Framework, das sicherstellt, dass jeder Coding-Agent (Claude Code, Codex, Cursor, Copilot, Devin, Gemini CLI, Pi, Windsurf, Kiro CLI u.a.) in jeder Sitzung fünf grundlegende Fragen allein aus dem Repository beantworten kann: Was ist das? Wie ist es organisiert? Wie führe ich es aus? Wie verifiziere ich es? Wo haben wir aufgehört? Es ersetzt das Vertrauen auf das Gedächtnis des Agenten durch klare, versionierte Dateien, die das gesamte Team teilt. Der Bootstrap-Prozess analysiert das bestehende Repository (Konfigurationsdateien, CI, Agentenkonfiguration), identifiziert Lücken und installiert dann ein skalierbares Harness bestehend aus: einer kurzen Einstiegsdatei (`AGENTS.md` / `CLAUDE.md`), einer Verifizierungsskriptsammlung (`scripts/harness/`), Architektur- und Entscheidungsdokumentation, einem aufgabenspezifischen Task-Management-Ordner (`.harness/tasks/`), der lokal bleibt (gitignoriert), und Lebenszyklus-Skills (`harness-start`, `harness-handoff`, `harness-cleanup`, `harness-evaluate`), die nach dem Klonen des Repos für alle Agenten verfügbar sind. Das Skill folgt einem strengen 10-Schritte-Workflow: Ziel bestätigen, Bestand ermitteln, Ausführung entdecken, nur über Lücken fragen, Grundgerüst kopieren, projektspezifische Details ausfüllen, Einstiegsdatei verdrahten, Konfiguration zusammenführen (z.B. `.gitignore`, `.claude/settings.json`, `.worktreeinclude`), einmalig beweisen (durch Ausführung der Verifizierungsskripte und einen Sitzungs-Neustarttest) und abschließend einen Bericht liefern. Es überschreibt niemals vorhandene Dateien ohne Rückfrage. Entscheidend ist, dass das Harness einen Vertrag etabliert: Agenten können nicht mehr behaupten, etwas sei erledigt, bevor die Verifizierungsskripte dies bestätigt haben. Die Integritätsprüfungen (`feature.py` stellt sicher, dass der Aufgabenstatus nicht manuell geändert wird) und die Unabhängigkeit des Evaluators stellen sicher, dass „erledigt“ durch Skripte entschieden wird, nicht durch den Agenten. Der gesamte Prozess ist nicht-invasiv und bevorzugt vorhandene Tooling des Projekts (Makefile, CI-Konfiguration).

Funktioniert mit✓Claude Code✓Codex CLI✓Cursor✓Gemini CLI✓OpenCode✓Windsurf
npx skills add https://github.com/Gabriel-Valin/harness-bootstrap/tree/HEAD

Installed? Explore more Codierung & Entwicklung skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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

SchichtWoCommitted?Zweck
EinstiegsdateiCLAUDE.md und/oder AGENTS.mdjaKurze Karte: Was, wie ausführen, wie verifizieren, harte Regeln, Links
Dokumentationdocs/ARCHITECTURE.md, PRODUCT.md, RELIABILITY.md, docs/decisions/jaWissen, das der Agent nicht aus dem Code ableiten kann
Vertragharness/ (Konfiguration, Regeln, Checkliste, Rubrik, Qualitätsdokument, Vorlagen, README)jaGleiche Regeln für alle, nur durch PR änderbar
Verifikationscripts/harness/jainit.sh, verify.sh, feature.py, check_architecture.py, cleanup-scan.sh
Lebenszyklus.agents/skills/harness-*, gespiegelt für Agenten, die einen anderen Ordner lesenjaStarten, Übergeben, Aufräumen, Auswerten
AdapterPro Agent, z. B. .claude/agents/, .claude/hooks/ für Claude CodejaOptionale Extras: Subagent, Hooks
Aufgabenstatus.harness/tasks/<TASK-ID>/neinFeature-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:

  1. 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.sh meldet 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. Siehe references/discovery.md.
  2. harness/architecture-rules.json: eine Regel pro Grenze, gemäß references/architecture-rules.md. Jede Regel benötigt why und fix, die für einen Agenten geschrieben sind, denn die Fehlermeldung ist die Feedbackschleife.
  3. Dokumentation: Erstellen Sie docs/ARCHITECTURE.md, docs/PRODUCT.md, docs/RELIABILITY.md nur dort, wo das Repository kein Äquivalent hat, ausgehend von assets/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, als TODO(confirm): ... anstatt zu raten. Wenn anderswo Äquivalente existieren, verlinken Sie darauf anstatt zu duplizieren.
  4. 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 in harness/README.md, den Handoff- und Cleanup-Skills und den Vorlagen auf das bestehende.
  5. harness/quality-document.md: Listen Sie die tatsächlichen Module mit einer ehrlichen Anfangsnote auf, oder unknown, 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.

SituationTun Sie dies
Weder AGENTS.md noch CLAUDE.md existierenErstellen Sie AGENTS.md aus dem Gelernten, plus dem Abschnitt.
Nur AGENTS.md existiertFügen Sie den Abschnitt zu AGENTS.md hinzu.
Nur CLAUDE.md existiert, das Team verwendet nur Claude CodeFügen Sie den Abschnitt zu CLAUDE.md hinzu.
Nur CLAUDE.md existiert, das Team verwendet auch andere AgentenFragen 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 existierenFü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:

AgentZeiger
Claude CodeCLAUDE.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 CLIGEMINI.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 aus assets/snippets/gitignore.txt an, die fehlen.
  • Nur Claude Code, .claude/settings.json: Führen Sie die Hooks aus assets/adapters/claude-code/settings-hooks.json zusammen. Lesen Sie die vorhandene Datei, fügen Sie an vorhandene hooks.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.py versiegelt den Aufgabenstatus und weigert sich zu arbeiten, nachdem eine manuelle Bearbeitung stattgefunden hat, und die Einstiegsdatei weist jeden Agenten an, zu Sitzungsbeginn init.sh auszuführen.
  • Nur Claude Code, .worktreeinclude: Wenn das Projekt git-ignorierte Dateien wie .env zum Ausführen benötigt, listen Sie sie auf, damit jeder von Claude Code erstellte Worktree eine Kopie erhält. Für einfaches git worktree add erwähnen Sie diese Dateien in harness/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, plus skills-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-start Skill (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 Makefile mit make check hat, setzen Sie make check in config.sh ein, anstatt seine Teile neu aufzulisten.
  • Halten Sie die Laufzeitabhängigkeiten auf bash, git und python3 (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.

Verwandte Skills