hustyladislav/redaction-pour-agents

Référence pour la rédaction de tout document consommé par un agent : une compétence, un AGENTS.md / CLAUDE.md, un document atteint par un pointeur. L'emballage diffère ; la rédaction, non : les mêmes leviers rendent chaque document prévisible, puisque l'agent suit le même processus à chaque exécution plutôt que de produire la même sortie.

Lorsque le document que vous rédigez est une compétence, lisez SKILL-MECHANICS.md pour les métadonnées d'en-tête, le choix de l'invocation et les compétences routeuses.

Pointeurs de contexte

Un pointeur de contexte est une référence conservée dans le contexte de l'agent qui nomme un élément de matériel hors contexte et encode la condition pour y accéder. La description d'une compétence en est un ; une ligne dans AGENTS.md nommant un document est le même objet. Le libellé du pointeur, et non sa cible, décide quand l'agent atteint le matériel, et avec quelle fiabilité. Une cible indispensable derrière un pointeur mal formulé est un bogue de variance : affinez d'abord le libellé, et intégrez le matériel seulement si l'affinage échoue.

Un pointeur fait deux choses : indiquer ce qu'est le matériel, et lister les branches qui doivent déclencher son accès (une branche est un cas distinct que le document traite, de sorte que différentes exécutions empruntent des chemins différents à travers lui). Chaque mot d'un pointeur toujours chargé coûte à chaque tour, il mérite donc un élagage encore plus sévère que le corps :

• Mettez le mot principal en tête : le pointeur est l'endroit où il effectue son travail de déclenchement.
• Un déclencheur par branche. Les synonymes qui renomment une seule branche sont une branche écrite deux fois ; réduisez-les et ne conservez que les branches véritablement distinctes.
• Supprimez l'identité que le corps porte déjà.

Les deux charges

Chaque document et pointeur que vous ajoutez dépense l'un des deux budgets suivants :

• Charge de contexte est le coût du matériel toujours chargé dans la fenêtre de l'agent : une ligne de AGENTS.md, une description de compétence, tout ce qui se trouve dans le contexte à chaque tour, dépensant des tokens et de l'attention, que cela se déclenche ou non.
• Charge cognitive est le coût pour l'humain : quels documents existent et quand les consulter. L'humain est l'index. Ce n'est pas un coût à minimiser : c'est le prix de l'action humaine ; dépensez-le là où le jugement humain compte, retirez-le là où ce n'est pas le cas.

Le matériel atteint uniquement via un pointeur échappe à la charge de contexte au prix de la ligne du pointeur lui-même ; le matériel sans pointeur repose entièrement sur la charge cognitive.

Hiérarchie de l'information

Un document est construit à partir de deux types de contenu : les étapes (les actions ordonnées que l'agent exécute) et les références (définitions, règles, faits consultés à la demande). Les deux se mélangent librement : toutes des étapes (une recette), toutes des références (les règles d'une révision, cette compétence), ou les deux. La décision centrale est de savoir où chaque élément se situe sur la hiérarchie de l'information, une échelle classée par le degré d'immédiateté dont l'agent a besoin pour le matériel :

