feat: agents instructions extended

Author: sidey79

AGENTS.md

@@ -48,4 +48,199 @@ Diese Richtlinie gilt für alle AI-Agenten, die Code oder Systemkonfigurationen
 - [ ] Gesamte Testsuite (`pytest`) ohne Fehler durchgelaufen
 - [ ] Änderungen mit den Projekt‑Konventionen konsistent
 
-Diese Richtlinie gewährleistet, dass Code‑Änderungen nicht isoliert, sondern im Kontext des gesamten Projekts betrachtet werden und die langfristige Wartbarkeit sowie die Zuverlässigkeit der Software erhalten bleibt.
+Diese Richtlinie gewährleistet, dass Code‑Änderungen nicht isoliert, sondern im Kontext des gesamten Projekts betrachtet werden und die langfristige Wartbarkeit sowie die Zuverlässigkeit der Software erhalten bleibt.
+
+## Architecture-First Development Process
+
+Dieser Abschnitt definiert den verbindlichen Arbeitsablauf für die Entwicklung neuer Funktionen im PySignalduino-Projekt. Der zentrale Grundsatz lautet: **Jede neue Funktion beginnt mit einer vorausschauenden Erweiterung der Architekturdokumentation.** Diese dokumentierte Architektur dient als die einzige verbindliche Spezifikation und der primäre Leitfaden für alle nachfolgenden Implementierungsschritte.
+
+### Grundprinzipien
+
+1. **Architektur vor Code:** Design-Entscheidungen müssen zuerst in der Dokumentation reflektiert und abgestimmt werden, bevor jeglicher Code geschrieben wird.
+2. **Dokumentation als Single Source of Truth:** Die Architekturdokumentation ist die autoritative Referenz für alle Implementierungsentscheidungen.
+3. **Traceability:** Jede Code-Änderung muss auf eine spezifische Architekturentscheidung zurückführbar sein.
+4. **Compliance-Checks:** Implementierungen müssen regelmäßig auf Konformität mit der dokumentierten Architektur überprüft werden.
+
+### Vier-Phasen-Prozess
+
+#### Phase 1: Architekturdefinition mit verbindlichem Architekturproposal
+- **Ziel:** Erstellung eines vollständigen Architekturproposals, das alle Design-Entscheidungen dokumentiert
+- **Aktivitäten:**
+  - Anforderungsanalyse und Scope-Definition
+  - Erstellung von Architekturdiagrammen (Mermaid, PlantUML)
+  - Definition von Schnittstellen und Datenmodellen
+  - Risikoanalyse und Alternativenbewertung
+  - Erstellung eines Architecture Decision Record (ADR)
+- **Deliverables:**
+  - Architekturproposal im AsciiDoc-Format
+  - Mermaid-Diagramme für Komponenten- und Sequenzabläufe
+  - ADR im `docs/architecture/decisions/` Verzeichnis
+  - Review-Protokoll mit Genehmigung durch Architecture Owner
+
+#### Phase 2: Implementierungsplanung basierend auf genehmigter Architektur
+- **Ziel:** Detaillierte Planung der Implementierungsschritte unter strikter Einhaltung der Architektur
+- **Aktivitäten:**
+  - Aufteilung in konkrete Arbeitspakete (Tasks)
+  - Definition von Akzeptanzkriterien für jede Komponente
+  - Planung von Teststrategien (Unit, Integration, System)
+  - Ressourcen- und Zeitplanung
+  - Erstellung von Mockups/Prototypen für kritische Pfade
+- **Deliverables:**
+  - Implementierungsplan mit Task-Breakdown
+  - Testplan mit Coverage-Zielen
+  - Prototypen für Risikokomponenten
+  - Genehmigung durch Feature Developer und Reviewer
+
+#### Phase 3: Implementierung mit strikter Konformität zur Architektur
+- **Ziel:** Code-Entwicklung unter ständiger Referenzierung der Architekturdokumentation
+- **Aktivitäten:**
+  - Iterative Entwicklung gemäß Implementierungsplan
+  - Regelmäßige Architektur-Compliance-Checks
+  - Dokumentation von Abweichungen und deren Begründung
+  - Kontinuierliche Integration und Code-Reviews
+  - Anpassung der Dokumentation bei notwendigen Änderungen
+- **Deliverables:**
+  - Vollständiger implementierter Code
+  - Aktualisierte Dokumentation (Inline-Kommentare, Docstrings)
+  - Testsuite mit ausreichender Coverage
+  - Compliance-Report gegenüber Architekturproposal
+
+#### Phase 4: Validation & Integration mit Architektur-Compliance-Checks
+- **Ziel:** Validierung der Implementierung gegen Architekturanforderungen und Integration in das Gesamtsystem
+- **Aktivitäten:**
+  - Ausführung aller Tests (Unit, Integration, System)
+  - Architektur-Compliance-Review durch Architecture Owner
+  - Performance- und Sicherheitsaudits
+  - Integrationstests mit bestehenden Komponenten
+  - Endgültige Dokumentationsprüfung
+- **Deliverables:**
+  - Testberichte und Coverage-Report
+  - Compliance-Zertifizierung durch Architecture Owner
+  - Finalisierte Dokumentation
+  - Merge-Request mit vollständiger Nachweisbarkeit
+
+### Rollen und Verantwortlichkeiten
+
+#### Architecture Owner
+- **Verantwortlichkeiten:**
+  - Genehmigung von Architekturproposals
+  - Durchführung von Architektur-Reviews
+  - Compliance-Checks während der Implementierung
+  - Finale Freigabe für Integration
+- **Befugnisse:**
+  - Veto-Recht bei Architekturverstößen
+  - Anforderung von Design-Änderungen
+  - Genehmigung von ADRs
+
+#### Feature Developer
+- **Verantwortlichkeiten:**
+  - Erstellung von Architekturproposals
+  - Implementierung gemäß genehmigter Architektur
+  - Dokumentation von Design-Entscheidungen
+  - Durchführung von Selbst-Checks auf Compliance
+- **Befugnisse:**
+  - Vorschlag von Architekturalternativen
+  - Beantragung von Architektur-Änderungen via ADR
+  - Code-Reviews für Teammitglieder
+
+#### Reviewer
+- **Verantwortlichkeiten:**
+  - Code-Review mit Fokus auf Architekturkonformität
+  - Prüfung der Testabdeckung
+  - Validierung der Dokumentationsaktualität
+  - Sicherstellung der Wartbarkeit
+- **Befugnisse:**
+  - Blockierung von Merge-Requests bei Compliance-Problemen
+  - Anforderung zusätzlicher Tests
+  - Empfehlung für Architecture Owner
+
+### Architecture Documentation Standards
+
+#### AsciiDoc-Templates
+Alle Architekturdokumente müssen den standardisierten Templates folgen:
+- **Architekturproposal:** `docs/architecture/templates/proposal_template.adoc`
+- **ADR (Architecture Decision Record):** `docs/architecture/templates/adr_template.adoc`
+- **Komponentenbeschreibung:** `docs/architecture/templates/component_template.adoc`
+
+#### Mermaid-Diagramme
+- **Verpflichtende Diagrammtypen:**
+  - Komponentendiagramm (Component Diagram)
+  - Sequenzdiagramm (Sequence Diagram)
+  - Zustandsdiagramm (State Diagram) bei komplexen Zustandsmaschinen
+- **Einbettung:** Direkte Einbettung in AsciiDoc-Dokumente via `[mermaid]`-Block
+- **Versionierung:** Diagramme müssen im `docs/architecture/diagrams/` Verzeichnis als `.mmd`-Dateien gespeichert werden
+
+#### ADRs (Architecture Decision Records)
+- **Format:** Lightweight ADR gemäß MADR-Standard
+- **Speicherort:** `docs/architecture/decisions/`
+- **Nummerierung:** Sequentiell (ADR-001, ADR-002, ...)
+- **Inhalt:** Kontext, Entscheidung, Konsequenzen, Alternativen
+
+### Erweiterte Checkliste vor dem Commit
+
+Diese Checkliste erweitert die bestehende Checkliste um Architektur-spezifische Prüfpunkte:
+
+#### Architektur-Compliance
+- [ ] Architekturproposal liegt vor und ist genehmigt
+- [ ] ADR für alle wesentlichen Design-Entscheidungen erstellt
+- [ ] Implementierung folgt den spezifizierten Schnittstellen
+- [ ] Keine Verletzung von Architekturprinzipien (z.B. Single Responsibility)
+- [ ] Datenmodelle entsprechen den definierten Schemata
+
+#### Dokumentation
+- [ ] Architekturdokumentation aktualisiert (AsciiDoc-Dateien)
+- [ ] Mermaid-Diagramme auf Aktualität geprüft
+- [ ] Inline-Kommentare und Docstrings angepasst
+- [ ] API-Referenzen konsistent mit Implementierung
+- [ ] README.md und andere Markdown-Dateien geprüft
+
+#### Tests
+- [ ] Bestehende Tests angepasst und erfolgreich ausgeführt
+- [ ] Neue Tests für geänderte/neue Logik erstellt
+- [ ] Architektur-spezifische Integrationstests vorhanden
+- [ ] Test-Coverage mindestens 80% für neue Komponenten
+- [ ] Gesamte Testsuite (`pytest`) ohne Fehler durchgelaufen
+
+#### Code-Qualität
+- [ ] Code-Review durch Reviewer durchgeführt
+- [ ] Architektur-Compliance-Check durch Architecture Owner
+- [ ] Linting (`ruff`, `black`) ohne Fehler
+- [ ] Type-Checks (`mypy`) erfolgreich
+- [ ] Änderungen mit den Projekt-Konventionen konsistent
+
+### Prozessvisualisierung
+
+```mermaid
+flowchart TD
+    A[Neue Funktionsanforderung] --> B[Phase 1: Architekturdefinition]
+    B --> C{Architekturproposal<br/>genehmigt?}
+    C -->|Ja| D[Phase 2: Implementierungsplanung]
+    C -->|Nein| B
+    D --> E[Phase 3: Implementierung]
+    E --> F[Regelmäßige Compliance-Checks]
+    F --> G{Compliance<br/>verletzt?}
+    G -->|Ja| H[ADR für Änderung<br/>oder Rückführung]
+    H --> E
+    G -->|Nein| I[Phase 4: Validation & Integration]
+    I --> J{Alle Tests bestanden<br/>und Compliance ok?}
+    J -->|Ja| K[Merge & Deployment]
+    J -->|Nein| I
+    
+    subgraph "Architektur-Governance"
+        L[Architecture Owner Review]
+        M[ADR Management]
+        N[Compliance Monitoring]
+    end
+    
+    B --> L
+    D --> L
+    I --> L
+    H --> M
+    F --> N
+```
+
+### Verbindlichkeit
+
+Dieser Architecture-First Development Process ist für **alle** neuen Funktionen und wesentlichen Änderungen verbindlich. Ausnahmen sind nur bei kritischen Bugfixes erlaubt und müssen durch einen Emergency-ADR dokumentiert werden. Jede Abweichung vom Prozess muss vom Architecture Owner genehmigt werden.
+
+Die Einhaltung dieses Prozesses gewährleistet, dass Design-Entscheidungen bewusst getroffen, dokumentiert und nachvollziehbar sind, was die langfristige Wartbarkeit, Skalierbarkeit und Qualität des PySignalduino-Projekts sicherstellt.