Guide d'ingénierie

Dépôts navigables par les agents

Donnez aux agents de code et aux examinateurs un chemin fiable d'une tâche jusqu'au plus petit code pertinent, aux vérifications et aux preuves de livraison.

Publié le: 14 juil. 2026
Temps de lecture: 10 min de lecture

Sur cette page

Un dépôt est navigable par un agent lorsqu'un agent de code peut découvrir ses règles de fonctionnement, localiser le sous-système pertinent, exécuter la bonne validation et laisser un changement vérifiable sans s'appuyer sur un savoir tribal caché. Il ne s'agit pas d'optimiser le texte pour un modèle, mais de rendre les contraintes de livraison logicielle explicites et exécutables pour chaque contributeur.

L'article d'OpenAI de février 2026 sur le harness engineering présente l'environnement autour de l'agent comme une part importante de son efficacité. Les travaux d'Anthropic sur les environnements de longue durée aboutissent à une conclusion compatible : les agents ont besoin d'un état de départ propre, de tâches incrémentales et d'artefacts durables qui survivent à une réinitialisation du contexte.

Fournir des instructions locales et par niveaux

Utilisez un court fichier d'instructions à la racine pour les commandes à l'échelle du dépôt, les limites d'architecture et les règles de sécurité. Ajoutez des consignes au niveau des répertoires uniquement lorsque les règles changent réellement, par exemple pour un service avec une commande de test distincte ou un répertoire de clients générés. Gardez les fichiers assez courts pour être lus avant le début du travail et liez des documents plus détaillés au lieu de les dupliquer.

De bonnes instructions répondent à des questions opérationnelles, pas à des préférences génériques :

Comment un agent doit-il établir une référence propre ?
Quelles commandes doivent être exécutées pour un changement dans ce répertoire ?
Quels chemins sont générés, fournis par un tiers ou restreints ?
Quelles API, migrations ou contrats de compatibilité nécessitent l'examen d'un responsable ?
Quelles données ne doivent jamais entrer dans les fixtures, journaux, prompts ou snapshots de test ?
Quel est le format attendu du changement et de la passation ?

N'utilisez pas les instructions pour accorder une autorité de sécurité. Un fichier peut expliquer que l'accès à la production est interdit ; le sandbox et la politique d'identité doivent l'imposer.

Exposer une carte d'architecture, pas une encyclopédie

Les grands dépôts submergent humains et agents lorsque la première réponse contient des milliers de fichiers. Publiez une carte compacte des services déployables, de la responsabilité des packages, des principaux points d'entrée, des bibliothèques partagées, des frontières de données et des commandes de build. Liez chaque composant à ses tests, sa configuration d'exécution et son runbook opérationnel.

Préférez des conventions stables à un index qui exige un crawler spécifique au modèle. Des répertoires prévisibles, des noms de packages clairs, des métadonnées de responsabilité et des graphes de dépendances générés fonctionnent dans les IDE, la CI et les outils d'agents. Si un document d'architecture est obsolète, dites-le et pointez vers la source de référence plutôt que de présenter une fiction assurée.

Le contexte doit être progressif, non exhaustif

Commencez par les instructions de la tâche et la carte d'architecture. Laissez l'agent découvrir les fichiers par recherche ciblée et via les imports. Charger un monorepo entier dans le contexte accroît le coût et peut enfouir la contrainte importante.

Rendre la référence reproductible

Un agent de code ne peut pas distinguer de façon fiable une nouvelle défaillance d'une défaillance préexistante sans référence connue. Fournissez une commande d'amorçage qui installe les dépendances déclarées, identifie les services requis et signale les prérequis. Fournissez une vérification de santé rapide exécutable avant les modifications, et consignez le résultat attendu lorsqu'une exception connue existe.

Épinglez ou déclarez l'environnement d'exécution, le gestionnaire de packages, le formateur, le compilateur et l'exécuteur de tests. Utilisez des vérifications hermétiques ou conteneurisées pour les dépendances difficiles à reproduire. Évitez les étapes qui dépendent silencieusement du profil shell d'un développeur, d'une base de données locale en cours d'exécution ou d'un identifiant non suivi.

Pour une tâche, capturez le commit de base, l'état du fichier de verrouillage des dépendances, l'image ou la version de l'environnement et la commande de test. Ces détails transforment le rapport « les tests sont passés » en une preuve qu'un examinateur peut reproduire.

Transformer les retours en boucle déterministe

