mitai-jinkendo/.claude/rules/DOCUMENTATION.md

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