161 lines
9.5 KiB
Markdown
161 lines
9.5 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) │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
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`.
|
||
|
||
---
|
||
|
||
## 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-bootstrap.fish ← Fish-Variante (voll funktionsgleich)
|
||
│ ├── copilot-update.sh ← Aktualisiert Templates + Hooks in Repos
|
||
│ ├── copilot-update.fish ← Fish-Variante
|
||
│ └── selftest.sh ← CI/lokaler Bootstrap-Dry-Run (sh+fish)
|
||
└── user-settings/
|
||
└── settings.json ← VS Code User-Level Settings (Layer 1)
|
||
```
|
||
|
||
---
|
||
|
||
## Wie `git init-copilot` funktioniert (Opt-in)
|
||
|
||
Git hat keinen `post-init` Hook – `.github/` und `.vscode/` befinden sich im Working Tree, nicht in `.git/`, weshalb `init.templateDir` allein nicht ausreicht. Statt den globalen `git init` zu überschreiben (invasiv – würde auch bei `git clone` fremder Repos greifen), gibt es einen **separaten Opt-in-Alias** `init-copilot`.
|
||
|
||
**Git-Alias mit Rekursionsschutz**
|
||
|
||
In `~/.gitconfig` (wird von deploy.sh/.fish gesetzt):
|
||
```ini
|
||
[alias]
|
||
init-copilot = !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 → **kein Rekursions-Loop**
|
||
- Letztes Nicht-Flag-Argument wird als Zielverzeichnis erkannt (`dir=.` als Default)
|
||
- Nach erfolgreichem `git init` wird `copilot-bootstrap.sh` ausgeführt
|
||
- Der Standard-`git init` bleibt unverändert; frühere invasive `alias.init`/`init.templateDir` werden von deploy.sh gezielt entfernt
|
||
|
||
---
|
||
|
||
## 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.
|
||
|
||
## Shell-Skripte ändern
|
||
|
||
Alle Skripte gibt es paarweise (POSIX/bash + fish) und müssen synchron bleiben:
|
||
`deploy`, `copilot-bootstrap`, `copilot-update`. Die `.sh`-Variante ist jeweils die
|
||
Referenz, die `.fish`-Variante bildet dieselben Schritte in Fish-Syntax ab.
|
||
|
||
CI (`.github/workflows/ci.yml`) prüft bei jedem Push/PR:
|
||
- `shellcheck` für alle `*.sh` + git-Hooks
|
||
- `fish -n` für alle `*.fish`
|
||
- `scripts/selftest.sh` (Bootstrap-Dry-Run sh+fish gegen isoliertes Fake-HOME)
|
||
|
||
Lokal vor dem Commit: `sh scripts/selftest.sh` ausführen.
|
||
|
||
---
|
||
|
||
## 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 |
|
||
| `docs/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 |
|
||
| Kein globales `init.templateDir`, Opt-in `git init-copilot` | Standard-`git init`/`git clone` bleiben unberührt; Quality Gate landet nur in bewusst gewählten Repos |
|
||
| Remote-Quelle konfigurierbar (env/Config) + Offline-Modus | Keine hartkodierte Infrastruktur; `git copilot-update` läuft auch ohne Netz und endet graceful (exit 0) |
|
||
| `detect_vscode_user_dir` in jedem Skript dupliziert | Skripte laufen standalone aus `~/.local/bin` → keine gemeinsame Lib sourcebar; bewusst kopiert statt geteilt |
|
||
|
||
## 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 |
|
||
| `$USER` unbound unter `set -u` | `deploy.sh` nutzt `set -euo pipefail`; `$USER` fehlt in minimalen Envs (`env -i`, CI) | In `detect_vscode_user_dir` `${USER:-}` statt `$USER` |
|
||
| fish: Funktion ändert Skript-Variable nicht | fish-Funktionen sehen Caller-Locals nicht | `set -g` für Zähler/Flags die eine Funktion schreibt (z. B. `_append_gitignore`) |
|