V4TIME/V4SKILL

Systematischer Agent – Disziplinierte Programmierpraktiken

Wann verwenden

Jede Programmieraufgabe, Modifikation, Debugging-Sitzung oder Implementierungsarbeit. Diese Fähigkeit ist ein grundlegendes Betriebssystem für die Herangehensweise an jede Codeänderung – kein optionales Add-on.

Wird automatisch für alle codebezogenen Aufgaben aufgerufen. Wenn der Benutzer dich bittet, Code zu ändern, hinzuzufügen, zu reparieren oder zu erstellen, befolge diese Fähigkeit.

Kernregeln

1. Niemals Annahmen über das Projekt treffen

Bevor du eine Datei berührst, musst du wissen, was tatsächlich vorhanden ist. Lies die Datei. Überprüfe ihren aktuellen Zustand. Verlasse dich nicht auf die Erinnerung, was „da sein sollte“ – lies sie.

Konkrete Aktionen:

• read_file die Datei, die du ändern wirst, einschließlich umgebendem Kontext
• search_files nach verwandtem Code, Importen, Funktionsaufrufern und Referenzen
• Überprüfe, ob der Server läuft und Endpunkte antworten, bevor du Änderungen testest
• Stelle sicher, dass Konfigurationsdateien tatsächlich das enthalten, was du denkst

2. Relevante Dateien inspizieren, bevor du etwas änderst

Nicht blind patchen. Für jede Datei, die du bearbeiten möchtest:

1. Lies die gesamte Datei (oder den relevanten Abschnitt mit ausreichendem Kontext)
2. Verstehe die aktuelle Struktur, Importe, Abhängigkeiten und Muster
3. Identifiziere, was geändert werden muss und warum
4. Schreibe erst dann den Patch oder die Bearbeitung

Beim Patchen: Füge genügend umgebenden Kontext in old_string ein, um die Übereinstimmung eindeutig zu machen. Ein Patch, der an mehreren Stellen übereinstimmt, wird an der falschen Stelle angewendet.

Beim Lesen großer Dateien: Verwende offset/limit, um schrittweise zu lesen. Versuche nicht, eine 1600-Zeilen-Datei in einem Aufruf zu laden, wenn du nur eine Funktion brauchst – aber LESE die Funktion, die du änderst, vollständig, einschließlich ihrer Signatur und aller Aufrufstellen.

3. Vor der Ausführung einen prägnanten Plan erstellen

Vor jeder nicht-trivialen Programmieraufgabe schreibe einen kurzen Plan (3–7 Aufzählungspunkte), der Folgendes beantwortet:

• Welche Dateien müssen geändert werden
• Was jede Änderung bewirkt (eine Zeile pro Änderung)
• In welcher Reihenfolge die Änderungen erfolgen sollen
• Welche Verifizierungsschritte den Erfolg bestätigen

Beispiel:

Plan:
1. app.py Zeilen 762–770 lesen – _get_hermes_response-Signatur prüfen
2. Parameter image_url: str = None zur Signatur hinzufügen
3. image_url=image_url zu allen 5 _call_api-Aufrufen innerhalb der Funktion hinzufügen
4. image_url von chat() an _get_hermes_response übergeben
5. Server neu starten, mit curl image-Payload testen

Beginne nicht mit dem Programmieren, bevor du den Plan genannt hast. Wenn der Plan falsch ist, wird der Code falsch sein.

4. Tools zur Verifizierung von Behauptungen verwenden, statt zu raten

Jede Behauptung über die Codebasis sollte durch Tool-Ausgaben gestützt werden, nicht durch Erinnerung.

Behauptung	Wie verifizieren
„Datei X hat Funktion Y"	grep -n oder read_file der Datei
„Der Server läuft"	curl des Health-Endpunkts
„Die Änderung funktioniert"	Führe den tatsächlichen Test aus, nimm nichts an
„Der API-Key ist konfiguriert"	Lese storage/apis.json
„Das CSS wird geladen"	curl der statischen Datei, HTTP-Status prüfen
„Der Patch wurde korrekt angewendet"	grep nach dem neuen Text, oder read_file des Bereichs

Schreibe niemals eine Antwort, die sagt „es sollte funktionieren", ohne verifiziert zu haben, dass es tatsächlich tut.

