From d94aceb6dc824b1d043e158fcaae8eae78c54d15 Mon Sep 17 00:00:00 2001 From: "Christoph K." Date: Wed, 4 Mar 2026 20:54:56 +0100 Subject: [PATCH] claude Erweiterung --- CLAUDE.md | 243 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 206 insertions(+), 37 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a48b76d..001da18 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -3,58 +3,227 @@ ## Projekt Autonomer Go Coding-Agent ähnlich wie Ralphy. Nutzt lokale LLMs via OpenAI-kompatibler API (Docker AI, Port 12434). -Die lokelen LLM sind klein und laufen auf einem kleinen Rechner mit 16GB RAM, daher ist die Planung und Task-Aufteilung besonders wichtig. +Die lokalen LLMs sind klein und laufen auf einem Rechner mit 16GB RAM – +daher ist die Planung und Task-Aufteilung in atomare Schritte besonders wichtig. -Das Projekt soll mehrere Agenten unterstüzen die jeweils für eine Aufgabe spezialisert sind. -Folgende Agenten sind geplant: -- Planner-Agent: Zerlegt die PRD.md in atomare Tasks -- Code-Agent: Führt die Tasks aus, schreibt Code, führt Tests aus, dokumentiert -- Test-Agent : Führt die Tests aus, analysiert Fehler, gibt Feedback an Code-Agent -- Reseach-Agent: Recherchiert spezifische Fragen und gibt Inspiration basirend auf Internet-Quellen die konfigurierbar sein sollen (github, google suche, reddit, stackoverflow) +Das Projekt unterstützt mehrere spezialisierte Agenten die zusammenarbeiten: +- **Planner-Agent**: Zerlegt PRD.md in atomare, ausführbare Tasks +- **Code-Agent**: Führt Tasks aus, schreibt Code, dokumentiert +- **Test-Agent**: Führt Tests aus, analysiert Fehler, gibt Feedback an Code-Agent +- **Research-Agent**: Recherchiert Fragen basierend auf konfigurierbaren Quellen + (GitHub, Google, Reddit, StackOverflow) -Jeder Agent soll seine Erkennisse und Fortschritte in einer Session-Datei (.agent-session.md) dokumentieren, damit der Fortschritt nachvollziehbar ist und die Agenten voneinander lernen können. -Des Weiteren soll jeder Agent eine TODO list im Markdown-Format führen, damit die Aufgaben klar strukturiert und priorisiert sind. +Jeder Agent dokumentiert Erkenntnisse in `.agent-session.md` damit Fortschritte +nachvollziehbar sind und Agenten voneinander lernen können. -Das Projekt soll eine modulare Architektur haben, damit neue Agenten oder Tools leicht hinzugefügt werden können. +--- -Das Projekt soll eine markdown basierte Dokumentation haben die die Architektur gut erklärt und die wichtigsten Konzepte beschreibt. +## Aktueller Implementierungsstand + +### Fertig ✅ +- `main.go` – Flag-Parsing, Modell-Auswahl via /v1/models API +- `agent/loop.go` – Worker-Loop mit Tool Calling + XML-Fallback Parser +- `agent/tools.go` – ToolExecutor: write_file, read_file, list_files (rekursiv), task_complete +- `agent/logger.go` – Verbose-Logging mit --verbose Flag +- `agent/session.go` – Session-Persistenz in .agent-session.md +- `prd/parser.go` – PRD.md Checkbox-Parser + MarkTaskComplete + +### In Arbeit 🔄 +- `agent/planner.go` – Planner-Agent (Grundgerüst vorhanden, noch nicht in loop.go integriert) + +### Geplant 📋 +- `agent/code.go` – Code-Agent +- `agent/test.go` – Test-Agent +- `agent/research.go` – Research-Agent + +--- ## Architektur + +### Dateien - `main.go` – Einstiegspunkt, Flag-Parsing, Modell-Auswahl -- `agent/loop.go` – Worker-Loop, Tool Calling, XML-Fallback Parser -- `agent/tools.go` – Tool-Executor (write_file, read_file, list_files, task_complete) -- `agent/logger.go` – Verbose-Logging -- `agent/session.go` – Session-Persistenz in .agent-session.md -- `agent/planner.go` – Planner-Agent (expandiert PRD → atomare Tasks) -- `agent/code.go` – Code-Agent (führt Tasks aus, schreibt Code, dokumentiert) -- `agent/test.go` – Test-Agent (führt Tests aus, analysiert Fehler, gibt Feedback an Code-Agent) -- `agent/research.go` – Research-Agent (recherchiert +- `agent/loop.go` – Haupt-Loop, koordiniert alle Agenten +- `agent/tools.go` – Tool-Executor (Filesystem-Operationen) +- `agent/logger.go` – Strukturiertes Logging +- `agent/session.go` – Session-Persistenz +- `agent/planner.go` – Planner-Agent +- `agent/code.go` – Code-Agent (geplant) +- `agent/test.go` – Test-Agent (geplant) +- `agent/research.go` – Research-Agent (geplant) - `prd/parser.go` – PRD.md Parser +--- + +## Agent Interface + +Jeder Agent implementiert dieses Interface: + +```go +type Agent interface { + Run(task Task) (Result, error) + Name() string +} + +type Task struct { + ID int + Title string + Description string + OriginTask string +} + +type Result struct { + Success bool + Output string + Findings string // wird in .agent-session.md dokumentiert +} +``` + +Jeder Agent bekommt: +- Einen `*openai.Client` für LLM-Calls +- Einen `*ToolExecutor` für Filesystem-Zugriff +- Einen `*Logger` für strukturiertes Logging +- Einen `*Session` für Persistenz + +--- + ## Wichtige Konventionen -- Go Modulname: llm-agent -- LLM Endpoint: http://127.0.0.1:12434/v1 -- Arbeitsverzeichnis: ./output (per --workdir Flag) -- PRD-Datei: PRD.md (per --prd Flag) -- Default Modell: docker.io/ai/qwen3-coder:latest + +- **Go Modulname**: `llm-agent` +- **LLM Endpoint**: `http://127.0.0.1:12434/v1` +- **Default Modell**: `docker.io/ai/qwen3-coder:latest` +- **Arbeitsverzeichnis**: `./output` (per `--workdir` Flag) +- **PRD-Datei**: `PRD.md` (per `--prd` Flag) +- **Session-Datei**: `{workdir}/.agent-session.md` +- **Pfade**: immer relativ zum workdir, niemals absolut +- **Kontext**: frischer Kontext pro Task (kein Context-Bloat) +- **Fehlerbehandlung**: maxRetries=3 mit exponential Backoff + +--- + +## Bekannte Probleme & Workarounds + +| Problem | Workaround | +|---|---| +| Modell nutzt XML-Format statt JSON Tool Calling | XML-Fallback Parser in `loop.go` (`parseXMLToolCalls`) | +| Kleine Modelle (3B) halten sich nicht an Formate | Mindestens 7B Modell empfohlen | +| `go run` zeigt auf `/tmp` | `os.Getwd()` statt `os.Executable()` | +| LLM schreibt absoluten Pfad | `sanitizePath()` extrahiert relativen Teil | +| `TASK_COMPLETE` ohne Arbeit in Turn 0 | Guard in `runTask()` – prüft ob Tool-Call stattfand | +| API Timeout bei großen Modellen | `context.WithTimeout` auf 5 Minuten | + +--- ## Commands + +```bash +# Bauen go build -o llm-agent . -go test ./... + +# Starten +go run main.go --workdir output --prd PRD.md go run main.go --workdir output --prd PRD.md --verbose +go run main.go --workdir output --prd PRD.md --verbose --model docker.io/ai/qwen3-coder:latest -## Vorgehensweise -- Verfeinere die Architektur und die Agenten-Designs, -- Implementiere die Basis-Architektur und den Planner-Agent -- Teste den Planner-Agent -- Implementiere den Code-Agent -- Teste den Code Agent -- Implementiere den Research-Agent -- Teste den Research-Agent +# Tests +go test ./... +go test -v ./agent/... +go test -cover ./agent/... +``` -## Späteree Erweiterungen -Integration einer Vektor-Datenbank für die Speicherung von Agenten-Erkenntnissen und Code-Snippets, um die Wiederverwendbarkeit und das Lernen der Agenten zu verbessern. +--- -Integration von git um zwischenschritte zu dokumentieren und die Zusammenarbeit zwischen mehreren Agenten zu verbessern und die Steuerung über Pull Requests zu ermöglichen. +## Vorgehensweise für Claude Code + +1. Verfeinere Agent-Interface und Basis-Architektur +2. Integriere `planner.go` in `loop.go` +3. Implementiere `code.go` (Code-Agent) +4. Teste Code-Agent mit einfachen Tasks +5. Implementiere `test.go` (Test-Agent) +6. Verbinde Code-Agent und Test-Agent in Feedback-Loop +7. Implementiere `research.go` (Research-Agent) + +--- + +## Spätere Erweiterungen + +- **Vektor-Datenbank**: Speicherung von Agenten-Erkenntnissen und Code-Snippets + für Wiederverwendbarkeit und Lernen zwischen Sessions +- **Git-Integration**: Automatische Commits pro Task, Steuerung via Pull Requests, + Zusammenarbeit mehrerer Agenten auf separaten Branches +- **Discord-Integration**: Echtzeit-Monitoring und Interaktion mit Agenten + über Discord Chat +- **Streaming**: LLM-Antworten Wort für Wort ausgeben statt auf einmal warten + +--- + +## Session-Format (.agent-session.md) + +```markdown +# Agent Session + +Started: 2026-03-04 20:00:00 +Model: docker.io/ai/qwen3-coder:latest +PRD: output/PRD.md + +## Plan + +### Erstelle go.mod[1] +Origin: Projektstruktur anlegen +Description: Erstelle go.mod mit Modulname llm-agent... + +## Tasks + +### ✅ Erstelle go.mod +Status: complete +Started: 2026-03-04 20:00:01 +Completed: 2026-03-04 20:00:45 + +### ❌ Erstelle main.go +Status: failed +Attempts: 3 +Error: maximale Turns (10) erreicht ohne task_complete + +### ⏳ Erstelle README.md +Status: pending +``` + +--- + +## Tool-Übersicht + +## Tool-Übersicht + +| Tool | Parameter | Beschreibung | +|---|---|---| +| `write_file` | `path`, `content` | Datei schreiben, Verzeichnisse werden automatisch erstellt | +| `read_file` | `path` | Dateiinhalt lesen | +| `list_files` | `path`, `recursive?` | Verzeichnis auflisten, optional rekursiv | +| `delete_file` | `path` | Datei löschen | +| `move_file` | `from`, `to` | Datei verschieben oder umbenennen | +| `run_command` | `command`, `args[]`, `workdir?` | Beliebigen Shell-Befehl ausführen (z.B. `go build`, `go test`) | +| `run_tests` | `path?`, `flags[]?` | `go test ./...` ausführen, gibt Ergebnis und Fehler zurück | +| `git_command` | `args[]` | Beliebigen git-Befehl ausführen (z.B. `["commit", "-m", "msg"]`) | +| `git_status` | – | `git status` – zeigt geänderte Dateien | +| `git_diff` | `path?` | `git diff` – zeigt Änderungen | +| `git_commit` | `message`, `files[]?` | Dateien stagen und committen | +| `git_log` | `limit?` | Letzte Commits anzeigen | +| `web_search` | `query`, `sources[]?` | Websuche, optionale Quellen: `github`, `stackoverflow`, `reddit`, `google` | +| `fetch_url` | `url` | Inhalt einer URL abrufen und als Text zurückgeben | +| `task_complete` | `summary?` | Task als erledigt markieren, optionale Zusammenfassung | +| `task_failed` | `reason` | Task explizit als fehlgeschlagen markieren mit Begründung | + +--- + +## Sicherheitsregeln + +| Tool | Einschränkung | +|---|---| +| `write_file`, `delete_file`, `move_file` | Nur innerhalb `workdir` | +| `run_command` | Konfigurierbare Whitelist erlaubter Befehle | +| `git_command` | Nur im Projekt-Root, kein `git push` ohne Bestätigung | +| `web_search`, `fetch_url` | Optional deaktivierbar per Flag `--no-network` | + +--- + +## Implementierung -Integration von Discors Chat um die Agenten in Echtzeit zu überwachen und mit ihnen zu interagieren. \ No newline at end of file