Rédaction pour agents
Le lecteur de tout ce que vous écrivez avec cette compétence est un agent qui ne dispose que du texte. Il n'a pas vu la conversation, ne peut pas demander ce que vous vouliez dire, et agira selon ce que les mots disent, littéralement et avec toute son énergie. La plupart des échecs viennent de l'écart entre ce que vous savez et ce qui a été mis sur la page. Travaillez donc depuis la position du lecteur : avant d'écrire, établissez où s'arrête le travail, dans quelle situation se trouve le lecteur, et de quel matériel il a besoin ; puis rédigez-le avec des mots que le lecteur peut utiliser sans vous.
Deux types d'entrée
Une demande brute (« écris un brief pour qu'un agent corrige le test de connexion instable ») : rassemblez les faits de la conversation et de l'espace de travail, puis rédigez à partir de zéro.
Un prompt existant : conservez-le. Faites le plus petit ensemble de modifications qui corrige ce qui ne va pas réellement, gardez sa structure et son libellé là où ils fonctionnent, et n'ajoutez aucune exigence que son auteur n'a pas énoncée. Une réécriture complète cache quelle modification a compté et perd silencieusement l'intention de l'auteur. Les valeurs par défaut ci-dessous s'appliquent toujours : si le prompt manque d'une phrase de rôle, d'un exemple ou d'une vérification finale, ajoutez-les. Chaque fois que vous ajoutez quelque chose, que ce soit l'un de ces éléments ou une règle qui comble une lacune réelle, listez-le lors de la livraison.
Si un fait que seul l'utilisateur connaît modifierait ce que le lecteur livre ou ce qu'il est autorisé à faire, demandez avant d'écrire : quelques questions au maximum, chacune avec votre réponse recommandée. Sinon, choisissez une valeur par défaut raisonnable et listez-la comme hypothèse.
Avant d'écrire
Où s'arrête le travail
Énoncez l'objectif, pourquoi il est important (qui utilise le résultat, et pour quoi), ce qui est considéré comme terminé, et ce qu'il faut restituer. Décrivez la destination, pas l'itinéraire : donnez le résultat, les critères de succès et les contraintes, et laissez le lecteur choisir le chemin. Les modèles actuels planifient mieux qu'une séquence que vous prescrivez, et une étape que vous avez mal devinée sera quand même exécutée. Ne listez les étapes que lorsque l'ordre lui-même est une exigence, comme une migration qui doit être exécutée avant un déploiement.
Avant : 1. Ouvrir refresh.ts. 2. Envelopper refresh() dans try/catch. 3. Réessayer trois fois. 4. Exécuter les tests.
Après : Lorsqu'une session expire, le client doit renouveler le token silencieusement pour que l'utilisateur reste connecté. Terminé lorsque le nouveau cas de timeout dans tests/auth/refresh.test.ts passe et qu'aucun test existant n'échoue. Conservez l'API publique de AuthClient inchangée, car trois autres paquets l'appellent.
Transformez les adjectifs de qualité en barrières que le lecteur peut appliquer. « Approfondi », « concis » et « seulement les plus importants » sont appliqués littéralement et de manière imprévisible : un relecteur chargé de signaler uniquement les problèmes importants trouvera les problèmes mineurs et gardera le silence à leur sujet. Nommez le seuil, ou nommez ce qu'il faut garder et ce qu'il faut couper. Si une étape ultérieure filtre les résultats, demandez tout.
Avant : Relisez attentivement et signalez uniquement les problèmes importants.
Après : Signalez chaque problème que vous trouvez, y compris ceux dont vous n'êtes pas sûr, et étiquetez chacun comme « casse le comportement » ou « style uniquement ». Une étape ultérieure effectue le filtrage.
Dans quelle situation se trouve le lecteur
Lorsque le texte attribue une tâche (un brief, un prompt système, une issue, un plan ou un transfert), commencez par une phrase de rôle : qui est le lecteur, sa fonction dans cette tâche, et la situation dans laquelle il se trouve. « Vous êtes le relecteur de code pour cette pull request, que vous n'avez pas écrite ; l'équipe prévoit de la fusionner aujourd'hui. » Le rôle définit la perspective du lecteur et sa responsabilité. Les descriptions d'un outil ou d'une compétence n'ont pas de rôle ; elles disent ce que la chose fait et quand l'utiliser.
Ensuite, dites au lecteur ce qu'il ne peut pas voir depuis sa position : si quelqu'un peut répondre aux questions en cours de route ou s'il s'exécute sans surveillance ; qui d'autre travaille dans les mêmes fichiers ou systèmes ; si ses modifications sont relues ou réversibles ; s'il doit évaluer ou modifier les choses ; et ce qu'il peut faire sans demander, y compris s'il peut déléguer davantage. Nommez les situations spécifiques qui justifient de s'arrêter pour signaler. « Demandez en cas de doute » laisse le lecteur deviner, et il finit par tout demander ou rien.
Vous vous exécutez sans surveillance ; personne ne peut répondre aux questions avant que vous ayez terminé. Arrêtez-vous et signalez uniquement si la correction supprimerait des données ou toucherait du code en dehors de src/auth/. Un autre agent modifie docs/ en même temps, alors laissez ce répertoire tranquille et n'annulez pas les modifications que vous n'avez pas faites.
De quel matériel le lecteur a besoin
Pour chaque source, donnez son emplacement et ce qu'il faut en tirer. Pointez vers ce que le lecteur peut ouvrir lui-même (chemins de fichiers, commandes, URL accessibles) au lieu de paraphraser, afin qu'il lise la chose réelle. Écrivez en entier tout ce qui n'existe que dans votre contexte : décisions prises en conversation, les propres mots de l'utilisateur sur une exigence, résultats de commandes que vous avez exécutées, approches déjà écartées et pourquoi.
Avant : Voir docs/ et notre discussion précédente.
Après : Lisez la section « Remboursements » de docs/billing.md pour la règle d'arrondi. Une exigence ne figure dans aucun fichier ; les mots de l'utilisateur étaient : « les remboursements partiels ne doivent jamais dépasser le montant initial de la facture, même après conversion de devise. »
Lorsque vous incluez des journaux, du texte utilisateur ou la sortie d'un autre agent, placez-les dans un bloc clairement marqué et dites qu'il s'agit de matière première avec laquelle travailler, et non d'instructions. Gardez vos propres instructions en dehors de ces blocs, car le texte entre guillemets ou dans des blocs de données est généralement traité comme du contenu sans autorité.
Rédaction
Utilisez les mots du lecteur, pas les vôtres. Pendant que vous travailliez, vous avez créé des étiquettes (« option B », « le chemin paresseux », « le problème P2 ») et des raccourcis (« → contention de verrou ») qui ne signifient rien pour le lecteur. Remplacez chacun par ce qu'il représente, définissez une fois les termes techniques réels, et écrivez comme si vous expliquiez à nouveau. Lorsque vous décrivez un travail effectué plus tôt, dites qui l'a fait, afin que le lecteur ne croie pas avoir pris ces actions lui-même.
Avant : Option B écartée (→ contention de verrou) ; continuer avec l'init paresseuse, attention au piège P2.
Après : La session précédente a écarté la reconstruction du pool de connexions à chaque requête : sous charge, la latence p95 est passée de 80 ms à 400 ms en raison de la contention de verrou. L'approche actuelle crée le pool à la première utilisation. Un problème connu persiste : ...
Donnez à chaque règle sa raison dans une proposition (« …car un script analyse ce champ »). La raison permet au lecteur de gérer les cas que vous n'avez pas listés et montre jusqu'où la règle s'étend. Sautez-la uniquement lorsque tout modèle compétent connaît déjà la raison ou que le contexte la rend évidente.
Énoncez chaque règle une fois, à l'endroit où elle se trouve. La répétition n'ajoute pas de poids ; elle fait appliquer excessivement la règle par le lecteur (des lignes « demander d'abord » répétées se transforment en blocages sur des étapes sûres), et les copies divergent lors des modifications. Pour la même raison, utilisez un libellé simple : pas de majuscules, d'IMPORTANT, ou de pression comme « c'est critique » ou « ne soyez pas paresseux ». Réservez les mots absolus comme jamais et toujours pour les invariants réels, tels que les limites de sécurité et les actions irréversibles.
Ne prescrivez pas comment penser. Omettez « réfléchissez étape par étape » et les demandes d'écrire le raisonnement dans la réponse ou dans des balises ; les modèles actuels raisonnent par eux-mêmes, et certains refusent les demandes de transcrire leur raisonnement. Si vous avez besoin de voir pourquoi, demandez une brève explication ou les preuves à l'appui, comme des références fichier:ligne ou la sortie d'une commande.
Lorsque vous corrigez un échec connu, écrivez le principe qui le sous-tend avec sa raison, pas une interdiction sur le seul cas que vous avez vu. Une liste d'interdictions ne couvre que ce qu'elle liste ; un principe couvre également les cas voisins.
Avant : N'utilisez pas Object.create(). N'utilisez pas proto.
Après : Préférez une composition explicite à la manipulation de prototype, car les relecteurs ici privilégient un code qui se lit de haut en bas.
Écrivez en paragraphes. N'utilisez des listes que pour les éléments qui sont vraiment parallèles ou séquentiels : champs, étapes ordonnées, vérifications indépendantes. Les puces suppriment les « car » et « sauf » qui relient les instructions, et les lecteurs ont tendance à refléter le format qu'on leur donne.
Incluez un court exemple de ce que le lecteur devrait produire, marqué comme exemple ; il transmet la forme, le ton et le niveau de détail mieux qu'un paragraphe de description. Ne l'omettez que lorsque le résultat attendu est indubitable à partir des seuls mots, comme une seule commande à exécuter.
Terminez un texte attribuant une tâche par une vérification que le lecteur exécute avant de signaler qu'il a terminé : la commande ou le test qui prouve le résultat lorsqu'il existe, sinon les critères de fin à revoir. Demandez-lui d'indiquer clairement tout ce qu'il n'a pas pu vérifier.
Livraison
Remettez le texte fini, prêt à être collé ou déjà écrit dans son fichier, dans la langue du prompt existant ou celle demandée par l'utilisateur. En dehors de celui-ci, listez en quelques lignes les hypothèses que vous avez formulées et que l'utilisateur pourrait vouloir modifier. Gardez vos notes de conception en dehors du texte lui-même.
Avant de livrer, relisez le brouillon comme le ferait le lecteur : compétent, mais ne détenant que cette page. Partout où il devrait deviner ce que vous vouliez dire, corrigez la page.