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
125 lines
4 KiB
Markdown
125 lines
4 KiB
Markdown
# Benutzerhandbuch – rd13_copilot_setup
|
||
|
||
Dieses Dokument erklärt wie du das Copilot-Setup auf einem neuen System einrichtest und täglich nutzt.
|
||
|
||
---
|
||
|
||
## Ersteinrichtung auf einem neuen System
|
||
|
||
### Schritt 1: Repo klonen
|
||
|
||
```bash
|
||
git clone <repo-url> ~/dotfiles/copilot-setup
|
||
cd ~/dotfiles/copilot-setup
|
||
```
|
||
|
||
### Schritt 2: Deploy-Skript ausführen
|
||
|
||
```bash
|
||
bash scripts/deploy.sh # macOS oder Linux (bash)
|
||
fish scripts/deploy.fish # Linux mit fish-Shell
|
||
```
|
||
|
||
Das Skript erledigt **einmalig** alles automatisch:
|
||
|
||
| Was | Wo |
|
||
|---|---|
|
||
| VS Code User-Settings | `~/.vscode-server/data/User/settings.json` (Remote) / `~/.config/Code/User/` (lokal) |
|
||
| Prompt Files | `~/.vscode-server/data/User/prompts/` |
|
||
| Git-Templates | `~/.git-templates/` |
|
||
| Bootstrap-Skript | `~/.local/bin/copilot-bootstrap.sh` |
|
||
| Git-Alias `init` | `~/.gitconfig` |
|
||
|
||
### Schritt 3: VS Code Settings Sync aktivieren (optional)
|
||
|
||
`Ctrl+Shift+P` → **Settings Sync: Turn On** → Mit GitHub-Account einloggen → Alle Elemente auswählen
|
||
|
||
---
|
||
|
||
## Tägliche Nutzung
|
||
|
||
### Neues Repo anlegen
|
||
|
||
```bash
|
||
git init mein-projekt
|
||
cd mein-projekt
|
||
```
|
||
|
||
Der `git init`-Alias legt automatisch `.github/copilot-instructions.md` und `.vscode/` an. Danach:
|
||
|
||
1. Die `TODO`-Felder in `.github/copilot-instructions.md` ausfüllen
|
||
2. Committen:
|
||
```bash
|
||
git add .github .vscode
|
||
git commit -m "chore: add copilot workspace config"
|
||
```
|
||
|
||
### Bestehendes oder geklontes Repo ausstatten
|
||
|
||
```bash
|
||
cd /pfad/zum/repo
|
||
copilot-bootstrap.sh
|
||
# oder: sh ~/.local/bin/copilot-bootstrap.sh
|
||
```
|
||
|
||
### Prompt Files im Chat nutzen
|
||
|
||
In GitHub Copilot Chat einfach `/` tippen:
|
||
|
||
| Prompt | Wofür |
|
||
|---|---|
|
||
| `/requirements` | Requirements Engineering Workshop |
|
||
| `/architecture` | Architektur-Review + ADR erstellen |
|
||
| `/new-feature` | Vollständiger Feature-Workflow |
|
||
| `/code-review` | Security + Qualitäts-Review |
|
||
| `/debug` | Root-Cause-Analyse + Fix |
|
||
| `/refactor` | Refactoring ohne Behavior-Change |
|
||
| `/write-tests` | Test-Generierung |
|
||
| `/done-check` | Definition of Done Checkliste |
|
||
| `/docker` | Docker/Compose-Aufgaben |
|
||
| `/history` | Agent-History loggen + Kontext-Summary aktualisieren |
|
||
|
||
---
|
||
|
||
## Was jedes neue Repo bekommt
|
||
|
||
Nach `git init` oder `copilot-bootstrap.sh` erhält jedes Repo automatisch:
|
||
|
||
| Was | Wo | Zweck |
|
||
|---|---|---|
|
||
| Copilot-Anweisungen | `.github/copilot-instructions.md` | Agent-Verhalten für dieses Repo |
|
||
| VS Code-Einstellungen | `.vscode/settings.json` | Repo-spezifische Editor-Konfiguration |
|
||
| Empfohlene Extensions | `.vscode/extensions.json` | Extension-Vorschläge für das Team |
|
||
| Persistente Daten | `data/` | Service-Daten getrennt nach Service-Namen |
|
||
| Agent-Logs | `history/prompts/` | Vollständige Konversationen (gitignored) |
|
||
| Agent-Kontext | `history/summary/PROJECT_CONTEXT.md` | Komprimierter Projektzustand für Agenten |
|
||
| Nutzer-Doku | `docs/USER.md` | Dokumentation für Endnutzer |
|
||
| Admin-Doku | `docs/ADMIN.md` | Dokumentation für Administratoren |
|
||
| Entwickler-Doku | `docs/MAINTAINER.md` | Dokumentation für Entwickler |
|
||
| Quality-Gate-Hook | `.git/hooks/pre-commit` | Prüft Tests + Doku bei jedem Commit |
|
||
|
||
---
|
||
|
||
## Häufige Fragen
|
||
|
||
**`copilot-bootstrap.sh: command not found`**
|
||
`~/.local/bin` ist nicht im PATH. Entweder direkt aufrufen: `sh ~/.local/bin/copilot-bootstrap.sh`
|
||
Oder in `~/.bashrc` / `~/.config/fish/config.fish` hinzufügen:
|
||
```bash
|
||
export PATH="$HOME/.local/bin:$PATH" # bash/zsh
|
||
```
|
||
```fish
|
||
fish_add_path ~/.local/bin # fish
|
||
```
|
||
|
||
**`git init` legt keine Copilot-Dateien an**
|
||
Das deploy-Skript wurde noch nicht auf diesem System ausgeführt. Schritt 1+2 wiederholen.
|
||
|
||
**Der pre-commit Hook blockiert meinen Commit**
|
||
Der Hook hat Tests oder Dokumentation vermisst. Optionen:
|
||
- Tests schreiben: Copilot Chat → `/write-tests`
|
||
- Dokumentation aktualisieren: `docs/USER.md`, `docs/ADMIN.md` oder `docs/MAINTAINER.md`
|
||
- Bewusst überspringen: `git commit --no-verify` (bitte sparsam verwenden)
|
||
|
||
**Ich will die Templates aktualisieren**
|
||
Im `rd13_copilot_setup`-Repo die Dateien in `git-templates/` ändern, committen, dann `deploy.sh` erneut ausführen.
|