/harness – Harness Engineering 最小实践

/harness

Harness Engineering 最小实践. Mit drei Einschränkungen (Inspector, Worker, Reviewer) wird die Kreativität der KI in die richtige Bahn gelenkt – durch ein gemeinsames TODO.md-Kanban für kontinuierliche Verbesserung. Inspiriert von der Harness-Engineering-Methodik: Ein leichtgewichtiger, aber deterministischer Prozessrahmen, der KI-Agenten von „freiem Spiel“ zu „vorhersagbarer Lieferung hochwertiger Ergebnisse“ macht.

Auslösebedingungen

Sofortige Ausführung

• Benutzereingabe /harness – vollständiger Zyklus (Inspector + Worker + Reviewer Loop)
• Benutzereingabe /harness inspect – nur Inspector ausführen
• Benutzereingabe /harness work – nur Worker + Reviewer einmal ausführen
• Benutzereingabe /harness loop – Worker + Reviewer kontinuierlich ausführen, bis keine Aufgaben mehr zu erledigen sind

Der Benutzer kann nach dem Befehl zusätzliche natürliche Anweisungen als Kontext für den aktuellen Zyklus angeben. Z. B.:

• /harness Fokus diesmal auf stillen Datenverlust
• /harness work Repariere zuerst die P0-Umgebungsvariablenprüfung
• /harness inspect Kalibriere nur das aktuelle Skelettziel, führe Worker nicht aus

Zeitgesteuerte Ausführung (Cron)

Nutzt die integrierten Claude-Code-Tools CronCreate / CronDelete / CronList. Durch die native Session-Isolation beeinflussen sich verschiedene Sessions gegenseitig nicht.

Befehl	Beschreibung
/harness cron "*/30 * * * *"	Alle 30 Minuten einen vollständigen Zyklus ausführen
/harness cron "*/30 * * * *" inspect	Alle 30 Minuten nur Inspector ausführen
/harness cron "0 */2 * * *" work	Alle 2 Stunden Worker + Reviewer ausführen
/harness cron "*/15 * * * *" loop	Alle 15 Minuten kontinuierlich Aufgaben abarbeiten
/harness cron list	Alle Harness-Cron-Jobs der aktuellen Session anzeigen
/harness cron stop <job_id>	Bestimmten Cron-Job löschen
/harness cron stop	Alle Harness-Cron-Jobs der aktuellen Session löschen (nach interaktiver Bestätigung einzeln)

Einschränkungen:

• Cron-Jobs sind nur während der Lebensdauer der aktuellen Claude-Code-Session aktiv. Nach Schließen des Terminals verfallen sie.
• Wiederkehrende Jobs laufen maximal 7 Tage.
• Cron-Jobs werden nur im REPL-Idle-Zustand ausgelöst und unterbrechen keine laufenden Gespräche.

Drei-Rollen-Protokoll

Kernprinzip: Ergebnisse validieren

Jede Rolle muss ihre eigenen Ergebnisse validieren – nicht einfach nur „fertig“ melden.

• Inspector: Nach dem Erstellen einer Aufgabe prüfen, ob die Beschreibung klar genug und der Hinweis umsetzbar ist.
• Worker: Nach Codeänderungen die im Projekt definierten Validierungsbefehle ausführen (laut AGENTS.md / CLAUDE.md / TODO.md / README usw.). Wenn das Projekt E2E- oder echte Ablaufvalidierungen definiert, müssen diese ausgeführt und dokumentiert werden.
• Reviewer: Bei der Überprüfung sicherstellen, dass der Worker die relevanten Validierungsbefehle ausgeführt hat. Wenn E2E- oder echte Ablaufvalidierungen existieren und die Änderung diesen Pfad betrifft, muss der Reviewer die Validierung verweigern oder nachholen, falls der Worker sie nicht ausgeführt hat.

E2E-Validierung ist nicht optional. Wenn das Projekt keine spezifischen E2E- oder echten Ablaufvalidierungen hat oder diese aufgrund fehlender externer Abhängigkeiten nicht ausgeführt werden können, muss der Grund explizit dokumentiert werden.

Inspector (Planer)            – Entscheidet über die Richtung, entdeckt Aufgaben
  ↓ Schreibt in TODO.md
TODO.md (Gemeinsames Kanban)
  ↓
