138 lines
7.7 KiB
Markdown
138 lines
7.7 KiB
Markdown
# Maintainer-Handbuch – rd13_copilot_setup
|
||
|
||
Dieses Dokument beschreibt Architektur, Designentscheidungen und wie das Projekt erweitert wird.
|
||
|
||
---
|
||
|
||
## Architektur: 3-Schichten-Modell
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Layer 1: Immer aktiv (User settings.json) │
|
||
│ • Senior-Dev-Grundregeln in codeGeneration.instructions │
|
||
│ • Commit-Format, Review-Standard, Test-Standard │
|
||
│ • Copilot Feature-Flags │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ Layer 2: Auf Abruf (Prompt Files ~/.vscode-server/…) │
|
||
│ • /requirements /architecture /new-feature │
|
||
│ • /code-review /debug /refactor │
|
||
│ • /write-tests /done-check /docker │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ Layer 3: Repo-spezifisch (.github/copilot-instructions) │
|
||
│ • Stack, Konventionen, ADR-Entscheidungen │
|
||
│ • Definition of Done für dieses Projekt │
|
||
│ • NFRs (Performance, Availability, Security) │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
---
|
||
|
||
## Dateistruktur
|
||
|
||
```
|
||
rd13_copilot_setup/
|
||
├── docs/
|
||
│ ├── USER.md ← Endnutzer-Dokumentation
|
||
│ ├── ADMIN.md ← Administrator-Dokumentation (Deploy, Hooks, PATH)
|
||
│ └── MAINTAINER.md ← Dieses Dokument
|
||
├── git-templates/ ← Template-Quellen für neue Repos
|
||
│ ├── .github/
|
||
│ │ └── copilot-instructions.md ← Wird pro Repo individualisiert (TODO-Felder)
|
||
│ ├── .vscode/
|
||
│ │ ├── settings.json ← Repo-spezifische VS Code Einstellungen
|
||
│ │ └── extensions.json ← Empfohlene Extensions für neue Repos
|
||
│ ├── hooks/
|
||
│ │ ├── pre-commit ← Agent Quality Gate (6 Checks)
|
||
│ │ └── post-merge ← Opt-in: copilot-update.sh nach git pull
|
||
│ ├── docs/
|
||
│ │ ├── USER.md ← Template Endnutzer-Doku
|
||
│ │ ├── ADMIN.md ← Template Admin-Doku
|
||
│ │ ├── MAINTAINER.md ← Template Maintainer-Doku
|
||
│ │ └── requirements/
|
||
│ │ └── REQUIREMENTS.md ← Template für persistente Anforderungen
|
||
│ └── history/
|
||
│ └── summary/
|
||
│ └── PROJECT_CONTEXT.md ← Template Agent-Kontext-Summary
|
||
├── prompts/ ← Wiederverwendbare Copilot-Workflows
|
||
│ └── *.prompt.md ← /requirements /history /check-consistency ...
|
||
├── scripts/
|
||
│ ├── deploy.sh ← Bash-Deploy (macOS + Linux)
|
||
│ ├── deploy.fish ← Fish-Deploy (Linux)
|
||
│ ├── copilot-bootstrap.sh ← POSIX-sh Bootstrap für einzelne Repos
|
||
│ ├── copilot-update.sh ← Aktualisiert Templates + Hooks in Repos
|
||
│ └── copilot-bootstrap.fish ← Fish-Variante (legacy, optional)
|
||
└── user-settings/
|
||
└── settings.json ← VS Code User-Level Settings (Layer 1)
|
||
```
|
||
|
||
---
|
||
|
||
## Wie `git init` automatisiert wird
|
||
|
||
Git hat keinen `post-init` Hook – `.github/` und `.vscode/` befinden sich im Working Tree, nicht in `.git/`, weshalb `init.templateDir` allein nicht ausreicht.
|
||
|
||
**Lösung: Git-Alias mit Rekursionsschutz**
|
||
|
||
In `~/.gitconfig` (wird von deploy.sh/.fish gesetzt):
|
||
```ini
|
||
[alias]
|
||
init = !f() { dir=.; for a in "$@"; do case "$a" in -*) ;; *) dir="$a" ;; esac; done; "$(git --exec-path)/git-init" "$@" && "$HOME/.local/bin/copilot-bootstrap.sh" "$dir"; }; f
|
||
```
|
||
|
||
- `!` → externer Shell-Befehl (via `/bin/sh`), kein Git-Subcommand
|
||
- `$(git --exec-path)/git-init` → ruft das echte `git-init`-Binary direkt auf, umgeht den Alias → **kein Rekursions-Loop**
|
||
- Letzte Nicht-Flag-Argument wird als Zielverzeichnis erkannt (`dir=.` als Default)
|
||
- Nach erfolgreichem `git init` wird `copilot-bootstrap.sh` ausgeführt
|
||
|
||
---
|
||
|
||
## Neuen Prompt hinzufügen
|
||
|
||
1. Datei `prompts/mein-workflow.prompt.md` anlegen
|
||
2. Format:
|
||
```markdown
|
||
---
|
||
mode: agent
|
||
description: Kurzbeschreibung für den Chat-Slash-Command
|
||
---
|
||
# Mein Workflow
|
||
…
|
||
```
|
||
3. `deploy.sh` erneut ausführen → deployed die neue Datei in `~/.vscode-server/…/prompts/`
|
||
4. In `README.md` und `docs/USER.md` in der Prompt-Tabelle eintragen
|
||
5. Committen
|
||
|
||
## Template-Dateien ändern
|
||
|
||
Dateien unter `git-templates/` bearbeiten → `deploy.sh` ausführen → neue Repos bekommen die neue Version. Bestehende Repos werden **nicht** automatisch aktualisiert (Bootstrap überschreibt nicht).
|
||
|
||
**Wichtig beim Ändern von `git-templates/hooks/pre-commit`:** Die Datei muss nach dem Deployen ausführbar sein (`chmod +x`). `deploy.sh` erledigt das automatisch.
|
||
|
||
## Deploy-Skripte ändern
|
||
|
||
`deploy.sh` (bash) ist die Referenzimplementierung. `deploy.fish` sollte immer dieselben Schritte in Fish-Syntax abbilden. Nach Änderungen beide synchron halten.
|
||
|
||
---
|
||
|
||
## Designentscheidungen
|
||
|
||
| Entscheidung | Begründung |
|
||
|---|---|
|
||
| POSIX sh für Bootstrap-Script | Läuft auf jedem System ohne extra Dependencies (kein fish nötig) |
|
||
| Git-Alias statt Fish-Wrapper | Portabel: funktioniert in bash, sh, CI, GUI-Clients – nicht nur in fish |
|
||
| `git --exec-path` statt `command git` | `command` umgeht Aliases in fish/zsh, aber nicht in POSIX sh; `--exec-path` ist universell |
|
||
| Templates nicht auto-updaten | Idempotenz: Bootstrap überschreibt nie – Nutzer können Templates nach Init anpassen |
|
||
| 3 Zielgruppen-Docs (USER/ADMIN/MAINTAINER) | Klare Trennung: Nutzer ≠ Ops ≠ Dev; jede Gruppe findet ihren Kontext direkt |
|
||
| `data/` gitignored, Ordner-Struktur tracked | Persistente Daten gehören nie ins Git; Struktur als Konvention dokumentiert |
|
||
| `history/prompts/` committed | Vollständige Agent-History bleibt im Repo erhalten; ermöglicht lückenlose Nachvollziehbarkeit |
|
||
| pre-commit Hook als Quality Gate (6 Checks) | Automatisches Netz: Tests, Doku, 3-Zielgruppen, PROJECT_CONTEXT, Requirements, Session-Datei; Opt-outs via `.copilot-no-tests` / `.copilot-no-docs` / `.copilot-no-requirements` |
|
||
| Check 6: Session-Datei muss in jedem Commit gestaged sein | Jeder Commit ist mit Agent-Session verknüpft; kein Opt-out; erzwingt `/history` vor `git commit` |
|
||
| Check 6 prüft Datum + `### Prompt`-Inhalt | Verhindert reine Nachtrag-Blöcke ohne echte Prompt-Einträge; Session-Datei muss heutiges Datum im Namen tragen |
|
||
|
||
## Bekannte Fallstricke
|
||
|
||
| Problem | Ursache | Fix |
|
||
|---|---|---|
|
||
| `Syntax error: word unexpected` in `copilot-update.sh` Zeile ~60 | Box-Drawing-Zeichen (`────`) direkt ans `fi` angehängt statt auf eigener Zeile | `fi` allein auf Zeile, Kommentar-Linie separat (`# ──`) |
|
||
| Self-Update überschreibt manuell deployten Fix | Self-Update holt Version aus Remote-Cache, der noch kaputten Stand hat | Erst committen + pushen, dann manuell deployen: `cp scripts/copilot-update.sh ~/.local/bin/` |
|
||
| Leerzeile vor `---` in `copilot-instructions.md` wird entfernt | `$(awk ...)` strippt trailing newlines; `printf '%s\n%s\n'` setzt Blöcke direkt zusammen | `printf '%s\n\n%s\n'` verwenden |
|