125 lines
6.3 KiB
Markdown
125 lines
6.3 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 (Tests + Doku-Check)
|
|||
|
|
│ ├── docs/
|
|||
|
|
│ │ ├── USER.md ← Template Endnutzer-Doku
|
|||
|
|
│ │ ├── ADMIN.md ← Template Admin-Doku
|
|||
|
|
│ │ └── MAINTAINER.md ← Template Maintainer-Doku
|
|||
|
|
│ └── history/
|
|||
|
|
│ └── summary/
|
|||
|
|
│ └── PROJECT_CONTEXT.md ← Template Agent-Kontext-Summary
|
|||
|
|
├── prompts/ ← Wiederverwendbare Copilot-Workflows
|
|||
|
|
│ └── *.prompt.md
|
|||
|
|
├── scripts/
|
|||
|
|
│ ├── deploy.sh ← Bash-Deploy (macOS + Linux)
|
|||
|
|
│ ├── deploy.fish ← Fish-Deploy (Linux)
|
|||
|
|
│ ├── copilot-bootstrap.sh ← POSIX-sh Bootstrap für einzelne Repos (Haupt-Script)
|
|||
|
|
│ └── 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/` gitignored | Agent-Logs können groß und vertraulich sein; nur der komprimierte Kontext (summary) wird committed |
|
|||
|
|
| pre-commit Hook als Quality Gate | Automatisches Netz verhindert dass Tests/Doku vergessen werden; `--no-verify` bleibt als bewusstes Escape-Valve |
|