Worker (Reparierer)           – Nimmt Aufgaben an, ändert Code
  [Zu vergeben] → [In Bearbeitung] → [Zur Überprüfung]
  ↓
Reviewer (Prüfer)             – Prüft Code, entscheidet gemäß Projektregeln: annehmen oder zurückweisen
  Bestanden → Done Log + (nur wenn erlaubt) git commit
  Nicht bestanden → [Abgelehnt] + Reparaturanleitung
  ↓
Worker kann [Abgelehnt] erneut übernehmen …

Aufgaben-Zustandsautomat

Markierung	Bedeutung	Wer kann ändern
[Zu vergeben]	Nicht übernommen	Inspector kann neu hinzufügen/ändern, Worker kann übernehmen
[In Bearbeitung]	Worker arbeitet daran	Worker setzt beim Übernehmen, andere ändern nicht
[Zur Überprüfung]	Worker fertig	Worker setzt bei Fertigstellung, Reviewer prüft
[Abgelehnt]	Reviewer zurückgewiesen	Reviewer setzt bei Ablehnung, Worker kann erneut übernehmen

Ausführungsschritte

Schritt 1 – Benutzeranweisungen parsen

Aus der Benutzereingabe extrahieren:

1. Cron-Modus: Enthält die Eingabe das Schlüsselwort cron?
2. Modus: cron / inspect / work / loop / full (Standard)
3. Zusätzlicher Kontext: Natürlicher Text nach dem Befehl (falls vorhanden)

Bei Cron-Modus zu Schritt 5 springen. Sonst mit Schritt 2 fortfahren.

Zusätzlichen Kontext in einer temporären Datei speichern:

echo "Zusätzliche Benutzeranweisungen: <vom Benutzer eingegebener natürlicher Text>" > /tmp/harness-context.txt
#   Lebensdauer: Im Full-Modus lesen Inspector und Worker-Reviewer beide davon;
#   Worker-Reviewer löscht die Datei erst am Ende der eigentlichen Übergabe (bei vorzeitigem Abbruch bleibt sie erhalten).

Ohne zusätzlichen Kontext eine leere Datei erstellen (Subprozesse erkennen leere Dateien und injizieren nichts).

Schritt 2 – Projektumgebung prüfen

# Sicherstellen, dass wir im Projektstammverzeichnis sind
test -f TODO.md || echo "NOT_HARNESS_PROJECT"
# Prüfen, ob die Skill-Skripte vorhanden sind (relativ zum Skill-Verzeichnis)
test -f ../harness/inspector.sh && test -f ../harness/worker-reviewer.sh || echo "SCRIPTS_MISSING"

Wenn die Umgebung nicht stimmt, abbrechen und den Benutzer informieren.

Beispielhafte Ausführung:

cd <projekt> && bash ~/.codex/skills/harness/inspector.sh
cd <projekt> && bash ~/.codex/skills/harness/worker-reviewer.sh --loop
HARNESS_PROJECT_DIR=/abs/path/to/project bash ~/.codex/skills/harness/inspector.sh

Falls TODO.md nicht existiert, eine minimale Vorlage erstellen:

# Project Improvement Board

## Current Phase: Initialisierung

## Goals
- [ ] Noch auszufüllen nach erster Inspector-Prüfung

## Done Log

Schritt 3 – Je nach Modus ausführen

Modus: inspect

cd <Projektverzeichnis> && bash <Skill-Verzeichnis>/inspector.sh

Modus: work

cd <Projektverzeichnis> && bash <Skill-Verzeichnis>/worker-reviewer.sh

Modus: loop

cd <Projektverzeichnis> && bash <Skill-Verzeichnis>/worker-reviewer.sh --loop

Modus: full (Standard)

# Phase 1: Inspector-Prüfung
cd <Projektverzeichnis> && bash <Skill-Verzeichnis>/inspector.sh

# Phase 2: Worker+Reviewer-Schleife
cd <Projektverzeichnis> && bash <Skill-Verzeichnis>/worker-reviewer.sh --loop

Schritt 4 – Ergebnisse ausgeben

Nach Abschluss dem Benutzer melden:

Harness-Zyklus abgeschlossen

Inspector:
  - Aktuelles Ziel: ...
  - Architekturbeurteilung: ...
  - Neue/angepasste Aufgaben: N

Worker+Reviewer:
  - Erledigte Aufgaben: N
  - Abgelehnte Aufgaben: N
  - Verbleibende offene Aufgaben: N

