Erstellt: 2025-12-25 | Aktualisiert: 2025-12-25

Was ist Code Hygiene?

Code Hygiene ist die kontinuierliche Pflege der technischen Sauberkeit. Sie fragt nicht nach Architektur oder Design, sondern:

• Sind Dateien überschaubar?
• Sind Verantwortlichkeiten sichtbar?
• Sind offensichtliche Risiken erkennbar?
• Ist der Code lesbar und wartbar?

Der Code Hygiene Score

Ein normalisierter Wert zwischen 0-100, der die hygienische Sauberkeit einer Code-Datei bewertet.

Formel

Score = Σ (Faktor_i × Gewicht_i) / Σ Gewicht_i

Jeder Faktor wird auf 0-100 normalisiert, bevor er gewichtet wird. Keine versteckten Sprünge, keine magischen Faktoren.

Unterkapitel

• Faktoren - Was wird gemessen
• Normalisierung - Wie werden Rohwerte skaliert
• Gewichtung - Wie stark zählt jeder Faktor

Interpretation

Was der Score leistet

• Kontinuierliche Hygiene-Überwachung
• Trendbeobachtung: „Welche Datei kippt gerade?"
• Review-Unterstützung
• Vergleich ähnlicher Dateien

Was der Score nicht ist

Kein Architektur-Score. Keine Design-Bewertung. Keine Business-Logic-Analyse.

Nur Hygiene: Ordnung, Vergleichbarkeit, Auffälligkeiten sichtbar machen.

PHP Quality & Security Tools

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

Statische Analyse, Code-Style-Prüfung und Security-Scanning für PHP. Stellt Codequalität, PSR-12 Konformität, Typsicherheit und OWASP-Compliance sicher.

Verwendung

# Prüfung (dev)
/var/www/scripts/php-check.sh

# Prüfung (beliebiges Projekt)
/var/www/scripts/php-check.sh /pfad/zum/projekt

# Mit automatischer Korrektur
/var/www/scripts/php-check.sh /pfad/zum/projekt --fix

PHPStan + Strict Rules

Statische Analyse für Typsicherheit, Null-Safety und Bug-Erkennung.

PHP-CS-Fixer

Automatische Code-Formatierung nach PSR-12 Standard.

Regeln

• PSR-12 Basis
• Short Array Syntax []
• Single Quotes, Trailing Commas
• Sortierte Imports, keine ungenutzten

Semgrep (OWASP Security)

Pattern-basierter Security Scanner für OWASP-Vulnerabilities.

Erkannte Vulnerabilities

Direkt ausführen

/root/.local/bin/semgrep scan \
    --config /opt/php-tools/semgrep-security.yml \
    src app

Composer Audit

Prüft Composer-Dependencies auf bekannte CVEs.

composer audit --working-dir=/var/www/dev.campus.systemische-tools.de

PHPUnit

Unit-Testing Framework für PHP mit PHP 8 Attributen.

Verwendung

# Tests ausführen (dev)
/var/www/scripts/php-test.sh

# Tests ausführen (beliebiges Projekt)
/var/www/scripts/php-test.sh /pfad/zum/projekt

# Mit Coverage-Report
/var/www/scripts/php-test.sh /pfad/zum/projekt --coverage

Test-Struktur

tests/
└── Unit/
    └── Domain/
        └── ValueObject/
            └── TaskStatusTest.php

Beispiel-Test

#[CoversClass(TaskStatus::class)]
class TaskStatusTest extends TestCase
{
    #[DataProvider('terminalStatusProvider')]
    public function testIsTerminal(TaskStatus $status, bool $expected): void
    {
        $this->assertSame($expected, $status->isTerminal());
    }
}

Automatisierung

PostToolUse Hook (nach jeder Dateiänderung)

Pre-Sync Check (vor Deployment)

Prinzipien & Prüfungen

Scripts im Detail

php-check.sh

Hauptscript für vollständige Qualitäts- und Sicherheitsprüfung. Führt alle 4 Checks sequentiell aus.

Checks

Verwendung

# Dev-Projekt prüfen
/var/www/scripts/php-check.sh

# Beliebiges Projekt prüfen
/var/www/scripts/php-check.sh /var/www/anderes-projekt

# Mit automatischer Style-Korrektur
/var/www/scripts/php-check.sh /var/www/dev.campus.systemische-tools.de --fix

Ausgabe

=== PHP Quality & Security Check: Fri Dec 20 12:00:00 CET 2025 ===
Project: /var/www/dev.campus.systemische-tools.de

