Parallele Coding-Agenten mit tmux und Markdown-Spezifikationen

Manuel Schipper betreibt parallele Coding-Agenten mit einem schlanken Setup, das tmux, Markdown-Dateien, Bash-Aliases und sechs Slash-Befehle nutzt. Es handelt sich um Standard-Agenten ohne Subagenten-Profile oder Orchestratoren, die eine Rollenbenennung pro tmux-Fenster verwenden: Planner (erstellt Markdown-Spezifikationen), Worker (implementiert aus fertigen Specs) und PM (Backlog-Pflege und Ideensammlung).

Feature-Design-System

Der größte Teil der Code-Erstellung erfolgt aus fertigen Spezifikationen, die Feature Designs (FDs) genannt werden. Ein FD ist eine Markdown-Datei, die Folgendes enthält:

• Das zu lösende Problem
• Alle in Betracht gezogenen Lösungen mit Vor- und Nachteilen für jede
• Die endgültige Lösung mit Implementierungsplan, einschließlich der zu aktualisierenden Dateien
• Verifizierungsschritte

Nach der Einführung dieses Systems kann Schipper parallel mit 4-8 Agenten arbeiten. Bei mehr als 8 Agenten leidet die Entscheidungsqualität. Das System wurde manuell in einem Projekt mit 300+ Specs aufgebaut und dann mithilfe eines /fd-init-Befehls, der das Setup in jedes Repository bootstrappt, auf neue Projekte übertragen.

FD-Verfolgung und Lebenszyklus

Jedes FD erhält eine nummerierte Spec-Datei (FD-001, FD-002...), die in einem Index über alle FDs hinweg verfolgt wird. Die Dateien befinden sich in docs/features/ und durchlaufen 8 Phasen:

• Geplant: Identifiziert, noch nicht entworfen
• Entwurf: Aktive Lösungsgestaltung
• Offen: Entworfen, bereit zur Implementierung
• In Bearbeitung: Wird derzeit implementiert
• Ausstehende Verifizierung: Code fertig, wartet auf Laufzeitverifizierung
• Abgeschlossen: Verifiziert und funktionsfähig, bereit zum Archivieren
• Zurückgestellt: Auf unbestimmte Zeit verschoben
• Geschlossen: Wird nicht umgesetzt

Slash-Befehle

Sechs Slash-Befehle handhaben den gesamten Lebenszyklus:

• /fd-new: Erstellt ein neues FD aus einer Ideensammlung
• /fd-status: Zeigt den Index an: was aktiv ist, ausstehende Verifizierung und Erledigtes
• /fd-explore: Bootstrappt eine Sitzung: lädt Architekturdokumente, Entwicklerhandbuch, FD-Index
• /fd-deep: Startet 4 parallele Opus-Agenten, um ein schwieriges Designproblem zu erkunden
• /fd-verify: Korrekturlesen von Code, Vorschlag eines Verifizierungsplans, Commit
• /fd-close: Archiviert das FD, aktualisiert den Index, aktualisiert das Changelog

Jeder Commit bezieht sich auf sein FD (z.B. "FD-049: Implementierung des inkrementellen Index-Rebuilds"). Das Changelog sammelt sich automatisch an, wenn FDs abgeschlossen werden.

FD-Dateibeispiel

FD-051: Multi-Label-Dokumentenklassifizierung
Status: Offen
Priorität: Mittel
Aufwand: Mittel
Auswirkung: Bessere Trefferquote für nachgelagerte Filterung

Problem
Eingehende Dokumente erhalten eine einzelne Kategoriebezeichnung, aber viele umfassen mehrere Themen. Nachgelagerte Filter verpassen relevante Dokumente, weil der Klassifikator eine einzige beste Übereinstimmung erzwingt.
Lösung
Ersetze Einzel-Label-Klassifizierung durch Multi-Label:

Nutze ein LLM, um Konfidenzscores pro Kategorie zuzuweisen.
Akzeptiere alle Labels mit einem Score über 0,90.
Für mehrdeutige Scores (0,50-0,90) führe einen zweiten LLM-Durchlauf mit Few-Shot-Beispielen zur Bestätigung durch.
Speichere alle Labels mit Scores, damit nachgelagerte Abfragen flexibel schwellenwertbasiert filtern können.

Zu ändernde Dateien

src/classify/multi_label.py (neu: LLM-basierte Multi-Label-Logik)
src/classify/prompts.py (neu: Few-Shot-Vorlagen für mehrdeutige Fälle)
sql/01_schema.sql (füge document_labels-Tabelle mit Scores hinzu)
sql/06_classify_job.sql (neu: geplante Klassifizierung nach dem Import)

Verifizierung

Führe den Klassifikator auf der Staging-Dokumententabelle aus
Überprüfe, ob keine Fehler im Betriebslog auftreten, führe Gesundheitschecks durch
Stichprobe: Dokumente mit bekanntem Multi-Themen-Inhalt haben erwartete Labels
Führe Tests aus, bestätige, dass nachgelagerte Filter den Konfidenzschwellenwert respektieren

Systeminitialisierung

Ausführung von /fd-init in einem beliebigen Repository:

• Leitet Projektkontext aus CLAUDE.md, Paketkonfigurationen und Git-Log ab
• Erstellt Verzeichnisstruktur (docs/features/, docs/features/archive/)
• Erzeugt eine an das Projekt angepasste FEATURE_INDEX.md
• Erstellt eine FD-Vorlage
• Installiert die sechs Slash-Befehle
• Fügt FD-Lebenszyklus-Konventionen an die CLAUDE.md des Projekts an

Erstellte Dateien umfassen docs/features/FEATURE_INDEX.md (Feature-Index), docs/features/TEMPLATE.md (FD-Dateivorlage), docs/features/archive/ (Archivverzeichnis), CHANGELOG.md (Keep a Changelog-Format) und Aktualisierungen von CLAUDE.md mit Projektkonventionen einschließlich des FD-Systems.