10 — Eigenes KI-System bauen

🏗️

Grundlagen

Architektur-Prinzipien

Bevor du eigene Erweiterungen baust, verstehe die Design-Prinzipien, die Claw Code wartbar und erweiterbar machen.

Kernkonzept 10 Min

Claw Code basiert auf einem modularen Drei-Schichten-Design. Wenn du eigene Komponenten hinzufügst, solltest du diese Struktur respektieren — dann bleibt dein Code wartbar und verständlich.

🪞 Spiegelungsschicht

Dateien: commands.py, tools.py, reference_data/
Zweck: Unveränderliche JSON-Snapshots als "Quelle der Wahrheit"
Regel: Diese Schicht ändert sich nie zur Laufzeit

↓

⚙️ Orchestrierungsschicht

Dateien: runtime.py, query_engine.py
Zweck: Intelligentes Routing, Session-Management, Logik
Regel: Hier implementierst du neue Algorithmen

↓

🔧 Infrastrukturschicht

Dateien: setup.py, context.py, session_store.py
Zweck: Persistenz, Umgebung, Logging, Bootstrap
Regel: Neue Subsysteme integrieren sich hier

💡

Golden Rule

Schichten kommunizieren nur nach unten. Die Orchestrierung darf die Infrastruktur nutzen, aber nicht umgekehrt. So vermeidest du zirkuläre Abhängigkeiten.

Checkliste: Bereit zum Erweitern?

Alle Tests laufen: python3 -m unittest discover -s tests zeigt nur OKs

Verzeichnisstruktur verstanden: Ich weiß, wo src/, tests/ und reference_data/ liegen

Git-Repository initialisiert: Ich kann meine Änderungen versionieren

Backup erstellt: Original-Dateien sind gesichert oder ich arbeite in einem Fork

⌨️

Erweiterung 1

Eigene Befehle hinzufügen

Erweitere den Katalog der ~150 Befehle um deine eigenen, maßgeschneiderten Kommandos.

Einstieg 15 Min

Befehle werden in src/reference_data/commands_snapshot.json definiert. Jeder Befehl ist ein JSON-Objekt mit bestimmten Feldern.

Schritt 1: JSON-Struktur verstehen

json — commands_snapshot.json

{
  "commands": [
    {
      "name": "my-deploy",
      "responsibility": "Deployt die Anwendung auf Produktion",
      "source_hint": "deploy_module",
      "args": ["environment", "version"],
      "description": "Führt den Production-Deployment-Prozess aus"
    }
  ]
}

Schritt 2: Felder erklärt

Feld	Pflicht	Beschreibung
`name`	Ja	Eindeutiger Identifier (keine Leerzeichen)
`responsibility`	Ja	Was macht der Befehl? Wird beim Routing gescored
`source_hint`	Optional	Modul/Herkunft für Gruppierung
`args`	Optional	Liste von Argument-Namen
`description`	Optional	Ausführliche Beschreibung

Schritt 3: Befehl hinzufügen

JSON öffnen

Öffne src/reference_data/commands_snapshot.json in deinem Editor

Eintrag hinzufügen

Füge deinen Befehl zum commands-Array hinzu (vor dem letzten ])

Validieren

Teste mit: python3 -m src.main commands --query "dein-befehl"

bash

# Test: Wird der neue Befehl gefunden?
$ python3 -m src.main commands --query "deploy"

Gefundene Befehle:
- my-deploy: Deployt die Anwendung auf Produktion

# Details anzeigen
$ python3 -m src.main show-command "my-deploy"

✅

Erfolg!

Dein Befehl ist jetzt Teil des Systems und wird beim Prompt-Routing berücksichtigt. Das Routing erkennt ihn anhand der responsibility und des name.

🛠️

Erweiterung 2

Eigene Tools hinzufügen

Tools sind die Aktionen, die dein KI-Agent ausführen kann. Lerne, wie du neue hinzufügst.

Kern 15 Min

Tools unterscheiden sich von Befehlen: Während Befehle deskriptiv sind ("was soll passieren"), sind Tools aktiv ("was wird ausgeführt").

Tool-JSON-Struktur

json — tools_snapshot.json

{
  "tools": [
    {
      "name": "DatabaseQuery",
      "description": "Führt eine SQL-Abfrage auf der Datenbank aus",
      "permission_level": "read-only",
      "args": {
        "query": "SQL-Query-String",
        "database": "Name der Datenbank"
      }
    }
  ]
}

