Eric Coissac
c776733402
Add comprehensive Claude Code configuration for Rust/Go projects, including: - CLAUDE.md with delegation heuristics and guardrails - Subagents: qwen3-worker (LM Studio), code-reviewer, task-planner - Skills for delegation rules and Rust/Go conventions - Hooks: post-write-lint, pre-bash-guard, subagent-stop-log - MCP server (stdio) to interface with LM Studio - README and technical report documenting the architecture
508 lines
17 KiB
Markdown
508 lines
17 KiB
Markdown
# Rapport Technique : Orchestration Robuste avec Claude Code et Délégation à un LLM Local
|
|
|
|
**Auteur** : Eric Coissac
|
|
**Date** : 26 mars 2026
|
|
**Contexte** : Ce document décrit une architecture robuste exploitant les mécanismes natifs de **Claude Code** (subagents, hooks, skills, MCP) pour déléguer des tâches à faible complexité à **Qwen3-Coder** (via LM Studio), tout en maintenant Claude Code comme orchestrateur central.
|
|
|
|
---
|
|
|
|
## 1. Pourquoi cette architecture — et ce qu'elle n'est *pas*
|
|
|
|
Le document original décrivait un système où Claude Code appelait un script Python externe (`delegate_to_qwen.py`) pour piloter Qwen3. C'est un anti-pattern : cela court-circuite les mécanismes natifs de Claude Code et réintroduit de la complexité là où l'écosystème propose déjà des solutions mieux intégrées.
|
|
|
|
En mars 2026, Claude Code dispose de cinq systèmes fondamentaux :
|
|
|
|
| Système | Rôle |
|
|
|---------|------|
|
|
| **CLAUDE.md** | Contexte permanent du projet (règles, conventions, heuristiques) |
|
|
| **Skills** | Instructions chargées à la demande selon la pertinence |
|
|
| **Subagents** | Agents spécialisés avec fenêtre de contexte isolée, outils restreints, modèle configurable |
|
|
| **Hooks** | Scripts shell ou prompts LLM déclenchés sur des événements du cycle de vie |
|
|
| **MCP servers** | Extensions vers des outils et services externes via protocole standardisé |
|
|
|
|
La délégation à Qwen3 s'intègre naturellement via un **subagent pointant vers LM Studio** ou via un **MCP server stdio minimal**. Le script Python devient optionnel — il reste utile comme wrapper si LM Studio n'expose pas d'interface MCP, mais il ne doit pas être l'orchestrateur.
|
|
|
|
---
|
|
|
|
## 2. Architecture cible
|
|
|
|
```
|
|
Utilisateur
|
|
│
|
|
▼
|
|
Claude Code (orchestrateur)
|
|
│ lit CLAUDE.md au démarrage
|
|
│ charge les skills pertinents à la demande
|
|
│
|
|
├─── Subagent : qwen3-worker ──────► LM Studio (localhost:1234)
|
|
│ contexte isolé modèle Qwen3-Coder
|
|
│ outils : Read, Write, Bash
|
|
│
|
|
├─── Subagent : code-reviewer ──────► Claude Haiku (coût réduit)
|
|
│ validation syntaxe/style
|
|
│
|
|
├─── Hooks ──────────────────────────► scripts shell
|
|
│ PostToolUse : lint auto
|
|
│ SubagentStop : log décision
|
|
│ PreToolUse : garde-fous
|
|
│
|
|
└─── MCP servers (optionnel)
|
|
qwen3-mcp (stdio) : wrapper LM Studio
|
|
```
|
|
|
|
**Principe clé** : Claude Code ne lit pas les fichiers sources pour les passer à Qwen3. C'est Qwen3 (via son subagent ou son agent loop) qui lit les fichiers dont il a besoin — le contenu ne transite pas par le contexte de Claude Code.
|
|
|
|
---
|
|
|
|
## 3. Structure du projet
|
|
|
|
```
|
|
.claude/
|
|
├── CLAUDE.md # contexte projet + heuristiques de délégation
|
|
├── settings.json # hooks et permissions
|
|
├── agents/
|
|
│ ├── qwen3-worker.md # subagent → LM Studio
|
|
│ ├── code-reviewer.md # subagent → Haiku (validation)
|
|
│ └── task-planner.md # subagent → Opus (planification complexe)
|
|
├── skills/
|
|
│ ├── delegation-rules.md # quand déléguer à Qwen3
|
|
│ └── rust-go-conventions.md # conventions spécifiques au projet
|
|
└── hooks/
|
|
├── post-write-lint.sh # lint automatique après écriture
|
|
├── subagent-stop-log.sh # observabilité
|
|
└── pre-bash-guard.sh # sécurité
|
|
mcp/
|
|
└── qwen3-mcp/
|
|
├── server.py # MCP server stdio (optionnel)
|
|
└── agent_lm.py # agent loop local (~120 lignes)
|
|
```
|
|
|
|
---
|
|
|
|
## 4. CLAUDE.md — contexte et heuristiques
|
|
|
|
```markdown
|
|
# Projet [nom]
|
|
|
|
## Stack
|
|
- Rust (edition 2024), Go 1.24
|
|
- Tests : cargo test, go test
|
|
- Lint : clippy (Rust), golangci-lint (Go)
|
|
|
|
## Heuristiques de délégation
|
|
|
|
Délègue à `qwen3-worker` si la tâche est **atomique** et satisfait TOUS les critères :
|
|
- ≤ 3 fichiers concernés
|
|
- Pas de modification d'API publique
|
|
- Pas de dépendance externe non encore importée
|
|
- Tâches typiques : génération de tests unitaires, reformatage, documentation inline,
|
|
conversion de types simples, scaffolding de stubs
|
|
|
|
Traite toi-même si :
|
|
- Refactoring cross-module
|
|
- Conception d'architecture
|
|
- Debugging avec contexte multi-fichiers
|
|
- Modification de traits/interfaces publics
|
|
|
|
## Garde-fous absolus
|
|
- Ne jamais passer `rm -rf` sans confirmation explicite
|
|
- Ne jamais committer sans que les tests passent
|
|
- Toujours vérifier `git diff` avant un commit
|
|
```
|
|
|
|
---
|
|
|
|
## 5. Subagent `qwen3-worker`
|
|
|
|
Fichier : `.claude/agents/qwen3-worker.md`
|
|
|
|
```markdown
|
|
---
|
|
name: qwen3-worker
|
|
description: >
|
|
Délègue à Qwen3-Coder via LM Studio les tâches atomiques sur 1-3 fichiers :
|
|
génération de tests unitaires, documentation inline, scaffolding de stubs,
|
|
reformatage de code. N'utilise PAS pour du refactoring cross-module ou de
|
|
la conception d'architecture.
|
|
tools: [Read, Write, Bash]
|
|
model: inherit
|
|
---
|
|
|
|
Tu es un assistant de codage spécialisé exécutant des tâches courtes et précises.
|
|
|
|
## Comportement
|
|
1. Lis les fichiers nécessaires avec l'outil Read (ne reçois pas le contenu en entrée).
|
|
2. Effectue la transformation demandée.
|
|
3. Écris le résultat avec Write.
|
|
4. Exécute le linter approprié (clippy pour Rust, golangci-lint pour Go) et corrige
|
|
les erreurs éventuelles (max 2 tentatives).
|
|
5. Retourne un résumé : fichiers modifiés, changements effectués, résultat du lint.
|
|
|
|
## Format de sortie
|
|
```
|
|
STATUS: success|partial|failure
|
|
FILES_MODIFIED: liste des fichiers
|
|
SUMMARY: description des changements
|
|
LINT: passed|failed (+ détail si failed)
|
|
```
|
|
|
|
Ne génère pas de fonctions non demandées. Ne modifie pas les signatures publiques.
|
|
```
|
|
|
|
> **Note importante** : le champ `model: inherit` signifie que ce subagent utilise le modèle courant de la session. Pour pointer vers LM Studio, il faut soit configurer `ANTHROPIC_BASE_URL` pour ce subagent, soit utiliser le MCP server décrit en section 7.
|
|
|
|
---
|
|
|
|
## 6. Hooks
|
|
|
|
### `settings.json`
|
|
|
|
```json
|
|
{
|
|
"hooks": {
|
|
"PostToolUse": [
|
|
{
|
|
"matcher": "Write",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "bash .claude/hooks/post-write-lint.sh",
|
|
"async": true
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"SubagentStop": [
|
|
{
|
|
"matcher": ".*",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "bash .claude/hooks/subagent-stop-log.sh"
|
|
}
|
|
]
|
|
}
|
|
],
|
|
"PreToolUse": [
|
|
{
|
|
"matcher": "Bash",
|
|
"hooks": [
|
|
{
|
|
"type": "command",
|
|
"command": "bash .claude/hooks/pre-bash-guard.sh"
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### `post-write-lint.sh`
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# Lint automatique après écriture de fichier
|
|
FILE=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('file_path',''))")
|
|
|
|
if [[ "$FILE" == *.rs ]]; then
|
|
cargo clippy --quiet 2>&1 | tail -20
|
|
elif [[ "$FILE" == *.go ]]; then
|
|
golangci-lint run "$FILE" 2>&1 | tail -20
|
|
fi
|
|
```
|
|
|
|
### `subagent-stop-log.sh`
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# Observabilité : log chaque fin de subagent
|
|
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
|
|
PAYLOAD=$(cat)
|
|
AGENT=$(echo "$PAYLOAD" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('agent_name','unknown'))" 2>/dev/null)
|
|
echo "$TIMESTAMP agent=$AGENT" >> .claude/logs/subagent-decisions.log
|
|
```
|
|
|
|
### `pre-bash-guard.sh`
|
|
|
|
```bash
|
|
#!/usr/bin/env bash
|
|
# Bloque les commandes destructives sans confirmation
|
|
CMD=$(echo "$CLAUDE_TOOL_INPUT" | python3 -c "import json,sys; print(json.load(sys.stdin).get('command',''))")
|
|
|
|
if echo "$CMD" | grep -qE 'rm -rf|DROP TABLE|git push --force'; then
|
|
echo "BLOQUÉ : commande dangereuse détectée. Confirmez explicitement."
|
|
exit 2 # exit 2 = deny dans Claude Code
|
|
fi
|
|
```
|
|
|
|
---
|
|
|
|
## 7. MCP Server (optionnel — si LM Studio n'est pas accessible comme modèle)
|
|
|
|
Si l'objectif est de router un subagent vers LM Studio plutôt que vers l'API Anthropic, le moyen le plus simple est un MCP server stdio minimal.
|
|
|
|
### `mcp/qwen3-mcp/server.py`
|
|
|
|
```python
|
|
#!/usr/bin/env python3
|
|
"""
|
|
MCP server stdio minimaliste exposant un outil `qwen3_task`.
|
|
Appelé par Claude Code via : claude mcp add --transport stdio qwen3 -- python3 mcp/qwen3-mcp/server.py
|
|
"""
|
|
import sys
|
|
import json
|
|
import requests
|
|
|
|
LMSTUDIO_URL = "http://localhost:1234/v1/chat/completions"
|
|
QWEN3_MODEL = "qwen3-coder" # nom du modèle dans LM Studio
|
|
|
|
|
|
def call_qwen3(task: str, files: list[str]) -> str:
|
|
context = ""
|
|
for path in files:
|
|
try:
|
|
with open(path) as f:
|
|
context += f"--- {path} ---\n{f.read()}\n\n"
|
|
except OSError as e:
|
|
context += f"--- {path} --- ERREUR: {e}\n\n"
|
|
|
|
prompt = f"""Tu es un assistant de codage. Effectue la tâche suivante de manière précise.
|
|
|
|
TÂCHE: {task}
|
|
|
|
FICHIERS:
|
|
{context}
|
|
|
|
Retourne uniquement le code modifié ou généré, sans explication.
|
|
"""
|
|
resp = requests.post(
|
|
LMSTUDIO_URL,
|
|
json={
|
|
"model": QWEN3_MODEL,
|
|
"messages": [{"role": "user", "content": prompt}],
|
|
"temperature": 0.2,
|
|
"max_tokens": 4096,
|
|
},
|
|
timeout=120,
|
|
)
|
|
resp.raise_for_status()
|
|
return resp.json()["choices"][0]["message"]["content"]
|
|
|
|
|
|
def handle_tool_call(tool_name: str, args: dict) -> str:
|
|
if tool_name == "qwen3_task":
|
|
return call_qwen3(args["task"], args.get("files", []))
|
|
return f"Outil inconnu : {tool_name}"
|
|
|
|
|
|
# Boucle MCP stdio (protocole JSON-RPC simplifié)
|
|
for line in sys.stdin:
|
|
try:
|
|
req = json.loads(line)
|
|
if req.get("method") == "tools/call":
|
|
result = handle_tool_call(
|
|
req["params"]["name"], req["params"].get("arguments", {})
|
|
)
|
|
print(json.dumps({"id": req["id"], "result": {"content": [{"type": "text", "text": result}]}}))
|
|
elif req.get("method") == "tools/list":
|
|
print(json.dumps({
|
|
"id": req["id"],
|
|
"result": {"tools": [{
|
|
"name": "qwen3_task",
|
|
"description": "Délègue une tâche de codage atomique à Qwen3-Coder via LM Studio.",
|
|
"inputSchema": {
|
|
"type": "object",
|
|
"properties": {
|
|
"task": {"type": "string", "description": "Description précise de la tâche"},
|
|
"files": {"type": "array", "items": {"type": "string"}, "description": "Chemins des fichiers concernés"}
|
|
},
|
|
"required": ["task"]
|
|
}
|
|
}]}
|
|
}))
|
|
elif req.get("method") == "initialize":
|
|
print(json.dumps({"id": req["id"], "result": {"protocolVersion": "2024-11-05", "capabilities": {"tools": {}}}}))
|
|
except Exception as e:
|
|
print(json.dumps({"error": str(e)}), file=sys.stderr)
|
|
sys.stdout.flush()
|
|
```
|
|
|
|
**Installation** :
|
|
```bash
|
|
claude mcp add --transport stdio qwen3 -- python3 mcp/qwen3-mcp/server.py
|
|
```
|
|
|
|
---
|
|
|
|
## 8. Skill de délégation
|
|
|
|
Fichier : `.claude/skills/delegation-rules.md`
|
|
|
|
```markdown
|
|
---
|
|
name: delegation-rules
|
|
description: Règles pour décider quand et comment déléguer à qwen3-worker ou qwen3 MCP
|
|
---
|
|
|
|
# Règles de Délégation à Qwen3
|
|
|
|
## Critères de délégation (TOUS requis)
|
|
- ≤ 3 fichiers source concernés
|
|
- Tâche atomique, sans dépendance à résoudre
|
|
- Pas de modification de signature publique (trait, interface exportée)
|
|
- Contexte de fichier estimé < 8 000 tokens
|
|
|
|
## Tâches typiques éligibles
|
|
- Génération de tests unitaires pour une fonction donnée
|
|
- Ajout de documentation (doc comments Rust, godoc Go)
|
|
- Scaffolding de stubs à partir d'une interface
|
|
- Conversion de types internes simples
|
|
- Reformatage / réorganisation d'imports
|
|
|
|
## Procédure
|
|
1. Évalue les critères ci-dessus.
|
|
2. Si éligible → utilise le subagent `qwen3-worker` en précisant la tâche et les fichiers.
|
|
3. Attends le résumé de sortie (STATUS / FILES_MODIFIED / LINT).
|
|
4. Si STATUS=failure → prends en charge toi-même.
|
|
5. Si STATUS=partial → corrige les points restants directement.
|
|
|
|
## Ne jamais déléguer
|
|
- Refactoring impliquant > 3 fichiers
|
|
- Changement d'architecture ou de design pattern
|
|
- Debugging avec stacktrace à analyser
|
|
- Tâches nécessitant une recherche web ou du contexte externe
|
|
```
|
|
|
|
---
|
|
|
|
## 9. Pipeline de validation native
|
|
|
|
Claude Code valide via les hooks et les subagents dédiés — pas via du code de validation embarqué dans le script de délégation.
|
|
|
|
| Étape | Mécanisme | Déclencheur |
|
|
|-------|-----------|-------------|
|
|
| Lint syntaxique | `post-write-lint.sh` (hook) | PostToolUse/Write automatique |
|
|
| Validation de style | subagent `code-reviewer` | explicitement demandé |
|
|
| Tests | `Bash: cargo test / go test` | dans le subagent ou directement |
|
|
| Contrôle des diffs | `Bash: git diff --stat` | avant tout commit |
|
|
|
|
### Subagent `code-reviewer`
|
|
|
|
```markdown
|
|
---
|
|
name: code-reviewer
|
|
description: >
|
|
Révise du code Rust ou Go pour détecter bugs, régressions, problèmes de style.
|
|
Utilise après génération par qwen3-worker ou avant un commit.
|
|
tools: [Read, Grep, Glob, Bash]
|
|
model: claude-haiku-4-5-20251001
|
|
---
|
|
|
|
Tu es un reviewer expérimenté en Rust et Go.
|
|
|
|
Pour chaque fichier fourni :
|
|
1. Vérifie la cohérence des types et la gestion d'erreurs.
|
|
2. Identifie les patterns non idiomatiques.
|
|
3. Signale les tests manquants pour les chemins critiques.
|
|
|
|
Format de sortie :
|
|
```
|
|
VERDICT: approved|changes_requested
|
|
ISSUES: liste numérotée (vide si approved)
|
|
```
|
|
```
|
|
|
|
---
|
|
|
|
## 10. Boucle de correction contrôlée
|
|
|
|
La boucle de correction n'est pas un script externe — elle est gérée nativement par Claude Code via le prompt du subagent et les hooks.
|
|
|
|
Séquence type :
|
|
1. Claude Code délègue à `qwen3-worker`.
|
|
2. Le subagent retourne `STATUS: failure` avec détail.
|
|
3. Claude Code lit le résumé, corrige lui-même ou re-délègue avec le feedback intégré dans le prompt.
|
|
4. Maximum 2 re-délégations ; au-delà, Claude Code traite directement.
|
|
|
|
---
|
|
|
|
## 11. Sécurité
|
|
|
|
Les garde-fous sont dans les **hooks** (non contournables par le contexte) plutôt que dans des fonctions Python.
|
|
|
|
```json
|
|
{
|
|
"permissions": {
|
|
"allow": [
|
|
"Bash(cargo:*)",
|
|
"Bash(go:*)",
|
|
"Bash(git diff*)",
|
|
"Bash(git add*)",
|
|
"Bash(git commit*)",
|
|
"Read(**/*.rs)",
|
|
"Read(**/*.go)",
|
|
"Write(**/*.rs)",
|
|
"Write(**/*.go)"
|
|
],
|
|
"deny": [
|
|
"Bash(rm -rf*)",
|
|
"Bash(curl * | bash*)",
|
|
"Bash(git push --force*)"
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## 12. Observabilité
|
|
|
|
Les logs sont produits par les hooks, pas par du code applicatif.
|
|
|
|
```
|
|
.claude/logs/
|
|
├── subagent-decisions.log # timestamp + agent name à chaque SubagentStop
|
|
└── delegation-outcomes.log # STATUS de chaque délégation (si ajouté au hook)
|
|
```
|
|
|
|
Pour des métriques plus élaborées (taux de délégation, taux d'échec), un hook `SubagentStop` peut écrire dans un fichier JSON et un script externe peut agréger.
|
|
|
|
---
|
|
|
|
## 13. Workflow complet — exemple
|
|
|
|
**Requête** : "Génère les tests unitaires pour les fonctions `parse_header` et `validate_checksum` dans `src/parser.rs`."
|
|
|
|
1. Claude Code lit `CLAUDE.md` → identifie les heuristiques de délégation.
|
|
2. Charge le skill `delegation-rules.md` → tâche éligible (1 fichier, atomique, pas d'API publique).
|
|
3. Délègue au subagent `qwen3-worker` : *"Génère des tests unitaires pour `parse_header` et `validate_checksum` dans `src/parser.rs`"*.
|
|
4. `qwen3-worker` lit `src/parser.rs` via l'outil Read (le contenu ne passe pas par le contexte principal).
|
|
5. Écrit les tests dans `src/parser.rs` (ou `tests/parser_tests.rs`).
|
|
6. Hook `post-write-lint.sh` déclenché → `cargo clippy` → résultat injecté dans le contexte du subagent.
|
|
7. Subagent retourne : `STATUS: success | FILES_MODIFIED: src/parser.rs | LINT: passed`.
|
|
8. Claude Code confirme à l'utilisateur.
|
|
|
|
---
|
|
|
|
## 14. Ce qui a changé par rapport au document initial
|
|
|
|
| Document initial | Cette version |
|
|
|-----------------|---------------|
|
|
| Script Python `delegate_to_qwen.py` comme orchestrateur | Claude Code natif comme orchestrateur |
|
|
| Validation syntaxique dans le script | Hook `post-write-lint.sh` (déterministe, non contournable) |
|
|
| Boucle de correction en Python | Gérée par le prompt du subagent + logique d'orchestration Claude |
|
|
| Sécurité dans `is_safe_file()` | Permissions natives (`settings.json`) + hook `pre-bash-guard.sh` |
|
|
| Logs en Python | Hooks shell sur les événements du cycle de vie |
|
|
| Tools MCP = scripts ad hoc | MCP server stdio standard + subagents natifs |
|
|
|
|
---
|
|
|
|
## 15. Prochaines étapes recommandées
|
|
|
|
1. **Bootstrapper la structure** : créer `.claude/agents/`, `settings.json`, `CLAUDE.md` avec les templates ci-dessus.
|
|
2. **Tester LM Studio** : vérifier que `curl http://localhost:1234/v1/models` répond avant d'activer le MCP server.
|
|
3. **Calibrer les heuristiques** : après 20-30 délégations, affiner les critères dans `delegation-rules.md` selon les résultats observés dans les logs.
|
|
4. **Envisager `model:` explicite** : si Claude Haiku est suffisant pour `qwen3-worker` (coût réduit, latence moindre), configurer `model: claude-haiku-4-5-20251001` à la place du LLM local.
|
|
5. **MCP Tool Search** : activer `ENABLE_TOOL_SEARCH=auto` pour réduire la consommation de contexte quand les MCP servers sont nombreux.
|