# AGENTS.md – Verhaltensregeln und Projekt-Historie ## Zweck dieses Dokuments Diese Datei richtet sich an **Coding-Agenten (Claude, Codex u.ä.), die in diesem Repository arbeiten**. Sie definiert Verhaltensregeln (Abschnitt 1) und kurze Projekt-Orientierung (Abschnitt 2). ## TL;DR 1. Erst lesen (Zeilen der Zielstelle nennen), dann ändern. 2. Erst ausführen, dann berichten. Prosa ohne Tool-Call ≠ Ausführung. 3. UI-/Server-Änderung → `./scripts/smoke_test.sh` → Ausgabe zitieren. 4. Nach Refactor: `grep -c ` = 1. Sonst nicht fertig. 5. Doku beschreibt Code, nicht die Arbeit am Code. Details in den Regeln R1–R7 unten. --- ## 1. Verhaltensregeln für Agenten ### 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 – 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 - ein tatsächlich ausgeführter `curl`-/Test-Aufruf zeigt das neue Verhalten. Fehlen diese Belege, ist die Aufgabe nicht erledigt — die Tool-Aufrufe absetzen und erneut prüfen. ### R4 – UI-/Server-Änderungen gegen das laufende System prüfen Bei Änderungen an `web/serve.py` oder `web/index.html`: führe den Smoke-Test aus und zitiere die Ausgabe im Bericht: ```bash ./scripts/smoke_test.sh ``` Das Skript startet den Server temporär auf einem eigenen Port (Default 8082), prüft alle bekannten Endpunkte und räumt sich selbst auf. Du musst nichts über Hintergrund-Jobs, `&`, `nohup` oder Port-Cleanup wissen. Exit-Code 0 = alle 200; sonst 1. Für Änderungen, die der Smoke-Test nicht abdeckt (neuer Endpunkt, geänderte Response, JSON-Edit-Flow im Browser), zusätzlich gezielten `curl`-Aufruf oder Browser-Check ergänzen. „Sieht korrekt aus" ohne ausgeführten Test zählt nicht. ### 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. ### 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. ### 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). --- ## 2. Projekt-Orientierung ### Einstieg ```bash python3 web/serve.py # startet Server auf http://localhost:8081 ./scripts/smoke_test.sh # temporärer Server + Endpunkt-Check + Cleanup (fuer R4) ./scripts/cleanup_server.sh # beendet hängende Instanzen python3 scripts/validate.py # validiert Template-Struktur ``` ### Relevante Pfade | Pfad | Zweck | |-----------------------------|--------------------------------------------------------| | `web/serve.py` | HTTP-Server (Port 8081, GET + PUT) | | `web/index.html` | Single-Page-Frontend | | `web/templates.json` | Katalog (wird als `/templates.json` ausgeliefert) | | `templates/system/*.json` | System-Templates | | `templates/user/*.md` | User-Templates | | `scripts/validate.py` | Template-Validierung | | `docs/` | Weitere technische Dokumentation | | `history/CHANGELOG.md` | Änderungs-Chronik | ### Datenschema `templates.json` und Template-Einträge `web/templates.json` ist eine **Liste** von Einträgen. Schema jedes Eintrags: ```json { "path": "…", "type": "…", "name": "…", "description": "…", "version": "…", "tags": [], "format": "md|json" } ``` Gültige Werte von `type`: **`system`**, **`user`**, **`custom`**. Andere Werte sind tote Pfade — prüfe das, bevor du UI-Elemente oder Filter auf `type` vergleichst (siehe R5). ### Endpunkte | URL | Status | Beschreibung | |--------------------------------------------------|--------|-------------------------------------------| | `GET /` und `GET /index.html` | 200 | Frontend | | `GET /templates.json` | 200 | Katalog (aus `web/templates.json`) | | `GET /templates/system/*.json` | 200 | System-Templates | | `GET /templates/user/*.md` | 200 | User-Templates | | `PUT /templates/...` | 200 | Template speichern (Content-Type `text/*`)| ### Routing-Regel (wichtig, nicht intuitiv) `serve.py` mappt `/templates.json` → `web/templates.json` (der Katalog liegt beim Frontend). Alle anderen `/templates/...`-Pfade mappen auf `/templates/...` (die eigentlichen Templates). --- ## 3. Bekannte Einschränkungen - Der Server ist für **Entwicklung** gedacht: synchron, ohne Auth, ohne Path-Traversal-Prüfung (siehe `docs/SECURITY.md`). - PUT-Endpunkt ist nicht authentifiziert — nur lokal verwenden. --- ## 4. Geplant / TODO Noch nicht umgesetzt — bitte nicht als vorhanden dokumentieren, bevor es wirklich existiert: - [ ] `docs/*.md` inhaltlich ausarbeiten (aktuell nur Stubs). - [ ] `history/` mit strukturierten Protokoll-Einträgen je Release füllen. - [ ] Automatischer Server-Neustart (`systemd` oder `pm2`). - [ ] SSL/HTTPS für Produktionsbetrieb. - [ ] Docker-Containerisierung. - [ ] Path-Traversal-Schutz und Auth für den PUT-Endpoint. --- *Historie: `git log --oneline`. Letzte Aktualisierung: 2026-04-24.*