Construction d'un agent de codage pour un contexte de 8k : répartition planificateur/exécuteur, budgétisation des jetons et exécution parallèle

La plupart des outils de codage IA supposent des modèles à 200 000 tokens, mais si vous utilisez des LLM locaux via Ollama, LM Studio ou des API gratuites comme Groq ou OpenRouter, vous êtes limité à environ 8 000 tokens. Cela ne suffit pas pour un projet entier — à peine pour un seul gros fichier. Un développeur a passé des semaines à construire un agent CLI conçu pour cette contrainte et partage les leçons pratiques apprises.

Architecture de base : séparation planificateur/exécuteur

L'agent ne montre jamais l'ensemble du projet au LLM. Au lieu de cela, il divise le travail en trois rôles :

• Planificateur : ne voit qu'une carte légère du projet (résumés Markdown de chaque dossier, environ 300 à 500 tokens au total) ainsi que la demande de l'utilisateur, et produit une liste de tâches.
• Exécuteur : ne voit qu'un seul fichier et une seule tâche par appel — jamais deux fichiers ensemble.
• Orchestrateur : code pur (pas de LLM) qui construit un graphe de dépendances à partir de la liste de tâches et décide quelles tâches peuvent être exécutées en parallèle ou séquentiellement.

Cela transforme les refontes multi-fichiers d'un problème de fenêtre de contexte en un problème d'ordonnancement. Le planificateur n'a pas besoin de voir le code, et l'exécuteur ne voit qu'une quantité limitée de code à la fois.

Budget de tokens imposé dans le code

Chaque appel LLM passe par une vérification canFit() qui mesure le prompt système + les tokens de sortie réservés + la mémoire + le code réel. Si le code ne tient pas, l'agent se rabat sur un index de lignes par fichier (généré une fois pour les fichiers de plus de ~150 lignes) et ne prend que la section pertinente.

Calcul du budget pour 8192 tokens :

Prompt système + instructions : ~1000
Réservé pour la réponse : ~2000
Mémoire à court terme (4 entrées) : ~360
Disponible pour le code réel : ~4800 (environ 140-190 lignes)

Lorsque le budget est serré, le contexte des dossiers est supprimé en premier, puis la mémoire, avant de couper le code réel.

Exécution parallèle comme multiplicateur de vitesse

Comme chaque exécuteur ne voit qu'un seul fichier, les modifications indépendantes sur plusieurs fichiers s'exécutent simultanément. Une refonte de 5 fichiers s'achève à peu près dans le temps de la plus longue modification individuelle. Le graphe de dépendances (construit dans le code à partir de la liste de tâches du planificateur) détermine l'ordre.

Points douloureux et correctifs

• Requêtes de type question écrasant les fichiers : demander « combien de lignes a X ? » a amené l'exécuteur à écrire la réponse dans le fichier. Correction : ajout d'un champ action_type: "query" dans la sortie du planificateur, acheminé via un chemin de code qui ne touche jamais le disque.
• Cartes de projet obsolètes causant des erreurs d'aiguillage silencieuses : si l'utilisateur mentionnait un fichier renommé absent de la carte, le planificateur l'acheminait silencieusement vers la correspondance la plus proche. Désormais, l'orchestrateur vérifie que les chemins de fichiers mentionnés existent sur le disque et renvoie une erreur claire s'ils n'existent pas.
• Fences Markdown dans la sortie de l'exécuteur : les modèles plus petits enveloppent le code dans des triples backticks même lorsqu'on leur dit de ne pas le faire. Correctif : les supprimer en post-traitement plutôt que de lutter avec le prompt.
• Coût en tokens de la mémoire : la mémoire persistante ajoute environ 80 à 90 tokens par entrée. Le contexte du dossier est supprimé en premier lorsque le budget est serré, puis la mémoire, avant que le code réel ne soit coupé.

Questions ouvertes

La séparation planificateur/exécuteur passe-t-elle à l'échelle pour des bases de code de plus de 50 fichiers ? Le graphe de dépendances reste gérable, mais la carte du projet commence à coûter des tokens réels. Actuellement, le contexte du dossier est supprimé en premier, mais les modifications plus profondes perdent du contexte. L'implémentation est open-source si vous voulez creuser.