panbergco/agent-cli-writer

Rédacteur de CLI pour agent

Un agent cherche la commande, pas le manuel. Une règle qui n'existe que dans un document est suivie lorsque l'agent a la chance de la lire. Les mesures qui sous-tendent ceci se trouvent dans references/evidence.md.

La règle : chaque règle de l'outil est énoncée par l'outil, au moment où elle s'applique. Ce qu'il affiche, ce qu'il refuse et ce qu'il facilite constituent le manuel.

Ce qu'un agent fait avec un outil

• Cherche d'abord la commande ; n'ouvre le manuel qu'en cas de doute, et est souvent sûr et se trompe.
• Lit pour confirmer un plan déjà fait : il cherche la syntaxe, pas les règles.
• Oublie tout entre les sessions et réapprend l'outil à chaque fois.
• Envoie plusieurs appels à la fois.
• Paie à nouveau pour chaque caractère que l'outil a affiché, lors de chaque requête ultérieure.
• Ne peut pas attendre à moindre coût : il sonde ou dort, et chaque sondage est une requête payante.
• Fait ce que dit la réponse qui se trouve devant lui, plus sûrement que ce qu'un document a dit plus tôt.

Méthode

Douze vérifications, chacune avec la manière de la vérifier. tool est une commande fictive.

