prompt_template/AGENTS.md

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 <name> = 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:

grep -cE 'function\s+<name>' 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:

./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

python3 web/serve.py          # startet Server auf http://localhost:8081 (Server-Port)
./scripts/smoke_test.sh       # temporärer Server + Endpunkt-Check + Cleanup (fuer R4, Standard-Port 8082)
./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
scripts/cleanup_server.sh	Beendet serve.py auf Port 8081 (Standard) oder angegebenem Port
docs/	Weitere technische Dokumentation

Datenschema templates.json und Template-Einträge

web/templates.json ist eine Liste von Einträgen. path-Felder sind relativ zu ROOT (Projektstamm), OHNE ../ Präfix.

Schema jedes Eintrags:

{ "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 <ROOT>/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.