# 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