Permission Levels

Level	Bedeutung	Beispiel
`read-only`	Nur lesen, keine Änderungen	Datei lesen, Datenbank-Query
`write`	Schreiben, aber keine Gefahr	Datei schreiben, Konfiguration ändern
`destructive`	Kann Daten zerstören	Löschen, Formatieren, Drop Table
`system`	System-weite Änderungen	Prozesse killen, Neustart

Tool mit Permission-Check

bash

# Neues Tool testen
$ python3 -m src.main tools --query "DatabaseQuery"

# Tool blockieren (für sichere Modi)
$ python3 -m src.main tools --deny-tool DatabaseQuery

⚠️

Sicherheit

Wähle das Permission-Level sorgfältig. Das System verwendet es, um zu entscheiden, ob ein Tool in bestimmten Modi (z.B. "Safe Mode") verfügbar ist.

🎯

Erweiterung 3

Routing-Strategie anpassen

Der Routing-Algorithmus entscheidet, welche Befehle und Tools für einen Prompt ausgewählt werden. Passe ihn an deine Bedürfnisse an.

Fortgeschritten 25 Min

Das Herzstück ist PortRuntime.route_prompt() in src/runtime.py. Hier wird entschieden, welche Komponenten für einen Prompt relevant sind.

Wie der Algorithmus funktioniert

python — runtime.py (vereinfacht)

def route_prompt(self, prompt, limit=5):
    # 1. Tokenisieren
    tokens = self._tokenize(prompt)

    # 2. Scoren
    scores = []
    for cmd in self.commands:
        score = self._score(tokens, cmd)
        scores.append((cmd, score))

    # 3. Sortieren und Limit
    scores.sort(key=lambda x: x[1], reverse=True)
    return scores[:limit]

Scoring-Funktion anpassen

Du kannst die Gewichtung der verschiedenen Felder anpassen:

python — Beispiel: Angepasstes Scoring

def _score(self, tokens, entry):
    # Original: Gleiche Gewichtung
    # Angepasst: Name ist wichtiger

    score = 0
    name_tokens = set(entry.name.lower().split())
    resp_tokens = set(entry.responsibility.lower().split())

    # Name: 3x Gewichtung
    score += len(tokens & name_tokens) * 3.0
    # Responsibility: 1x Gewichtung
    score += len(tokens & resp_tokens) * 1.0

    return score / len(tokens)

Eigene Routing-Strategien

Strategie	Anwendungsfall	Implementierung
Prefix-Match	CLI-ähnliche Befehle	Prüfe ob Prompt mit Befehls-Name startet
Kategorie-Boost	Gewisse Tools bevorzugen	+0.5 Score für bestimmte source_hint
Kontext-Aware	Session-History berücksichtigen	Häufig genutzte Befehle boosten
Semantic Match	Synonyme erkennen	Erweitere Tokens mit Synonymen

💡

Testen ist wichtig

Nach jeder Änderung am Routing: python3 -m src.main route "dein test prompt". So siehst du sofort, ob deine Änderung das gewünschte Ergebnis bringt.

Route testen

bash

$ python3 -m src.main route "Erstelle eine neue Datenbank" --limit 5

Routed Matches:
1. Command: database-create (Score: 0.92)
2. Tool: DatabaseQuery (Score: 0.75)
3. Command: setup-db (Score: 0.68)
...

📦

Erweiterung 4

Neues Subsystem erstellen

Ein Subsystem ist ein eigenständiges Modul mit klarer Verantwortung. So erstellst du eins von Grund auf.

Fortgeschritten 30 Min

Subsysteme folgen einem Paket-Muster. Jedes Subsystem ist ein Python-Paket unter src/.

Schritt-für-Schritt: Subsystem erstellen

Verzeichnis erstellen

Erstelle einen neuen Ordner für dein Subsystem

$ mkdir src/mysubsystem
$ touch src/mysubsystem/__init__.py

__init__.py erstellen

Definiere, was exportiert wird

# src/mysubsystem/__init__.py
from .engine import MySubsystemEngine

__all__ = ["MySubsystemEngine"]

Hauptmodul erstellen

Implementiere die Kernlogik

# src/mysubsystem/engine.py

