christoph/goralphy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

claude Erweiterung

Browse Source
This commit is contained in:
Christoph K.
2026-03-04 20:54:56 +01:00
parent 1749cbc403
commit d94aceb6dc
1 changed files with 206 additions and 37 deletions
Download Patch File Download Diff File Expand all files Collapse all files

243
CLAUDE.md
View File

@@ -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.