Das Elements-System
Einleitung
Wer mit KI-Werkzeugen wie Claude Code arbeitet, stößt schnell auf ein praktisches Problem: Die KI braucht Kontext. Sie muss wissen, welche Regeln im Projekt gelten, welche Werkzeuge verfügbar sind, wie der Code strukturiert sein soll. Ohne diesen Kontext produziert sie zwar funktionierenden Code, aber keinen, der zu den bestehenden Systemen passt.
=== Das Problem ohne zentrales Wissen ===
Entwickler fragt Claude Code:
"Erstelle eine Datenbankabfrage für Benutzer"
Claude Code antwortet (ohne Kontext):
// Veraltete, unsichere Methode ohne Prepared Statements
// Details siehe Kapitel "Integration"
Das Problem:
✗ Veraltete Funktionen verwendet
✗ Sicherheitslücken möglich
✗ Fehlerbehandlung fehlt
✗ Nicht kompatibel mit dem Rest des ProjektsIn kleinen Projekten lässt sich das noch manuell lösen. Eine Textdatei mit Hinweisen, ein paar Beispiele, fertig. Doch sobald mehrere Projekte existieren, mehrere Sprachen im Einsatz sind, mehrere Menschen und KI-Systeme zusammenarbeiten, wird diese Methode unübersichtlich. Regeln widersprechen sich, Werkzeuge sind doppelt definiert, niemand weiß mehr, welche Version einer Vorlage die aktuelle ist.
Eine zentrale Wissensbasis
Die Lösung ist ein gemeinsamer Ort, an dem alle diese Informationen liegen. Ein Verzeichnis, das Regeln, Werkzeuge, Projektdefinitionen und Code-Vorlagen enthält. Eine Datenbank, auf die sowohl Menschen als auch KI-Systeme zugreifen können. Das ist die Grundidee hinter dem Elements-System.
=== Das Elements-System ===
$ elements stats
Typ Aktiv Beschreibung
─────────────────────────────────────────────────────
rule 316 Einzelne Prüfungen und Regeln
contract 23 Regel-Sammlungen für Kontexte
hook 55 Eingriffspunkte im Ablauf
tool 14 Verfügbare Werkzeuge
process 2 Ablauf-Definitionen
template 8 Code-Vorlagen
...
─────────────────────────────────────────────────────
Gesamt 461 Elemente im SystemJeder Eintrag in diesem Verzeichnis heißt Element. Ein Element hat einen Typ (etwa "Regel" oder "Werkzeug"), einen Namen und eine Definition. Die Definition beschreibt, was dieses Element tut, wann es gilt und wie es angewendet wird. Ändert sich etwas, wird eine neue Version angelegt. Die alte bleibt erhalten, falls jemand nachschauen möchte, was früher galt.
Warum das hilft
Wenn Claude Code eine PHP-Datei bearbeitet, fragt es das Elements-System: Welche Regeln gelten für PHP in diesem Projekt? Das System antwortet mit einer Liste von Prüfungen, etwa "SQL-Abfragen müssen parametrisiert sein" oder "Fehler müssen geloggt werden". Claude Code kennt diese Regeln nicht von sich aus. Es lernt sie aus dem Elements-System.
=== Mit Elements-System ===
Entwickler öffnet PHP-Datei
│
▼
Elements-System liefert Kontext:
• contract-php-security
• contract-php-database
│
▼
Entwickler fragt Claude Code:
"Erstelle eine Datenbankabfrage für Benutzer"
Claude Code antwortet (mit Kontext):
$stmt = $pdo->prepare("SELECT * FROM users WHERE id = ?");
$stmt->execute([$id]);
$user = $stmt->fetch(PDO::FETCH_ASSOC);
Ergebnis:
✓ PDO statt veralteter Funktionen
✓ Prepared Statement gegen Injection
✓ Konsistent mit ProjektstandardDas Gleiche funktioniert für Menschen. Wer wissen möchte, welche Werkzeuge im Projekt verfügbar sind, fragt das System. Wer eine neue Regel hinzufügen möchte, trägt sie dort ein. Wer prüfen möchte, ob Regeln sauber definiert sind, nutzt die eingebauten Qualitätsprüfungen.
$ elements list tool
tool (14)
├── browser HTTP-Browser für Web-Scraping
├── db_sql Datenbank-Abfragen ausführen
├── download Dateien herunterladen
├── http HTTP-Anfragen senden
├── lexoffice Buchhaltungs-API
└── ... (9 weitere)Selbstoptimierung
Ein interessanter Nebeneffekt: Das Elements-System kann sich selbst überwachen. Es erkennt, wenn zwei Regeln dasselbe prüfen. Es meldet, wenn eine Definition unvollständig ist. Es zeigt, welche Elemente seit langem nicht mehr genutzt wurden. Diese Selbstprüfung verhindert, dass das System mit der Zeit unübersichtlich wird.
$ elements quality
=== Elements Quality Check ===
Prüfung Ergebnis
─────────────────────────────────────────────
Pattern-Duplikate 0 ✓
Fehlende Descriptions 3 ⚠
Inaktive Elements 19 ℹ
Verwaiste Rules 5 ⚠
─────────────────────────────────────────────
Empfehlung: 8 Elemente sollten überprüft werdenDas Prinzip dahinter ist einfach: Was für Code gilt, gilt auch für die Regeln, die Code prüfen. Keine Wiederholungen, keine verwaisten Einträge, keine widersprüchlichen Definitionen. Das System hält sich an dieselben Standards, die es anderen auferlegt.
Was in diesem Kapitel kommt
- Das Konzept Die Grundidee eines zentralen Verzeichnisses für KI-gestützte Entwicklung.
- Element-Typen Die 14 Kategorien im System: Regeln, Verträge, Werkzeuge, Prozesse, Vorlagen und mehr.
- CLI-Referenz Befehle für die Kommandozeile, um Elemente anzuzeigen, zu prüfen und zu bearbeiten.
- Architektur Wie das System aufgebaut ist und wie die einzelnen Teile zusammenspielen.
- Element-Lebenszyklus Von der Erstellung über Änderungen bis zur Deaktivierung.
- Quality Checks Automatische Prüfungen, die das System sauber halten.
- Integration Wie Elements mit anderen Werkzeugen zusammenarbeitet.
1. Das Konzept
Das Problem mit verteiltem Wissen
In jeder Entwicklungsumgebung sammelt sich Wissen an. Welche Coding-Standards gelten? Welche Werkzeuge sind erlaubt? Wie sollen Dateien benannt werden? Dieses Wissen liegt oft an verschiedenen Orten: in Dokumentationen, in Konfigurationsdateien, in den Köpfen der Beteiligten, manchmal auch nur in alten E-Mails.
=== Typische Situation ohne zentrales System ===
Wo liegt das Wissen?
┌─────────────────────────────────────────────────────────────┐
│ Coding-Standards → Wiki (veraltet seit 6 Monaten) │
│ Erlaubte Werkzeuge → README.md in Projekt A │
│ Namenskonventionen → "Das weiß nur Peter" │
│ Security-Regeln → .eslintrc + phpcs.xml + custom.py │
│ Deployment-Prozess → E-Mail von 2023 │
│ API-Richtlinien → Confluence (anderer Workspace) │
└─────────────────────────────────────────────────────────────┘
Problem: 6 Orte, 6 Formate, niemand kennt alleFür Menschen ist das mühsam, aber machbar. Sie fragen Kollegen, durchsuchen Wikis, schauen in alte Projekte. Eine KI kann das nicht. Sie arbeitet nur mit dem, was ihr explizit mitgegeben wird. Fehlt eine Information, improvisiert sie, und das Ergebnis passt oft nicht zu dem, was erwartet wurde.
Ein gemeinsames Gedächtnis
Das Elements-System ist ein Versuch, dieses Problem zu lösen. Es sammelt alle Regeln, Werkzeuge und Definitionen an einem Ort. Dieser Ort ist eine Datenbank, auf die sowohl Menschen als auch KI-Systeme zugreifen können. Jeder Eintrag folgt demselben Schema: ein Typ, ein Name, eine Definition.
=== Struktur eines Elements ===
$ elements show rule/sql-prepared-required
=== rule/sql-prepared-required ===
┌─────────────────────────────────────────────────────────────┐
│ Typ: rule │
│ Name: sql-prepared-required │
│ Version: 2 │
│ Status: aktiv │
│ Erstellt: 2024-08-15 von karl │
├─────────────────────────────────────────────────────────────┤
│ Definition: │
│ { │
│ "description": "SQL muss Prepared Statements verwenden", │
│ "pattern": "\\$.*=.*['\"]SELECT.*\\$", │
│ "message": "Prepared Statements verwenden", │
│ "severity": "error", │
│ "applies_to": ["php"] │
│ } │
└─────────────────────────────────────────────────────────────┘Der Typ gibt an, um welche Art von Information es sich handelt. Eine Regel beschreibt, was erlaubt oder verboten ist. Ein Werkzeug beschreibt, welche Programme zur Verfügung stehen. Ein Vertrag fasst mehrere Regeln zu einem Paket zusammen. Ein Prozess beschreibt, in welcher Reihenfolge Arbeitsschritte ablaufen.
Der Name identifiziert den Eintrag eindeutig. Die Definition enthält alle Details: Was tut dieses Element? Wann gilt es? Wie wird es angewendet? Diese Struktur macht es möglich, Einträge maschinell zu verarbeiten, zu durchsuchen und zu validieren.
Wie die KI darauf zugreift
Wenn Claude Code eine Datei bearbeitet, passiert im Hintergrund eine Abfrage. Das System ermittelt, zu welchem Projekt die Datei gehört, welche Sprache verwendet wird und welche Verträge für diese Kombination gelten. Aus den Verträgen werden die einzelnen Regeln geladen. Diese Regeln erscheinen dann als Hinweise während der Arbeit.
=== Ablauf: KI-Zugriff auf Elements ===
┌─────────────────┐
│ Datei geöffnet: │
│ UserService.php │
└────────┬────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 1. Kontext ermitteln │
│ Projekt: karlkratz-de │
│ Sprache: PHP │
│ Pfad: src/Services/ │
└────────┬────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 2. Passende Verträge laden │
│ $ elements list contract --for=php --project=karlkratz │
│ │
│ → contract-php-security │
│ → contract-php-database │
│ → contract-kk-style │
└────────┬────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 3. Regeln aus Verträgen extrahieren │
│ │
│ contract-php-security enthält: │
│ • sql-prepared-required │
│ • xss-output-encoding │
│ • input-validation │
│ • ... (12 weitere) │
└────────┬────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Regeln als Kontext bereitstellen │
│ │
│ Claude Code sieht: 28 aktive Regeln für diese Datei │
└─────────────────────────────────────────────────────────────┘Das funktioniert automatisch. Niemand muss die Regeln bei jeder Bearbeitung neu eingeben. Sie sind einmal definiert und gelten ab dann für alle Dateien, auf die der Vertrag zutrifft.
Versionierung
Regeln ändern sich. Was heute als beste Praxis gilt, kann morgen überholt sein. Das Elements-System speichert jede Änderung als neue Version. Die alte Version bleibt erhalten. Das hat zwei Vorteile.
=== Versionierung in der Praxis ===
$ elements history rule/sql-prepared-required
Version Status Datum Änderung
────────────────────────────────────────────────────────────
v2 aktiv 2024-08-15 14:30 Pattern verbessert
v1 inaktiv 2024-03-01 10:00 Initial
$ elements show rule/sql-prepared-required --version=1
=== rule/sql-prepared-required (v1) ===
{
"description": "SQL muss parametrisiert sein",
"pattern": "mysql_query",
"severity": "warning"
}
Unterschied zu v2:
• Pattern war zu eng gefasst
• Severity war nur "warning" statt "error"Erstens lässt sich nachvollziehen, wie eine Regel früher definiert war. Wenn Code plötzlich Warnungen produziert, die er vorher nicht produzierte, kann man prüfen, ob sich eine Regel geändert hat.
Zweitens ermöglicht es einen kontrollierten Übergang. Eine neue Regel kann zunächst als Entwurf existieren, bevor sie aktiviert wird. Oder eine alte Regel kann deaktiviert werden, ohne dass sie gelöscht wird, falls sie später doch wieder gebraucht wird.
Der Unterschied zu Konfigurationsdateien
Konfigurationsdateien erfüllen einen ähnlichen Zweck, haben aber Einschränkungen. Sie liegen im Dateisystem verstreut. Jedes Werkzeug hat sein eigenes Format. Änderungen sind schwer nachzuvollziehen. Abhängigkeiten zwischen Konfigurationen sind nicht sichtbar.
=== Vergleich: Konfigurationsdateien vs. Elements ===
┌────────────────────┬─────────────────────┬─────────────────────┐
│ Aspekt │ Konfigurationsdatei │ Elements-System │
├────────────────────┼─────────────────────┼─────────────────────┤
│ Speicherort │ Verstreut │ Zentrale Datenbank │
│ Format │ Je nach Tool │ Einheitlich (JSON) │
│ Versionierung │ Manuell (Git) │ Automatisch │
│ Abhängigkeiten │ Nicht sichtbar │ Explizit definiert │
│ Validierung │ Tool-spezifisch │ Zentral │
│ Suche │ grep/find │ elements list/show │
│ KI-Zugriff │ Muss gelesen werden │ Automatisch │
└────────────────────┴─────────────────────┴─────────────────────┘Das Elements-System löst diese Probleme, indem es ein einheitliches Format erzwingt. Alle Elemente liegen in derselben Datenbank. Alle haben dieselbe Struktur. Änderungen werden protokolliert. Abhängigkeiten sind explizit: Ein Vertrag verweist auf Regeln, ein Prozess verweist auf Werkzeuge.
=== Abhängigkeiten sichtbar machen ===
$ elements show contract/contract-php-security
Enthaltene Regeln:
├── rule/sql-prepared-required
├── rule/xss-output-encoding
├── rule/input-validation
└── ... (12 weitere)
Verwendet von:
├── project/karlkratz-de
├── project/nevoteam-de
└── project/masterdev
Änderung an diesem Vertrag betrifft: 3 Projekte, 15 RegelnDiese Einheitlichkeit macht es möglich, das gesamte System zu analysieren. Welche Regeln werden nirgends verwendet? Welche Verträge haben widersprüchliche Definitionen? Welche Werkzeuge fehlen noch? Das System kann sich selbst prüfen, weil alle Informationen in einem Format vorliegen.
2. Element-Typen
Das Elements-System kennt 14 verschiedene Typen. Jeder Typ hat eine bestimmte Funktion. Die Typen lassen sich in vier Gruppen einteilen: Regeln und Verträge, Werkzeuge und Prozesse, Projektdefinitionen sowie Vorlagen und Spezifikationen.
Regeln und Verträge
Rule (Regel): Eine einzelne Prüfung. Beispiel: "SQL-Abfragen müssen parametrisiert sein". Eine Regel beschreibt, was erlaubt oder verboten ist, und enthält oft ein Muster, das im Code gesucht wird. Das System enthält über 300 Regeln.
$ elements show rule/xss-output-encoding
=== rule/xss-output-encoding ===
{
"name": "xss-output-encoding",
"description": "Alle Ausgaben müssen HTML-encoded werden",
"pattern": "echo\\s+\\$",
"message": "htmlspecialchars() für Ausgaben verwenden",
"severity": "error",
"fix_example": "echo htmlspecialchars($var, ENT_QUOTES, 'UTF-8');"
}Contract (Vertrag): Eine Sammlung von Regeln, die zusammengehören. Der Vertrag "PHP Security" fasst alle sicherheitsrelevanten Regeln für PHP zusammen. Verträge machen es einfacher, viele Regeln auf einmal anzuwenden. Das System enthält 23 Verträge.
$ elements show contract/contract-php-security
=== contract/contract-php-security ===
{
"name": "contract-php-security",
"description": "Sicherheitsregeln für PHP-Entwicklung",
"rules": [
"sql-prepared-required",
"xss-output-encoding",
"input-validation-required",
"file-upload-validation",
"session-security",
"error-handling-no-details"
],
"applies_to": {
"languages": ["php"],
"paths": ["src/", "public/"]
}
}
Dieser Vertrag enthält 6 Regeln und gilt für PHP-Dateien in src/ und public/Werkzeuge und Aktionen
Tool (Werkzeug): Ein Programm, das zur Verfügung steht. Beispiel: Das Werkzeug "http" beschreibt, wie HTTP-Anfragen ausgeführt werden. Ein Werkzeug-Element enthält den Pfad zum Programm, die verfügbaren Optionen und Beispiele für die Verwendung.
$ elements show tool/db_sql
=== tool/db_sql ===
{
"name": "db_sql",
"description": "Datenbank-Abfragen ausführen",
"path": "/var/www/tools/db_sql/db_sql.py",
"usage": "db_sql query -s -d -q ",
"options": {
"-s": "Server (ki, localhost)",
"-d": "Datenbank",
"-q": "SQL-Query",
"--json": "JSON-Ausgabe",
"--limit": "Ergebnisse limitieren"
},
"examples": [
"db_sql query -s ki -d masterdev -q 'SELECT * FROM users LIMIT 5'",
"db_sql query -s ki -d masterdev -q 'SHOW TABLES' --json"
]
}Action (Aktion): Ein Befehl, der normalerweise nicht direkt verwendet werden soll. Beispiel: "curl" ist als Action definiert, weil stattdessen das Werkzeug "http" verwendet werden soll. Actions dienen als Hinweis für die KI, welche Alternativen existieren.
$ elements show action/curl
=== action/curl ===
{
"name": "curl",
"description": "HTTP-Anfragen via curl - NICHT DIREKT VERWENDEN",
"alternative": "tool/http",
"reason": "http bietet bessere Fehlerbehandlung und Logging",
"message": "Verwende 'http' statt 'curl' für HTTP-Anfragen"
}Handler: Ein ausführbares Modul für bestimmte Aufgaben. Beispiel: Der Handler "code" kümmert sich um Code-Operationen, der Handler "mail" um E-Mail-Versand. Handler sind komplexer als Werkzeuge und enthalten oft mehrere Komponenten.
$ elements show handler/mail
=== handler/mail ===
{
"name": "mail",
"description": "E-Mail-Versand und -Verwaltung",
"components": [
"sender",
"template-engine",
"queue"
],
"config": {
"smtp_server": "mail.karlkratz.de",
"default_from": "noreply@karlkratz.de"
}
}Ablauf und Struktur
Process (Prozess): Eine Abfolge von Schritten. Ein Prozess beschreibt, in welcher Reihenfolge Aufgaben erledigt werden. Beispiel: Der Prozess "Code erstellen" definiert die Schritte von der Planung bis zur Fertigstellung.
$ elements show process/code-create
=== process/code-create ===
{
"name": "code-create",
"description": "Ablauf für neue Code-Erstellung",
"steps": [
{
"name": "analyze",
"description": "Anforderungen verstehen",
"tools": ["elements"]
},
{
"name": "plan",
"description": "Implementierung planen",
"output": "todo-list"
},
{
"name": "implement",
"description": "Code schreiben",
"contracts": ["contract-php-security"]
},
{
"name": "verify",
"description": "Prüfen und testen",
"tools": ["test-runner"]
}
]
}Hook: Ein Eingriffspunkt im Ablauf. Hooks erlauben es, auf bestimmte Ereignisse zu reagieren. Beispiel: Der Hook "PreFileWrite" wird ausgelöst, bevor eine Datei geschrieben wird. Er kann Prüfungen durchführen oder Änderungen vornehmen.
$ elements list hook --limit=5
hook (55)
├── pre-file-open Vor dem Öffnen einer Datei
├── pre-file-write Vor dem Schreiben einer Datei
├── post-file-write Nach dem Schreiben einer Datei
├── session-start Bei Session-Start
└── permission-check Bei BerechtigungsprüfungHook-Action: Eine Aktion, die von einem Hook ausgelöst wird. Während der Hook das Ereignis beschreibt, definiert die Hook-Action, was konkret passieren soll.
Projekte und Konfiguration
Project (Projekt): Eine Projektdefinition. Enthält den Namen, den Pfad und projektspezifische Einstellungen. Beispiel: Das Projekt "karlkratz.de" mit seinem Pfad und den zugehörigen Verträgen.
$ elements show project/karlkratz-de
=== project/karlkratz-de ===
{
"name": "karlkratz-de",
"path": "/var/www/dev.karlkratz.de",
"production_path": "/var/www/karlkratz.de",
"languages": ["php", "javascript", "css"],
"database": "karlkratz_de",
"contracts": [
"contract-php-security",
"contract-php-database",
"contract-kk-page-structure",
"contract-kk-content-style",
"contract-css-fundamentals"
]
}Config (Konfiguration): Einstellungen, die mehrere Elemente betreffen. Beispiel: Die Konfiguration "code-extensions" listet alle Dateiendungen auf, die als Code gelten. Konfigurationen sind allgemeiner als Projektdefinitionen.
$ elements show config/code-extensions
=== config/code-extensions ===
{
"name": "code-extensions",
"description": "Dateiendungen, die als Code behandelt werden",
"extensions": {
"php": [".php", ".phtml"],
"javascript": [".js", ".mjs", ".jsx"],
"typescript": [".ts", ".tsx"],
"python": [".py"],
"css": [".css", ".scss", ".less"]
}
}Component (Komponente): Eine Sprachdefinition. Die Komponente "php" enthält Regeln und Muster, die speziell für PHP gelten. Die Komponente "python" das Gleiche für Python. Komponenten werden von Verträgen referenziert.
Vorlagen und Spezifikationen
Template (Vorlage): Ein wiederverwendbares Code-Muster. Beispiel: Die Vorlage "php/page/hauptseite" definiert, wie eine Hauptseite in PHP strukturiert sein soll. Vorlagen sparen Zeit und sorgen für Konsistenz.
$ elements list template
template (8)
├── php/page/hauptseite Struktur für Hauptseiten
├── php/page/unterseite Struktur für Unterseiten
├── php/service/base Basis-Service-Klasse
├── php/controller/api API-Controller-Template
├── js/component/base React/JS-Komponente
├── css/module/base CSS-Modul-Vorlage
├── python/script/cli CLI-Script-Vorlage
└── sql/migration/base Datenbank-MigrationSpec (Spezifikation): Eine Beschreibung, welche Felder ein Element haben muss. Die Spezifikation für "contract" definiert, dass jeder Vertrag einen Namen, eine Beschreibung und eine Liste von Regeln braucht. Spezifikationen dienen der Validierung.
$ elements show spec/rule
=== spec/rule ===
{
"name": "rule",
"description": "Spezifikation für Rule-Elemente",
"required_fields": [
{"name": "name", "type": "string"},
{"name": "description", "type": "string"},
{"name": "pattern", "type": "string"},
{"name": "message", "type": "string"},
{"name": "severity", "type": "enum", "values": ["error", "warning", "info"]}
],
"optional_fields": [
{"name": "applies_to", "type": "array"},
{"name": "fix_example", "type": "string"},
{"name": "tags", "type": "array"}
]
}Base: Grundlegende Definitionen, die von anderen Elementen verwendet werden. Beispiel: Die Base "verbs" enthält die erlaubten Verben wie "create", "update", "delete". Bases sind die Fundamente des Systems.
Übersicht
$ elements stats
=== Elements Statistics ===
Typ Aktiv Inaktiv Beschreibung
─────────────────────────────────────────────────────────────────
rule 316 12 Einzelne Prüfungen
hook 55 3 Eingriffspunkte im Ablauf
contract 23 2 Regel-Sammlungen
tool 14 1 Verfügbare Werkzeuge
action 10 0 Nicht empfohlene Befehle
spec 10 0 Validierungsregeln
template 8 1 Code-Vorlagen
handler 6 0 Ausführbare Module
config 4 0 Globale Einstellungen
project 4 0 Projektdefinitionen
base 3 0 Grundlegende Definitionen
component 3 0 Sprachdefinitionen
hook-action 3 0 Hook-Reaktionen
process 2 0 Ablauf-Definitionen
─────────────────────────────────────────────────────────────────
Gesamt 461 193. CLI-Referenz
Das Elements-System wird über die Kommandozeile bedient. Die wichtigsten Operationen sind: Elemente auflisten, Details anzeigen, Qualität prüfen.
Elemente auflisten
Der Befehl elements list zeigt alle aktiven Elemente. Die Ausgabe ist nach Typ gruppiert.
$ elements list
=== Elements Registry ===
contract (23)
├── contract-api-design
├── contract-claude-code-hooks
├── contract-code-process
├── contract-css-fundamentals
├── contract-documentation
├── contract-javascript-base
├── contract-kk-content-style
├── contract-kk-page-structure
├── contract-php-database
├── contract-php-security
└── ... (13 weitere)
rule (316)
├── api-consistent-error-format
├── api-http-status-codes
├── api-json-response
└── ... (313 weitere)
tool (14)
├── browser
├── db_sql
├── download
├── http
└── ... (10 weitere)Bei über 400 Elementen ist die vollständige Liste lang. Deshalb lässt sich die Ausgabe auf einen bestimmten Typ einschränken:
$ elements list contract
contract (23)
├── contract-api-design
├── contract-claude-code-hooks
├── contract-code-process
├── contract-css-fundamentals
├── contract-documentation
├── contract-javascript-base
├── contract-kk-content-style
├── contract-kk-page-structure
├── contract-php-database
├── contract-php-security
├── contract-php-template
├── contract-python-base
├── contract-python-database
├── contract-python-elements
├── contract-python-tools
├── contract-python-standard
├── contract-shell-scripts
├── contract-sql-base
├── contract-system-config
├── contract-template-variables
├── contract-typescript-base
├── contract-workflow-handler
└── contract-yaml-configDetails anzeigen
Der Befehl elements show zeigt die vollständige Definition eines Elements. Das Format ist immer typ/name:
$ elements show contract/contract-php-security
=== contract/contract-php-security ===
Version: 3
Status: aktiv
Erstellt: 2024-11-15 14:23:07
Autor: karl
Definition:
{
"name": "contract-php-security",
"description": "Sicherheitsregeln für PHP-Entwicklung",
"rules": [
"sql-prepared-required",
"xss-output-encoding",
"input-validation-required",
"file-upload-validation",
"session-security",
"error-handling-no-details"
],
"applies_to": {
"languages": ["php"],
"paths": ["src/", "public/"]
}
}Die Ausgabe enthält die Version, das Erstellungsdatum, den Autor und die komplette Definition als JSON. Bei Verträgen sieht man die Liste der enthaltenen Regeln. Bei Werkzeugen sieht man den Pfad und die Optionen:
$ elements show tool/http
=== tool/http ===
Version: 2
Status: aktiv
Erstellt: 2024-09-03 10:15:42
Autor: system
Definition:
{
"name": "http",
"description": "HTTP-Anfragen ausführen",
"path": "/var/www/tools/http/http.py",
"usage": "http [options]",
"options": {
"-H": "Header hinzufügen",
"-d": "Request Body",
"-o": "Output-Datei",
"--json": "JSON-Ausgabe"
},
"examples": [
"http GET https://api.example.com/users",
"http POST https://api.example.com/users -d '{\"name\": \"Test\"}'"
]
}Statistiken
Der Befehl elements stats zeigt eine Übersicht, wie viele Elemente jeder Typ enthält:
$ elements stats
=== Elements Statistics ===
Typ Aktiv Inaktiv Gesamt
─────────────────────────────────────────
rule 316 12 328
hook 55 3 58
contract 23 2 25
tool 14 1 15
action 10 0 10
spec 10 0 10
template 8 1 9
handler 6 0 6
config 4 0 4
project 4 0 4
base 3 0 3
component 3 0 3
hook-action 3 0 3
process 2 0 2
─────────────────────────────────────────
Gesamt 461 19 480Qualitätsprüfung
Der Befehl elements quality prüft das System auf Probleme:
$ elements quality
=== Elements Quality Check ===
Pattern-Duplikate: 0 ✓
Fehlende Descriptions: 3 ⚠
Inaktive Elements: 19 ℹ
Verwaiste Rules: 5 ⚠
─── Fehlende Descriptions ───
• rule/legacy-api-check
• config/deprecated-paths
• hook/debug-output
─── Verwaiste Rules ───
• rule/old-mysql-connect (in keinem Contract)
• rule/deprecated-curl (in keinem Contract)
• rule/legacy-session (in keinem Contract)
• rule/temp-workaround-1 (in keinem Contract)
• rule/temp-workaround-2 (in keinem Contract)Die Prüfung findet vier Arten von Problemen:
- Pattern-Duplikate: Zwei Regeln, die dasselbe Muster prüfen.
- Fehlende Beschreibungen: Elemente ohne description-Feld.
- Inaktive Elemente: Elemente, die deaktiviert wurden.
- Verwaiste Regeln: Regeln, die in keinem Vertrag verwendet werden.
Versionshistorie
Der Befehl elements history zeigt alle Versionen eines Elements:
$ elements history contract/contract-php-security
=== Versionshistorie: contract/contract-php-security ===
Version Status Datum Autor Änderung
──────────────────────────────────────────────────────────────
v3 aktiv 2024-11-15 14:23:07 karl +2 rules
v2 inaktiv 2024-09-20 09:15:33 karl +1 rule
v1 inaktiv 2024-07-01 11:00:00 system InitialSo lässt sich nachvollziehen, wie sich ein Element über die Zeit verändert hat.
Validierung
Der Befehl elements validate prüft ein einzelnes Element gegen seine Spezifikation:
$ elements validate contract/contract-php-security
=== Validierung: contract/contract-php-security ===
Spec: contract
Status: ✓ Gültig
Geprüfte Felder:
✓ name (required, string)
✓ description (required, string)
✓ rules (required, array)
✓ applies_to (optional, object)Bei Fehlern erscheint eine Meldung, was fehlt oder falsch ist:
$ elements validate contract/incomplete-contract
=== Validierung: contract/incomplete-contract ===
Spec: contract
Status: ✗ Ungültig
Fehler:
✗ description: Pflichtfeld fehlt
✗ rules: Muss mindestens 1 Element enthaltenElemente erstellen und ändern
Neue Elemente werden mit elements create angelegt. Die Definition wird als JSON über die Standardeingabe oder als Datei übergeben:
$ elements create rule meine-neue-regel
Definition eingeben (JSON):
{
"name": "meine-neue-regel",
"description": "Prüft auf veraltete Funktionsaufrufe",
"pattern": "mysql_query\\(",
"message": "Verwende PDO statt mysql_* Funktionen",
"severity": "error"
}
✓ Element rule/meine-neue-regel erstellt (v1)Bestehende Elemente werden mit elements update geändert:
$ elements update rule/meine-neue-regel
Aktuelle Version: 1
Neue Definition eingeben (JSON):
{
"name": "meine-neue-regel",
"description": "Prüft auf veraltete mysql_* Funktionsaufrufe",
"pattern": "mysql_(query|connect|select_db)\\(",
"message": "Verwende PDO statt mysql_* Funktionen",
"severity": "error"
}
✓ Element rule/meine-neue-regel aktualisiert (v1 überschrieben)Mit der Option --new-version wird eine neue Version angelegt, statt die bestehende zu überschreiben:
$ elements update rule/meine-neue-regel --new-version
Aktuelle Version: 1
Neue Definition eingeben (JSON):
{ ... }
✓ Element rule/meine-neue-regel aktualisiert
v1 → inaktiv
v2 → aktivElemente deaktivieren
Der Befehl elements delete deaktiviert ein Element:
$ elements delete rule/meine-alte-regel
Element: rule/meine-alte-regel (v2)
Aktion: Deaktivieren (bleibt in DB erhalten)
Fortfahren? [j/N] j
✓ Element rule/meine-alte-regel deaktiviertDas Element wird nicht gelöscht, sondern als inaktiv markiert. Es bleibt in der Datenbank erhalten. Mit der Option --hard wird es endgültig entfernt:
$ elements delete rule/testregel --hard
⚠ WARNUNG: Element wird unwiderruflich gelöscht!
Element: rule/testegel (v1)
Aktion: Endgültig löschen
Fortfahren? [j/N] j
✓ Element rule/testegel gelöscht (alle Versionen)4. Architektur
Das Elements-System besteht aus drei Hauptkomponenten: der Engine, dem Resolver und den Models. Alle Daten liegen in einer MySQL-Datenbank. Die Kommunikation erfolgt über eine Kommandozeilen-Schnittstelle.
Die Datenbank
Im Zentrum steht eine einzige Tabelle namens elements. Sie enthält alle Elemente unabhängig von ihrem Typ. Die wichtigsten Spalten sind:
=== Tabellenstruktur: elements ===
┌────────────┬──────────────┬─────────────────────────────────────┐
│ Spalte │ Typ │ Beschreibung │
├────────────┼──────────────┼─────────────────────────────────────┤
│ id │ INT │ Eindeutige Nummer │
│ type │ VARCHAR(50) │ rule, contract, tool, ... │
│ name │ VARCHAR(100) │ Eindeutiger Name │
│ definition │ JSON │ Vollständige Definition │
│ version │ INT │ Versionsnummer │
│ is_active │ BOOLEAN │ Aktiv oder deaktiviert │
│ created_at │ DATETIME │ Erstellungszeitpunkt │
│ created_by │ VARCHAR(50) │ Autor │
└────────────┴──────────────┴─────────────────────────────────────┘Diese Struktur macht es möglich, beliebige Elementtypen zu speichern, ohne die Datenbank zu ändern. Die Flexibilität liegt im JSON-Feld definition, das je nach Typ unterschiedliche Felder enthält.
Die Engine
Die Engine ist das Herzstück des Systems. Sie kümmert sich um alle Datenbankoperationen: Elemente laden, speichern, aktualisieren, löschen. Die Engine verwaltet auch einen internen Zwischenspeicher, damit häufig genutzte Elemente nicht jedes Mal aus der Datenbank geladen werden müssen.
=== Engine-Funktionen ===
┌─────────────────────────────────────────────────────────────────┐
│ Funktion │ Beschreibung │
├─────────────────────────────┼───────────────────────────────────┤
│ get(typ, name) │ Lädt ein Element │
│ list(typ) │ Listet alle Elemente eines Typs │
│ create(typ, name, def) │ Erstellt neues Element │
│ update(typ, name, def) │ Aktualisiert bestehendes Element │
│ delete(typ, name) │ Deaktiviert oder löscht Element │
│ validate(typ, def) │ Prüft gegen Spezifikation │
└─────────────────────────────┴───────────────────────────────────┘Der Resolver
Der Resolver löst Abhängigkeiten auf. Wenn ein Vertrag geladen wird, enthält er nur die Namen der zugehörigen Regeln. Der Resolver lädt diese Regeln und fügt sie zusammen. Wenn ein Prozess geladen wird, enthält er Verweise auf Handler und Werkzeuge. Der Resolver löst auch diese Verweise auf.
=== Resolver in Aktion ===
Eingabe: contract/contract-php-security
1. Vertrag laden
│
▼
{
"name": "contract-php-security",
"rules": ["sql-prepared", "xss-encode", "input-validate"]
}
│
▼
2. Regeln auflösen
│
├── rule/sql-prepared → laden
├── rule/xss-encode → laden
└── rule/input-validate → laden
│
▼
3. Zusammenfügen
Ausgabe: Vollständiger Vertrag mit allen Regel-Definitionen
{
"name": "contract-php-security",
"rules": [
{ "name": "sql-prepared", "pattern": "...", ... },
{ "name": "xss-encode", "pattern": "...", ... },
{ "name": "input-validate", "pattern": "...", ... }
]
}Der Resolver arbeitet rekursiv. Ein Vertrag kann auf andere Verträge verweisen. Der Resolver folgt diesen Verweisen und sammelt alle benötigten Elemente ein. Am Ende steht ein vollständig aufgelöster Kontext, den die KI oder ein Werkzeug direkt verwenden kann.
Die Models
Models sind Klassen, die die Struktur der Elemente beschreiben. Jeder Elementtyp hat ein eigenes Model mit den erlaubten Feldern und Datentypen. Die Models dienen zwei Zwecken:
Erstens machen sie den Code lesbarer. Statt mit Dictionaries zu arbeiten, arbeitet der Code mit typisierten Objekten. Ein Element hat Eigenschaften wie element.name oder element.definition.
Zweitens ermöglichen sie Validierung. Wenn ein neues Element erstellt wird, prüft das System, ob alle Pflichtfelder vorhanden sind und die richtigen Datentypen haben.
=== Model-Validierung ===
$ elements validate rule/test-rule
Model: RuleModel
Pflichtfelder:
✓ name (string)
✓ description (string)
✓ pattern (string, regex)
✓ message (string)
✓ severity (enum: error|warning|info)
Optionale Felder:
○ applies_to (object)
○ examples (array)
○ tags (array)Der Datenfluss
Wenn Claude Code eine Datei bearbeitet, passiert Folgendes:
=== Datenfluss: Datei bearbeiten ===
┌──────────────────┐
│ Claude Code │ Entwickler öffnet PHP-Datei
│ öffnet Datei │
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Hook: │ "Welche Verträge gelten
│ PreFileOpen │ für diese Datei?"
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Elements Engine │ Sucht passende Verträge
│ lädt Verträge │ (PHP + Projekt + Pfad)
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Resolver │ Löst Vertrag auf, lädt
│ sammelt Regeln │ alle enthaltenen Regeln
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Regeln als │ Claude Code sieht die
│ Kontext │ Regeln als Hinweise
└────────┬─────────┘
│
▼
┌──────────────────┐
│ Code wird │ Vorschläge berücksichtigen
│ geschrieben │ die geladenen Regeln
└──────────────────┘Dieser Ablauf ist für den Benutzer unsichtbar. Er passiert im Hintergrund, jedes Mal wenn eine Datei geöffnet oder bearbeitet wird.
Komponenten-Übersicht
Die wichtigsten Dateien des Systems:
=== System-Komponenten ===
┌────────────────────────────────────────────────────────────────┐
│ Komponente │ Aufgabe │
├────────────────┼───────────────────────────────────────────────┤
│ engine │ Datenbankoperationen, Cache-Verwaltung │
│ resolver │ Abhängigkeitsauflösung, Referenz-Verfolgung │
│ models │ Datenmodelle, Validierungslogik │
│ command │ Kommandozeilen-Schnittstelle │
│ specs │ Spezifikationen für jeden Elementtyp │
└────────────────┴───────────────────────────────────────────────┘
Zusammenspiel:
CLI-Befehl
│
▼
command.py ───────────────────┐
│ │
▼ ▼
engine.py resolver.py
│ │
▼ │
Datenbank ◄───────────────────┘
│
▼
Cache5. Element-Lebenszyklus
Jedes Element durchläuft einen Lebenszyklus: Es wird erstellt, möglicherweise mehrfach aktualisiert und irgendwann deaktiviert. Das System protokolliert jeden dieser Schritte.
Erstellung
Ein neues Element entsteht durch den Befehl elements create. Das System prüft zuerst, ob bereits ein Element mit demselben Typ und Namen existiert. Falls ja, wird die Erstellung abgelehnt.
$ elements create rule sql-injection-check
Definition eingeben (JSON):
{
"name": "sql-injection-check",
"description": "Verhindert SQL-Injection durch String-Konkatenation",
"pattern": "\\$_(GET|POST|REQUEST)\\[.*\\].*\\.",
"message": "Benutzereingaben nicht direkt in SQL verwenden",
"severity": "error"
}
Validierung...
✓ name: vorhanden
✓ description: vorhanden
✓ pattern: gültiger Regex
✓ severity: erlaubter Wert
✓ Element rule/sql-injection-check erstellt (v1)Dann prüft das System die Definition gegen die Spezifikation des Typs. Fehlen Pflichtfelder oder haben Felder den falschen Datentyp, wird die Erstellung abgelehnt:
$ elements create rule incomplete-rule
Definition eingeben (JSON):
{
"name": "incomplete-rule"
}
Validierung...
✓ name: vorhanden
✗ description: Pflichtfeld fehlt
✗ pattern: Pflichtfeld fehlt
✗ Element nicht erstellt - ValidierungsfehlerDas neue Element erhält automatisch Version 1, den Status "aktiv" und einen Zeitstempel. Der Autor wird aus dem Kontext übernommen, in dem der Befehl ausgeführt wurde.
Aktualisierung
Bestehende Elemente werden mit elements update geändert. Auch hier prüft das System zuerst die Definition gegen die Spezifikation.
Es gibt zwei Arten der Aktualisierung:
In-Place-Update: Die bestehende Definition wird überschrieben. Die Versionsnummer bleibt gleich. Diese Methode eignet sich für kleine Korrekturen, etwa Tippfehler in Beschreibungen.
$ elements update rule/sql-injection-check
Aktuelle Version: 1
Neue Definition eingeben (JSON):
{
"name": "sql-injection-check",
"description": "Verhindert SQL-Injection durch String-Konkatenation in Queries",
"pattern": "\\$_(GET|POST|REQUEST)\\[.*\\].*\\.",
"message": "Benutzereingaben nicht direkt in SQL verwenden - PDO nutzen",
"severity": "error"
}
✓ Element rule/sql-injection-check aktualisiert (v1 überschrieben)Versions-Update: Die alte Version wird als inaktiv markiert. Eine neue Version wird erstellt. Die alte Version bleibt in der Datenbank erhalten. Diese Methode eignet sich für inhaltliche Änderungen, bei denen die Historie wichtig ist.
$ elements update rule/sql-injection-check --new-version
Aktuelle Version: 1
Neue Definition eingeben (JSON):
{
"name": "sql-injection-check",
"description": "Verhindert SQL-Injection in allen Formen",
"pattern": "(\\$_(GET|POST|REQUEST)\\[|\\\"\\s*\\.\\s*\\$)",
"message": "Keine dynamischen Werte in SQL - nur Prepared Statements",
"severity": "error"
}
✓ Element rule/sql-injection-check aktualisiert
v1 → inaktiv (archiviert)
v2 → aktivVersionierung
Jedes Element kann mehrere Versionen haben. Zu jedem Zeitpunkt ist genau eine Version aktiv. Die anderen sind als inaktiv markiert, bleiben aber abrufbar.
Der Befehl elements history zeigt alle Versionen eines Elements:
$ elements history rule/sql-injection-check
=== Versionshistorie: rule/sql-injection-check ===
Version Status Datum Autor Änderung
──────────────────────────────────────────────────────────────
v3 aktiv 2024-12-01 09:30:15 karl Pattern erweitert
v2 inaktiv 2024-10-15 14:22:08 karl Message verbessert
v1 inaktiv 2024-08-01 11:00:00 system Initial
Details zu einer Version anzeigen:
$ elements show rule/sql-injection-check --version=1So lässt sich nachvollziehen, wie sich eine Definition über die Zeit verändert hat.
Versionen können nicht gelöscht werden. Diese Einschränkung ist beabsichtigt. Sie stellt sicher, dass die Historie vollständig bleibt und Änderungen nachvollziehbar sind.
Deaktivierung
Der Befehl elements delete deaktiviert ein Element. Das bedeutet: Es wird nicht gelöscht, sondern als inaktiv markiert. Bei Abfragen erscheint es nicht mehr, aber es bleibt in der Datenbank erhalten.
$ elements delete rule/alte-regel
Element: rule/alte-regel (v2)
Status: aktiv
Letzte Änderung: 2024-09-15 von karl
Aktion: Deaktivieren
(Element bleibt in DB, kann reaktiviert werden)
Fortfahren? [j/N] j
✓ Element rule/alte-regel deaktiviert
Hinweis: Reaktivierung möglich mit:
$ elements update rule/alte-regel --new-versionDeaktivierte Elemente können reaktiviert werden, indem sie mit update und --new-version erneut angelegt werden.
Die Option --hard löscht ein Element endgültig. Diese Option sollte nur verwendet werden, wenn ein Element versehentlich erstellt wurde und keine historische Bedeutung hat.
$ elements delete rule/testeintrag --hard
⚠ WARNUNG: Unwiderrufliche Löschung!
Alle Versionen werden entfernt.
Historie geht verloren.
Element: rule/testeintrag
Versionen: 1
Endgültig löschen? [j/N] j
✓ Element rule/testeintrag gelöscht (1 Version entfernt)Logging
Jede Operation wird in einer separaten Tabelle protokolliert. Das Log enthält:
- Welches Element betroffen war (Typ und Name).
- Welche Aktion ausgeführt wurde (create, update, delete).
- Wann die Aktion stattfand.
- Wer die Aktion ausgeführt hat.
- Die Eingabedaten (bei create und update).
$ elements log --last=5
=== Elements Log (letzte 5 Einträge) ===
Datum Aktion Element Autor
────────────────────────────────────────────────────────────────────
2024-12-01 09:30:15 update rule/sql-injection-check karl
2024-12-01 09:15:02 create rule/new-validation-rule karl
2024-11-30 16:45:33 delete rule/deprecated-check system
2024-11-30 14:20:11 update contract/contract-php-security karl
2024-11-30 10:05:44 create hook/pre-commit-validate karl
Details: elements log --show=Das Log ist schreibgeschützt. Einträge können nicht gelöscht oder geändert werden. Das garantiert eine lückenlose Nachvollziehbarkeit aller Änderungen am System.
Cache
Um die Datenbank zu entlasten, speichert die Engine häufig genutzte Elemente in einem Zwischenspeicher. Dieser Cache wird automatisch aktualisiert, wenn ein Element geändert wird.
=== Interner Ablauf bei Element-Zugriff ===
1. Anfrage: elements show contract/contract-php-security
│
▼
2. Cache prüfen: Ist Element im Cache?
│
┌─────┴─────┐
│ ja │ nein
▼ ▼
3a. Aus Cache 3b. Aus Datenbank laden
laden und in Cache speichern
│ │
└───────┬───────┘
▼
4. Element zurückgebenDer Cache ist ein internes Detail, das für die Benutzung des Systems keine Rolle spielt. Er sorgt lediglich dafür, dass häufig verwendete Elemente schneller geladen werden.
6. Quality Checks
Ein System mit über 400 Elementen kann schnell unübersichtlich werden. Das Elements-System enthält deshalb automatische Qualitätsprüfungen, die Probleme aufdecken, bevor sie sich ausbreiten.
Der Quality-Befehl
Der Befehl elements quality führt alle Prüfungen auf einmal aus:
$ elements quality
=== Elements Quality Check ===
Prüfung Ergebnis
─────────────────────────────────────────────
Pattern-Duplikate 0 ✓
Fehlende Descriptions 3 ⚠
Inaktive Elements 19 ℹ
Verwaiste Rules 5 ⚠
Zirkuläre Referenzen 0 ✓
Ungültige Referenzen 0 ✓
─────────────────────────────────────────────
Gesamt-Status ⚠ 8 ProblemeWenn Probleme gefunden werden, erscheinen darunter Details: Welche Elemente sind betroffen und warum.
Pattern-Duplikate
Regeln enthalten oft Muster, die im Code gesucht werden. Wenn zwei Regeln dasselbe Muster haben, prüfen sie dasselbe, aber aus verschiedenen Verträgen. Das ist meistens ein Fehler.
$ elements quality --check=duplicates
=== Pattern-Duplikate ===
Gefunden: 2 Duplikate
┌────────────────────────────────────────────────────────────────┐
│ Pattern: mysql_query\( │
├────────────────────────────────────────────────────────────────┤
│ • rule/no-mysql-query (contract-php-security) │
│ • rule/deprecated-mysql (contract-php-legacy) │
└────────────────────────────────────────────────────────────────┘
┌────────────────────────────────────────────────────────────────┐
│ Pattern: eval\( │
├────────────────────────────────────────────────────────────────┤
│ • rule/no-eval (contract-php-security) │
│ • rule/dangerous-eval (contract-code-review) │
└────────────────────────────────────────────────────────────────┘
Empfehlung:
Eine der duplizierten Regeln löschen oder
Pattern unterscheidbar machen.Die Prüfung findet alle Regeln mit identischem Pattern und listet sie auf. Die Lösung ist, eine der Regeln zu löschen oder die Muster unterscheidbar zu machen.
Fehlende Beschreibungen
Jedes Element sollte eine Beschreibung haben, die erklärt, was es tut. Elemente ohne Beschreibung sind schwer zu verstehen, besonders wenn der ursprüngliche Autor nicht mehr verfügbar ist.
$ elements quality --check=descriptions
=== Fehlende Beschreibungen ===
Gefunden: 3 Elemente ohne description
Typ Name Erstellt
────────────────────────────────────────────────────
rule legacy-api-check 2024-03-15
config deprecated-paths 2024-05-22
hook debug-output 2024-08-10
Beheben:
$ elements update rule/legacy-api-check
→ description-Feld hinzufügenDie Prüfung findet alle Elemente, bei denen das Feld description fehlt oder leer ist. Die Lösung ist, eine sinnvolle Beschreibung zu ergänzen.
Inaktive Elemente
Deaktivierte Elemente bleiben in der Datenbank. Mit der Zeit sammeln sich davon viele an. Die Prüfung zählt, wie viele inaktive Elemente existieren.
$ elements quality --check=inactive
=== Inaktive Elemente ===
Gefunden: 19 inaktive Elemente
Nach Typ:
rule 12 ████████████
contract 4 ████
hook 2 ██
template 1 █
Nach Alter:
> 1 Jahr 8 ████████
> 6 Monate 5 █████
> 3 Monate 4 ████
< 3 Monate 2 ██
Älteste inaktive Elemente:
• rule/old-mysql-syntax (inaktiv seit 2023-01-15)
• rule/ie-compatibility (inaktiv seit 2023-03-22)
• contract/legacy-checks (inaktiv seit 2023-05-10)
Aufräumen:
$ elements delete rule/old-mysql-syntax --hardEine hohe Zahl ist nicht unbedingt ein Problem. Sie kann aber darauf hinweisen, dass alte Elemente regelmäßig aufgeräumt werden sollten. Elemente, die seit Jahren inaktiv sind und keine historische Bedeutung haben, können mit --hard endgültig gelöscht werden.
Verwaiste Regeln
Regeln sind dazu gedacht, in Verträgen verwendet zu werden. Eine Regel, die in keinem Vertrag vorkommt, hat keinen Effekt. Sie wird nie angewendet.
$ elements quality --check=orphans
=== Verwaiste Regeln ===
Gefunden: 5 Regeln ohne Vertrag
Regel Erstellt Autor
─────────────────────────────────────────────────────
rule/temp-workaround-1 2024-06-01 dev
rule/temp-workaround-2 2024-06-01 dev
rule/old-mysql-connect 2024-02-15 system
rule/deprecated-curl 2024-04-20 karl
rule/legacy-session 2024-03-10 system
Mögliche Aktionen:
1. Zu bestehendem Vertrag hinzufügen:
$ elements show contract/contract-php-security
→ rules-Array erweitern
2. Neuen Vertrag erstellen:
$ elements create contract cleanup-rules
3. Regel deaktivieren:
$ elements delete rule/temp-workaround-1Die Prüfung findet alle aktiven Regeln, die in keinem aktiven Vertrag referenziert sind. Die Lösung ist, die Regel entweder einem Vertrag zuzuordnen oder zu deaktivieren.
Regelmäßige Prüfung
Die Qualitätsprüfung sollte regelmäßig ausgeführt werden, etwa wöchentlich. Je früher ein Problem entdeckt wird, desto einfacher ist es zu beheben.
=== Empfohlener Rhythmus ===
┌────────────────────────────────────────────────────────────────┐
│ Zeitpunkt │ Prüfung │
├────────────────────────┼───────────────────────────────────────┤
│ Nach jeder Änderung │ elements validate │
│ Wöchentlich │ elements quality │
│ Nach Umstrukturierung │ elements quality --verbose │
│ Vor Release │ elements quality --strict │
└────────────────────────┴───────────────────────────────────────┘Ein guter Zeitpunkt ist nach größeren Änderungen am System: Wenn viele neue Regeln hinzugefügt wurden, wenn Verträge umstrukturiert wurden, oder wenn alte Elemente aufgeräumt wurden.
Selbstanwendung
Das Elements-System wendet dieselben Prinzipien auf sich selbst an, die es anderen auferlegt. Keine Duplikate, keine undokumentierten Einträge, keine verwaisten Definitionen.
=== Selbstprüfung ===
Das System prüft sich selbst:
┌─────────────────────────────────────────────────────────────┐
│ "Jede Regel muss eine Beschreibung haben" │
│ │
│ ↓ gilt auch für ↓ │
│ │
│ Die Regel selbst, die diese Anforderung definiert │
└─────────────────────────────────────────────────────────────┘
Konsequenz:
Wenn die Quality-Prüfung Probleme meldet,
betrifft das auch System-eigene Elemente.Diese Selbstanwendung ist kein Zufall. Sie ist ein bewusstes Designprinzip. Ein System, das Qualitätsregeln durchsetzt, sollte diese Regeln auch selbst einhalten. Sonst verliert es an Glaubwürdigkeit.
7. Integration
Das Elements-System ist Teil eines größeren Ökosystems. Es arbeitet mit Hooks, Code Intelligence und dem Workflow-System zusammen. Diese Integration macht es erst wirklich nützlich.
Integration mit Hooks
Hooks sind Eingriffspunkte, die auf bestimmte Ereignisse reagieren. Wenn Claude Code eine Datei öffnet, speichert oder bearbeitet, werden Hooks ausgelöst. Diese Hooks fragen das Elements-System nach den geltenden Regeln.
=== Hook-Ablauf: Datei öffnen ===
┌─────────────────────┐
│ Claude Code │
│ öffnet config.php │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Hook: PreFileOpen │ ← Wird automatisch ausgelöst
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Elements-Abfrage: │
│ "Welche Verträge │
│ gelten für PHP │
│ in diesem Pfad?" │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Antwort: │
│ • contract-php-security
│ • contract-php-database
│ • contract-kk-style │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Regeln geladen, │
│ als Kontext aktiv │
└─────────────────────┘Ein Beispiel: Der Hook PreFileWrite wird ausgelöst, bevor eine Datei geschrieben wird. Er fragt: Welche Verträge gelten für diese Datei? Das Elements-System antwortet mit einer Liste von Regeln. Der Hook prüft, ob der neue Code diese Regeln einhält.
=== Hook-Ablauf: Datei speichern ===
┌─────────────────────┐
│ Speichern │
│ angefordert │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Hook: PreFileWrite │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Regel-Prüfung │
│ │
│ ✓ sql-prepared │
│ ✓ xss-encoding │
│ ✗ input-validation │ ← Verstoß gefunden
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Meldung: │
│ "Zeile 45: Input │
│ nicht validiert" │
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│ Speichern │
│ abgebrochen │
└─────────────────────┘Die Hook-Definitionen selbst liegen im Elements-System. Der Typ hook beschreibt, welche Hooks existieren und wann sie ausgelöst werden. Der Typ hook-action beschreibt, was bei Auslösung passiert.
$ elements show hook/pre-file-write
=== hook/pre-file-write ===
{
"name": "pre-file-write",
"description": "Wird vor dem Speichern einer Datei ausgelöst",
"trigger": "file.write.before",
"actions": [
"hook-action/validate-contracts",
"hook-action/check-security"
],
"applies_to": {
"extensions": ["php", "js", "ts", "py"]
}
}Integration mit Code Intelligence
Code Intelligence analysiert Quellcode: Welche Klassen existieren? Welche Funktionen rufen welche anderen auf? Welche Abhängigkeiten bestehen?
=== Code Intelligence Daten ===
$ code deps UserService
UserService
├── verwendet
│ ├── DatabaseConnection
│ ├── CacheService
│ └── Logger
└── wird verwendet von
├── AuthController
├── ProfileController
└── AdminServiceDiese Informationen fließen in das Elements-System ein. Wenn eine neue Klasse erstellt wird, kann das System automatisch prüfen, ob sie den Architektur-Regeln entspricht. Wenn eine Funktion geändert wird, kann es die betroffenen Abhängigkeiten anzeigen.
=== Automatische Prüfung bei Änderung ===
Geändert: src/Services/UserService.php
Code Intelligence meldet:
3 abhängige Klassen betroffen
Elements-Prüfung:
✓ Architektur-Regeln eingehalten
✓ Keine zirkulären Abhängigkeiten
⚠ AuthController sollte geprüft werden
┌─────────────────────────────────────────────────────────────┐
│ Empfehlung: Tests für folgende Klassen ausführen: │
│ • AuthController │
│ • ProfileController │
│ • AdminService │
└─────────────────────────────────────────────────────────────┘Die Projektdefinitionen im Elements-System (Typ project) verweisen auf die Daten in Code Intelligence. So weiß das System, welche Dateien zu welchem Projekt gehören und welche Sprachen verwendet werden.
$ elements show project/karlkratz-de
{
"name": "karlkratz-de",
"path": "/var/www/dev.karlkratz.de",
"languages": ["php", "javascript", "css"],
"contracts": [
"contract-php-security",
"contract-php-database",
"contract-kk-page-structure",
"contract-kk-content-style"
],
"code_intelligence": {
"entities": 356,
"dependencies": 1196,
"last_scan": "2025-01-14 15:30:00"
}
}Integration mit dem Workflow-System
Das Workflow-System verwaltet Aufgaben: Was muss getan werden? Wer ist zuständig? Wie ist der Status?
Wenn das Elements-System ein Problem findet, kann es automatisch eine Aufgabe erstellen:
=== Automatische Task-Erstellung ===
Elements-Quality-Check meldet:
5 verwaiste Regeln gefunden
│
▼
Workflow-Task erstellt:
┌─────────────────────────────────────────────────────────────┐
│ Task #3505 │
│ "Verwaiste Regeln prüfen und zuordnen" │
│ │
│ Erstellt: 2025-01-14 16:00:00 │
│ Quelle: elements quality (automatisch) │
│ Priorität: normal │
│ │
│ Beschreibung: │
│ 5 aktive Regeln sind keinem Vertrag zugeordnet. │
│ Prüfen und entweder zuordnen oder deaktivieren. │
│ │
│ Betroffene Elemente: │
│ • rule/temp-workaround-1 │
│ • rule/temp-workaround-2 │
│ • rule/old-mysql-connect │
│ • rule/deprecated-curl │
│ • rule/legacy-session │
└─────────────────────────────────────────────────────────────┘Umgekehrt kann das Workflow-System das Elements-System abfragen. Wenn eine Aufgabe lautet "Neue Regel für SQL-Injection erstellen", kann der Bearbeiter direkt sehen, welche ähnlichen Regeln bereits existieren.
=== Task mit Elements-Kontext ===
Task: "Neue Regel für SQL-Injection erstellen"
Elements-Kontext automatisch geladen:
Ähnliche bestehende Regeln:
• rule/sql-prepared-required
"SQL-Abfragen müssen Prepared Statements verwenden"
• rule/sql-no-string-concat
"Keine String-Konkatenation in SQL-Queries"
• rule/sql-input-escape
"Benutzereingaben müssen escaped werden"
Relevante Verträge:
• contract-php-security (enthält 2 SQL-Regeln)
• contract-php-database (enthält 1 SQL-Regel)Das Zusammenspiel
Ein typischer Ablauf zeigt, wie die Systeme zusammenarbeiten:
=== Kompletter Ablauf ===
1. Entwickler öffnet PHP-Datei
│
▼
2. Hook → Elements: "Welche Verträge?"
│
▼
3. Elements lädt Verträge, Resolver sammelt Regeln
│
▼
4. Claude Code zeigt Regeln als Kontext
│
▼
5. Entwickler schreibt Code
│
▼
6. Code verletzt Regel (z.B. unsichere SQL-Query)
│
▼
7. Hook: PreFileWrite → Prüfung
│
▼
8. Verstoß gemeldet: "Zeile 45: SQL nicht parametrisiert"
│
▼
9. Code Intelligence: Verletzung protokolliert
│
▼
10. Optional: Workflow-Task erstellt
│
▼
11. Entwickler korrigiert, speichert erneut
│
▼
12. Alle Prüfungen bestanden ✓Dieser Ablauf passiert automatisch. Der Entwickler merkt davon nur die Hinweise, die Claude Code anzeigt, und die Meldungen, wenn Regeln verletzt werden.
=== Was der Entwickler sieht ===
┌─────────────────────────────────────────────────────────────┐
│ Claude Code │
│ │
│ Datei: src/Services/UserService.php │
│ Aktive Regeln: 12 (aus 3 Verträgen) │
│ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ 44 │ // Unsichere Query: String-Verkettung mit Variable │
│ │ │
│ │ ⚠ sql-prepared-required │
│ │ Verwende Prepared Statements statt Verkettung │
│ │ │
│ ─────────────────────────────────────────────────────────── │
│ │
│ Korrekter Code: │
│ $stmt = $pdo->prepare("SELECT * FROM users WHERE id = ?");│
│ $stmt->execute([$id]); │
└─────────────────────────────────────────────────────────────┘