1. Enseigner au point d'utilisation. La réponse à une commande dit ce que le chemin qui vient d'être emprunté coûte, et nomme le meilleur chemin.

   $ tool machine new
   créé m-41 (s'arrête tout seul dans 60 min)
   note : le travail commencé à la main dans cette machine ne conserve aucun enregistrement d'exécution.
          pour un travail que vous devez suivre : tool job start --from <dir> -- <cmd>
   

   Vérifiez : chaque verbe avec une utilisation incorrecte connue le dit dans sa propre sortie.
2. Un refus est une leçon. Dites ce qui a été refusé, pourquoi, et la commande exacte suivante avec les propres arguments de l'appelant complétés. Donnez tous les problèmes en une seule réponse. Ne quittez jamais avec un code non nul sans paroles. Une erreur d'utilisation affiche la forme correcte de cette seule sous-commande.

   tool : refusé : `job wait j-7` retiendrait ce tour pendant jusqu'à 40 min.
          suivant :  tool job show j-7          (où il en est maintenant)
                     tool job start … --notify  (être prévenu quand il se termine)
   

   Vérifiez : aucun chemin de sortie sans message ; chaque refus comporte un suivant :.
3. Transportez le manuel dans l'outil. tool rules affiche les règles de fonctionnement en entier, se terminant par un code de version. Les verbes qu'un agent pilote à la main refusent un appelant non interactif qui n'a pas défini le code actuel (TOOL_RULES=<code>), en une ligne. Les verbes qui sont l'interface machine restent ouverts. Le code change lorsque les règles changent. Vérifiez : un agent vierge recevant uniquement le nom de la commande a les règles dans son contexte avant son premier appel qui crée, modifie ou supprime quelque chose.
4. Faire du bon chemin le chemin facile. Avant d'écrire "préférer X", faites en sorte que X fasse tout le travail : prenez l'entrée que les agents ont vraiment, revenez immédiatement, conservez un enregistrement. Les agents contournent une commande recommandée qui bloque, perd l'historique ou ne peut pas prendre leur entrée. Énoncez les conséquences, pas les préférences : "Y ne conserve aucun enregistrement" fonctionne là où "préférer X" ne fonctionne pas. Vérifiez : pour chaque "préférer" dans la documentation, nommez ce que le chemin évité offre que le chemin préféré n'a pas, et comblez cet écart.
5. Une seule commande répond à "où en suis-je, et pourquoi". tool status, en quelques lignes : ce qui est à moi, ce qui tourne, comment la dernière chose s'est terminée et pourquoi, quoi faire ensuite. Les agents lisant le stockage ou les journaux de l'outil directement signifie que le statut manque d'un fait. Vérifiez : comptez ces lectures dans des transcriptions réelles ; les trois questions les plus courantes doivent figurer dans le statut.
6. Travail long : démarrer, revenir, dire. Au bout d'environ une minute : start renvoie un identifiant immédiatement ; show <handle> donne la chronologie, le code de sortie et les dernières lignes, même après que le travailleur soit parti ou que l'appelant soit mort ; la fin est délivrée à l'appelant avec le résultat et la raison. Un message n'est qualifié que lorsqu'il apporte quelque chose de nouveau sur lequel l'agent peut agir maintenant : pas de "continuez" périodique. Vérifiez : rien ne bloque plus de 60 secondes par défaut ; chaque tâche a un enregistrement et un avis de fin avec le résultat, la raison et la prochaine étape.
7. Imprimer peu. La sortie par défaut tient sur un écran : environ 40 lignes ou 2 000 caractères. Plus va dans un fichier dont le chemin est imprimé, ou derrière --full. Pas de bannières, pas d'animation de progression ; instructions permanentes une fois par session. La sortie qui est coupée le dit et dit où se trouve le reste. Vérifiez : mesurez les caractères renvoyés par commande sur une semaine réelle et donnez un budget aux trois totaux les plus importants.
8. Deux lecteurs : une personne et un programme. Texte sur un terminal. En mode pipeline, ou avec --json : uniquement des lignes JSON, noms de champs stables, un résumé final. Le code de sortie est le résultat : 0 fait, et des codes séparés pour refusé, mauvaise utilisation, expiré, jamais exécuté. Diagnostics sur la sortie d'erreur standard. Vérifiez : tool <verbe> | cat s'analyse ; --help répertorie chaque code de sortie.
9. Sûr à répéter, sûr immédiatement. Exécuter une commande deux fois ne fait pas la chose deux fois, ou dit qu'elle était déjà faite. Deux appels simultanés d'un même agent ne perdent pas les écritures de l'autre : verrouillez, ou refusez le second avec des mots. Les verbes destructeurs nécessitent un indicateur explicite et proposent --dry-run. Vérifiez : un test exécute chaque verbe d'écriture deux fois à la fois.
10. Limitez-le et laissez un enregistrement. Limites de temps par défaut ; ce que l'outil crée expire tout seul ; list montre les restes ; cleanup supprime ce que cet appelant a fait ; le coût d'une chose est une commande. Chaque action est enregistrée avec qui, quand et la version de l'outil ; tool version la nomme. Vérifiez : tuez l'appelant en cours d'exécution ; rien ne tourne sans limite, et l'enregistrement dit ce qui s'est passé.
11. Un nom pour une chose. Le même nom dans la commande, sa sortie, ses erreurs et sa documentation ; un verbe pour une action à travers les noms. Les indicateurs inconnus et les arguments supplémentaires sont refusés, jamais ignorés. Vérifiez : listez les noms que l'outil affiche ; chaque concept a exactement un nom.
12. Les secrets restent dehors. Jamais sur une ligne de commande, jamais renvoyé en écho, jamais dans un enregistrement : à partir d'un fichier, de l'entrée standard ou de l'environnement, masqué dans la sortie.

Rédaction du manuel de l'outil

Le manuel explique ; l'outil impose. Rien de contraignant ne vit uniquement en lui.

• Description : ce que l'outil fait et quand le charger, dans les mots qu'une tâche utiliserait, en nommant les verbes.
• Ordre : d'abord les règles contraignantes, chacune avec sa conséquence ; puis un court tableau de l'objectif et de la commande ; puis l'échec et quoi faire.
• Taille : au maximum 150 lignes, aucune ligne de plus de 100 caractères. Les agents impriment des fichiers avec des longues lignes coupées et perdent la fin de chaque large ligne de tableau.
• Tableaux : rien de contraignant à l'intérieur d'une cellule de tableau.

Prouvez-le sur un agent vierge

Une nouvelle session qui n'a jamais vu l'outil ou son manuel, recevant une tâche réelle et le nom de la commande :

1. Enregistrez chaque appel, sa sortie et son code de sortie.
2. Comptez : consultations d'aide, appels échoués, répétitions d'un appel échoué, sondages, lectures directes du stockage ou des journaux, caractères renvoyés.
3. Chaque compte supérieur à zéro est un défaut de l'outil, pas de l'agent. Corrigez le message ou le chemin, puis exécutez à nouveau dans une autre session vierge.
4. Exécutez une fois de plus avec le manuel chargé : rien ne doit empirer, et le manuel ne doit pas contredire l'outil.

Terminé lorsqu'un agent vierge termine la tâche sans consultation d'aide, sans appel échoué qu'il a dû deviner pour s'en sortir, sans sondage et sans lecture directe du stockage.

Modes d'échec

Règle manuelle uniquement (l'outil ne l'énonce jamais) · Échec muet (code de sortie non nul, sans paroles) · Pourquoi sans suivant (une raison et aucune commande) · Décharge d'aide complète · Préféré mais pire (le chemin recommandé manque de ce que l'autre a) · Écart de statut (les agents lisent le stockage) · Bloqueur (une commande retient le tour) · Harcèlement (un message périodique sans rien de nouveau) · Avis d'aller voir (dit que quelque chose s'est passé, pas quoi) · Mur de texte · Coupure silencieuse · Écriture perdue (deux appels à la fois, un résultat) · Deux noms · Restes (rien n'expire).