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