5. Nach jeder wesentlichen Modifikation testen oder das Ergebnis inspizieren

Nach jeder Codeänderung:

1. Syntaxprüfung: python3 -c "import py_compile; py_compile.compile('app.py', doraise=True)" – muss vor dem Neustart bestehen
2. Server neu starten, wenn die Änderung in app.py ist
3. Das geänderte Verhalten testen:
   • Bei API-Änderungen: curl den Endpunkt mit einer repräsentativen Payload
   • Bei Frontend-Änderungen: überprüfen, ob die statische Datei ausgeliefert wird (HTTP 200)
   • Bei Konfigurationsänderungen: die Konfigurationsdatei lesen, um zu bestätigen
4. Die tatsächliche Ausgabe prüfen – nicht das, was du erwartet hast, sondern das, was das Tool zurückgegeben hat

Eine Änderung ist erst abgeschlossen, wenn du das Testergebnis gesehen hast. „Ich denke, es funktioniert" ist keine Verifizierung.

6. Wenn etwas fehlschlägt, den tatsächlichen Fehler diagnostizieren, bevor du einen anderen Ansatz versuchst

Wenn ein Test fehlschlägt oder ein Patch nicht angewendet wird:

1. Lies die tatsächliche Fehlermeldung – kopiere sie wörtlich. Fasse sie nicht zusammen.
2. Identifiziere die Grundursache – was genau ist fehlgeschlagen und warum
3. Bilde eine Hypothese über die Behebung
4. Teste die Hypothese mit einem Tool – versuche nicht einfach einen anderen Patch
5. Wenn der Fix nicht funktioniert, lies den Fehler erneut – er könnte sich geändert haben oder du hast ihn falsch gelesen

Anti-Patterns, die vermieden werden sollten:

• Drei verschiedene Patches hintereinander anwenden, ohne zu prüfen, ob einer funktioniert hat
• Den Fix aufgrund des Fehlertyps erraten, anstatt den Fehlertext zu lesen
• Nicht zusammenhängenden Code ändern, wenn der Fehler an einer bestimmten Stelle liegt
• Den Server neu starten, ohne den Syntaxfehler zu beheben, der ihn am Starten hindert

7. Eine Aufgabe erst dann als abgeschlossen bezeichnen, wenn das Ergebnis verifiziert wurde

Eine Aufgabe ist nur dann abgeschlossen, wenn:

• Die Codeänderung geschrieben und syntaxgeprüft ist ✓
• Der Server mit dem neuen Code läuft ✓
• Das geänderte Verhalten das erwartete Ergebnis liefert (durch Tool-Ausgabe verifiziert) ✓
• Du auf den spezifischen Test/Befehl/die Ausgabe verweisen kannst, die es beweist ✓

Erkläre niemals „erledigt" basierend auf einer erfolgreichen Patch-Anwendung. Ein Patch kann an der falschen Stelle angewendet werden, einen Syntaxfehler einführen oder das Problem tatsächlich nicht beheben. Die Patch-Anwendung ist Schritt 1 der Verifizierung, nicht das Ende.

Verfahren

Für jede Codeänderung:

1. Lesen – inspiziere die Datei(en), die du ändern wirst. Kenne den aktuellen Zustand.
2. Planen – schreibe 3–7 Punkte: welche Änderungen, in welcher Reihenfolge, wie verifizieren.
3. Ändern – nimm die Bearbeitungen vor. Eine atomare Änderung nach der anderen bei Dateiübergreifenden Änderungen.
4. Syntaxprüfung – py_compile oder Äquivalent. Behebe Fehler, bevor du fortfährst.
5. Neu starten – falls der laufende Server den neuen Code benötigt.
6. Testen – curl, ausführen oder inspizieren. Verifiziere, dass das tatsächliche Verhalten der Absicht entspricht.
7. Berichten – gib an, was geändert wurde, was der Test gezeigt hat und ob es verifiziert ist.

Für Debugging:

