106 lines
3 KiB
Markdown
106 lines
3 KiB
Markdown
|
# 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.) -->
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
┌──────────────────────────────────────────────────────────┐
|
|||
|
|
│ 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 (gitignored)
|
|||
|
|
│ └── 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
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 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 `history/summary/PROJECT_CONTEXT.md`.
|
|||
|
|
Nach Abschluss einer Aufgabe wird dort der Projektzustand aktualisiert.
|
|||
|
|
|
|||
|
|
- Vollständige Konversationen: `history/prompts/` (committed – History bleibt vollständig erhalten)
|
|||
|
|
- Komprimierter Kontext: `history/summary/PROJECT_CONTEXT.md` (committed)
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## Neues Feature hinzufügen
|
|||
|
|
|
|||
|
|
1. `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 |
|
|||
|
|
|---|---|
|
|||
|
|
| … | … |
|