# Maintainer-Handbuch – [PROJEKT_NAME]

> Zielgruppe: **Entwickler & Maintainer** – Menschen, die den Code verstehen, erweitern oder reviewen.
> Voraussetzung: Entwicklungserfahrung mit dem eingesetzten Stack.

---

## Architektur

<!-- TODO: Beschreibe die Architektur (C4, Hexagonal, Event-Driven, etc.) -->

Für Repos mit einem Namen beginnend mit `rd13_` gilt als Grundannahme:

- Der Runner läuft in Docker.
- Alle Services werden über Caddy als Proxy bereitgestellt.
- Die zentrale Proxy-Infrastruktur liegt im Repo `rd13_system_proxy`.

```
┌──────────────────────────────────────────────────────────┐
│  TODO: Architektur-Diagramm (ASCII oder Mermaid)          │
└──────────────────────────────────────────────────────────┘
```

**Wichtige Komponenten:**

| Komponente | Verantwortlichkeit | Ort |
|---|---|---|
| … | … | `src/…` |

---

## Projektstruktur

```
[PROJEKT_NAME]/
├── data/                   ← Persistente Daten (gitignored)
│   └── <service>/          ← Ein Unterordner pro Service
├── docs/
│   ├── USER.md             ← Endnutzer-Dokumentation
│   ├── ADMIN.md            ← Administrator-Dokumentation
│   ├── MAINTAINER.md       ← Dieses Dokument
│   └── history/
│       ├── prompts/        ← Vollständige Agent-Konversationen (committed)
│       └── summary/
│           └── PROJECT_CONTEXT.md ← Aktueller Projektzustand für Agent-Kontext
└── …                       ← Source Code
```

---

## Entwicklungsumgebung aufsetzen

<!-- TODO: Wie richtet man die lokale Entwicklungsumgebung ein? -->

```bash
git clone <repo>
cd <repo>
# Dependencies installieren
# Dev-Server starten
```

> **Default-Shell:** `.github/copilot-instructions.md` enthält im Abschnitt
> *Entwicklungsumgebung* das Feld `- **Default-Shell:**`. Es sagt dem Copilot-Agent,
> welche Shell-Syntax er für Terminal-Kommandos nutzen soll. Beim Bootstrap wird der
> Wert automatisch aus `$SHELL` erkannt; bei abweichender Entwicklungs-Shell den Wert
> dort anpassen.

---

## Architekturentscheidungen (ADRs)

ADR-Dateien liegen unter `docs/adr/`. Format: `NNN-titel.md`.

| Nr. | Titel | Status | Datum |
|---|---|---|---|
| 000 | Template | accepted | … |

---

## Coding-Konventionen

<!-- TODO: Projektspezifische Konventionen -->

- **Branches:** `feat/<ticket>-beschreibung`, `fix/<ticket>-beschreibung`
- **Commits:** Conventional Commits (`feat|fix|chore|docs|refactor|test|ci`)
- **Tests:** `tests/` spiegelt Source-Struktur, ≥ 80% Coverage
- **Linting:** …

---

## Agent-Kontext & History

Der Agent liest beim Start immer `docs/history/summary/PROJECT_CONTEXT.md`.
Nach Abschluss einer Aufgabe wird dort der Projektzustand aktualisiert.

- Vollständige Konversationen: `docs/history/prompts/` (committed – History bleibt vollständig erhalten)
- Komprimierter Kontext: `docs/history/summary/PROJECT_CONTEXT.md` (committed)

---

## Neues Feature hinzufügen

1. `docs/history/summary/PROJECT_CONTEXT.md` lesen – aktuellen Stand verstehen
2. Issue / Ticket anlegen
3. Branch: `git checkout -b feat/<ticket>-beschreibung`
4. Implementieren + Tests schreiben
5. Dokumentation in `docs/USER.md` oder `docs/ADMIN.md` aktualisieren
6. `git commit` – Quality Gate läuft automatisch (pre-commit hook)
7. PR erstellen + Review

---

## Designentscheidungen

| Entscheidung | Begründung |
|---|---|
| … | … |