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):

[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

Datei prompts/mein-workflow.prompt.md anlegen

Format:

---
mode: agent
description: Kurzbeschreibung für den Chat-Slash-Command
---
# Mein Workflow
…

deploy.sh erneut ausführen → deployed die neue Datei in ~/.vscode-server/…/prompts/
In README.md und docs/USER.md in der Prompt-Tabelle eintragen
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

7.7 KiB Raw Blame History Unescape Escape