<!-- SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. --> <!-- SPDX-License-Identifier: Apache-2.0 -->

Explorer le comportement prévu d'un agent

Capturez ce que l'agent doit faire. La mission produit et les objectifs utilisateur importent plus que l'inventaire d'implémentation. Le résultat de cette skill est la donnée que ethos-write écrit dans ethos.md — le contrat durable que les personnes et agents lisent avant de construire, évaluer, revoir ou modifier cet agent. Une entrée sous-spécifiée ici conduit chacun à deviner l'intention à partir du code et des traces.

Cette skill est d'abord explorer, puis un entretien d'intention obligatoire. Scannez la base de code et la documentation, déduisez les champs façonnés par l'implémentation, puis posez à l'utilisateur les questions d'intention que la source ne peut pas assumer. Ne sautez pas l'entretien parce que le scan semblait complet, et ne sautez pas une question parce que vous pensez déjà connaître la réponse. Ne déversez pas le brouillon ethos.md tant que cet entretien n'a pas posé au moins trois questions et reçu une réponse à chacune.

La division du travail est : déduire l'implémentation, demander l'intention. Presque tout ce que l'agent est peut être lu dans la source. Rien sur ce que le développeur veut ne peut l'être. Les contraintes, les compromis, les principes, la mission et la vision vivent dans la tête de l'utilisateur, ce sont donc les questions qui valent la peine d'y consacrer du temps.

Créer un ethos.md capture l'intention et n'autorise aucun changement à l'application de l'agent. Ne demandez pas de permissions de changement ou d'optimisation, ni comme sujet séparé ni à l'intérieur d'une autre section. La permission de changer le code, les prompts, les modèles, les tools ou les évaluations appartient au workflow effectuant ce travail si l'utilisateur le demande. Créer un ethos.md n'implique aucun suivi. Préservez les politiques de sécurité organisationnelle déjà confirmées et leurs propriétaires connus, y compris l'examen de sécurité requis avant de déployer un tool avec accès en écriture. Enregistrer une restriction existante n'accorde pas de permission ni n'exige un nouvel entretien de permission.

Le schéma que vous remplissez

L'ethos.md a cinq champs front-matter de base, plus updated_timestamp optionnel, et quatorze sections de corps. Chaque section de corps est requise. Un champ est une porte de qualité pour le handoff : ethos-write est bloqué jusqu'à ce que Role soit concret. Pour toute autre section canonique sans rien à dire, écrivez _(none)_ plutôt que de supprimer le titre.

Les quatorze titres sont un plancher, pas un plafond. Les titres ## supplémentaires et les clés YAML front-matter supplémentaires sont autorisés. Conservez-les si l'utilisateur les ajoute. Ne supprimez pas les sections personnalisées pour que le fichier paraisse « strict ».

Front matter

