283 lines
12 KiB
Markdown
283 lines
12 KiB
Markdown
# rd13_copilot_setup
|
||
|
||
GitHub Copilot Workspace-Konfiguration für maximale Produktivität – portierbar auf alle Maschinen und Repositories.
|
||
|
||
## Was ist das?
|
||
|
||
Dieses Repo enthält alle Konfigurationsdateien die nötig sind um GitHub Copilot wie ein Team aus Senior-Entwicklern arbeiten zu lassen:
|
||
|
||
- **User-Level Settings** – Copilot-Flags und Senior-Dev-Grundverhalten (per Settings Sync auf alle Geräte)
|
||
- **Prompt Files** – 10 wiederverwendbare Agent-Workflows (`/requirements`, `/new-feature`, `/architecture`, etc.)
|
||
- **Git-Templates** – per Opt-in in ein Repo kopiert (`git init-copilot` oder `copilot-bootstrap.sh`)
|
||
- **Bootstrap-Skript** – bestehende und geclonte Repos in Sekunden ausstatten (POSIX sh, läuft überall)
|
||
- **Update-Mechanismus** – Templates und Prompts in allen Repos mit einem Befehl aktuell halten: `git copilot-update`
|
||
|
||
Für Repos mit einem Namen beginnend mit `rd13_` gilt als allgemeine Infrastruktur-Annahme:
|
||
|
||
- Der Runner läuft in Docker.
|
||
- Alle Services laufen hinter Caddy als Proxy.
|
||
- Die zentrale Proxy-Implementierung liegt im Repo `rd13_system_proxy`.
|
||
|
||
---
|
||
|
||
## Templates aktuell halten – neuer Standard
|
||
|
||
Nach der Ersteinrichtung gibt es einen einzigen Befehl um alle Templates, Prompt-Dateien
|
||
und Git-Hooks in einem Repo auf den neuesten Stand zu bringen:
|
||
|
||
```bash
|
||
git copilot-update
|
||
```
|
||
|
||
Was das macht:
|
||
1. **Setup-Quelle holen** – aus konfiguriertem Remote oder lokalem Klon (`COPILOT_SETUP_DIR`); offline nutzbar
|
||
2. **Globale Templates updaten** – `~/.git-templates/` + VS Code Prompt-Dateien
|
||
3. **Repo-lokale Hooks updaten** – `.git/hooks/pre-commit`
|
||
4. **`copilot-instructions.md`** – nur überschreiben wenn noch TODO-Platzhalter enthalten (Backup `.bak` wird angelegt)
|
||
|
||
Die Remote-Quelle ist **nicht** fest verdrahtet. Konfiguration (Vorrang: Env > Config-Datei):
|
||
|
||
| Variable | Zweck |
|
||
|---|---|
|
||
| `COPILOT_SETUP_REMOTE_SSH` | SSH-URL des Setup-Repos |
|
||
| `COPILOT_SETUP_REMOTE_HTTP` | HTTP-URL (Fallback) |
|
||
| `COPILOT_SETUP_DIR` | Lokaler Klon/Arbeitskopie (Offline-Betrieb) |
|
||
| `COPILOT_SETUP_CONFIG` | Alternativer Pfad zur Config-Datei |
|
||
|
||
Config-Datei (sh-Syntax) unter `~/.config/copilot-setup/config`:
|
||
|
||
```sh
|
||
COPILOT_SETUP_REMOTE_SSH="ssh://git@host:22/you/rd13_copilot_setup.git"
|
||
COPILOT_SETUP_REMOTE_HTTP="https://host/you/rd13_copilot_setup.git"
|
||
```
|
||
|
||
Ist keine Quelle erreichbar, endet `git copilot-update` **ohne Fehler** (graceful skip) –
|
||
es gibt dann nichts zu aktualisieren.
|
||
|
||
> **Empfehlung:** In jedem Repo nach einem `git pull` auf dem Setup-Repo ausführen,
|
||
> oder wenn ein neues Feature-Prompt oder eine Hook-Verbesserung verfügbar ist.
|
||
|
||
### Opt-in: Auto-Deploy für das Setup-Repo selbst
|
||
|
||
Standardmäßig setzt `deploy.sh` **keine** automatischen Hooks. Wer will, dass nach jedem
|
||
`git pull` im Setup-Repo automatisch neu deployt wird:
|
||
```bash
|
||
bash scripts/deploy.sh --with-self-update-hook # installiert post-merge Auto-Deploy
|
||
```
|
||
|
||
### Opt-in: Auto-Update in anderen Repos nach git pull
|
||
|
||
```bash
|
||
copilot-bootstrap.sh --with-update-hook /pfad/zum/repo
|
||
# → installiert post-merge Hook: git pull → git copilot-update
|
||
```
|
||
|
||
---
|
||
|
||
## Schnellstart
|
||
|
||
### Ersteinrichtung (Linux / macOS)
|
||
|
||
```bash
|
||
# 1. Repo klonen
|
||
git clone <this-repo> ~/dotfiles/copilot-setup
|
||
cd ~/dotfiles/copilot-setup
|
||
|
||
# 2. Deploy-Skript ausführen
|
||
bash scripts/deploy.sh # macOS (bash)
|
||
fish scripts/deploy.fish # Linux mit fish
|
||
```
|
||
|
||
Das Skript legt alles an den richtigen Orten ab. Es ist **nicht-invasiv**: es überschreibt
|
||
weder den globalen `git init` noch setzt es `init.templateDir` (fremde `git init`/`git clone`
|
||
bleiben unberührt). Für Auto-Bootstrap eines neuen Repos gibt es den Opt-in-Alias:
|
||
|
||
```bash
|
||
git init-copilot mein-neues-repo # = git init + copilot-bootstrap
|
||
```
|
||
|
||
### Bestehende oder geclonte Repos ausstatten
|
||
|
||
```bash
|
||
cd /path/to/existing-repo
|
||
copilot-bootstrap.sh
|
||
# → legt .github/copilot-instructions.md + .vscode/ + Hooks an, überschreibt nichts
|
||
|
||
# Mit opt-in Auto-Update nach git pull:
|
||
copilot-bootstrap.sh --with-update-hook
|
||
```
|
||
|
||
### VS Code Settings Sync aktivieren (einmalig pro Gerät)
|
||
|
||
`Ctrl+Shift+P` → **Settings Sync: Turn On** → Mit GitHub-Account einloggen → Alle Elemente auswählen
|
||
|
||
---
|
||
|
||
## Struktur
|
||
|
||
```
|
||
rd13_copilot_setup/
|
||
├── user-settings/
|
||
│ └── settings.json ← In ~/.config/Code/User/settings.json (Linux)
|
||
│ oder ~/Library/Application Support/Code/User/ (macOS)
|
||
├── prompts/ ← In VS Code User/prompts/ ablegen (Settings Sync)
|
||
│ ├── requirements.prompt.md /requirements – Requirements Engineering Workshop
|
||
│ ├── architecture.prompt.md /architecture – Architektur-Review + ADR erstellen
|
||
│ ├── new-feature.prompt.md /new-feature – Vollständiger Feature-Workflow
|
||
│ ├── code-review.prompt.md /code-review – Security + Qualitäts-Review
|
||
│ ├── debug.prompt.md /debug – Root-Cause-Analyse + Fix
|
||
│ ├── refactor.prompt.md /refactor – Refactoring ohne Behavior-Change
|
||
│ ├── write-tests.prompt.md /write-tests – Test-Generierung
|
||
│ ├── done-check.prompt.md /done-check – Definition of Done Checkliste
|
||
│ ├── docker.prompt.md /docker – Docker/Compose-Aufgaben
|
||
│ └── history.prompt.md /history – Agent-History loggen + Kontext aktualisieren
|
||
├── git-templates/ ← Quelle für ~/.git-templates (kein globales init.templateDir)
|
||
│ ├── .github/
|
||
│ │ └── copilot-instructions.md ← Template mit TODO-Feldern + Konventionen
|
||
│ ├── .vscode/
|
||
│ │ ├── settings.json
|
||
│ │ └── extensions.json
|
||
│ ├── hooks/
|
||
│ │ ├── pre-commit ← Agent Quality Gate (Tests + Doku-Check)
|
||
│ │ └── post-merge ← Opt-in: copilot-update nach git pull
|
||
│ ├── docs/
|
||
│ │ ├── USER.md ← Template: Endnutzer-Dokumentation
|
||
│ │ ├── ADMIN.md ← Template: Administrator-Dokumentation
|
||
│ │ ├── MAINTAINER.md ← Template: Entwickler-Dokumentation
|
||
│ │ └── history/
|
||
│ │ └── summary/
|
||
│ │ └── PROJECT_CONTEXT.md ← Template: Agent-Kontext-Summary
|
||
├── docs/
|
||
│ ├── USER.md ← Benutzerhandbuch (Einrichtung + Nutzung)
|
||
│ ├── ADMIN.md ← Administrator-Handbuch (Deploy, Hooks, PATH)
|
||
│ └── MAINTAINER.md ← Architektur, Designentscheidungen, Erweiterung
|
||
└── scripts/
|
||
├── deploy.sh ← Deployment-Skript (bash, für macOS + Linux)
|
||
├── deploy.fish ← Deployment-Skript (fish, für Linux)
|
||
├── copilot-bootstrap.sh ← Einzelnes Repo ausstatten (POSIX sh, portabel)
|
||
├── copilot-bootstrap.fish ← Einzelnes Repo ausstatten (fish)
|
||
├── copilot-update.sh ← Templates + Hooks in allen Repos updaten (POSIX sh)
|
||
└── copilot-update.fish ← Templates + Hooks in allen Repos updaten (fish)
|
||
```
|
||
|
||
---
|
||
|
||
## Architektur: 3-Schichten-Modell
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────┐
|
||
│ Layer 1: Immer aktiv (User settings.json) │
|
||
│ • 9 Senior-Dev-Grundregeln in codeGeneration.instructions│
|
||
│ • Commit-Format, Review-Standard, Test-Standard │
|
||
│ • Copilot Feature-Flags │
|
||
├─────────────────────────────────────────────────────────┤
|
||
│ Layer 2: Auf Abruf (Prompt Files) │
|
||
│ • /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) │
|
||
└─────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**Layer 1** gilt automatisch für jede Anfrage ohne Prompt-File.
|
||
**Layer 2** wird per `/prompt-name` im Chat aufgerufen.
|
||
**Layer 3** ist git-tracked, liegt im Repo und wird von Copilot automatisch geladen.
|
||
|
||
---
|
||
|
||
## Was jedes Repo automatisch bekommt
|
||
|
||
Nach `git init-copilot` oder `copilot-bootstrap.sh`:
|
||
|
||
| Was | Wo |
|
||
|---|---|
|
||
| Copilot-Anweisungen + Konventionen | `.github/copilot-instructions.md` |
|
||
| VS Code-Einstellungen | `.vscode/` |
|
||
| **pre-commit Quality Gate** | `.git/hooks/pre-commit` |
|
||
| **Persistente Daten (gitignored)** | `data/` |
|
||
| **Agent-Konversationen (committed)** | `docs/history/prompts/` |
|
||
| **Agent-Kontext-Summary (committed)** | `docs/history/summary/PROJECT_CONTEXT.md` |
|
||
| **Endnutzer-Dokumentation** | `docs/USER.md` |
|
||
| **Administrator-Dokumentation** | `docs/ADMIN.md` |
|
||
| **Entwickler-Dokumentation** | `docs/MAINTAINER.md` |
|
||
|
||
---
|
||
|
||
## Prompt Files – Wann was verwenden
|
||
|
||
| Prompt | Aufruf | Wann verwenden |
|
||
|---|---|---|
|
||
| `requirements` | `/requirements` | Vor dem Start – User Stories, ACs, NFRs erarbeiten |
|
||
| `architecture` | `/architecture` | Bei nicht-trivialen Entscheidungen → ADR erstellen |
|
||
| `new-feature` | `/new-feature` | Feature starten – alle 5 Phasen von Req bis Commit |
|
||
| `code-review` | `/code-review` | Vor dem Merge – OWASP + Qualität + Performance |
|
||
| `debug` | `/debug` | Bug analysieren – Root Cause, kein Symptom-Fix |
|
||
| `refactor` | `/refactor` | Code verbessern ohne Behavior-Change |
|
||
| `write-tests` | `/write-tests` | Test-Coverage-Lücken schließen |
|
||
| `done-check` | `/done-check` | Abnahme-Check vor dem Merge (7-Punkte-Checkliste) |
|
||
| `docker` | `/docker` | Docker/Compose analysieren, debuggen, erweitern |
|
||
| `history` | `/history` | Agent-Session loggen + Kontext-Summary aktualisieren |
|
||
|
||
---
|
||
|
||
## Neues Repo einrichten – Checkliste
|
||
|
||
Mit dem Opt-in-Alias `git init-copilot <pfad>` passiert alles **automatisch**
|
||
(= `git init` + `copilot-bootstrap.sh`). Der Standard-`git init` bleibt unberührt.
|
||
|
||
Nach `git clone` oder für ein bestehendes Repo:
|
||
|
||
```bash
|
||
# Option A: Bootstrap-Skript (empfohlen)
|
||
copilot-bootstrap.sh
|
||
|
||
# Option A+: Mit opt-in Auto-Update-Hook (copilot-update nach jedem git pull)
|
||
copilot-bootstrap.sh --with-update-hook
|
||
|
||
# Option B: Manuell
|
||
mkdir -p .github .vscode
|
||
cp ~/.git-templates/.github/copilot-instructions.md .github/
|
||
cp ~/.git-templates/.vscode/settings.json .vscode/
|
||
cp ~/.git-templates/.vscode/extensions.json .vscode/
|
||
```
|
||
|
||
Danach:
|
||
1. TODO-Felder in `.github/copilot-instructions.md` ausfüllen
|
||
2. `git copilot-update` – stellt sicher dass alle Hooks auf dem neuesten Stand sind
|
||
|
||
→ Detaillierte Anleitungen: [docs/USER.md](docs/USER.md) | [docs/MAINTAINER.md](docs/MAINTAINER.md)
|
||
|
||
---
|
||
|
||
## .github/copilot-instructions.md ausfüllen
|
||
|
||
Die wichtigsten Felder:
|
||
|
||
```markdown
|
||
## Project
|
||
[1-2 Sätze was das Projekt macht]
|
||
|
||
## Stack
|
||
- Language: TypeScript / Python / Go / ...
|
||
- Framework: Next.js / FastAPI / ...
|
||
- Database: PostgreSQL / Redis / ...
|
||
|
||
## Architecture
|
||
- Pattern: Hexagonal / MVC / Event-driven
|
||
- Key constraints: [z.B. "stateless services", "no ORM"]
|
||
|
||
## Conventions
|
||
- Branch: feat/<ticket>-description
|
||
- Commits: Conventional Commits
|
||
- Naming: camelCase functions, PascalCase classes
|
||
|
||
## Non-Functional Requirements
|
||
- Response time: <200ms p95
|
||
- Availability: 99.9%
|
||
```
|
||
|
||
Je mehr Kontext hier steht, desto besser arbeitet Copilot ohne Nachfragen.
|