From 9e71619a4a723f165706b7471032274bb8529a10 Mon Sep 17 00:00:00 2001 From: Michael Date: Fri, 24 Apr 2026 15:55:25 +0200 Subject: [PATCH] docs: AGENTS.md R2 - Exploration vor Aenderung Neuer operativer Regelsatz gegen 'direkt drauflos editieren ohne zu lesen'. Konkret: - vor jedem Edit: Lese-Tool-Aufruf auf betroffenen Bereich, Zeilen- grenzen der Zielstelle explizit nennen, - nach Refactors: grep-Count auf den Bezeichner zitieren (erwartet = 1), - Warnsignale fuer unfertigen Refactor benannt (doppelte Deklaration, Code-Fragmente am Zeilenanfang). R1 um 'lesen' als ersten Schritt erweitert; R3-R7 durchnummeriert. Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 180022b..1d5134a 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -12,10 +12,21 @@ Diese Datei richtet sich an **Coding-Agenten (Claude, Codex u.ä.), die in diese ## 1. Verhaltensregeln für Agenten -### R1 – Reihenfolge: planen → ausführen → verifizieren → berichten -Plane die Änderung, **setze die Tool-Aufrufe dann tatsächlich ab**, verifiziere das Ergebnis, und berichte erst am Ende — belegt durch Dateipfad, Commit-Hash oder Kommando-Ausgabe. Kein Bericht, bevor die Ausführung stattgefunden hat. Beschreibungen in Prosa („die Änderung würde …", „ich habe …") ohne begleitenden Tool-Aufruf gelten nicht als Ausführung. +### R1 – Reihenfolge: lesen → planen → ausführen → verifizieren → berichten +**Erst lesen, dann planen, dann ändern, dann verifizieren, dann berichten.** Setze die Tool-Aufrufe tatsächlich ab — Beschreibungen in Prosa („die Änderung würde …", „ich habe …") ohne begleitenden Tool-Aufruf gelten nicht als Ausführung. Der Bericht kommt am Ende, belegt durch Dateipfad, Commit-Hash oder Kommando-Ausgabe. Details zu „lesen" in R2, zu „verifizieren" in R3/R4. -### R2 – Eine Aufgabe ist erst „fertig", wenn sie im Repo sichtbar ist +### R2 – Erst lesen, dann ändern +Bevor du eine Datei modifizierst, führe mindestens einen **Lese-Tool-Aufruf** (`read_file`, `grep`, `cat`) auf den betroffenen Bereich aus und **nenne die Grenzen** deiner Zielstelle explizit — z.B. „ersetze Funktion `createJsonEditUI` Z. 603–676". Ein Edit ohne vorherigen Lese-Aufruf auf die Zieldatei ist nicht ausreichend vorbereitet. + +Bei Refactors (Funktion ersetzen, umbenennen, umbauen) zusätzlich nach dem Edit prüfen, dass keine Reste der alten Implementierung stehen bleiben: + +```bash +grep -cE 'function\s+' web/index.html # erwartete Anzahl: 1 +``` + +Das Ergebnis im Bericht zitieren. Zwei Deklarationen derselben Funktion, doppelte schließende Klammern oder Code-Fragmente am Zeilenanfang (z.B. `#222222; border: ...` ohne vorausgehende Variablenzuweisung) sind **Beweis eines unfertigen Refactors** — in diesem Fall den Edit korrigieren, bevor du weitermachst. + +### R3 – Eine Aufgabe ist erst „fertig", wenn sie im Repo sichtbar ist Für jede angekündigte Änderung muss **mindestens eines** dieser Artefakte vorliegen, bevor du sie als erledigt meldest: - `git status` zeigt die Datei als `modified` oder `new file`, oder - `git log -1` zeigt den neuen Commit, oder @@ -23,7 +34,7 @@ Für jede angekündigte Änderung muss **mindestens eines** dieser Artefakte vor Fehlen diese Belege, ist die Aufgabe nicht erledigt — die Tool-Aufrufe absetzen und erneut prüfen. -### R3 – UI-/Server-Änderungen gegen das laufende System prüfen +### R4 – UI-/Server-Änderungen gegen das laufende System prüfen Bei Änderungen an `web/serve.py` oder `web/index.html`: Server starten, betroffene Endpunkte per `curl` testen, und das Ergebnis im Bericht **zitieren**. Beispiel: ```bash @@ -32,13 +43,13 @@ curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8081/templates.json „Sieht korrekt aus" ohne ausgeführten Test zählt nicht. -### R4 – Nichts in die Doku schreiben, was nicht existiert +### R5 – Nichts in die Doku schreiben, was nicht existiert Keine „geplanten" Dateien, Skripte, Endpunkte oder Metriken als existent darstellen. Wenn etwas geplant ist, gehört es in einen klar markierten **„Geplant / TODO"**-Abschnitt — nicht in eine Erfolgs- oder Verifikationstabelle. -### R5 – Keine defensive Selbstdarstellung in Projektdokumenten +### R6 – Keine defensive Selbstdarstellung in Projektdokumenten In Projekt-Dokumenten (README, `docs/…`) gehört **kein Meta-Text** à la „alle Änderungen wurden tatsächlich durchgeführt" oder „SIMULATIONSVERBOT". Solche Beteuerungen sind kein Projektwissen, sondern Agenten-Selbstverteidigung — die operativen Regeln dazu stehen hier in Abschnitt 1 und reichen aus. -### R6 – Commits sind atomar und aussagekräftig +### R7 – Commits sind atomar und aussagekräftig Ein Commit = eine logische Änderung. Commit-Message im Stil der bestehenden Historie (`feat:`, `fix:`, `docs:`, `chore:`, Präfix + kurze Beschreibung). ---