1. Étape intégrée est le niveau principal : ce que l'agent fait, dans l'ordre.
2. Référence intégrée est consultée à la demande. Il s'agit souvent d'un ensemble de pairs légitimes et à plat (chaque règle d'une révision sur un même échelon), ce qui est une bonne disposition, pas un défaut.
3. Référence déléguée est repoussée dans un fichier séparé, atteint par un pointeur de contexte, chargé uniquement lorsque le pointeur se déclenche. S'étend d'un fichier frère dans le même dossier à une référence entièrement externe qui peut vivre n'importe où et que n'importe quel document peut pointer.

Poussez trop peu vers le bas et le sommet gonfle ; poussez trop et vous cachez du matériel dont l'agent a réellement besoin. Cette tension est toute la décision.

Divulgation progressive est le mouvement vers le bas de l'échelle (hors du fichier principal et derrière un pointeur) afin que le sommet reste lisible. Il ne s'agit pas principalement d'une optimisation de tokens : c'est ainsi que la hiérarchie est protégée. La ramification est le meilleur test de divulgation : intégrez ce dont chaque branche a besoin, et poussez derrière un pointeur ce que seules certaines branches atteignent. Lorsqu'un document comporte des étapes, les références intégrées qui devraient être divulguées les enterrent et transformer l'attention qui leur est portée en un pile-ou-face : un levier de variance, pas seulement de lisibilité.

Co-localisation est le complément intra-fichier : là où l'échelle décide à quelle distance un élément se trouve, la co-localisation décide ce qui se trouve à côté une fois sur place. Gardez la définition d'un concept, ses règles et ses mises en garde sous une même rubrique plutôt que dispersées, afin que la lecture d'une partie amène ses voisines. Le test : le document doit se lire comme une documentation écrite pour l'agent. Le matériel regroupé se lit ainsi ; le matériel dispersé, non. (Distinct de la duplication : celle-ci répète un sens en deux endroits ; la dispersion fragmente un sens en plusieurs.)

L'étalement est le mode de défaillance ici : un document tout simplement trop long, même lorsque chaque ligne est vivante et unique. L'attention s'amenuise sur l'excédent, et chaque ligne supplémentaire est une de plus à garder pertinente. Le remède est l'échelle : divulguez les références derrière des pointeurs, et scindez par branche ou séquence afin que chaque chemin ne porte que ce dont il a besoin.

Étapes et critères d'achèvement

Chaque étape se termine sur un critère d'achèvement, la condition qui indique à l'agent que le travail est terminé. Deux propriétés en font un levier :

• Clarté : l'agent peut-il distinguer fait de non-fait ? Une limite vague (« compréhension atteinte ») invite à l'achèvement prématuré : terminer l'étape avant qu'elle ne soit réellement terminée, l'attention glissant vers le fait d'être terminé. Les étapes encore visibles devant (les étapes post-achèvement) fournissent l'attrait ; la clarté du critère est la résistance. Défendez dans l'ordre : affinez d'abord la limite (local et peu coûteux) ; seulement si elle est irrémédiablement floue et que vous observez la précipitation, cachez les étapes ultérieures en scindant la séquence. Cacher ne fonctionne qu'à travers une véritable limite de contexte (un transfert ou un envoi à un sous-agent ; un appel en ligne laisse les étapes ultérieures dans le contexte et n'efface rien).
• Exigence : ce qu'elle requiert. « Chaque modèle modifié pris en compte » force un travail approfondi là où « produire une liste de modifications » ne le fait pas. L'exigence génère le travail de fond (les recherches que l'agent effectue dans le cadre du travail, latentes dans le libellé plutôt qu'écrites comme une étape distincte), et elle n'est pas liée à l'étape : « chaque règle appliquée » lie un corpus de références à plat tout comme « chaque étape effectuée » lie une séquence, ce qui est la façon dont un document tout en références porte encore une barre d'exhaustivité.

Les critères les plus forts sont à la fois vérifiables et exhaustifs.

Quand scinder

Scinder un document en deux dépense l'une des deux charges, donc ne scindez que si la coupure le justifie :

• Par séquence : scindez une série d'étapes où les étapes post-achèvement incitent l'agent à se précipiter sur celle qui précède. Les maintenir hors de vue génère plus de travail de fond sur la tâche en cours. Attention à l'inverse : fusionner des séquences expose chaque étape aux étapes ultérieures de ce qui suit, invitant à l'achèvement prématuré.
• Par invocation, spécifique à la compétence : voir SKILL-MECHANICS.md.

Mots directeurs

Un mot directeur est un concept compact vivant déjà dans le pré-entraînement du modèle avec lequel l'agent pense en exécutant le document (leçon, brouillard de guerre, balles traçantes). Répété comme un token, jamais comme une phrase, il accumule une définition distribuée et ancre toute une région de comportement dans le moins de tokens possible, en recrutant des a priori que le modèle possède déjà. En inventer un fonctionne si vous le définissez clairement, mais un mot inventé ne recrute aucun a priori : vous payez en tokens de définition ce qu'un mot pré-entraîné donne gratuitement ; utilisez d'abord un mot existant.

Il ancre deux fois. Dans le corps, exécution : l'agent atteint le même comportement à chaque fois que le mot apparaît, et à l'intérieur d'une référence à plat, il concentre l'attention sur une classe de choses à rechercher. Dans un pointeur, invocation : lorsque le même mot vit dans vos instructions, vos documents et votre code source, l'agent relie ce langage partagé au matériel et l'atteint plus fiablement.

Cherchez les occasions de refactoriser avec des mots directeurs. Une triade épelée sur trois sites, un pointeur dépensant une phrase pour désigner une idée. Chacun est un passage qui demande à être réduit à un seul token :

• « rapide, déterministe, faible surcharge » → serré (une boucle serrée).
• « une boucle en laquelle vous avez confiance » → rouge, transformant une porte floue en un état binaire observable (la boucle passe au rouge sur le bogue, ou non).

Vous gagnez deux fois : moins de tokens, et un accrochage plus net pour que l'agent accroche sa réflexion. Supposez que chaque document contient des reformulations que les mots directeurs retirent. Allez les trouver.

La négation est le mode de défaillance à côté de ce levier : diriger par l'interdiction traîne le comportement interdit dans le contexte et le rend plus disponible, pas moins. Ne pensez pas à un éléphant, et l'éléphant est tout ce qu'il y a ; la négation est un modificateur faible que le concept fortement activé submerge, de sorte que l'interdiction se lit à moitié comme une instruction pour faire la chose. Incitez le positif : énoncez le comportement cible (« écrivez des commentaires d'une ligne ») afin que le comportement interdit ne soit jamais prononcé. Une interdiction ne mérite sa place que comme une barrière de sécurité dure que vous ne pouvez pas formuler positivement ; même dans ce cas, associez-la à la cible positive pour que l'attention se pose sur ce qu'il faut faire.

Élagage

• Conservez chaque signification dans une source de vérité unique : un endroit faisant autorité, de sorte que modifier le comportement soit une modification en un seul endroit. La duplication (le même sens à plus d'un endroit) coûte de la maintenance et des tokens, et gonfle l'importance d'un sens sur l'échelle au-delà de son rang réel. (L'inverse accidentel d'un mot directeur, qui répète un token intentionnellement, jamais le sens.)
• L'environnement est aussi une source de vérité (scripts package.json, fichiers de configuration, l'arborescence des répertoires, la sortie --help), et un document qui le reformule est un cache : une copie d'une recherche, qui ne mérite sa charge que lorsque la recherche est coûteuse. Mettez en cache ce que l'agent ne peut pas trouver en regardant : la convention non écrite, la raison derrière un choix, l'écueil qu'aucune configuration n'avoue. Laissez les recherches d'un fichier ou d'une commande à l'environnement, où elles ne peuvent pas devenir obsolètes.
• Vérifiez chaque ligne pour pertinence : porte-t-elle encore sur ce que fait le document ? Une ligne perd sa pertinence en ne portant jamais sur la tâche (simple exposition, ou une branche qui devrait être divulguée) ou en devenant obsolète à mesure que le comportement ou le monde qu'elle décrit change. Les documents plus courts sont plus faciles à garder pertinents. Sans une discipline d'élagage, le destin par défaut est la sédimentation : des couches obsolètes qui se déposent parce qu'ajouter semble sûr et retirer semble risqué, jusqu'à ce que vous deviez creuser à travers elles pour trouver ce qui est encore vivant.
• Traquez les non-opérations phrase par phrase : une instruction que le modèle obéit déjà par défaut paie une charge pour ne rien dire. Le test (change-t-elle le comportement par rapport à la valeur par défaut ?) est relatif au modèle, pas au lecteur : deux personnes en désaccord sur une non-opération sont en désaccord sur la valeur par défaut, et la règlent en exécutant le document, pas par débat. Lorsqu'une phrase échoue, supprimez la phrase entière plutôt que d'en tailler les mots. Le test évalue également les mots directeurs : un mot trop faible pour battre la valeur par défaut (« soyez minutieux » alors que l'agent est déjà à peu près minutieux) est une non-opération, et la solution est un mot plus fort (« impitoyable »), pas une technique différente.