class MySubsystemEngine:
    def __init__(self, config=None):
        self.config = config or {}

    def initialize(self):
        pass

    def process(self, data):
        return {"result": "processed"}

Integration

Füge das Subsystem in den Runtime ein

# In src/runtime.py oder main.py

from mysubsystem import MySubsystemEngine

class PortRuntime:
    def __init__(self):
        ...
        self.my_engine = MySubsystemEngine()
        self.my_engine.initialize()

Subsystem-Struktur

Verzeichnisstruktur

src/
├── mysubsystem/
│ ├── __init__.py # Öffentliche API
│ ├── engine.py # Kern-Implementierung
│ ├── models.py # Datenmodelle
│ ├── utils.py # Hilfsfunktionen
│ └── tests.py # Modul-Tests
└── main.py # Integration

Best Practices für Subsysteme

Eine Verantwortung: Ein Subsystem = ein klarer Zweck
Loose Coupling: Wenig Abhängigkeiten zu anderen Subsystemen
Klare API: Nur notwendige Funktionen in __init__.py exportieren
Eigene Tests: Jedes Subsystem hat eigene Unit-Tests

✅

Teste dein Subsystem

Führe nach der Integration alle Tests aus: python3 -m unittest discover -s tests. Dein neues Subsystem sollte keine bestehenden Tests zerstören.

🚀

Ausblick

Nächste Schritte & Ressourcen

Du hast alle Grundlagen. Hier sind Ideen und Ressourcen für deine weitere Reise.

Inspiration ∞

Projekt-Ideen zum Ausprobieren

🤖

Custom Agent

Baue einen spezialisierten Agenten für einen bestimmten Workflow (z.B. Code-Review, Dokumentation)

🔌

Plugin-System

Erweitere das System um dynamisch ladbare Plugins aus einem Ordner

📊

Analytics Dashboard

Füge Metriken hinzu: Welche Befehle werden oft geroutet? Wo sind die Engpässe?

🌐

Web-Interface

Baue eine Web-Oberfläche für das Routing-System mit Flask oder FastAPI

📝

Prompt-Templates

Erstelle ein System für wiederverwendbare Prompt-Vorlagen mit Variablen

🔗

API-Integration

Verbinde das System mit einer echten LLM-API (OpenAI, Anthropic, etc.)

Wichtige Dateien als Referenz

Datei	Wofür
`src/main.py`	CLI-Entrypoint — hier fügst du neue Befehle hinzu
`src/runtime.py`	Routing-Logik — hier passt du den Algorithmus an
`src/query_engine.py`	Session-Management — hier erweiterst du den State
`src/commands.py`	Befehls-Ladung — hier könntest du dynamische Befehle laden
`src/tools.py`	Tool-Ladung — hier könntest du externe Tools integrieren
`tests/`	Tests — hier fügst du Tests für deine Erweiterungen hinzu

💡

Tipp: Klein anfangen

Fange mit einer kleinen Erweiterung an — einem neuen Befehl oder einem einfachen Tool. Sobald das läuft, wächst dein Vertrauen und Verständnis.

🎓

Abschluss

Du hast es geschafft!

Von den ersten Terminal-Befehlen bis zum eigenen KI-System — das ist eine beeindruckende Reise.

🎉

🏆

Herzlichen Glückwunsch!

Du hast den kompletten Claw Code How-To Guide durchgearbeitet. Du verstehst jetzt:

✅ Die Drei-Schichten-Architektur
✅ Wie Prompt-Routing funktioniert
✅ Wie Sessions und Turn-Loops arbeiten
✅ Wie du eigene Befehle, Tools und Subsysteme erstellst

Du bist bereit, deine eigenen Ideen umzusetzen!

Was jetzt?

Experimentiere: Passe das System an deine Bedürfnisse an
Dokumentiere: Schreibe auf, was du gelernt hast
Teile: Zeig anderen, was du gebaut hast
Erweitere: Füge Features hinzu, die du vermisst

Deine nächste Sitzung

$ python3 -m src.main bootstrap "Baue etwas Grossartiges"

Status: Bereit
Session: Neuanfang
Ziel: Unbegrenzt

→ Deine Reise beginnt jetzt.

Viel Erfolg mit deinem eigenen KI-System!
— Das Claw Code Team

← Zurück zur Übersicht Zum Buch →