1. Reproduzieren – erhalte die tatsächliche Fehlerausgabe. Kopiere sie wörtlich.
2. Lokalisieren – finde heraus, wo im Code der Fehler auftritt. grep, read_file, Stacktrace.
3. Verstehen – lies den fehlerhaften Code vollständig. Rate nicht, was er tut – lies ihn.
4. Hypothese aufstellen – welche spezifische Änderung würde diesen spezifischen Fehler beheben?
5. Beheben – nimm die minimale Änderung vor, die die Grundursache adressiert.
6. Verifizieren – führe den fehlgeschlagenen Test erneut aus. Bestätige, dass der Fehler weg ist UND nichts anderes kaputtgegangen ist.
7. Wenn immer noch fehlschlagend – gehe zurück zu Schritt 1. Der Fehler könnte sich geändert haben. Lies ihn erneut.

Für mehrstufige Aufgaben:

• Führe jeweils einen Schritt aus. Verifiziere jeden Schritt, bevor du zum nächsten übergehst.
• Wenn Schritt 3 von der Korrektheit von Schritt 2 abhängt, verifiziere Schritt 2 zuerst.
• Bündle keine unverifizierten Änderungen – wenn Schritt 2 falsch ist, wird Schritt 3s „Behebung" ebenfalls falsch sein.

Fallstricke

• Dieselben Zeilen wiederholt lesen, ohne zu handeln. Wenn du eine Funktion dreimal gelesen hast und sie nicht bearbeitet hast, steckst du fest. Entweder mache die Änderung oder gib an, was dich blockiert.
• Dateiinhalte erraten. Lese immer die Datei. Die Erinnerung, was „da war", ist nach mehreren Patches nicht zuverlässig.
• Syntaxprüfung überspringen. Ein Patch kann sauber angewendet werden und trotzdem die Syntax brechen. Überprüfe immer.
• Testen ohne Neustart. Wenn app.py geändert wurde, hat der laufende Server den alten Code. Starte vor dem Testen neu.
• Erledigt aufgrund von Patch-Erfolg erklären. „Patch angewendet" ≠ „Aufgabe abgeschlossen." Verifiziere das Verhalten.
• Fehlermeldungen nicht lesen. Der Fehlertext sagt dir, was fehlgeschlagen ist. Lies ihn. Leite nicht allein aus dem Fehlertyp ab.
• Übermäßiges Patchen. Wende die minimale Änderung an, die das spezifische Problem behebt. Schreibe keine gesamten Funktionen neu, wenn eine Zeile falsch ist.

Verifizierungs-Checkliste

Bevor du eine Programmieraufgabe als abgeschlossen meldest, bestätige jedes Element:

• Datei(en) vor der Änderung gelesen (aktuellen Zustand kennen)
• Plan geschrieben (welche Änderungen, in welcher Reihenfolge)
• Syntaxprüfung bestanden (py_compile oder Äquivalent)
• Server neu gestartet, wenn app.py geändert wurde
• Test ausgeführt (curl, ausführen oder inspizieren) – tatsächliche Ausgabe gesehen
• Ausgabe entspricht erwartetem Verhalten
• Keine neuen Fehler eingeführt

Wie diese Fähigkeit mit anderen interagiert

• Dies ist eine Grundlagenfähigkeit – sie gilt für ALLE Programmierarbeiten, unabhängig davon, welche andere Fähigkeit aktiv ist
• Wenn test-driven-development aktiv ist, ist TDD die Testmethode; diese Fähigkeit regelt die allgemeine Disziplin
• Wenn systematic-debugging aktiv ist, hat das Debugging sein eigenes detailliertes Verfahren; Regel 6 dieser Fähigkeit gilt dennoch
• Wenn spike aktiv ist (Wegwerfexperiment), gelten die Regeln „prüfe vor Änderung" und „verifiziere nachher" immer noch – Spikes können chaotisch, aber nicht nachlässig sein
• Wenn human-first-ui oder webmxerz für Designarbeit aktiv sind, regelt diese Fähigkeit die Codeänderungen, die das Design umsetzen – Designfähigkeiten geben vor, WAS gebaut werden soll, diese Fähigkeit regelt, WIE man es sicher baut
• Fähigkeiten werden bei Bedarf über skill_view(name) geladen – sie sind KEINE kontinuierlich aktiven Hintergrundprozesse. Eine Fähigkeit ist nur während der Sitzungsdurchgänge, in denen sie geladen wird, im Spiel. Designunterstützungsfähigkeiten (webmxerz, human-first-ui) werden für bestimmte UI-Aufgaben konsultiert; diese Fähigkeit bleibt die Grundlage für die Programmierarbeit, die das Design umsetzt.