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
124 lines
6.3 KiB
Markdown
124 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 |
|