[1/4] PHPStan - Static Analysis + Strict Rules
✓ PHPStan: OK

[2/4] PHP-CS-Fixer - Code Style (PSR-12)
✓ PHP-CS-Fixer: OK

[3/4] Composer Audit - Dependency Vulnerabilities
✓ Composer Audit: No vulnerabilities

[4/4] Semgrep - OWASP Security Scan
✓ Semgrep: No vulnerabilities

=== Summary ===
All checks passed!

php-style-check.sh

Schnelle Style-Prüfung für einzelne Dateien. Wird vom PostToolUse Hook verwendet.

Verhalten

• Prüft nur *.php Dateien
• Überspringt View-Dateien (Templates)
• Verwendet PHP-CS-Fixer im Check-Mode
• Gibt nur Warnung aus, blockiert nicht

Verwendung

# Einzelne Datei prüfen
/var/www/scripts/php-style-check.sh /var/www/dev.campus.systemische-tools.de/src/Controller/HomeController.php

php-test.sh

PHPUnit Test-Runner für Unit-Tests.

Verwendung

# Tests im dev-Projekt
/var/www/scripts/php-test.sh

# Tests in anderem Projekt
/var/www/scripts/php-test.sh /var/www/anderes-projekt

# Mit Coverage-Report
/var/www/scripts/php-test.sh /var/www/dev.campus.systemische-tools.de --coverage

Ausgabe

=== PHP Unit Tests: Fri Dec 20 12:00:00 CET 2025 ===
Project: /var/www/dev.campus.systemische-tools.de

Found 3 test file(s)

PHPUnit 12.5.4

TaskStatus
 ✓ Is terminal with completed returns true
 ✓ Is terminal with failed returns true
 ✓ Is terminal with pending returns false

✓ All tests passed!

fix-permissions.sh

Setzt Dateiberechtigungen für Web-Verzeichnisse zurück.

Betroffene Verzeichnisse

• /var/www/dev.campus.systemische-tools.de
• /var/www/prod.campus.systemische-tools.de

Verwendung

# Als root ausführen
sudo /var/www/scripts/fix-permissions.sh

Wann verwenden

• Nach manuellem Datei-Upload
• Nach Git-Operationen (falls verwendet)
• Bei Permission-Denied Fehlern
• Nach Änderungen durch andere Benutzer

Script-Übersicht

Python Quality Tools

Für die KI-Pipeline unter /var/www/scripts/pipeline/ stehen zusätzliche Python-Tools bereit.

python-check.sh

Prüfscript für Python-Code.

Checks

Verwendung

# Prüfung
/var/www/scripts/python-check.sh

# Auto-Fix Linting
/var/www/scripts/pipeline/venv/bin/ruff check /var/www/scripts/pipeline --fix

# Auto-Format
/var/www/scripts/pipeline/venv/bin/ruff format /var/www/scripts/pipeline

Frontend Quality Tools

Erstellt: 2025-12-20 | Aktualisiert: 2025-12-31

Linting und Validierung für JavaScript, CSS und HTML. Stellt Code-Qualität, Konsistenz und Best Practices im Frontend sicher.

Quick Start

# JavaScript prüfen
/var/www/scripts/js-check.sh

# CSS prüfen
/var/www/scripts/css-check.sh

# HTML/PHP-Views prüfen
/var/www/scripts/html-check.sh

# Beliebiges Projekt prüfen
/var/www/scripts/js-check.sh /var/www/anderes-projekt

ESLint (JavaScript)

Statische Analyse für JavaScript-Code. Findet Bugs, erzwingt Best Practices und konsistenten Style.

Regeln

Browser Globals

Folgende Browser-APIs sind als readonly konfiguriert:

window, document, console, setTimeout, clearTimeout,
requestAnimationFrame, cancelAnimationFrame, AbortController,
URL, URLSearchParams, performance, Date, fetch,
localStorage, sessionStorage, location, FormData,
Headers, Response, Request, MutationObserver,
IntersectionObserver, ResizeObserver

Direkt ausführen

# Check
npx eslint public/js --config /var/www/scripts/eslint.config.js

# Mit Auto-Fix
npx eslint public/js --config /var/www/scripts/eslint.config.js --fix

Prettier (Formatting)

Automatische Code-Formatierung für JavaScript. Wird von js-check.sh verwendet.

Direkt ausführen

# Check
npx prettier --check "public/js/**/*.js"

# Auto-Format
npx prettier --write "public/js/**/*.js"

Stylelint (CSS)

Linting für CSS-Dateien. Fokus auf echte Fehler, keine Style-Präferenzen.

