Conrad Schulz
045e2e7202
- New repo convention: /data/<service>/ for all persistent service data (gitignored) - New repo convention: /history/prompts/ (gitignored) + /history/summary/PROJECT_CONTEXT.md for agent session logging and compressed project context - git-templates/hooks/pre-commit: quality gate checking tests + docs on every commit - git-templates/docs/: USER.md, ADMIN.md, MAINTAINER.md templates (3 target groups) - git-templates/history/summary/PROJECT_CONTEXT.md: agent context template - prompts/history.prompt.md: /history prompt for logging sessions + updating summary - copilot-bootstrap.sh: creates all new folders, .gitignore entries, installs hook - deploy.sh + deploy.fish: deploy hooks, doc templates, history template - docs/ADMIN.md: new admin handbook for this project - docs/USER.md + docs/MAINTAINER.md: updated with new conventions - git-templates/.github/copilot-instructions.md: extended DoD + new conventions - README.md: updated structure overview + prompt table
105 lines
3 KiB
Markdown
105 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/` (gitignored, lokal)
|
||
- 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 |
|
||
|---|---|
|
||
| … | … |
|