Lars
7940dc7560
- .gitignore: .claude/docs, rules, commands tracken; settings.local weiter ignorieren - DOCUMENTATION.md: verbindliche Ablage functional/technical/working/issues - .claude/README.md: Agent-Einstieg; GITEA_ISSUES_INDEX aus MCP (Stand 2026-04-08) - Arbeitspapiere von docs/ nach .claude/docs/working/ verschoben - docs/MEMBERSHIP_SYSTEM.md als Stub; kanonisch technical/MEMBERSHIP_SYSTEM.md - CLAUDE.md Pflichtlektüre und Links angepasst; docs/README.md vereinfacht Made-with: Cursor
375 lines
14 KiB
Markdown
375 lines
14 KiB
Markdown
# Dokumentations-Bereinigung & Struktur-Konzept
|
|
|
|
**Erstellt:** 2026-03-23
|
|
**Ziel:** Redundanzen entfernen, klare Trennung zwischen Gitea (Tracking) und Docs (Spezifikationen)
|
|
|
|
---
|
|
|
|
## Problem-Analyse
|
|
|
|
### Aktuelle Situation
|
|
|
|
**Planungs-/Tracking-Dokumente (.claude/docs/):**
|
|
- `BACKLOG.md` (~138 Zeilen) - Feature-Übersicht v9c-v9h
|
|
- `ROADMAP.md` (~414 Zeilen) - Detaillierte Phasenplanung (Phase 0-3, Issues #24-#30)
|
|
- `KNOWN_ISSUES.md` (~100+ Zeilen) - Bug-Tracking (BUG-009, BUG-003, etc.)
|
|
- `PENDING_FEATURES.md` (~50+ Zeilen) - Feature-Enforcement-TODOs
|
|
- `TODO_V9D_PHASE2.md` - Spezifische Phase-2-TODOs
|
|
- `ISSUES_TO_CREATE.md` - Temporär (Issues bereits erstellt)
|
|
- `.claude/feature-requests/logout-button-header.md` - Einzelner Feature Request
|
|
|
|
**Spezifikationen:**
|
|
- `functional/` - SLEEP_MODULE.md, TRAINING_TYPES.md, DEVELOPMENT_ROUTES.md, etc.
|
|
- `technical/` - MEMBERSHIP_SYSTEM.md, DATABASE.md, ARCHITECTURE.md, etc.
|
|
- `architecture/` - FEATURE_ENFORCEMENT.md
|
|
- `rules/` - ARCHITECTURE.md, CODING_RULES.md, LESSONS_LEARNED.md
|
|
|
|
### Redundanzen & Probleme
|
|
|
|
1. **Doppeltes Tracking:**
|
|
- ROADMAP.md enthält Issues #24-#30
|
|
- Diese sollten primär in Gitea sein
|
|
- ROADMAP.md enthält außerdem strategische Planung (Phase 0-3)
|
|
|
|
2. **Bug-Tracking außerhalb Gitea:**
|
|
- KNOWN_ISSUES.md dokumentiert Bugs
|
|
- BUG-009 ist offen, sollte als Gitea-Issue existieren
|
|
|
|
3. **Feature-Requests verstreut:**
|
|
- BACKLOG.md listet große Features
|
|
- PENDING_FEATURES.md listet TODOs
|
|
- .claude/feature-requests/ hat einzelne Requests
|
|
- Unklare Prioritäten
|
|
|
|
4. **TODOs ohne Kontext:**
|
|
- TODO_V9D_PHASE2.md ist phasenspezifisch
|
|
- Nach Phase-Abschluss veraltet
|
|
|
|
5. **Temporäre Dateien:**
|
|
- ISSUES_TO_CREATE.md (bereits erledigt, kann weg)
|
|
|
|
---
|
|
|
|
## Vorgeschlagene Struktur
|
|
|
|
### Prinzip: Gitea für Tracking, Docs für Spezifikationen
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ GITEA ISSUES │
|
|
│ (Primäres Tracking für Tasks, Bugs, kleine Features) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ - Konkrete implementierbare Tasks │
|
|
│ - Bugs (BUG-001, BUG-002, ...) │
|
|
│ - Kleine Features (≤ 1 Tag Aufwand) │
|
|
│ - Phase-Tasks (#24-#30) │
|
|
│ - Technical Debt (#32-#35) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ .claude/docs/functional/ │
|
|
│ (Fachliche Spezifikationen für große Features) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ - SLEEP_MODULE.md (v9d) │
|
|
│ - TRAINING_TYPES.md (v9d) │
|
|
│ - DEVELOPMENT_ROUTES.md (v9e) │
|
|
│ - MEDITATION.md (v9g) │
|
|
│ - AI_PROMPTS.md (v9f) │
|
|
│ - GOALS_VITALS.md (v9f) │
|
|
│ - RESPONSIVE_UI.md │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ .claude/docs/technical/ │
|
|
│ (Technische Spezifikationen & Referenz-Dokumentation) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ - ARCHITECTURE.md (System-Übersicht) │
|
|
│ - FRONTEND.md (Seiten, Komponenten, API-Integration) │
|
|
│ - AUTH.md (Auth-Flow, Sicherheit) │
|
|
│ - API_REFERENCE.md (Alle Endpoints) │
|
|
│ - DATABASE.md (Schema, Tabellen) │
|
|
│ - MEMBERSHIP_SYSTEM.md (v9c Membership) │
|
|
│ - MIGRATIONS.md (falls vorhanden) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ .claude/docs/ (Root-Level Meta-Dokumentation) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ - README.md (Dokumentations-Index + Konventionen) │
|
|
│ - CONTRIBUTING.md (Entwickler-Onboarding) │
|
|
│ - CHANGELOG.md (Versions-Historie, generiert aus git) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ .claude/rules/ │
|
|
│ (Verbindliche Entwicklungsregeln) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ - ARCHITECTURE.md (Architektur-Regeln, Versionierung) │
|
|
│ - CODING_RULES.md (Code-Standards) │
|
|
│ - LESSONS_LEARNED.md (Fehler, die nicht wiederholt werden) │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Konkrete Bereinigungsaktionen
|
|
|
|
### 1. LÖSCHEN (Redundant oder temporär)
|
|
|
|
| Datei | Grund | Aktion |
|
|
|-------|-------|--------|
|
|
| `ISSUES_TO_CREATE.md` | Temporär, Issues bereits erstellt (#32-#35) | **DELETE** |
|
|
| `TODO_V9D_PHASE2.md` | Phasenspezifisch, veraltet nach Abschluss | **DELETE** (oder archivieren) |
|
|
| `.claude/feature-requests/logout-button-header.md` | Einzelner Request, gehört in Gitea | **→ Gitea Issue, dann DELETE** |
|
|
|
|
### 2. MIGRIEREN zu Gitea Issues
|
|
|
|
| Quelle | Inhalt | Ziel-Aktion |
|
|
|--------|--------|-------------|
|
|
| `KNOWN_ISSUES.md` | BUG-009 (offen) | **→ Gitea Issue #36** (Bug) |
|
|
| `KNOWN_ISSUES.md` | BUG-003 (behoben) | **→ Archiv oder DELETE** (bereits behoben) |
|
|
| `PENDING_FEATURES.md` | Feature-Enforcement TODOs | **→ Gitea Issues #37-#39** (enhancement) |
|
|
| `feature-requests/logout-button-header.md` | Logout-Button Request | **→ Gitea Issue #40** (Quick Win) |
|
|
|
|
### 3. KONSOLIDIEREN
|
|
|
|
#### 3.1. ROADMAP.md → Aufteilen
|
|
|
|
**Problem:** Enthält sowohl strategische Planung als auch konkrete Issues
|
|
|
|
**Lösung:**
|
|
|
|
**BEHALTEN in ROADMAP.md (strategisch):**
|
|
- Phase-Übersicht (Phase 0-3)
|
|
- Meilensteine (M0.1-M3.x)
|
|
- Abhängigkeiten-Graph
|
|
- Timeline (KW-Planung)
|
|
- Risiken & Mitigationen
|
|
- Erfolgsmetriken
|
|
|
|
**MIGRIEREN zu Gitea (operativ):**
|
|
- Konkrete Issue-Beschreibungen (#24-#30) → Gitea Issues (bereits vorhanden?)
|
|
- Aufwands-Schätzungen → in Gitea Issue-Feldern
|
|
- Checklisten → in Gitea Issue-Beschreibungen
|
|
|
|
**RESULTAT:** ROADMAP.md wird zum strategischen Phasenplan (ohne Issue-Details)
|
|
|
|
#### 3.2. BACKLOG.md → Reduzieren
|
|
|
|
**Problem:** Mischung aus Feature-Übersicht und TODO-Listen
|
|
|
|
**Lösung:**
|
|
|
|
**BEHALTEN in BACKLOG.md:**
|
|
- Version-Übersicht (v9c-v9h Features)
|
|
- Links zu functional/-Specs
|
|
- Status-Übersicht (✅ KOMPLETT, 🟡 In Arbeit, 🔲 Geplant)
|
|
|
|
**ENTFERNEN aus BACKLOG.md:**
|
|
- Detaillierte Checklisten (gehören in Gitea Issues)
|
|
- "Offene Issues" Listen (primär in Gitea)
|
|
- Quick Wins (→ Gitea mit Label "quick-win")
|
|
|
|
**RESULTAT:** BACKLOG.md wird zum Feature-Katalog (Verweis auf Specs + Gitea)
|
|
|
|
#### 3.3. KNOWN_ISSUES.md → Archivieren oder löschen
|
|
|
|
**Vorschlag 1 (empfohlen):** DELETE
|
|
- Aktive Bugs → Gitea Issues
|
|
- Behobene Bugs → git commit messages + CHANGELOG.md
|
|
- Lessons Learned → `.claude/rules/LESSONS_LEARNED.md`
|
|
|
|
**Vorschlag 2:** Archivieren
|
|
- Umbenennen zu `KNOWN_ISSUES_ARCHIVE.md`
|
|
- Nur für Referenz (nicht aktiv gepflegt)
|
|
|
|
#### 3.4. PENDING_FEATURES.md → DELETE
|
|
|
|
**Grund:** Feature-Enforcement-TODOs sind konkrete Tasks
|
|
|
|
**Aktion:**
|
|
1. TODOs in Gitea Issues überführen (#37-#39)
|
|
2. Datei löschen
|
|
|
|
---
|
|
|
|
## Gitea Issues erstellen (aus existierenden Docs)
|
|
|
|
### Aus KNOWN_ISSUES.md
|
|
|
|
**#36: BUG-009 - Trainingstyp-Erstellung führt zu Internal Server Error**
|
|
- Priorität: High
|
|
- Label: bug, admin
|
|
- Aufwand: 1-2h
|
|
|
|
### Aus PENDING_FEATURES.md
|
|
|
|
**#37: Feature-Enforcement für Activity CSV-Import**
|
|
- Priorität: Medium
|
|
- Label: enhancement, feature-enforcement
|
|
- Aufwand: 2-3h
|
|
|
|
**#38: Feature-Enforcement für Nutrition CSV-Import UI**
|
|
- Priorität: Low
|
|
- Label: enhancement, feature-enforcement, ui
|
|
- Aufwand: 1h
|
|
|
|
**#39: Usage-Badges im Dashboard-Assistenten**
|
|
- Priorität: Low
|
|
- Label: enhancement, ux
|
|
- Aufwand: 1-2h
|
|
|
|
### Aus feature-requests/
|
|
|
|
**#40: Logout-Button im App-Header (neben Avatar)**
|
|
- Priorität: Low
|
|
- Label: quick-win, ux
|
|
- Aufwand: 15min
|
|
|
|
---
|
|
|
|
## Vorgeschlagene Konventionen
|
|
|
|
### Was gehört in Gitea Issues?
|
|
|
|
✅ **JA:**
|
|
- Bugs (alle Prioritäten)
|
|
- Konkrete implementierbare Tasks (≤ 5 Tage Aufwand)
|
|
- Quick Wins (≤ 1h Aufwand)
|
|
- Technical Debt Items
|
|
- Phase-spezifische Tasks (#24-#30)
|
|
- Refactorings
|
|
|
|
❌ **NEIN:**
|
|
- Große Feature-Pakete (v9e, v9f, v9g) → bleiben in functional/-Specs
|
|
- Strategische Planung (Phasen, Meilensteine) → bleibt in ROADMAP.md
|
|
- Architektur-Entscheidungen → bleiben in technical/-Docs
|
|
- Lessons Learned → bleiben in rules/LESSONS_LEARNED.md
|
|
|
|
### Was gehört in functional/-Specs?
|
|
|
|
✅ **Große Feature-Pakete (> 5 Tage Aufwand):**
|
|
- SLEEP_MODULE.md (v9d Phase 2b)
|
|
- TRAINING_TYPES.md (v9d Phase 1)
|
|
- DEVELOPMENT_ROUTES.md (v9e)
|
|
- AI_PROMPTS.md (v9f)
|
|
- MEDITATION.md (v9g)
|
|
|
|
**Format:**
|
|
- Fachliche Anforderungen (WAS wird gebaut)
|
|
- User Stories
|
|
- Use Cases
|
|
- Datenmodell (Konzept)
|
|
- UI-Mockups (optional)
|
|
- Verweis auf Gitea Epic/Milestone
|
|
|
|
### Was gehört in technical/-Specs?
|
|
|
|
✅ **Referenz-Dokumentation & Implementierungsdetails:**
|
|
- ARCHITECTURE.md (System-Übersicht)
|
|
- DATABASE.md (Schema-Referenz)
|
|
- API_REFERENCE.md (Endpoint-Katalog)
|
|
- Modul-spezifische Docs (MEMBERSHIP_SYSTEM.md)
|
|
|
|
**Format:**
|
|
- Technische Entscheidungen (WIE wird es gebaut)
|
|
- API-Spezifikationen
|
|
- Datenbank-Schema
|
|
- Code-Beispiele
|
|
- Design-Patterns
|
|
|
|
---
|
|
|
|
## Migrations-Plan
|
|
|
|
### Phase 1: Gitea Issues erstellen (1h)
|
|
|
|
1. **BUG-009** → Gitea Issue #36
|
|
2. **PENDING_FEATURES TODOs** → Gitea Issues #37-#39
|
|
3. **Logout-Button Request** → Gitea Issue #40
|
|
|
|
### Phase 2: Dokumentation bereinigen (30min)
|
|
|
|
1. **DELETE:**
|
|
- `ISSUES_TO_CREATE.md`
|
|
- `TODO_V9D_PHASE2.md`
|
|
- `.claude/feature-requests/logout-button-header.md`
|
|
- `KNOWN_ISSUES.md`
|
|
- `PENDING_FEATURES.md`
|
|
|
|
2. **KONSOLIDIEREN:**
|
|
- `ROADMAP.md` → Entferne Issue-Details, behalte Strategie
|
|
- `BACKLOG.md` → Entferne Checklisten, behalte Feature-Katalog
|
|
|
|
### Phase 3: README.md erstellen (30min)
|
|
|
|
**Datei:** `.claude/docs/README.md`
|
|
|
|
**Inhalt:**
|
|
- Dokumentations-Index (Was finde ich wo?)
|
|
- Konventionen (Gitea vs. Docs)
|
|
- Wie lege ich Issues an?
|
|
- Wie erstelle ich Spezifikationen?
|
|
|
|
---
|
|
|
|
## Ergebnis nach Bereinigung
|
|
|
|
### Datei-Reduktion
|
|
|
|
**Vorher:**
|
|
- 7 Tracking-Dokumente (.claude/docs/)
|
|
- 1 Feature-Request-Datei
|
|
- ~700+ Zeilen redundante Informationen
|
|
|
|
**Nachher:**
|
|
- 2 Meta-Dokumente (ROADMAP.md, BACKLOG.md) - deutlich schlanker
|
|
- 1 README.md (Dokumentations-Index)
|
|
- ~5-7 Gitea Issues (primäres Tracking)
|
|
|
|
### Klare Trennung
|
|
|
|
```
|
|
Gitea Issues (Tracking)
|
|
↓
|
|
Konkrete Tasks, Bugs, Quick Wins
|
|
Labels: bug, enhancement, quick-win
|
|
Aufwand: ≤ 5 Tage
|
|
|
|
.claude/docs/functional/ (Spezifikationen)
|
|
↓
|
|
Große Feature-Pakete (> 5 Tage)
|
|
Format: Fachliche Anforderungen
|
|
Verweis auf Gitea Epic/Milestone
|
|
|
|
.claude/docs/technical/ (Referenz)
|
|
↓
|
|
Implementierungsdetails
|
|
Format: Technische Spezifikationen
|
|
Generiert/aktualisiert nach Implementierung
|
|
|
|
.claude/rules/ (Regeln)
|
|
↓
|
|
Verbindliche Entwicklungsstandards
|
|
Format: Architektur-Regeln, Code-Standards
|
|
```
|
|
|
|
---
|
|
|
|
## Nächste Schritte
|
|
|
|
1. **Review:** User-Zustimmung zu diesem Plan einholen
|
|
2. **Gitea:** Issues #36-#40 anlegen
|
|
3. **Cleanup:** Dateien löschen/konsolidieren
|
|
4. **README:** `.claude/docs/README.md` erstellen
|
|
5. **ROADMAP/BACKLOG:** Kürzen auf strategische Infos
|
|
6. **Commit:** "docs: cleanup and consolidate documentation structure"
|
|
|
|
---
|
|
|
|
**Frage an User:**
|
|
- Sollen große Feature-Pakete (v9e, v9f, v9g) als Gitea **Milestones** angelegt werden?
|
|
- Pro: Alle Tasks/Issues zuordenbar
|
|
- Contra: Specs bleiben trotzdem in functional/
|
|
- **Empfehlung:** Ja, Milestones in Gitea + Verweis in functional/-Specs
|