Tuning de l'environnement d'un agent LLM

Ce guide décrit comment adapter (« tuner ») l'environnement de travail d'un agent LLM — terminal, shell, raccourcis, configuration — pour fluidifier la collaboration humain‑agent au quotidien.

Il est rédigé sur deux niveaux, à ne pas confondre :

1. Le principe universel : ce qui vaut pour n'importe quel agent LLM dans n'importe quel environnement (la méthode, les questions à se poser, la démarche de documentation).
2. Le cas d'étude particulier : nos pratiques concrètes — un agent précis (Claude Code) dans un environnement précis (celui de Mathieu : Windows 11 + Windows Terminal + PowerShell). Ce cas n'a pas valeur de norme : il illustre le principe, il ne le remplace pas.

Règle de lecture : tout ce qui est sous « Principe » est transposable ; tout ce qui est sous « Cas d'étude » est un exemple daté et situé, susceptible d'évoluer avec l'environnement de Mathieu.

1. Principe — pourquoi et comment tuner

1.1 Pourquoi

Un agent LLM en mode terminal hérite des contraintes de son hôte : émulateur de terminal, shell, encodage, raccourcis clavier, variables d'environnement. Un défaut d'ergonomie (un raccourci qui n'envoie pas la bonne séquence, un encodage qui casse les accents) dégrade chaque interaction, pas seulement une. Le tuning corrige ces frictions à la racine, une fois pour toutes.

1.2 Démarche

Pour chaque friction rencontrée :

1. Localiser la couche responsable. L'agent ? L'émulateur de terminal ? Le shell ? Le clavier / la disposition ? Ne pas corriger au mauvais étage.
2. Vérifier l'état réel avant de conclure (version d'outil, présence d'un binding, valeur d'une variable). Beaucoup de « bugs » sont des configurations absentes, pas des incompatibilités.
3. Appliquer le correctif au bon endroit, en privilégiant la solution pérenne et standard (séquences d'échappement reconnues, fichiers de config officiels) plutôt qu'un contournement fragile.
4. Garder un repli universel documenté (une solution qui marche partout, sans config), au cas où le correctif principal ne prendrait pas dans un autre contexte.
5. Documenter l'entrée (voir §3) : symptôme, couche, cause, correctif, repli.

1.3 Couches typiques à interroger

2. Cas d'étude — Claude Code dans l'environnement de Mathieu

Environnement de référence (au 2026‑05‑30) : Windows 11, Windows Terminal, shell PowerShell, Claude Code en CLI terminal‑only, Node v26. Disposition clavier AZERTY.

Ce cas est situé et daté. Il sert d'illustration concrète au principe du §1, pas de modèle à copier tel quel.

2.1 Saut de ligne multi‑lignes dans le prompt (Shift+Entrée)

• Symptôme : dans le prompt Claude Code, Shift+Entrée envoyait le message au lieu d'insérer un saut de ligne — impossible de rédiger confortablement un brief sur plusieurs lignes.

• Couche responsable : l'émulateur de terminal (Windows Terminal), pas l'agent. Vérification faite côté agent : Node v26 ⇒ le « VT mode » est actif, donc Claude Code sait recevoir la bonne séquence. Le problème était que Windows Terminal n'émettait aucune séquence pour shift+enter (aucun binding défini) ⇒ la touche retombait sur Entrée ⇒ envoi.

• Correctif appliqué : ajout d'un binding dans le settings.json de Windows Terminal, associant shift+enter à l'action sendInput envoyant la séquence CSI‑u  (Entrée + modificateur Shift au format kitty keyboard protocol / CSI‑u, que Claude Code interprète comme « insérer un saut de ligne »).

  // %LOCALAPPDATA%\Packages\Microsoft.WindowsTerminal_8wekyb3d8bbwe\LocalState\settings.json
  // Windows Terminal éclate automatiquement la définition en "actions" + "keybindings" :
  "actions": [
    {
      "command": { "action": "sendInput", "input": "" },
      "id": "User.sendInput.shiftEnter"
    }
  ],
  "keybindings": [
    { "id": "User.sendInput.shiftEnter", "keys": "shift+enter" }
  ]
  

  Appliqué à chaud : Windows Terminal surveille son settings.json et recharge sans redémarrage.

• Repli universel (toujours valable, aucune config) : Ctrl+J insère un saut de ligne dans le prompt. Le backslash \ en fin de ligne + Entrée fonctionne aussi, mais reste peu pratique pour rédiger.

• Statut : ✅ résolu le 2026‑05‑30.

2.2 Encodage et accents (rappel)

L'environnement impose UTF‑8 partout (voir AGENTS.md). Détail PowerShell utile : les fichiers écrits par certains cmdlets le sont en UTF‑16 LE par défaut — préciser -Encoding utf8 quand un autre outil doit relire le fichier.

2.3 Autonomie d'écriture dans le projet (permissions)

• Symptôme : l'agent demandait validation à chaque Edit/Write dans son propre dépôt — friction permanente alors que c'est « son » projet.

• Couche responsable : l'agent (système de permissions de Claude Code), pas le terminal.

• Cause : mode par défaut default + aucune règle allow pour l'édition ⇒ tout Edit/Write est soumis à confirmation. (Les lectures ne demandent jamais rien, dans tous les modes.)

• Correctif appliqué : dans .claude/settings.json (versionné), bloc permissions :

  "permissions": {
    "defaultMode": "acceptEdits",          // édition/écriture + ops fichier auto dans le repo
    "allow": ["Edit", "Write"]             // explicite pour les outils d'édition
  }
  

  Effet : édition/écriture libres dans le dépôt ; shell (git push, composer, docker…) toujours gated ; écritures hors dépôt (ex. inbox d'une autre instance) toujours confirmées. Le mode est lu au démarrage ; les règles allow prennent effet en direct.

• Repli universel : Shift+Tab pour basculer en acceptEdits à la volée sans toucher la config ; bypassPermissions (zéro garde-fou) existe mais déconseillé hors environnement isolé — verrouillé ici via disableBypassPermissionsMode.

• Propagation : ce défaut est embarqué dans le starter-pack pour que chaque repo de l'écosystème naisse avec la même autonomie.

• Statut : ✅ résolu le 2026‑05‑30.

2.4 Chantier ouvert — « shell with fun »

Projet annexe annoncé par Mathieu : rendre le shell de lancement des instances Claude « fun et sexy » (prompt, couleurs, alias, ergonomie). Non démarré au 2026‑05‑30 ; les réglages qui en sortiront viendront enrichir ce cas d'étude.

3. Modèle d'entrée (à dupliquer pour chaque nouveau tuning)

Chaque réglage documenté suit la même trame, pour rester comparable et transposable :

### <Titre du réglage>

- **Symptôme** : ce qu'on observe, côté usage.
- **Couche responsable** : agent / terminal / shell / système.
- **Cause** : pourquoi ça se produit (état réel constaté).
- **Correctif appliqué** : la solution pérenne + où elle se configure (+ snippet).
- **Repli universel** : la solution qui marche partout sans config.
- **Statut** : ✅ résolu (date) / 🔧 en cours / 💡 piste.

Voir aussi

• Guide de l'IA — intégration de l'IA dans le cycle de développement.
• AGENTS.md — consignes d'environnement (UTF‑8, EOL, français).