Un agent a besoin d'un moyen rapide d'apprendre si son correctif améliore le dépôt. Organisez les vérifications de la moins coûteuse à la plus coûteuse : syntaxe et formatage, types, tests unitaires ciblés, analyse statique, tests de contrat, puis tests d'intégration ou de navigateur. Chaque commande doit échouer avec un code de sortie exploitable et signaler les fichiers pertinents sans inonder la fenêtre de contexte de sorties sans rapport.

Distinguez la boucle d'itération de la barrière d'acceptation. Un test ciblé est idéal lors de la modification d'un module ; un build complet ou une suite de compatibilité des migrations peut être obligatoire avant la fusion. Déclarez les deux. Ne comptez pas sur un agent pour inférer qu'une large suite de tests est requise parce qu'un package adjacent l'a utilisée le mois dernier.

Lorsque les tests sont instables, classez et corrigez cette instabilité au lieu d'entraîner les agents à réessayer indéfiniment. Les tentatives masquent les régressions, gaspillent les budgets de latence et de coût et rendent les évaluations peu fiables.

Préserver l'état entre sessions sans polluer le contexte

Les sessions d'agents sont finies. Stockez l'état durable de livraison dans le dépôt et le système de livraison : liens vers les issues, enregistrement de tâche, commits, descriptions de pull request, artefacts de CI et passation concise du travail non résolu. Une passation doit identifier l'approche retenue, les chemins modifiés, la validation exécutée, les défaillances connues et la prochaine décision, sans reproduire chaque transcription de commande.

Anthropic décrit les fichiers d'avancement structurés comme un moyen de relier des sessions d'agents distinctes. Ce schéma peut être utile pour une branche de longue durée, mais il nécessite des règles de responsabilité et de nettoyage. Préférez les systèmes de référence existants lorsque possible. Un progress.md libre et permanent dans chaque répertoire peut devenir un contexte obsolète que les agents prennent pour la vérité actuelle.

Allouer délibérément contexte, latence et coût

La navigation dans un dépôt est un problème de budget. Fixez des tailles de sortie maximales pour les recherches et journaux, utilisez des filtres de fichiers et de symboles, et excluez par défaut les fichiers générés ou de verrouillage du contexte, sauf si la tâche les requiert. Mettez en cache les métadonnées immuables du dépôt par commit, mais invalidez-les lorsque les instructions, manifests de dépendances ou interfaces générées changent.

Suivez séparément le temps passé à l'amorçage, à la découverte du dépôt, à l'inférence du modèle, à l'exécution des tests et aux tentatives. Une exécution lente d'agent peut être due à une installation massive de dépendances ou à un environnement de test bloqué, plutôt qu'au raisonnement du modèle. Les contrôles de coût doivent préserver la correction : réduire le contexte en masquant les règles de responsabilité ou la sortie de test ne fait que créer plus tard un travail d'examen coûteux.

Examiner le dépôt comme une interface d'agent

Attribuez périodiquement une tâche bornée à un espace de travail d'agent neuf et doté du privilège minimal, puis observez où il se perd. Parmi les défauts fréquents figurent les instructions contradictoires, les prérequis de configuration manquants, les fichiers générés ambigus, les commandes de test exigeant un état non documenté et les sorties d'erreur trop volumineuses pour être utiles.

Mesurez la réussite de la référence au premier essai, le temps nécessaire pour localiser le composant responsable, le taux de réussite de validation, le contexte consommé avant la première modification, les reprises demandées par les examinateurs et les tâches abandonnées. Comparez ces métriques par révision du dépôt et version de l'environnement. Le but n'est pas de rendre chaque tâche autonome, mais de rendre le bon chemin contraint facile à suivre.

Liste de contrôle du dépôt

Gardez les instructions racine et locales concises, versionnées et cohérentes avec la CI.
Publiez la responsabilité des composants, les points d'entrée, les frontières de données et les commandes de validation.
Fournissez un amorçage propre et une vérification de référence rapide sans état local implicite.
Séparez les vérifications d'itération ciblées des barrières d'acceptation bloquant la fusion.
Stockez les passations durables dans les enregistrements de livraison existants et supprimez les notes temporaires obsolètes.
Limitez le contexte par défaut et la sortie des commandes tout en préservant les preuves nécessaires au débogage.
Imposez les limites de secrets, réseau et écriture par une politique, non par la seule documentation.

Références faisant autorité

Réduisez la friction dans les workflows d'ingénierie critiques

Échangez avec Optimi sur des parcours de livraison rapides et observables, ainsi que sur l'architecture edge qui soutient des systèmes d'ingénierie fiables.

Discuter de l'architecture de performance