870d6a2b1d
- serve.py: /templates.json mappt nun auf web/templates.json (GET + PUT).
Zuvor lieferte der Endpoint 404, weil der Handler nach ROOT/templates.json
suchte, die Datei aber in web/ liegt.
- AGENTS.md als Verhaltensregeln fuer Agenten umgebaut (statt defensive
Selbstbehauptung in Projektdoku). Erfundene/nicht existente Artefakte
aus der Doku entfernt, Commit-Tabelle aktualisiert, Tippfehler und
nicht gerenderter date-Ausdruck korrigiert.
- docs/{GETTING_STARTED,ARCHITECTURE,API_REFERENCE,DEPLOYMENT,DEBUGGING,
SECURITY}.md als Stubs angelegt (waren in docs/INDEX.md verlinkt, aber
inexistent).
- history/CHANGELOG.md als Stub angelegt.
- scripts/cleanup_server.sh angelegt (war in AGENTS.md als 'integriert'
beschrieben, fehlte aber).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
115 lines
6.2 KiB
Markdown
115 lines
6.2 KiB
Markdown
# 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 – Änderungen werden ausgeführt, nicht simuliert
|
||
Wenn du Tools wie `read_file`, `search_replace`, `bash`, `git commit` verwendest, führen diese **reale Änderungen** am Dateisystem bzw. Git-Repo durch. Es gibt in diesem Projekt **keinen Trockenmodus**. Plane sorgfältig, bevor du ausführst.
|
||
|
||
### R2 – Nach Plan kommt Ausführung + Verifikation
|
||
Nach einem Plan oder einer Simulation muss die Umsetzung **tatsächlich auf dem Zielsystem** erfolgen und **verifiziert** werden:
|
||
- Server tatsächlich starten (`python3 web/serve.py`)
|
||
- Endpunkte per `curl` oder Browser prüfen
|
||
- Nicht auf „sieht richtig aus" bauen, sondern auf tatsächliches Verhalten.
|
||
|
||
### R3 – 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.
|
||
|
||
### R4 – Keine defensive Selbstdarstellung in Projektdokumenten
|
||
In Projekt-Dokumenten (README, AGENTS.md, docs/…) gehört **kein Meta-Text** à la „alle Änderungen wurden tatsächlich durchgeführt" oder „EXPLIZITES SIMULATIONSVERBOT". Solche Beteuerungen sind kein Projektwissen, sondern Agenten-Selbstverteidigung — sie gehören maximal **hierher** (siehe R1, R2), nicht in technische Dokumente.
|
||
|
||
### R5 – 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/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*
|