| # CodingAgent — delegiert bauen, überprüfbar abnehmen |
|
|
| Stand: 2026-09-08. **Grundstein / Arbeitsvertrag v0.1.** Noch kein installierter |
| Workflow und noch kein Nachweis besserer Codequalität. |
|
|
| Samuel arbeitet mit einem Hauptagenten. Dieser macht aus dem gewünschten Verhalten |
| einen begrenzten Auftrag und delegiert die Implementierung an einen Coding-Subagenten, |
| möglichst mit einem günstigen Modell. Eine getrennte Prüfung entscheidet über die |
| technische Abnahmereife. Samuel entscheidet, ob das Ergebnis seinen Zweck erfüllt, |
| und gibt Commit oder Auslieferung ausdrücklich frei. |
|
|
| ## Was wir hier lösen |
|
|
| Delegation soll überprüfbare Änderungen liefern: mit klarer Anforderung, passendem |
| Repo-Kontext, sichtbaren Fehlern und Belegen für das Ergebnis. Ein erfolgreicher |
| Lauf allein reicht dafür nicht. |
|
|
| Die [vorhandene Diagnose](2026-09-08-code-qualitaet.md) ist der Ausgangspunkt. |
| Ihre Bestandszahlen und kausalen Erklärungen wurden für diesen Vertrag nicht erneut |
| verifiziert. Wenige Commits beweisen weder fehlende Nutzung noch schlechte Qualität; |
| die Anzahl breiter Exception-Handler beweist noch kein Fehlerschlucken. |
|
|
| Tests und Review verringern Unsicherheit. Sie garantieren keine Fehlerfreiheit. |
| Eine andere Modellfamilie ist eine mögliche zusätzliche Perspektive, kein Beweis |
| für Unabhängigkeit. Anforderungen und Prüfungen können denselben Irrtum enthalten. |
|
|
| ## Ein Durchlauf, vier Verantwortlichkeiten |
|
|
| | Rolle | Verantwortlich für | Ergebnis | |
| |---|---|---| |
| | Samuel | Gewünschtes Verhalten, Grenzen, fachliche Unklarheiten | Verständliches Erfolgskriterium | |
| | Hauptagent | Repo lesen, bestehende Lösungen finden, Auftrag begrenzen, Belege zusammenführen | Implementierbarer Auftrag und ehrlicher Status | |
| | Coding-Subagent | Implementierung im zugewiesenen Bereich, passende Entwicklertests | Diff und nachvollziehbare Testergebnisse | |
| | Prüfinstanz | Anforderung gegen tatsächlichen Diff und Verhalten prüfen | Befunde und technische Abnahmeempfehlung | |
|
|
| Der Hauptagent bleibt Samuels Ansprechpartner. Er bereitet technische Details vor; |
| Samuel muss keine Agenten auswählen oder Code vollständig gegenlesen. |
| Materielle fachliche Unklarheiten legt der Hauptagent mit einem konkreten Beispiel vor. |
|
|
| ## Vor der Delegation |
|
|
| Der Hauptagent liest die betroffenen Dateien, lokale Instruktionen und vorhandenen |
| Tests. Er sucht nach dem Zweck einer benötigten Funktion, nicht nur ihrem Namen. |
| Bestehende Utilities werden nur wiederverwendet, wenn ihr Verhalten passt. |
|
|
| Pro Änderung entsteht ein kurzer Auftrag, beispielsweise als `task.md` im jeweiligen |
| Arbeitsbereich. Nicht erfüllte Voraussetzungen bleiben ausdrücklich offen: |
|
|
| ```text |
| Ziel: Welches beobachtbare Verhalten soll sich ändern? |
| Erfolgskriterium: Bei [Ausgangslage / Eingabe] geschieht [Ergebnis]. |
| Fehlerfall: Bei [Störung] bleibt [Invariante] erhalten; [Signal] ist sichtbar. |
| Scope: Repo, Ausgangsstand, erlaubte Dateien und ausgeschlossene Änderungen. |
| Kontext: Bestehende Implementierung, passende Utilities, relevante Entscheidungen. |
| Prüfung: Konkrete Befehle und erwartete Beobachtungen; noch fehlende Voraussetzungen. |
| Delegation: Builder-Modell, getrennte Prüfinstanz, begrenztes Laufbudget. |
| ``` |
|
|
| Der Builder darf fachliche Kriterien nicht still ändern, Tests abschwächen oder |
| Fehler in leere Ergebnisse umwandeln, um einen grünen Lauf zu erreichen. |
| Er fängt Fehler nur dort ab, wo ein definiertes Wiederherstellungs- oder |
| Abbruchverhalten existiert. Ein breiter Handler an einer Prozessgrenze kann sinnvoll |
| sein, wenn Fehlerzustand und Folgen sichtbar bleiben. |
|
|
| ## Abnahme ist eine eigene Arbeit |
|
|
| Die Prüfinstanz erhält den Auftrag, den Ausgangsstand und den tatsächlichen Diff. |
| Die Zusammenfassung des Builders dient als Hinweis, nicht als Nachweis. |
| Sie prüft mindestens den relevanten Normalfall und einen risikorelevanten Fehlerfall |
| und liest die betroffenen Übergänge im Code auf Regressionen und unnötige Duplikation. |
|
|
| Bei einer Bugfix-Prüfung soll der Test den Defekt im Ausgangsstand erkennen und mit |
| dem Fix bestehen. Wo dies nicht reproduzierbar ist, wird die Beweisgrenze benannt. |
| Erwartete Ergebnisse folgen aus dem Vertrag, nicht aus dem gerade erzeugten Code. |
|
|
| Prüfbelege enthalten Befehl, Ergebnis und den geprüften Code-Stand. Nach einer |
| Änderung sind betroffene Belege zu erneuern. Fehlende Zugänge, abgebrochene Läufe oder |
| nicht ausgeführte Prüfungen ergeben **ungeprüft / blockiert**, niemals bestanden. |
| Nach einem fehlgeschlagenen Ansatz berichtet der Hauptagent den Befund an Samuel; |
| es gibt keine unbeschränkte Reparatur- oder Modellwechsel-Schleife. |
|
|
| Der Abschluss für Samuel passt in vier Punkte: |
|
|
| 1. Welches Verhalten wurde geändert? |
| 2. Was belegen Tests und getrenntes Review am aktuellen Stand? |
| 3. Welche Unsicherheit oder welcher Befund bleibt offen? |
| 4. Ist die Änderung technisch abnahmereif, und welche Freigabe steht noch aus? |
|
|
| **Implementiert → geprüft → fachlich abgenommen → committed → ausgeliefert** |
| sind getrennte Zustände. Bei laufenden Systemen kommt ein Beleg aus dem tatsächlichen |
| Betrieb hinzu. Ein lokaler Test ersetzt diesen nicht. |
|
|
| ## Gedächtnis im Repo |
|
|
| Der nächste Lauf liest eine kleine, versionierte Orientierung: relevante Einstiegspunkte, |
| wiederverwendbare Bausteine, Invarianten und die maßgeblichen Prüfkommandos. |
| Vorhandene Projektdokumentation wird dafür genutzt. Neue Notizen entstehen nur für |
| Wissen, das sonst verloren geht; Pfad- und Verhaltensangaben werden am Code geprüft. |
| Der Builder schlägt Aktualisierungen vor, die Prüfinstanz kontrolliert sie mit dem Diff. |
|
|
| ## Günstige Modelle: eine zu prüfende Betriebsentscheidung |
|
|
| Ein günstiges Modell erhält einen klar begrenzten Coding-Auftrag. Ein stärkeres Modell |
| kann Zerlegung und Review übernehmen. Die konkrete Modellbelegung bleibt offen, |
| bis Verfügbarkeit und ein echter Auftrag feststehen. |
|
|
| Für den ersten Versuch erfassen wir Modell, Laufzeit, verfügbare Kostenangaben, |
| Nacharbeit und Abnahmebefunde. Entscheidend sind **Gesamtkosten pro abgenommener |
| Änderung**, einschließlich Orchestrierung und Prüfung. Weniger Tokens, weniger Zeilen |
| oder mehr Commits sind allein keine Qualitätsbelege. |
|
|
| ## Der erste Nachweis |
|
|
| Ein einzelner realer, begrenzter Änderungsauftrag durchläuft diese Rollenverteilung. |
| Er ist abgeschlossen, wenn ein prüfbarer Diff, nachvollziehbare Verhaltenstests, |
| ein separates Review und Samuels fachliche Abnahme vorliegen. Erst dieser Versuch |
| zeigt, ob der Ablauf praktikabel ist; ein Kostenvorteil braucht einen vergleichbaren |
| Referenzlauf. Es werden nicht vorsorglich weitere Projekte einbezogen. |
|
|
| Aktuell fehlt noch dieser Pilotauftrag. Der lokale [Ponytail-Checkout](ponytail/README.md) |
| ist vorhandenes Material zur Vermeidung unnötigen Codes; seine Installation und seine |
| Wirkung in diesem Ablauf sind hier nicht nachgewiesen. |
|
|
