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:

1. Verhaltensregeln, an die sich Agenten halten müssen,
2. kurze Projekt-Orientierung (Einstieg, Pfade, Ports),
3. die Historie signifikanter Änderungen, soweit sie dokumentationswürdig sind.

---

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: Server starten, betroffene Endpunkte per curl testen, und das Ergebnis im Bericht zitieren. Beispiel:

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8081/templates.json

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

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. Historie signifikanter Änderungen

Autoritative Quelle bleibt git log. Diese Tabelle wird nur für Meilensteine gepflegt, nicht für jeden Commit.

Datum	Commit	Kurzbeschreibung
2026-04-24	97fa30b	fix: WCAG-Kontrast für alle Input-/Textarea-Elemente im JSON-Edit-Modal
2026-04-24	18cc40e	feat: JSON-Edit-Modal nach Schlüssel aufgeteilt + WCAG-Kontrast
2026-04-24	ee1b8f7	fix: JSON-Editor unterstützt Arrays und Objekte via Textarea
2026-04-24	4d9bc9d	docs: Klarstellung zur tatsächlichen Tool-Ausführung
2026-04-24	581b728	docs: Commit-Dokumentation in AGENTS.md ergänzt
2026-04-24	83117d0	feat: Editier-Button in Template-Karten + PUT-Endpoint in serve.py
2026-04-24	8e01dd7	chore: templates.json aktualisiert
2026-04-24	bd7203b	docs: Verifikations- und Evidenzabschnitt
2026-04-24	7a774bb	feat: Port 8081, Template-Pfade korrigiert, brainstorming.md
2026-04-24	cbd48df	docs: docs/INDEX.md angelegt
2026-04-24	d788c27	docs: AGENTS.md mit Dokumentationsverlauf

---

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

---

Letzte Aktualisierung: 2026-04-24