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 ## Projekt
Autonomer Go Coding-Agent ähnlich wie Ralphy. Autonomer Go Coding-Agent ähnlich wie Ralphy.
Nutzt lokale LLMs via OpenAI-kompatibler API (Docker AI, Port 12434). 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. Das Projekt unterstützt mehrere spezialisierte Agenten die zusammenarbeiten:
Folgende Agenten sind geplant: - **Planner-Agent**: Zerlegt PRD.md in atomare, ausführbare Tasks
- Planner-Agent: Zerlegt die PRD.md in atomare Tasks - **Code-Agent**: Führt Tasks aus, schreibt Code, dokumentiert
- Code-Agent: Führt die Tasks aus, schreibt Code, führt Tests aus, dokumentiert - **Test-Agent**: Führt Tests aus, analysiert Fehler, gibt Feedback an Code-Agent
- Test-Agent : Führt die Tests aus, analysiert Fehler, gibt Feedback an Code-Agent - **Research-Agent**: Recherchiert Fragen basierend auf konfigurierbaren Quellen
- Reseach-Agent: Recherchiert spezifische Fragen und gibt Inspiration basirend auf Internet-Quellen die konfigurierbar sein sollen (github, google suche, reddit, stackoverflow) (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. Jeder Agent dokumentiert Erkenntnisse in `.agent-session.md` damit Fortschritte
Des Weiteren soll jeder Agent eine TODO list im Markdown-Format führen, damit die Aufgaben klar strukturiert und priorisiert sind. 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 ## Architektur
### Dateien
- `main.go` – Einstiegspunkt, Flag-Parsing, Modell-Auswahl - `main.go` – Einstiegspunkt, Flag-Parsing, Modell-Auswahl
- `agent/loop.go` – Worker-Loop, Tool Calling, XML-Fallback Parser - `agent/loop.go` – Haupt-Loop, koordiniert alle Agenten
- `agent/tools.go` – Tool-Executor (write_file, read_file, list_files, task_complete) - `agent/tools.go` – Tool-Executor (Filesystem-Operationen)
- `agent/logger.go` – Verbose-Logging - `agent/logger.go` – Strukturiertes Logging
- `agent/session.go` – Session-Persistenz in .agent-session.md - `agent/session.go` – Session-Persistenz
- `agent/planner.go` – Planner-Agent (expandiert PRD → atomare Tasks) - `agent/planner.go` – Planner-Agent
- `agent/code.go` – Code-Agent (führt Tasks aus, schreibt Code, dokumentiert) - `agent/code.go` – Code-Agent (geplant)
- `agent/test.go` – Test-Agent (führt Tests aus, analysiert Fehler, gibt Feedback an Code-Agent) - `agent/test.go` – Test-Agent (geplant)
- `agent/research.go` – Research-Agent (recherchiert - `agent/research.go` – Research-Agent (geplant)
- `prd/parser.go` – PRD.md Parser - `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 ## Wichtige Konventionen
- Go Modulname: llm-agent
- LLM Endpoint: http://127.0.0.1:12434/v1 - **Go Modulname**: `llm-agent`
- Arbeitsverzeichnis: ./output (per --workdir Flag) - **LLM Endpoint**: `http://127.0.0.1:12434/v1`
- PRD-Datei: PRD.md (per --prd Flag) - **Default Modell**: `docker.io/ai/qwen3-coder:latest`
- 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 ## Commands
```bash
# Bauen
go build -o llm-agent . 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
go run main.go --workdir output --prd PRD.md --verbose --model docker.io/ai/qwen3-coder:latest
## Vorgehensweise # Tests
- Verfeinere die Architektur und die Agenten-Designs, go test ./...
- Implementiere die Basis-Architektur und den Planner-Agent go test -v ./agent/...
- Teste den Planner-Agent go test -cover ./agent/...
- Implementiere den Code-Agent ```
- Teste den Code Agent
- Implementiere den Research-Agent
- Teste den Research-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.