647c0f8b9e
Some checks are pending
CI / Lint & self-test (push) Waiting to run
Passives Default-Shell-Feld reichte nicht: Agent tippte weiter POSIX (VAR=$(...)) in eine fish-Shell. Neue MANDATORY-Sektion 'Terminal-Syntax' in der Framework-Sektion beider copilot-instructions.md mit exaktem Fehlerbild und deterministischem Ausweg (nicht-triviale Logik in .sh mit Shebang, bash datei.sh). Memory-Notiz shell-syntax.md ergaenzt. History + PROJECT_CONTEXT aktualisiert.
202 lines
9.7 KiB
Markdown
202 lines
9.7 KiB
Markdown
# GitHub Copilot – Project Instructions
|
||
|
||
## ⚡ Agent Session Protocol (MANDATORY)
|
||
|
||
> Diese Sektion hat höchste Priorität und darf nicht ignoriert werden.
|
||
|
||
**Session START** – Bevor du irgendetwas tust:
|
||
1. Lies `docs/history/summary/PROJECT_CONTEXT.md` (falls vorhanden)
|
||
2. Verstehe den aktuellen Projektzustand bevor du anfängst
|
||
|
||
**Session END** – Der Agent führt dies **automatisch** am Ende jeder Aufgabe aus, bevor er `git commit` ausführt:
|
||
1. Lies die bestehende `docs/history/prompts/YYYY-MM-DD_*_session.md` (falls vorhanden) und ergänze nur den neuen Teil
|
||
**Dateiformat zwingend:** Suffix `_session.md`, Dateiname beginnt mit heutigem Datum (`YYYY-MM-DD`)
|
||
2. **Für jeden Benutzer-Prompt seit dem letzten Commit** einen Block ergänzen:
|
||
```
|
||
### Prompt N
|
||
«wörtlicher Benutzertext – exakt, kein Paraphrasieren»
|
||
|
||
### Antwort N
|
||
«Was getan wurde + alle ausgeführten Kommandos im Code-Block + relevante Terminal-Outputs»
|
||
```
|
||
⚠ Kein „Nachtrag"-Block statt echter Prompt-Einträge. Die Benutzer-Nachricht **wörtlich** zitieren.
|
||
⚠ Keine reinen Stichpunkt-Zusammenfassungen. Ausgeführte Kommandos und Outputs gehören **wörtlich** in die Antwort.
|
||
⚠ Keine Platzhalter wie `PENDING` committen. Ist der Commit-Hash noch unbekannt: Hash weglassen oder Datei direkt nach dem Commit mit dem echten Hash aktualisieren und sofort (`git add docs/history/ && git commit`) nachziehen.
|
||
3. Aktualisiere `docs/history/summary/PROJECT_CONTEXT.md` mit dem neuen Projektstand
|
||
4. **Stage beide Dateien VOR `git commit`:** `git add docs/history/`
|
||
Der pre-commit Hook (Check 6) blockiert wenn:
|
||
- keine `*_session.md` gestaged ist
|
||
- der Dateiname nicht mit dem heutigen Datum beginnt
|
||
- die Datei keinen einzigen `### Prompt`-Eintrag enthält
|
||
|
||
> Kein Bypass. Kein Vergessen. Kein "mache ich beim nächsten Mal".
|
||
> Die History ist das Gedächtnis des Projekts.
|
||
> **Der Agent wartet nicht auf expliziten `/history`-Aufruf – er führt es automatisch vor jedem Commit aus.**
|
||
|
||
## ⛔ Verbotene Aktionen (NIEMALS ausführen)
|
||
|
||
- **`git commit --no-verify`** – Der pre-commit Quality Gate darf NIEMALS umgangen werden.
|
||
Wenn der Hook fehlschlägt: Problem beheben (Tests schreiben, Doku aktualisieren, Context aktualisieren).
|
||
Einzige Ausnahme: Der User fordert es explizit und begründet es.
|
||
- **`git push --force`** – Nie force-pushen ohne explizite Anweisung des Users.
|
||
- **Secrets in Code** – Keine Passwörter, API-Keys, Tokens in Dateien.
|
||
|
||
## 🖥 Terminal-Syntax (MANDATORY – Shell-Fehler vermeiden)
|
||
|
||
> Vor **jedem** Terminal-Kommando: lies das Feld **Default-Shell** (Abschnitt
|
||
> „Entwicklungsumgebung", unten nach `---`) und nutze die Syntax **genau dieser** Shell.
|
||
> Die Terminal-Tool-Beschreibung nennt die aktive Shell zusätzlich.
|
||
|
||
**Bei fish (hier der Normalfall):**
|
||
- Variablen: `set VAR (cmd)` — **niemals** `VAR=$(cmd)` (fish bricht ab mit „Unsupported use of '='").
|
||
- Blöcke enden mit `end`, **nicht** `done`/`fi`.
|
||
|
||
**Harte Regel gegen wiederholte Syntaxfehler:**
|
||
- Nur ein **einzelnes, triviales** Kommando direkt im Prompt tippen.
|
||
- Alles mit **Zuweisung, Schleife, Bedingung oder mehreren Statements** → in eine
|
||
`.sh`-Datei mit `#!/usr/bin/env bash` schreiben und mit `bash datei.sh` ausführen.
|
||
Dann ist die interaktive Shell-Syntax irrelevant und der Fehler kann nicht auftreten.
|
||
|
||
## ⚠ Bekannte Fallstricke (nicht vergessen!)
|
||
|
||
- **Scripts mit Self-Update (`copilot-update.sh/.fish`) immer erst committen+pushen, DANN manuell deployen.**
|
||
Reihenfolge zwingend:
|
||
1. Änderung im Repo vornehmen
|
||
2. `git add … && git commit && git push`
|
||
3. `cp scripts/copilot-update.sh ~/.local/bin/copilot-update.sh`
|
||
4. Testen
|
||
Falsche Reihenfolge (erst deployen, dann committen) → Self-Update überschreibt den manuell deployten Fix
|
||
mit der alten Version aus dem Remote-Cache. Der Fix geht verloren.
|
||
|
||
- **`fi ───` oder `end ───` in POSIX-sh/fish:** Box-Drawing-Zeichen nie direkt ans `fi`/`end` anhängen.
|
||
Kommentar-Trennlinie immer auf eigener Zeile: `# ── Abschnitt ──`
|
||
|
||
- **`printf '%s\n%s\n'` frisst trailing newlines** aus `$(awk ...)` Substitution.
|
||
Wenn eine Leerzeile zwischen zwei Blöcken erhalten bleiben soll: `printf '%s\n\n%s\n'` verwenden.
|
||
|
||
---
|
||
|
||
## 🖥 Entwicklungsumgebung
|
||
|
||
<!-- copilot:dev-shell – beim Bootstrap automatisch aus $SHELL gesetzt; jederzeit manuell änderbar -->
|
||
- **Default-Shell:** fish
|
||
|
||
Der Agent nutzt diese Shell für **alle** Terminal-Kommandos und passt die Syntax an
|
||
(fish ≠ POSIX sh/bash – z.B. `set -x VAR wert` statt `export VAR=wert`, `(cmd)` statt
|
||
`$(cmd)`, kein `&&`/`||`-Verketten in fish-Skripten). Bei anderem System / neuem Repo
|
||
diesen Wert anpassen.
|
||
|
||
## Project
|
||
<!-- TODO: Beschreibe das Projekt in 1-2 Sätzen -->
|
||
|
||
## Stack
|
||
<!-- TODO: Sprachen, Frameworks, wichtige Tools -->
|
||
- Language:
|
||
- Framework:
|
||
- Database:
|
||
- Infrastructure:
|
||
|
||
## Architecture
|
||
<!-- TODO: Relevante Architekturentscheidungen -->
|
||
- Pattern (MVC / Hexagonal / Event-driven / ...):
|
||
- Key constraints:
|
||
- ADR location: `docs/adr/`
|
||
|
||
## Project Structure Conventions
|
||
|
||
### Persistent Data (`/data/`)
|
||
- **Alle persistenten Service-Daten** gehören in `/data/<service-name>/` (Repo-Root)
|
||
- **Nie** Daten-Dateien committen – `/data/` ist vollständig gitignored
|
||
- Einen Unterordner pro Service (z.B. `data/postgres/`, `data/redis/`, `data/uploads/`)
|
||
- Erforderliche Unterordner in `docs/ADMIN.md` dokumentieren
|
||
|
||
### Requirements (`/docs/requirements/`)
|
||
- **Alle verstandenen Anforderungen** → `docs/requirements/REQUIREMENTS.md` (**committed, immer aktuell halten!**)
|
||
- **Beim Start einer neuen Aufgabe:** `docs/requirements/REQUIREMENTS.md` zuerst lesen (falls vorhanden)
|
||
- **Nach Anforderungs-Klärung:** Requirements-Datei aktualisieren und stagen
|
||
- Copilot Chat: `/requirements` → Requirements-Workshop starten oder bestehende Requirements aktualisieren
|
||
- Copilot Chat: `/check-consistency` → Konsistenz zwischen Code, Docs und Requirements prüfen
|
||
|
||
### Agent History (`/docs/history/`)
|
||
- **Vollständige Konversationen** → `docs/history/prompts/YYYY-MM-DD_beschreibung_session.md` (**Suffix `_session.md` zwingend** – Check 6 im pre-commit Hook erkennt daran das Agent-Log)
|
||
- **Komprimierter Kontext** → `docs/history/summary/PROJECT_CONTEXT.md` (**committed, immer aktuell halten!**)
|
||
- **Beim Start einer neuen Session:** `docs/history/summary/PROJECT_CONTEXT.md` zuerst lesen
|
||
- **Am Ende jeder Session:** beide Dateien committen
|
||
- Copilot Chat: `/history` → History loggen + Summary aktualisieren
|
||
|
||
### Documentation (3 Zielgruppen – alle 3 müssen existieren)
|
||
| Datei | Zielgruppe | Inhalt |
|
||
|---|---|---|
|
||
| `docs/USER.md` | Endnutzer | Features, How-To, FAQ – keine technischen Details |
|
||
| `docs/ADMIN.md` | Administratoren | Deployment, Konfiguration, Monitoring, Backup |
|
||
| `docs/MAINTAINER.md` | Entwickler | Architektur, ADRs, Konventionen, Erweiterung |
|
||
|
||
**Regel:** Jede bedeutende Änderung muss mindestens eine dieser Dateien aktualisieren.
|
||
Der pre-commit Hook prüft dies automatisch.
|
||
|
||
## Conventions
|
||
<!-- TODO: Projekt-spezifische Konventionen -->
|
||
- Branch naming: `feat/<ticket>-description`, `fix/<ticket>-description`
|
||
- Commit format: Conventional Commits (`feat|fix|chore|docs|refactor|test|ci`)
|
||
- File structure:
|
||
- Naming:
|
||
|
||
## Engineering Process
|
||
|
||
### Before starting any task
|
||
1. Lies `docs/requirements/REQUIREMENTS.md` (falls vorhanden) – verstehe die Anforderungen
|
||
2. Clarify requirements – user story + acceptance criteria vorhanden?
|
||
3. Impact analysis – welche bestehenden Komponenten sind betroffen?
|
||
4. Architecture check – passt die geplante Lösung zur bestehenden Architektur?
|
||
5. Test strategy – wie wird das Feature getestet?
|
||
|
||
### Definition of Ready (DoR)
|
||
A task can only be started when:
|
||
- [ ] Acceptance criteria are clear and unambiguous
|
||
- [ ] Non-functional requirements defined (performance, security, scalability)
|
||
- [ ] Architectural approach agreed upon
|
||
- [ ] No unresolved external blockers
|
||
|
||
### Definition of Done (DoD)
|
||
A task is only done when ALL of the following are true:
|
||
- [ ] Code implements the acceptance criteria
|
||
- [ ] Requirements-Konsistenz geprüft: keine Widersprüche zwischen Code und `docs/requirements/REQUIREMENTS.md`
|
||
- [ ] `docs/requirements/REQUIREMENTS.md` aktualisiert falls Anforderungen sich geändert haben
|
||
- [ ] Unit tests written and passing
|
||
- [ ] Integration tests (where applicable) passing
|
||
- [ ] No linter / type errors
|
||
- [ ] No secrets or credentials in code
|
||
- [ ] OWASP Top 10 reviewed
|
||
- [ ] Relevant documentation updated: `docs/USER.md` and/or `docs/ADMIN.md` and/or `docs/MAINTAINER.md`
|
||
- [ ] Alle 3 Zielgruppen-Dokumente vorhanden (`docs/USER.md`, `docs/ADMIN.md`, `docs/MAINTAINER.md`)
|
||
- [ ] Persistente Daten liegen ausschließlich in `/data/<service>/` (nie woanders)
|
||
- [ ] `docs/history/summary/PROJECT_CONTEXT.md` aktualisiert
|
||
- [ ] Commit message follows Conventional Commits
|
||
- [ ] No dead code, no TODOs left behind (or tracked as issues)
|
||
- [ ] pre-commit Quality Gate bestanden
|
||
|
||
## Testing Strategy
|
||
<!-- TODO: Anpassen auf das Projekt -->
|
||
- Framework:
|
||
- Coverage target: ≥ 80% (critical paths: 100%)
|
||
- Test pyramid: unit > integration > e2e
|
||
- Test location: `tests/` mirroring source structure
|
||
|
||
## Security
|
||
- No secrets in code or config files – use environment variables
|
||
- Validate all inputs at system boundaries
|
||
- Principle of least privilege for all permissions
|
||
- Dependency vulnerabilities: check before adding new deps
|
||
|
||
## Documentation Standards
|
||
- Code comments: explain WHY, not WHAT
|
||
- Public APIs: always documented
|
||
- Architecture decisions: write ADR in `docs/adr/` (template: `docs/adr/000-template.md`)
|
||
- CHANGELOG.md: update with every release
|
||
- **3-Zielgruppen-Regel:** USER.md (Endnutzer) + ADMIN.md (Ops) + MAINTAINER.md (Dev) – immer alle 3 pflegen
|
||
|
||
## Non-Functional Requirements
|
||
<!-- TODO: Anpassen -->
|
||
- Response time:
|
||
- Availability:
|
||
- Data retention:
|