# 🧩 Namenskonventionen für das KI-Cluster

## 1. Ziel
Diese Richtlinie legt die **einheitlichen Benennungsregeln** für alle Dateien, Klassen, Funktionen, Variablen, Logs, Tests und Ressourcen im gesamten KI-Cluster fest.  
Durch konsequente Namenskonventionen bleibt das System **verständlich, wartbar und maschinenlesbar** — insbesondere für automatisch arbeitende Module wie den Builder-Agent.

---

## 2. Allgemeine Regeln

- Verwende **englische Begriffe** für Code, Funktionsnamen, Klassen und Module.  
  (Nur Dokumentation und Beschreibungen dürfen deutsch sein.)  
- Namen sollen **beschreibend, aber kurz** sein.  
- Keine Umlaute, Leerzeichen oder Sonderzeichen in Dateinamen.  
- Trennzeichen je nach Kontext:  
  - **snake_case** für Dateien, Funktionen und Variablen  
  - **PascalCase** für Klassen  
  - **kebab-case** (Bindestriche) für Konfigurations- oder YAML-Dateien  
  - **UPPER_CASE** für Konstanten  

---

## 3. Dateibenennungen

| Typ | Regel | Beispiel |
|------|--------|-----------|
| Python-Dateien | `snake_case.py` | `logic_core.py`, `api_connector.py` |
| Konfigurationsdateien | `kebab-case.yaml` oder `.json` | `system-config.yaml` |
| Testdateien | `test_<ziel>.py` | `test_router.py` |
| Markdown-Dokumente | `PascalCase.md` | `KomponentenStandardstruktur.md` |
| Logdateien | `<modul>_<datum>.log` | `router_2025-11-12.log` |
| Diagramme/Bilder | `snake_case.png` / `.svg` | `system_flowchart.svg` |

---

## 4. Klassennamen

- Klassen verwenden **PascalCase**.  
- Präfixe dürfen die Art der Klasse kennzeichnen (optional).  
  Beispiele:  
  - `RouterModule`  
  - `APIModule`  
  - `MemoryManager`  
  - `ConfigLoader`  
- Abkürzungen vermeiden, außer sie sind allgemein bekannt (`API`, `UI`, `DB`).

Beispiel:
```python
class RouterModule:
    pass

class MemoryManager:
    pass
```

---

## 5. Funktions- und Methodennamen

- Verwenden **snake_case** (Kleinbuchstaben + Unterstriche).  
- Funktionsnamen beschreiben Aktionen.  
- Wenn eine Funktion boolesche Werte zurückgibt, sollte sie mit `is_`, `has_` oder `can_` beginnen.  
- Methoden innerhalb von Klassen folgen denselben Regeln.

Beispiele:
```python
def load_config():
    pass

def is_connected():
    return True

def send_message(data):
    pass
```

---

## 6. Variablen

- Verwenden **snake_case**.  
- Kurze, aber eindeutige Namen.  
- Keine kryptischen Ein-Buchstaben-Variablen außer in Schleifen (`i`, `j`, `k`).  
- Bei Konstanten **UPPER_CASE**.  

Beispiele:
```python
connection_status = True
user_name = "admin"
MAX_RETRIES = 5
```

---

## 7. Module und Pakete

- Paketnamen immer **kleingeschrieben**.  
- Zusammengesetzte Namen mit Unterstrich trennen.  
- Jeder Unterordner mit `__init__.py` kennzeichnet ein Modulpaket.

Beispielstruktur:
```plaintext
src/
├── api_connector/
│   ├── __init__.py
│   ├── client.py
│   └── handler.py
├── memory_manager/
│   ├── __init__.py
│   ├── database.py
│   └── indexer.py
└── router/
    ├── __init__.py
    └── router_core.py
```

---

## 8. Tests

- Jeder Testdateiname beginnt mit `test_`.  
- Testfunktionen folgen der Regel: `test_<funktion>`  
- Tests dürfen dieselben Bezeichner wie das Zielmodul enthalten.  

Beispiel:
```python
def test_load_config():
    assert load_config() is not None
```

---

## 9. Logging und Ereignisse

- Logdateien folgen dem Schema: `<komponente>_<YYYY-MM-DD>.log`  
- Logmeldungen enthalten Präfixe mit Modul- oder Funktionsname.  

Beispiel:
```python
self.logger.info("[RouterModule] Verbindung aufgebaut.")
self.logger.error("[APIModule] Timeout beim Request.")
```

---

## 10. Konfigurationen & YAML-Schlüssel

- YAML-Schlüssel sind **snake_case**, keine Leerzeichen.  
- Eindeutige Gruppierung durch logische Sektionen.  

Beispiel:
```yaml
system:
  version: 1.2
  language: de
  mode: production

communication:
  router_endpoint: "http://localhost:5000"
  memory_endpoint: "http://localhost:6000"
```

---

## 11. Branch- und Commit-Namen (optional für Git)

| Typ | Format | Beispiel |
|------|--------|-----------|
| Feature | `feature/<beschreibung>` | `feature/router-logging` |
| Fix | `fix/<beschreibung>` | `fix/memory-leak` |
| Dokumentation | `docs/<bereich>` | `docs/code-style` |

Commit-Messages folgen dem Schema:
```
<typ>: <kurze beschreibung>

<optional: längere erklärung>
```

Beispiel:
```
feature: API-Modul erweitert

- Neue Endpunkte für Statusabfragen
- Logging-System verbessert
```

---

## 12. Zusammenfassung

Diese Namenskonventionen gewährleisten:
- Lesbarkeit und Konsistenz im gesamten Projekt  
- Automatische Code-Generierung ohne Konflikte  
- Einfaches Wiedererkennen von Modulen und Funktionen  
- Einheitliches Verhalten in Tests, Logging und Dokumentation

---

© 2025 – KI-Cluster Homelab Architektur  
Autor: *[Dein Name oder Alias]*