5d0194a7b8
Some checks are pending
CI / Lint & self-test (push) Waiting to run
Neues Default-Shell-Feld in der Projekt-Sektion (nach ---), damit der Agent die richtige Shell-Syntax waehlt. Bootstrap erkennt $SHELL (Fallback fish, Whitelist gegen sed-Injection) und schreibt es in frisch erzeugte copilot-instructions.md; manuell aenderbar und ueberlebt copilot-update. selftest +3 Faelle (sh & fish), beide MAINTAINER.md dokumentiert.
117 lines
3.6 KiB
Markdown
117 lines
3.6 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.) -->
|
||
|
||
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 |
|
||
|---|---|
|
||
| … | … |
|