From a959d768505ba3ac807fcf2031f8a615a0351e0b Mon Sep 17 00:00:00 2001 From: Conrad Schulz Date: Tue, 2 Jun 2026 17:51:41 +0000 Subject: [PATCH] feat: requirements engineering + konsistenz-check - git-templates/docs/requirements/REQUIREMENTS.md: persistentes Requirements-Template mit User Stories, ACs, NFRs, Out-of-Scope, Aenderungshistorie - prompts/check-consistency.prompt.md: neuer /check-consistency Prompt (Code vs. Requirements vs. Docs, findet Widersprueche vor dem Commit) - git-templates/hooks/pre-commit: Check 5 hinzugefuegt (blockiert wenn REQUIREMENTS.md unstaged Aenderungen hat) - prompts/requirements.prompt.md: liest und schreibt jetzt docs/requirements/REQUIREMENTS.md - copilot-instructions.md (beide): Requirements-Sektion, DoD + Before-starting erweitert - git-templates/history/summary/PROJECT_CONTEXT.md: Requirements-Pfad erganzt --- .github/copilot-instructions.md | 18 ++++- git-templates/.github/copilot-instructions.md | 18 ++++- .../docs/requirements/REQUIREMENTS.md | 74 +++++++++++++++++++ .../history/summary/PROJECT_CONTEXT.md | 1 + git-templates/hooks/pre-commit | 20 ++++- ...6-02_copilot-update-auto-deploy_session.md | 33 +++++++++ history/summary/PROJECT_CONTEXT.md | 5 +- prompts/check-consistency.prompt.md | 54 ++++++++++++++ prompts/requirements.prompt.md | 26 ++++++- 9 files changed, 236 insertions(+), 13 deletions(-) create mode 100644 git-templates/docs/requirements/REQUIREMENTS.md create mode 100644 prompts/check-consistency.prompt.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index a1a5fd2..5a4941f 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -53,6 +53,13 @@ - 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 (`/history/`) - **Vollständige Konversationen** → `history/prompts/YYYY-MM-DD_beschreibung_session.md` (**Suffix `_session.md` zwingend** – post-commit Hook erkennt daran das Agent-Log) - **Komprimierter Kontext** → `history/summary/PROJECT_CONTEXT.md` (**committed, immer aktuell halten!**) @@ -80,10 +87,11 @@ Der pre-commit Hook prüft dies automatisch. ## Engineering Process ### Before starting any task -1. Clarify requirements – user story + acceptance criteria vorhanden? -2. Impact analysis – welche bestehenden Komponenten sind betroffen? -3. Architecture check – passt die geplante Lösung zur bestehenden Architektur? -4. Test strategy – wie wird das Feature getestet? +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: @@ -95,6 +103,8 @@ A task can only be started when: ### 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 diff --git a/git-templates/.github/copilot-instructions.md b/git-templates/.github/copilot-instructions.md index a1a5fd2..5a4941f 100644 --- a/git-templates/.github/copilot-instructions.md +++ b/git-templates/.github/copilot-instructions.md @@ -53,6 +53,13 @@ - 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 (`/history/`) - **Vollständige Konversationen** → `history/prompts/YYYY-MM-DD_beschreibung_session.md` (**Suffix `_session.md` zwingend** – post-commit Hook erkennt daran das Agent-Log) - **Komprimierter Kontext** → `history/summary/PROJECT_CONTEXT.md` (**committed, immer aktuell halten!**) @@ -80,10 +87,11 @@ Der pre-commit Hook prüft dies automatisch. ## Engineering Process ### Before starting any task -1. Clarify requirements – user story + acceptance criteria vorhanden? -2. Impact analysis – welche bestehenden Komponenten sind betroffen? -3. Architecture check – passt die geplante Lösung zur bestehenden Architektur? -4. Test strategy – wie wird das Feature getestet? +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: @@ -95,6 +103,8 @@ A task can only be started when: ### 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 diff --git a/git-templates/docs/requirements/REQUIREMENTS.md b/git-templates/docs/requirements/REQUIREMENTS.md new file mode 100644 index 0000000..9ef6ce9 --- /dev/null +++ b/git-templates/docs/requirements/REQUIREMENTS.md @@ -0,0 +1,74 @@ +# Requirements – [PROJEKT_NAME] + +> **Persistentes Anforderungs-Dokument** – wird vom Agenten gepflegt. +> Vor jeder Implementierung lesen. Nach jeder Anforderungs-Klärung aktualisieren. +> Copilot Chat: `/requirements` → Requirements-Workshop starten oder aktualisieren. +> Copilot Chat: `/check-consistency` → Konsistenz zwischen Code und Requirements prüfen. + +**Letzte Aktualisierung:** +**Version:** 0.1 (Draft) + +--- + +## Überblick + + + +--- + +## Nutzer-Rollen + +| Rolle | Beschreibung | Primäre Ziele | +|---|---|---| +| | | | + +--- + +## User Stories + + + +### US-001 – [Titel] + +> Als **[Rolle]** möchte ich **[Aktion]**, damit **[Nutzen]**. + +**Acceptance Criteria:** +- [ ] Given [Vorbedingung], When [Aktion], Then [Erwartetes Ergebnis] +- [ ] Given [Vorbedingung], When [Fehlerfall], Then [Fehlerbehandlung] + +**Status:** Draft | Ready | In Progress | Done +**Priorität:** Must Have | Should Have | Nice to Have + +--- + +## Non-Functional Requirements + +| ID | Kategorie | Anforderung | Messbar | +|---|---|---|---| +| NFR-001 | Performance | | | +| NFR-002 | Security | Keine Secrets im Code, Auth für alle Endpunkte | Ja – OWASP Top 10 | +| NFR-003 | Availability | | | +| NFR-004 | Maintainability | Neue Entwickler onboarden in < 1h | Ja – Onboarding-Checkliste | + +--- + +## Explizit Out of Scope + + +- [ ] TODO – Out-of-Scope-Item 1 + +--- + +## Offene Fragen & Risiken + +| # | Frage / Risiko | Verantwortlich | Deadline | Status | +|---|---|---|---|---| +| 1 | | | | Offen | + +--- + +## Änderungshistorie + +| Datum | Version | Änderung | Wer | +|---|---|---|---| +| | 0.1 | Initiale Draft-Version | Agent | diff --git a/git-templates/history/summary/PROJECT_CONTEXT.md b/git-templates/history/summary/PROJECT_CONTEXT.md index 4f4ae69..9895aac 100644 --- a/git-templates/history/summary/PROJECT_CONTEXT.md +++ b/git-templates/history/summary/PROJECT_CONTEXT.md @@ -56,6 +56,7 @@ - **Persistente Daten:** `/data//` (gitignored, nie committen!) - **Agent-Logs (voll):** `/history/prompts/` (committed – vollständige History im Repo) - **Dieser Kontext:** `/history/summary/PROJECT_CONTEXT.md` (committed) +- **Requirements:** `docs/requirements/REQUIREMENTS.md` (committed, immer aktuell halten!) - **Tests:** `tests/` (Struktur spiegelt Source) - **Docs:** `docs/USER.md` | `docs/ADMIN.md` | `docs/MAINTAINER.md` diff --git a/git-templates/hooks/pre-commit b/git-templates/hooks/pre-commit index a881ece..c71c458 100755 --- a/git-templates/hooks/pre-commit +++ b/git-templates/hooks/pre-commit @@ -6,6 +6,7 @@ # 2. Mindestens eine Zielgruppen-Dokumentation aktualisiert wurde # 3. Alle 3 Dokumentations-Zielgruppen vorhanden sind (USER/ADMIN/MAINTAINER) # 4. history/summary/PROJECT_CONTEXT.md aktualisiert wurde +# 5. docs/requirements/REQUIREMENTS.md keine unstaged Änderungen hat # # Hooks laufen immer – kein --no-verify verwenden. @@ -100,11 +101,28 @@ if [ -f "history/summary/PROJECT_CONTEXT.md" ]; then fi fi +# ── Check 5: Requirements-Konsistenz ───────────────────────────────────────── +# Wenn docs/requirements/REQUIREMENTS.md existiert und unstaged Änderungen hat, +# muss es vor dem Commit gestaged werden. +# Opt-out: Datei '.copilot-no-requirements' im Repo-Root deaktiviert diesen Check. +if [ -f "docs/requirements/REQUIREMENTS.md" ] && [ ! -f ".copilot-no-requirements" ]; then + REQ_UNSTAGED=$(git diff --name-only -- "docs/requirements/REQUIREMENTS.md" 2>/dev/null) + if [ -n "$REQ_UNSTAGED" ]; then + echo "" + echo "✗ AGENT QUALITY GATE [5/5]: Requirements-Datei hat unstaged Änderungen" + echo " docs/requirements/REQUIREMENTS.md wurde geändert aber nicht gestaged." + echo "" + echo " → git add docs/requirements/REQUIREMENTS.md" + echo " → Copilot Chat: /requirements (Requirements aktualisieren + konsistenz prüfen)" + ERRORS=$((ERRORS + 1)) + fi +fi + # ── Ergebnis ────────────────────────────────────────────────────────────────── if [ "$ERRORS" -gt 0 ]; then echo "" echo "══════════════════════════════════════════════════════════" - echo " $ERRORS von 4 Quality Gate(s) nicht bestanden." + echo " $ERRORS von 5 Quality Gate(s) nicht bestanden." echo " Behebe die Probleme bevor du committst." echo " ══════════════════════════════════════════════════════════" echo "" diff --git a/history/prompts/2026-06-02_copilot-update-auto-deploy_session.md b/history/prompts/2026-06-02_copilot-update-auto-deploy_session.md index 579f908..ef0b853 100644 --- a/history/prompts/2026-06-02_copilot-update-auto-deploy_session.md +++ b/history/prompts/2026-06-02_copilot-update-auto-deploy_session.md @@ -239,3 +239,36 @@ fix: review-findings behoben (7 Punkte) --- *Git-Block automatisch generiert durch post-commit hook.* + +--- + +## Git Commit + +| Feld | Wert | +|---|---| +| Datum | 2026-06-02 17:38:35 | +| Branch | `master` | +| Commit | `d31db9086fbee964b17d5ceb32ba545fbd15f35a` | +| Autor | Conrad Schulz | + +### Commit Message + +``` +fix: alle --no-verify Referenzen entfernt + pre-commit Nummerierung +``` + +### Geänderte Dateien + +| Status | Datei | +|---|---| +| M | .github/copilot-instructions.md | +| M | docs/ADMIN.md | +| M | docs/MAINTAINER.md | +| M | docs/USER.md | +| M | git-templates/.github/copilot-instructions.md | +| M | git-templates/hooks/pre-commit | +| M | history/prompts/2026-06-02_copilot-update-auto-deploy_session.md | +| M | history/summary/PROJECT_CONTEXT.md | + +--- +*Git-Block automatisch generiert durch post-commit hook.* diff --git a/history/summary/PROJECT_CONTEXT.md b/history/summary/PROJECT_CONTEXT.md index 9c1d32c..d04b510 100644 --- a/history/summary/PROJECT_CONTEXT.md +++ b/history/summary/PROJECT_CONTEXT.md @@ -8,7 +8,7 @@ ## Aktueller Projektstatus -**Letzte Aktualisierung:** 2026-06-02 – Konsistenzprüfung: alle --no-verify Referenzen entfernt +**Letzte Aktualisierung:** 2026-06-02 – Requirements Engineering + Konsistenz-Check hinzugefügt **Phase:** Produktion / stabil – wird bei Bedarf erweitert --- @@ -30,7 +30,8 @@ Quality Gate aus. | Datum | Aufgabe | Ergebnis | Entscheidungen | |---|---|---|---| | 2026-06-02 | Konsistenzprüfung: alle --no-verify Referenzen entfernt | `docs/USER.md`, `docs/ADMIN.md`, `docs/MAINTAINER.md`, beide `copilot-instructions.md`, `pre-commit` Check-Nummerierung `[1/3]→[1/4]` | Opt-outs (.copilot-no-tests/.copilot-no-docs) als Ersatz für --no-verify in Doku | -| 2026-06-02 | Review-Findings behoben (7 Punkte) | `git-templates/hooks/pre-commit`, `.copilot-no-docs`, beide `copilot-instructions.md`, `prompts/history.prompt.md`, `scripts/copilot-bootstrap.sh` | `.copilot-no-docs` Opt-out analog zu `.copilot-no-tests`; history.prompt.md Append-Verhalten korrekt dokumentiert | +| 2026-06-02 | Requirements Engineering + Konsistenz-Check | `git-templates/docs/requirements/REQUIREMENTS.md`, `prompts/check-consistency.prompt.md`, pre-commit Check 5, Requirements-Sektion in copilot-instructions.md | Anforderungen persistent in `docs/requirements/REQUIREMENTS.md`; `/check-consistency` Prompt für Konsistenzprüfung vor Commit; Check 5 blockiert nur bei unstaged Requirements-Änderungen | +| 2026-06-02 | Review-Findings behoben (7 Punkte) | pre-commit, `.copilot-no-docs`, beide copilot-instructions.md, history.prompt.md, copilot-bootstrap.sh | `.copilot-no-docs` Opt-out; history.prompt.md Append-Verhalten korrekt | | 2026-06-02 | copilot-update.sh + git alias + post-merge Hook | `scripts/copilot-update.sh`, `scripts/copilot-update.fish`, `git-templates/hooks/post-merge` | SSH+HTTP-Fallback; opt-in Update-Hook; copilot-instructions.md nur bei TODO überschreiben | | 2026-05-31 | Bug fix: mkdir -p .git/hooks + eigenes Repo bootstrapped | `e1f912f` | – | | 2026-05-31 | history/prompts/ committed statt gitignored | `95d0360` | Vollständige History bleibt im Repo | diff --git a/prompts/check-consistency.prompt.md b/prompts/check-consistency.prompt.md new file mode 100644 index 0000000..d1c273a --- /dev/null +++ b/prompts/check-consistency.prompt.md @@ -0,0 +1,54 @@ +--- +mode: agent +description: Konsistenz-Check – prüft ob Code, Docs und Requirements widerspruchsfrei sind +tools: + - codebase +--- + +# Konsistenz-Check + +Prüfe ob alle Teile des Projekts konsistent und widerspruchsfrei sind. +Dieser Check sollte vor jedem Commit ausgeführt werden. + +## 1. Requirements vs. Code + +Lies `docs/requirements/REQUIREMENTS.md` (falls vorhanden). + +- Sind alle User Stories korrekt implementiert? +- Gibt es Code-Verhalten das NICHT in den Requirements beschrieben ist? +- Gibt es Requirements die noch NICHT implementiert sind? (→ als TODO markieren) +- Widerspricht eine neue Implementierung einer bestehenden Anforderung? + +## 2. Code vs. Dokumentation + +- Stimmt `docs/USER.md` mit dem tatsächlichen Verhalten überein? +- Stimmt `docs/ADMIN.md` mit der tatsächlichen Konfiguration/Deployment überein? +- Stimmt `docs/MAINTAINER.md` mit der tatsächlichen Architektur überein? +- Gibt es Funktionen/Endpunkte/Befehle die dokumentiert sind aber nicht (mehr) existieren? + +## 3. Code vs. Code + +- Gibt es widersprüchliche Konfigurationen (z.B. Port in zwei Dateien unterschiedlich)? +- Gibt es doppelte/widersprüchliche Konstanten oder Defaults? +- Sind API-Contracts konsistent (Request/Response-Formate)? +- Gibt es veraltete TODO-Kommentare die inzwischen implementiert wurden? + +## 4. Ergebnis + +Erstelle einen kurzen Bericht: + +``` +## Konsistenz-Check – [DATUM] + +### ✓ Konsistent +- [was wurde geprüft und ist ok] + +### ✗ Widersprüche gefunden +- [Widerspruch 1]: [Beschreibung + betroffene Dateien] + +### ⚠ Offene Punkte +- [was ist unklar oder noch nicht überprüfbar] +``` + +Wenn Widersprüche gefunden wurden: **Behebe sie bevor du committst.** +Wenn alles konsistent ist: Kurze Bestätigung und Commit kann fortgesetzt werden. diff --git a/prompts/requirements.prompt.md b/prompts/requirements.prompt.md index df81559..bffb352 100644 --- a/prompts/requirements.prompt.md +++ b/prompts/requirements.prompt.md @@ -1,14 +1,36 @@ --- mode: agent -description: Requirements Engineering Workshop – User Stories, ACs und NFRs erarbeiten +description: Requirements Engineering – Requirements erarbeiten und in docs/requirements/REQUIREMENTS.md speichern tools: - codebase --- -# Requirements Engineering Workshop +# Requirements Engineering **Ausgangspunkt:** ${input:raw_request:Was wurde grob angefragt oder gewünscht?} +## Vorbereitung + +1. Prüfe ob `docs/requirements/REQUIREMENTS.md` bereits existiert. + - Wenn ja: Lies die Datei vollständig – vorhandene Requirements kennen. + - Wenn nein: Datei wird am Ende neu angelegt. + +2. Führe den Workshop durch und erarbeite/aktualisiere Requirements. + +## Ergebnis speichern + +Nach dem Workshop: Schreibe das vollständige, aktualisierte Requirements-Dokument +nach `docs/requirements/REQUIREMENTS.md`. Halte das Format aus dem Template ein: +- Alle User Stories mit ACs +- NFRs +- Out of Scope +- Offene Fragen +- Änderungshistorie mit heutigem Datum aktualisieren + +Dann: `git add docs/requirements/REQUIREMENTS.md` + +--- + Führe einen strukturierten Requirements-Workshop durch. Stelle Rückfragen wo nötig, aber arbeite so weit wie möglich mit dem vorhandenen Kontext.