Nächster Zyklus: Eingabe /harness zum Fortfahren

Schritt 5 – Cron-Modus (mit integrierten CronCreate/CronDelete/CronList)

5.1 Cron-Job erstellen: /harness cron "<cron_ausdruck>" [modus]

1. Cron-Ausdruck und optionalen Modus (inspect / work / loop / full) parsen.
2. Prompt entsprechend dem Modus erstellen:
   • full: "Harness full cycle ausführen. Nacheinander: 1. cd <projekt_pfad> && bash <skill_pfad>/inspector.sh 2. bash <skill_pfad>/worker-reviewer.sh --loop. Nach Abschluss Ergebnisse melden."
   • inspect: "Harness inspect ausführen. cd <projekt_pfad> && bash <skill_pfad>/inspector.sh ausführen. Nach Abschluss Ergebnisse melden."
   • work: "Harness work ausführen. cd <projekt_pfad> && bash <skill_pfad>/worker-reviewer.sh ausführen. Nach Abschluss Ergebnisse melden."
   • loop: "Harness loop ausführen. cd <projekt_pfad> && bash <skill_pfad>/worker-reviewer.sh --loop ausführen. Nach Abschluss Ergebnisse melden."
3. CronCreate aufrufen mit:
   • cron: Vom Benutzer bereitgestellter Cron-Ausdruck
   • prompt: Oben erstellter Prompt
   • recurring: true
4. Erfolg bestätigen und job_id zurückgeben.

5.2 Cron-Jobs anzeigen: /harness cron list

1. CronList aufrufen, um alle Cron-Jobs der aktuellen Session zu erhalten.
2. Jobs filtern, deren Prompt das Schlüsselwort "harness" enthält.
3. Tabellarisch anzeigen: job_id | Cron-Ausdruck | Modus | Erstellungszeit (falls vorhanden).
4. Wenn keine Harness-Cron-Jobs vorhanden sind, Hinweis: „Keine Harness-Cron-Jobs in der aktuellen Session.“

5.3 Cron-Job löschen: /harness cron stop [job_id]

• Mit job_id: CronDelete aufrufen, um den angegebenen Job zu löschen. Löschung bestätigen.
• Ohne job_id:
  1. CronList aufrufen und Harness-bezogene Jobs filtern.
  2. Dem Benutzer alle zu löschenden Jobs anzeigen.
  3. Nach Bestätigung durch Benutzer jeden Job einzeln mit CronDelete löschen.
  4. Löschergebnis melden.

Subprozess-Eingabemechanismus

Jeder Subprozess (Inspector / Worker / Reviewer) wird über claude -p gestartet. Die Eingabe setzt sich aus drei Teilen zusammen:

1. Rollen-Prompt – z. B. <Skill-Verzeichnis>/prompts/inspector.md
2. Projektdokumentation – Das Skript fügt automatisch Inhalte von AGENTS.md, CLAUDE.md, README, TODO.md usw. zusammen.
3. Zusätzlicher Benutzerkontext – Wird aus /tmp/harness-context.txt gelesen und an das Ende des Prompts angehängt.

Die drei Teile werden zusammengeführt und an claude -p übergeben, sodass der Subprozess sowohl das Gesamtbild des Projekts als auch die spezifische Absicht des Benutzers in diesem Zyklus hat.

Standardmäßig betrachtet das Skript das Arbeitsverzeichnis zum Zeitpunkt des Skriptaufrufs (pwd -P) als Projektverzeichnis. Falls das Skript von einem anderen Ort aufgerufen werden soll, kann das Projektverzeichnis mit HARNESS_PROJECT_DIR=/abs/path/to/project explizit überschrieben werden. Das Skill-Installationsverzeichnis dient nur zum Auffinden von Skripten und Prompts und wird nicht als Projektverzeichnis betrachtet.

Dateiliste

Datei	Verantwortung
prompts/inspector.md	Inspector-Rollen-Prompt
prompts/worker.md	Worker-Rollen-Prompt
prompts/reviewer.md	Reviewer-Rollen-Prompt
inspector.sh	Inspector-Ausführungsskript
worker-reviewer.sh	Worker+Reviewer-Ausführungsskript
TODO.md	Gemeinsames Aufgaben-Kanban (Projektstammverzeichnis)