Lars
b2bc8590c4
Some checks failed
Deploy Development / deploy (push) Failing after 4s
Docker & Deployment: - docker-compose.yml (Prod: Port 3003/8003) - docker-compose.dev-env.yml (Dev: Port 3098/8098) - Backend Dockerfile (Python 3.12-slim) - Frontend Dockerfile (Node 20 + Nginx) - Gitea Actions (deploy-dev.yml, deploy-prod.yml) Frontend: - React 18 + Vite setup - package.json, vite.config.js, index.html - App.jsx (minimal with version display) - api.js (complete API client) - app.css + AuthContext from Mitai - main.jsx entry point Backend Migrations: - 001_auth_membership.sql (Auth + Features + Tier Limits) - 002_organization.sql (Clubs, Divisions, Training Groups) - 003_catalogs.sql (Skills + Methods with sample data) Documentation: - .claude/rules/ (ARCHITECTURE, CODING_RULES, etc.) - SHINKAN_PROJECT_SETUP.md (technical setup guide) Server: - Directories created on Pi: /home/lars/docker/shinkan[-dev] - Gitea Runner configured and running Ready for first deployment to dev.shinkan.jinkendo.de version: 0.1.0 date: 2026-04-21
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
|