Lars
b6de1f15ea
All checks were successful
Deploy Development / deploy (push) Successful in 34s
Test Suite / pytest-backend (push) Successful in 25s
Test Suite / lint-backend (push) Successful in 0s
Test Suite / build-frontend (push) Successful in 7s
Test Suite / playwright-tests (push) Successful in 23s
- Introduced a centralized media archive (`/media`) with lifecycle management, including soft delete and recovery options. - Enhanced media upload functionality to support multiple files and automatic type inference. - Updated documentation to reflect the new media architecture and inline media linking specifications. - Version bump to 0.8.59 to accommodate changes in media handling and database schema. Co-authored-by: Cursor <cursoragent@cursor.com>
79 lines
4.1 KiB
Markdown
79 lines
4.1 KiB
Markdown
# Dokumentation – verbindliche Regeln
|
||
|
||
> **PFLICHTLEKTÜRE** für alle Agenten vor größeren Änderungen (neben `ARCHITECTURE.md`, `CODING_RULES.md`, `LESSONS_LEARNED.md`).
|
||
> Ziel: **ein** nachvollziehbarer Einstieg unter `.claude/`, klare Trennung **fachlich / technisch / Arbeitspapier / Issue**.
|
||
|
||
---
|
||
|
||
## 1. Einstiegspunkte (Reihenfolge)
|
||
|
||
1. Repo-Root: `CLAUDE.md` (Kontext, Links, Pflicht-Dokus)
|
||
2. Agent-Übersicht: **`.claude/README.md`** (Baum, wo was liegt)
|
||
3. Spez-Index: **`.claude/docs/README.md`**
|
||
4. **Session-Handover (aktuelle Prioritäten, Medien-Ist):** **`docs/HANDOVER.md`**
|
||
5. Aufgaben-Tracking: **Gitea** – Übersicht lokal: **`.claude/docs/GITEA_ISSUES_INDEX.md`** (regelmäßig refreshen nach Bedarf)
|
||
|
||
---
|
||
|
||
## 2. Ablagepflicht nach Dokumententyp
|
||
|
||
| Typ | Pfad | Inhalt / Regel |
|
||
|-----|------|----------------|
|
||
| **Fachliche Spec (WAS)** | `.claude/docs/functional/` | Domäne, Use Cases, UX-Ziele, fachliche Datenarchitektur. **Keine** reine API-Parameterliste (→ technical). |
|
||
| **Technische Spec (WIE)** | `.claude/docs/technical/` | API-, DB-, Implementierungsmuster, Agent-Guides, Migrationen. |
|
||
| **Architektur-Querschnitt** | `.claude/docs/architecture/` | Kurze Überblicke (z. B. Frontend-Baum), ergänzend zu technical. |
|
||
| **Arbeitspapier / Zwischenstand** | `.claude/docs/working/` | Analysen, Sessions, Migration-Notizen, **keine** langfristige Norm. Kann veraltet sein → Datum im Dokument. **Nicht** als alleinige „Wahrheit“ für Produkt zitieren. |
|
||
| **Audits & Matrizen** | `.claude/docs/audit/` | Zeitlich begrenzte Reviews, Reconciliation, Gitea-Vorlagen. |
|
||
| **Issue-Begleitung (lang, versioniert im Repo)** | `docs/issues/` | Epics, detaillierte Issue-Ausarbeitungen, Abnahme-Dokus, die mit Gitea-Nummern korrespondieren. **Dateiname:** sinnvoller Slug, z. B. `issue-50-phase-0a-goal-system.md`. |
|
||
| **Governance in `docs/` (aktueller Ausnahmebereich)** | `docs/PLACEHOLDER_*.md` | Platzhalter-Governance & Deployment-Hinweise, solange Pfade in Skripten/Docker auf `docs/` zeigen. Bei Umzug nach `technical/` **alle** Referenzen und Deploy-Pfade anpassen. |
|
||
|
||
---
|
||
|
||
## 3. Verboten / vermeiden
|
||
|
||
- **Keine** vollständige Duplikation derselben Spec an zwei Pflegen (außer kurzer Stub mit Verweis auf Kanon).
|
||
- **Keine** normativen Regeln nur in Chat; Regeln hier oder in `ARCHITECTURE.md` / `CODING_RULES.md` festhalten.
|
||
- **Keine** Mischung „Issue-Checkliste + langfristige Spec“ in einer Datei ohne Überschrift – lieber Spec in `functional|technical`, Checkliste in Gitea oder `docs/issues/`.
|
||
|
||
---
|
||
|
||
## 4. Pflege nach Änderungen
|
||
|
||
| Änderung | Pflege |
|
||
|----------|--------|
|
||
| Neues Feature (> 1–2 Tage) | Spec in `functional/` und ggf. `technical/`; Issue in Gitea; bei Bedarf `docs/issues/issue-NN-….md`. |
|
||
| Neue Endpoints / Tabellen | `technical/API_REFERENCE.md`, `technical/DATABASE.md` bzw. `.claude/library/*` nach Prozess. |
|
||
| Platzhalter (Registry-Pflicht) | `.claude/docs/technical/PLACEHOLDER_REGISTRY_FRAMEWORK.md`, Registrierung unter `backend/placeholder_registrations/`. |
|
||
| Mehrere offene Gitea-Themen | `GITEA_ISSUES_INDEX.md` aktualisieren (Kategorien, Dubletten-Hinweis). |
|
||
|
||
---
|
||
|
||
## 5. Lokale Agent-Artefakte (nicht zwingend im Git)
|
||
|
||
Bleiben unter `.claude/` für Kontinuität der Agenten, werden **standardmäßig nicht** versioniert:
|
||
|
||
- `.claude/task/` – Arbeitspakete pro Thema
|
||
- `.claude/handover/` – Session-Dateien (optional: nur `NEXT_SESSION_PROMPT.md` nach Bedarf versionieren)
|
||
|
||
Diese Ordner sind **kein** Ersatz für `working/` oder `docs/issues/`, wenn das Ergebnis für das Team festgehalten werden soll.
|
||
|
||
---
|
||
|
||
## 6. Kurzreferenz Pfade
|
||
|
||
```
|
||
.claude/README.md ← Einstieg Agent/Human
|
||
.claude/docs/README.md ← Spec-Katalog
|
||
.claude/docs/functional/ ← WAS
|
||
.claude/docs/technical/ ← WIE
|
||
.claude/docs/working/ ← Arbeitspapiere / Analysen
|
||
.claude/docs/audit/ ← Audits
|
||
.claude/docs/GITEA_ISSUES_INDEX.md ← Issue-Landkarte (lokal gepflegt)
|
||
docs/issues/ ← Issue-Epics (Repo)
|
||
docs/PLACEHOLDER_*.md ← Platzhalter (bis Migration der Pfade)
|
||
```
|
||
|
||
---
|
||
|
||
**Version:** 1.0 · **Stand:** 2026-04-08
|