78 lines
4.1 KiB
Markdown
78 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. 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
|