Sections de corps (dans l'ordre canonique)

L'ethos.md enregistre l'intention durable, pas une liste courante des défaillances observées. Suivez les problèmes connus et les motifs de défaillance récurrents où l'équipe suit les bugs.

Pré-vol

Vérifiez si un ethos.md existe déjà pour cet agent. Cherchez ethos.md, y compris un ETHOS.md écrit par Eval Author 0.1.0, à la racine du repository et à côté du package de l'agent. S'il en existe un, demandez à l'utilisateur s'il veut modifier l'ethos.md existant ou recommencer. S'il veut modifier, acheminez directement vers ethos-write.

find . -maxdepth 4 -iname ethos.md -not -path '*/.git/*' -not -path '*/node_modules/*' 2>/dev/null | grep . || echo "no ethos.md yet"

Si le repository a une spécification d'agent antérieure ou un doc de conception, lisez-le comme des réponses antérieures. Scannez la base de code, puis exécutez toujours l'entretien d'intention pour tout ce qu'il n'a jamais répondu.

Étape 1 — Explorer la base de code

Limiter à ~5 minutes d'utilisation d'outils. Lisez d'abord, posez la question ensuite. Les projets greenfield ne trouveront rien ici, ce qui est correct — passez à l'entretien d'intention et posez d'abord la question sur Role.

1. Trouvez les définitions d'agent et les points d'entrée. Cherchez les configs d'agent, les YAMLs workflow, les constructeurs d'agent Python, les system prompts, les skills et les définitions de tools :

   find . -maxdepth 5 -type f \( -name "agent.yaml" -o -name "agent.yml" \) 2>/dev/null
   find . -maxdepth 4 -type f \( -name "*.workflow.yaml" -o -name "*.workflow.yml" \) 2>/dev/null
   find . -maxdepth 4 -type d -name "agents" 2>/dev/null

   Utilisez ensuite Glob / Grep pour trouver langgraph, StateGraph, create_react_agent, system_prompt, skills, serveurs MCP et définitions de tools. Traitez tout nom de harness ou de framework que vous trouvez comme un indice sur le fonctionnement de l'agent, pas comme une valeur que ethos.md doit choisir.

2. Trouvez le contexte de conception. Cherchez README.md, AGENTS.md, docs produit/conception/planification, notes de lancement et tout ce qui est dans docs/. Lisez la documentation qui décrit les objectifs et la valeur utilisateur avant les détails d'implémentation quand ils semblent pertinents pour l'agent.

3. Mappez les résultats aux champs du schéma. En scannant, maintenez un tableau mental courant de ce que vous pouvez remplir à partir du code/docs. Soyez honnête sur la confiance : « déduit du system prompt » est différent de « confirmé par l'utilisateur ».

4. Notez le modèle uniquement comme une contrainte. L'ethos.md n'a pas de section Model. La config de l'agent porte déjà le modèle en usage, et il change sans toucher à l'ethos.md. Si le scan montre une liste blanche de fournisseurs ou une famille de modèles épinglée, portez-la dans Constraints comme un brouillon à confirmer.

   Inférences typiques par champ :

   • name — nom du répertoire, nom du workflow ou nom du package de haut niveau.
   • Role — premier paragraphe du README, préambule du system prompt ou docstring de haut niveau. Souvent partiel ; généralement besoin de confirmation de l'utilisateur.
   • Purpose & Outcomes — mission des docs produit, motivation README, préambule du system prompt ou contexte workflow. Traitez-le comme un brouillon à confirmer, jamais comme un saut. Le résultat (l'objectif commercial) est rarement dans le code ; même quand un README nomme une métrique, demandez à l'utilisateur de la confirmer.
   • Scope — audience des docs ou prompts ; catégories des capacités énumérées ou clusters de tools nommés ; limites in/out des règles du prompt.
   • Tools — à partir des décorateurs @tool, registres de tools, create_react_agent(tools=[...]), config de récupération/corpus ou clients API. Groupez les helpers de bas niveau quand ils partagent des credentials, des effets secondaires, de la fraîcheur et des modes de défaillance.
   • Harness — déduisez de comment l'agent fonctionne réellement : config d'adaptateur, YAML workflow, points d'entrée service, commandes CLI, Dockerfiles ou configs de déploiement. Capturez les capacités comportementalement pertinentes, pas un nom de catalogue. Si vous ne pouvez pas voir comment ça fonctionne, écrivez _(none)_.
   • Behavior — règles du system prompt (« ne jamais donner de conseil médical »), politique de refus/escalade, ton, limitations acceptées et non-objectifs.
   • Success Criteria — résultats de production souhaités, objectifs produit, normes de qualité, qualité de l'escalade, attentes d'exactitude et exemples de comportement réussi.
   • Trade-offs — pas dans le code ; demandez dans l'entretien d'intention.
   • Constraints — surtout pas dans le code, mais scannez pour des preuves partielles qui en valent la peine : une URL de base de gateway épinglée ou une liste blanche de fournisseurs, des paramètres de région, une redaction ou un middleware PII, des plafonds de timeout et de tokens, et des notes de conformité dans les docs. Traitez les résultats comme un brouillon de départ à confirmer, jamais comme la liste complète.
   • Evaluation Setup — cibles Makefile, scripts, config CI, YAMLs eval, définitions de métriques, seuils et notes de couverture.
   • Metric Semantics — à partir des définitions de scorer, noms de métriques dans les configs eval et noms de champs de télémétrie. Remplissez uniquement les entrées dont le sens est vraiment ambigu à partir du nom. Écrivez _(none)_ quand chaque nom est évident.
   • Principles — pas dans le code ; demandez dans l'entretien d'intention même si un prompt en suggère un. Un prompt est l'implémentation, pas l'intention derrière.
   • Vision — pas dans le code. Les docs de roadmap, les notes de conception ou une section future-work du README sont spéculatifs jusqu'à ce que l'utilisateur les confirme. Demandez. Écrivez _(none)_ plutôt que de deviner.
   • Open Questions — TODOs / FIXMEs dans le code adjacent à l'agent qui affectent l'utilisation sûre ou l'évaluation.

Étape 2 — Poser les questions d'intention

Le scan vous a dit ce que l'agent est. Il ne peut pas vous dire ce que le développeur veut. Menez un vrai entretien pour cette intention avant de montrer un brouillon ethos.md.

Cette étape est une porte dure. Ne présentez pas le brouillon complet et ne remettez pas à ethos-write jusqu'à ce que vous ayez posé au moins trois questions et reçu une réponse à chacune. « Le scan a rempli tout » et « poser semble inutile » ne sont pas des raisons de la sauter.

Quoi demander

Après le scan, divisez les champs en deux piles :

• Inferred — champs façonnés par l'implémentation que vous pouvez brouillonner depuis la source : Tools, Harness, Evaluation Setup, Behavior copié des prompts, Metric Semantics des noms de scorers.
• Intent — champs que la source ne peut pas assumer : Purpose & Outcomes, Principles et Vision toujours ; puis Constraints, Trade-offs et un Success Criteria classé quand le repo n'a que du câblage eval.

Parcourez la pile d'intention. Sautez un sujet uniquement quand cette conversation l'a déjà répondu. Un README, prompt ou roadmap n'est pas un substitut à une réponse utilisateur sur les sujets toujours-demander ci-dessous. Conservez tous les autres sujets d'intention non répondus sur la liste. Le travail greenfield ajoute Role, Scope et si l'agent est prompt-only avant cette liste d'intention.

Le nombre de questions est au minimum trois, puis autant de sujets d'intention restants qui ont toujours besoin d'une réponse. Préférez moins de questions nettes à une longue checklist, mais jamais moins de trois.

Toujours demander ces trois

Le code et les docs peuvent ressembler à les avoir déjà répondus. Ils ne l'ont pas, jusqu'à ce que l'utilisateur le dise. Demandez même quand vous avez un brouillon à haute confiance. Confirmer une inférence compte ; remplir silencieusement la section ne compte pas.

1. Purpose & Outcomes (objectif commercial). Confirmez la mission et le résultat pour lequel l'agent est responsable. Si vous avez déduit une métrique d'un README, montrez-la et demandez si c'est la cible.
2. Principles. L'appel de jugement quand Behavior s'épuise. Rejetez les vertus génériques. Demandez ce que cet agent devrait faire qu'une version négligente ne ferait pas.
3. Vision. Où l'agent se dirige, ou un explicit _(none)_. Ne copiez pas une section future-work dans Vision sans poser la question. La vision spéculative est l'échec habituel.

Si Role est manquant ou vague, posez cette question en premier pour que le reste de l'entretien soit fondé. Il ne remplace pas une des trois sujets toujours-demander.

Posez des questions sur les sujets restants dans cet ordre, en sautant ceux que cette conversation a déjà répondus :

1. Constraints — limites dures sur le fonctionnement de l'agent, y compris les approbations d'actions d'exécution si nécessaire.
2. Trade-offs — portes dures de comportement, puis un classement des résultats souhaités.
3. Un Success Criteria classé quand le repo n'a que du câblage eval.

Ne demandez pas quelles parties peuvent être optimisées ou changées, y compris dans un suivi, un checkpoint ou un examen de brouillon. Conservez les exigences de sécurité des actions d'exécution : par exemple, un agent peut avoir besoin d'approbation avant d'émettre un remboursement. Cela décrit son comportement prévu ; cela n'accorde pas de permission de changer son code.

Ne collectez pas les limites d'exécution. Un plafond de dépense ou un nombre d'expériences pour une exécution d'évaluation appartient à l'outil qui l'exécute. Si l'utilisateur en offre une volontairement, conservez la politique existante et supprimez le chiffre.

Comment demander

Suivez ce modèle de Q&A :

• Une question par message. Si un sujet a besoin de plus de profondeur, posez une question de suivi dans le message suivant. Ne regroupez pas quatre questions d'intention.
• Préférez les choix multiples. Fondez les options sur ce que vous avez trouvé. Incluez toujours un moyen de rejeter la liste (« Quelque chose d'autre » ou « Je ne sais pas »). Open-ended est correct quand une liste lettrée simulerait une certitude.
• Attendez la réponse avant la prochaine question.
• Acceptez « Je ne sais pas » et passez. Écrivez _(none)_ et enregistrez le gap dans Open Questions. Une contrainte fabriquée est pire qu'une manquante.
• Confirmez les limites déduites. Si le scan a trouvé une gateway épinglée ou un middleware de redaction, montrez-la et demandez si c'est une vraie limite.
• Confirmez l'intention déduite. Si le scan a produit un Purpose & Outcomes, Principles ou Vision plausible, montrez le brouillon comme une option. Ne traitez pas ce brouillon comme la réponse.

Exemple (un message, puis arrêtez) :

Le README dit que cet agent existe pour « réduire le volume de tickets ». Est-ce l'objectif commercial que je devrais enregistrer dans Purpose & Outcomes ?

A. Oui — le volume de tickets est le résultat (dites-moi la cible si vous l'avez) B. Proche, mais l'objectif réel est … (dites-moi) C. Pas de métrique commerciale — outil interne D. Je ne sais pas

Un exemple Constraints plus tard :

Le scan montre une gateway de modèle épinglée et pas de plafond de coût dans les docs.

Quelles limites dures Constraints devrait-elle enregistrer ?

A. L'agent doit utiliser cette gateway ; pas d'autres limites B. Cette gateway est requise, plus un plafond de coût de production ou de latence (dites-moi le chiffre) C. Pas de limites dures — écrivez _(none)_ D. Quelque chose d'autre

Rejetez les vertus génériques pour Principles. « Utile, inoffensif et honnête » ne donne rien au lecteur en aval. Demandez l'appel de jugement : qu'est-ce que cet agent fait qu'une version négligente ne ferait pas ? Si rien ne revient, écrivez _(none)_.

Poussez une fois sur une non-réponse pour Trade-offs. « Équilibrer qualité et coût » n'est pas décidable. Une question de suivi concrète produit généralement un classement. Si ce n'est pas le cas, enregistrez l'ambiguïté et passez.

Si l'utilisateur fournit du contexte extérieur, lisez-le et mettez à jour le brouillon déduit avant la prochaine question.

Drapeaux rouges — arrêtez et demandez

Ceux-ci signifient que vous avez sauté l'entretien :

• Vous êtes sur le point de coller le ethos.md complet et avez posé moins de trois questions
• Vous avez rempli Purpose & Outcomes, Principles ou Vision à partir du scan sans une réponse utilisateur
• Plusieurs questions d'intention dans un message
• Remise à ethos-write avec moins de trois réponses Q&A dans cette conversation

Étape 3 — Présenter le brouillon ethos.md

Après l'entretien, présentez l'intégralité de l'ethos.md à la fois — chaque champ, avec des valeurs déduites affichées inline et des gaps restants comme _(none)_. Puis posez une question :

« Voici le ethos.md complet que j'écrirais. Dites-moi ce à changer, et j'ai besoin d'un Role concret avant de pouvoir remettre à ethos-write. »

Montrez le ethos.md rendu inline en markdown (une section ## par champ, même forme que le fichier sur disque). Pour les champs que vous avez défini par défaut, notez le défaut entre parenthèses pour que l'utilisateur sache qu'il peut le modifier :

• Tools: Prompt-only. (défaut — dites-le si l'agent a besoin de tools)
• Purpose & Outcomes / Success Criteria déduit de l'implémentation (dites-le s'il y a du contexte extérieur à intégrer)

Quand l'utilisateur ne pouvait pas répondre à une section, écrivez _(none)_ et ajoutez le gap à Open Questions. Dites « Constraints : (none) — les limites opérationnelles restent non spécifiées » pour que la conséquence soit visible tant qu'il est encore bon marché de la corriger. Une limite non spécifiée n'accorde pas de permission de changement d'application.

Ne passez pas en revue le schéma champ par champ dans cet examen. Ne redémarrez pas l'entretien d'intention ici sauf si la réponse fait surface une contradiction.

N'utilisez pas la sténographie publique comme AUT ou « agent en test » dans le ethos.md rendu. Utilisez « cet agent » pour l'agent en cours de spécification. Utilisez « agent cible » uniquement quand le but de l'agent est explicitement d'inspecter ou de modifier un autre agent.

Suites autorisées après le brouillon :

1. Le requis dur Role est manquant ou vague — demandez-le avant le handoff.
2. La réponse de l'utilisateur fait surface une contradiction qui a besoin d'une clarification ciblée (par exemple, ils disent « supprimer le tool de recherche » mais la base de code montre que l'agent en dépend).

Étape 4 — Handoff

Après la réponse de l'utilisateur, appliquez les corrections et vérifiez la précondition unique et dure :

1. Role est une réponse concrète d'une phrase (pas « aider avec des trucs »).

Si c'est toujours non résolu, demandez-le dans un dernier message et arrêtez jusqu'à ce que l'utilisateur le fournisse. Ne remettez pas avec Role vide — l'artefact est inutile en aval même si l'analyseur l'accepte.

Chaque titre de section de corps doit être présent avant le handoff. Écrivez _(none)_ pour les gaps honnêtes, et notez-les dans Open Questions quand ils affectent l'utilisation sûre ou l'évaluation. Ne supprimez pas un titre.

Si la porte de qualité Role est satisfaite, annoncez le handoff en une ligne (« Remise à ethos-write pour écrire ethos.md ») et déclenchez-le.

Si l'utilisateur se rétracte

• Ils veulent changer un ou deux champs. Appliquez les modifications, ré-affichez les sections changées uniquement, demandez « ça va mieux ? », procédez.
• Ils veulent tout recommencer. Cela signifie généralement que le scan de la base de code s'est fondamentalement trompé. Re-scannez en gardant leur correction à l'esprit, puis re-présentez une fois.
• Ils continuent de changer d'avis sur Role. Arrêtez. Dites-leur que l'agent ne sera pas utile jusqu'à ce qu'ils puissent écrire une phrase concrète et proposez de revenir plus tard. Ne boucleriez pas sur le reformatage.
• Ils sautent les questions d'intention restantes. Vous avez déjà posé au moins trois, y compris Purpose & Outcomes, Principles et Vision. Traitez les sujets sautés comme « Je ne sais pas » : écrivez _(none)_, enregistrez-les dans Open Questions et dites une fois quel en est le coût. Puis présentez le brouillon. Ne ré-ouvrez pas l'entretien complet.
• Ils disent « juste écrivez-le » avant trois questions. Posez la prochaine question toujours-demander de toute façon. Après qu'ils aient répondu ou refusé chacune des trois, continuez.

Pièges

• « Vous décidez » signifie vous engager au défaut et l'annoncer. Exemple : « J'enregistrerai Tools: Prompt-only. Dites-moi de le changer si ce n'est pas le cas. » Ne remplissez jamais silencieusement.
• La sur-spécification de tools est l'erreur la plus courante. Les utilisateurs demandent un tool de recherche quand prompt-only suffirait. Sonde : « Avez-vous une preuve que le modèle seul échoue sur ceux-ci ? » Si non, supprimez le tool.
• L'inventaire des tools et harness doit être compressé. Ne créez pas une ligne par méthode helper quand plusieurs helpers partagent la même source, credential, effet secondaire, fraîcheur et mode de défaillance. Groupez-les et appelez seulement les différences qu'un évaluateur ou reviewer doit connaître.
• Mission avant la mécanique. Un ethos.md qui dit seulement comment le code actuel est câblé n'est pas suffisant. Si le contexte d'objectif ne peut pas être trouvé dans la base de code ou les docs, dites que la mission est déduite de l'implémentation et posez toujours à l'utilisateur de confirmer Purpose & Outcomes. Un objectif commercial deviné est pire que _(none)_.
• Ne déduisez jamais une contrainte que vous ne pouvez pas vérifier. Une liste blanche de fournisseurs ou un plafond de coût deviné déclare mal les limites opérationnelles de l'agent. Demandez ou écrivez _(none)_ et enregistrez le gap dans Open Questions.
• Les trade-offs rendent les résultats concurrents décidables. Un ordre de priorité indique à l'agent et ses évaluateurs quel résultat importe quand la qualité, la latence, le coût ou la fiabilité entrent en conflit. Cela n'accorde pas de permission d'optimisation.
• « Aucune contrainte de comportement » signifie généralement « Je n'y ai pas pensé ». Sonde une fois : « Quelque chose qui ne devrait jamais apparaître — noms, numéros de téléphone, mentions de concurrents ? » Une sonde, puis passez.
• Ne sautez pas le scan de base de code même si l'utilisateur semble impatient de répondre aux questions. Passer les cinq premières minutes à lire rend l'entretien plus court et plus incisif. Poser quelque chose que la base de code a déjà répondu perd la confiance immédiatement.
• Ne sautez pas l'entretien d'intention même si le scan semble complet. Posez au moins trois questions. Demandez toujours Purpose & Outcomes, Principles et Vision, même quand vous pensez déjà le savoir. Un à la fois. Choix multiples quand vous pouvez.
• N'inventez pas Vision à partir d'un backlog. Une puce de travail futur est spéculative jusqu'à ce que l'utilisateur la confirme. Demandez ou écrivez _(none)_.
• Une importation de framework n'est pas un harness. Décrivez comment l'agent fonctionne. Ne mappez pas une importation sur un nom de harness. Les importations telles que langchain, langgraph, crewai, autogen ou pydantic_ai ne disent rien à ce sujet.
• Enregistrez l'intention, pas la config d'exécution. Décrivez le comportement harness souhaité et les artefacts sans demander à l'utilisateur de concevoir une config d'exécution brute. Les fichiers de config restent avec l'implémentation de l'agent.
• N'inventez pas de champs Known Issues. Les problèmes connus et les motifs de défaillance récurrents appartiennent au traceur de problèmes de l'équipe, pas à l'ethos.md.