Fehler-Regeln (aktiviert)

Limits

Deaktivierte Style-Regeln

Folgende Regeln sind bewusst deaktiviert (null), da sie Style-Präferenzen und keine Fehler prüfen:

• no-descending-specificity
• declaration-block-single-line-max-declarations
• alpha-value-notation
• color-function-notation
• color-hex-length
• font-weight-notation

Direkt ausführen

# Check
npx stylelint "public/css/**/*.css" --config /var/www/scripts/.stylelintrc.json

# Mit Auto-Fix
npx stylelint "public/css/**/*.css" --config /var/www/scripts/.stylelintrc.json --fix

HTMLHint (HTML/PHP-Views)

Validierung von HTML-Struktur in PHP-Templates.

Aktivierte Regeln

Deaktivierte Regeln (PHP-Kompatibilität)

Diese Regeln produzieren False Positives bei PHP-Templates:

Direkt ausführen

htmlhint src/View --config /var/www/scripts/.htmlhintrc

Prüfscripts

js-check.sh

JavaScript-Qualitätsprüfung mit ESLint und Prettier.

Checks

Verwendung

# Dev-Projekt
/var/www/scripts/js-check.sh

# Anderes Projekt
/var/www/scripts/js-check.sh /var/www/anderes-projekt

Ausgabe

=== JavaScript Quality Check: Fri Dec 20 12:00:00 CET 2025 ===
Directory: /var/www/dev.campus.systemische-tools.de/public/js

Found 2 JavaScript file(s)

[1/2] ESLint - Linting
✓ ESLint: No errors (1 warning)

[2/2] Prettier - Formatting
✓ Prettier: All files formatted

=== Summary ===
All checks passed!

css-check.sh

CSS-Qualitätsprüfung mit Stylelint.

Verwendung

# Dev-Projekt
/var/www/scripts/css-check.sh

# Mit Auto-Fix
cd /var/www/dev.campus.systemische-tools.de && \
npx stylelint "public/css/**/*.css" --config /var/www/scripts/.stylelintrc.json --fix

Ausgabe

=== CSS Quality Check: Fri Dec 20 12:00:00 CET 2025 ===
Directory: /var/www/dev.campus.systemische-tools.de/public/css

Found 3 CSS file(s)

[1/1] Stylelint - Linting
✓ Stylelint: No errors

=== Summary ===
All checks passed!

html-check.sh

HTML-Validierung für PHP-Templates.

Hinweis

Das Script kopiert PHP-Views temporär als .html-Dateien für HTMLHint. Einige Regeln sind deaktiviert, da PHP-Syntax False Positives erzeugt.

Verwendung

# Dev-Projekt
/var/www/scripts/html-check.sh

# Anderes Projekt
/var/www/scripts/html-check.sh /var/www/anderes-projekt

Ausgabe

=== HTML Quality Check: Fri Dec 20 12:00:00 CET 2025 ===
Directory: /var/www/dev.campus.systemische-tools.de/src/View

Found 9 View file(s)

[1/1] HTMLHint - HTML Structure Check
Scanned 5 files, no errors found
✓ HTMLHint: No errors

=== Summary ===
All checks passed!

Script-Übersicht

Contracts

Die Frontend-Tools validieren folgende Architecture Contracts:

Konfigurationsdateien

Einschränkungen

HTMLHint + PHP

HTMLHint ist für reines HTML konzipiert. Bei PHP-Templates gibt es Einschränkungen:

• PHP-Tags werden als HTML-Content interpretiert
• tag-pair Regel muss deaktiviert bleiben
• spec-char-escape Regel muss deaktiviert bleiben
• Komplexe PHP-Kontrollstrukturen können Parsing-Probleme verursachen

Workaround

Die verbleibenden Regeln (ID-Unique, Alt-Require, Attr-Validation) funktionieren zuverlässig und bieten weiterhin Mehrwert.

Pipeline Qualitätsreport: LLM-Modellvergleich

Datum: 2025-12-22
Testdokument: Lernunterlagen_Teamcoach-Ausbildung-2026_extrakt_auftragsklaerung.pdf
Dokumentgröße: 5 Seiten, 12 Chunks, 9.890 Zeichen

Getestete Modelle

1. Entity Extraction

Ergebnisübersicht

Extrahierte Entitäten (Top 5 pro Modell)

gemma3:4b-it-qat

• Systemischer Teamcoach (CONCEPT)
• Teamentwicklung (CONCEPT)
• Konfliktklärung (CONCEPT)
• Entscheidungsfindung (CONCEPT)
• Teambuilding (CONCEPT)

Bewertung: Sehr umfassend, findet auch implizite Konzepte

Claude Opus

• Auftragsklärung (CONCEPT)
• Teambuilding (CONCEPT)
• Prozessbegleitung (CONCEPT)
• Teamentwicklung (CONCEPT)
• Teamcoaching (CONCEPT)

Bewertung: Präzise, fokussiert auf Kernkonzepte

gpt-oss:20b

❌ Keine valide JSON-Ausgabe. Das Modell ignorierte die Formatierungsanweisung und produzierte Freitext.

2. Taxonomy Classification

Analyse

• gemma3: Betont den Lerncharakter (Theorie/Praxis)
• Claude Opus: Betont den prozessualen Charakter (Organisation/Kommunikation)

Beide Klassifikationen sind valide und zeigen unterschiedliche Perspektiven auf denselben Text.

3. Question Generation

gemma3:4b-it-qat (3 Fragen, 3.7s)

1. Was ist die zentrale Aussage bezüglich Auftragsklärung?
   → Die Wichtigkeit einer guten Auftragsklärung kann gar nicht stark genug betont werden.
2. Welche Aussage wird getroffen, dass sich je nach Kontext ändert?
   → Je nachdem, um was es geht, wirst du nicht nur einen anderen 'Hut' aufsetzen...
3. Welche beiden Fragen werden als Ausgangspunkt für die Auftragsklärung genannt?
   → Worum genau geht es? Und worum geht es wirklich?

Claude Opus (3 Fragen, 6.7s)

1. Warum ist die Auftragsklärung mehr als nur eine Serviceleistung?
   → Die Auftragsklärung ist bereits eine erste Intervention, da sie den Prozess aktiviert...
2. Welche zwei zentralen Fragen sollten zu Beginn einer Auftragsklärung gestellt werden?
   → 'Worum genau geht es?' und 'Und worum geht es wirklich?'
3. Warum beeinflusst die Art des Auftrags die Arbeitsweise des Coaches?
   → Je nach Auftragsart nimmt der Coach eine andere Rolle ein...

Vergleich der Fragenqualität

Gesamtbewertung

Empfehlungen

Für die Pipeline (Massenverarbeitung)

→ gemma3:4b-it-qat

• Exzellente JSON-Compliance
• Gute Balance aus Geschwindigkeit und Qualität
• Kostenlos und lokal
• Findet mehr Entitäten als Claude Opus

Für Premium-Analyse

→ Claude Opus

• Höchste Antwortqualität
• Bessere Begründungen und Tiefgang
• Für wichtige Dokumente oder Qualitätskontrolle

Nicht empfohlen

❌ gpt-oss:20b

• Ignoriert JSON-Formatierungsanweisungen
• Für strukturierte Ausgabe ungeeignet
• Möglicherweise für freie Textgenerierung geeignet

Konfigurationsempfehlung

# config.py
DEFAULT_ANALYSIS_MODEL = "gemma3:4b-it-qat"  # Lokal, schnell, zuverlässig
PREMIUM_ANALYSIS_MODEL = "claude-opus-4-5-20251101"  # Für wichtige Dokumente

# Pipeline Steps
steps:
  - vision_analyze: minicpm-v:latest  # Vision bleibt bei MiniCPM
  - entity_extraction: gemma3:4b-it-qat
  - taxonomy_classification: gemma3:4b-it-qat
  - question_generation: gemma3:4b-it-qat  # Oder Claude für Premium

Pipeline-Vergleich: Ollama gemma3:27b vs Anthropic Opus 4.5

Datum: 2025-12-26
Dokument: Booklet_ProblemeLoesungen_RELAUNCH2026.pdf (2.5 MB, 100 Seiten)

Übersicht

Entitäten nach Typ

Relationstypen

Ontologie-Klassifizierung

Qualitative Unterschiede

Neue Entitäten mit Anthropic

• Als-ob-Rahmen, Assoziation, Dissoziation, Extra-Tool, Hasenbau-Haltung
• Interventions-Toolbox, Kompetenz-DNA, Probeklient*innen
• Stamm-Tool, Zweig-Tool, VAKOG, Zukunftsorientierung

Bessere Beschreibungen (Anthropic)

• "Berg" → "Insoo Kim Berg, Mitbegründerin der lösungsorientierten Kurztherapie"
• "De Shazer" → "Steve de Shazer, Begründer der lösungsorientierten Kurztherapie"

Fazit

Empfehlung: Anthropic für hochwertige semantische Analyse, Ollama für schnelle/kostenlose Verarbeitung.