agentleFS
SimonKreis-RichardSimonKreis-Richard/oracle-fusion-agentic-toolkit/AGENTS.md

oracle-fusion-agentic-toolkit

AGENTS.md0 starsChanged 51 days agoMITView on GitHub

Fichier maître pour tout agent travaillant sur ce dépôt. Lis-le en entier avant de modifier quoi que ce soit. L'état décisionnel et les options déjà rejetées sont dans memory/PROJECT.md. L'installation est dans SETUP.md. Plugin Claude Code pour un consultant fonctionnel Oracle Fusion Cloud HCM. Quatre métiers, un socle de connaissance partagé : déboguer (un ticket Jira devient un diagnostic de cause racine), configurer (une demande devient un changement construit, vérifié et documenté), conseiller (une question de conception devient une recommandation…

  • Reads credentials
  • Installs packages

The file

Files
AGENTS.md

AGENTS.md — oracle-fusion-agentic-toolkit

Fichier maître pour tout agent travaillant sur ce dépôt. Lis-le en entier avant de modifier quoi que ce soit. L'état décisionnel et les options déjà rejetées sont dans memory/PROJECT.md. L'installation est dans SETUP.md.

1. Vue d'ensemble

Plugin Claude Code pour un consultant fonctionnel Oracle Fusion Cloud HCM. Quatre métiers, un socle de connaissance partagé : déboguer (un ticket Jira devient un diagnostic de cause racine), configurer (une demande devient un changement construit, vérifié et documenté), conseiller (une question de conception devient une recommandation argumentée), tester (un scénario écrit, approuvé une fois, se déroule dans l'instance de test et laisse un document de preuve). Il ne touche jamais la production. Chaque skill produit deux choses, et seulement deux.

  1. Les gestes que l'opérateur exécute lui-même, dans l'ordre, avec le chemin exact dans l'instance.
  2. Le texte du message à envoyer, complet, à copier-coller, à Oracle ou au client.

Tout le reste (preuves, classification, hypothèses, options, impacts) existe pour justifier ces deux sorties, pas pour être lu.

Position dans l'arborescence

Le dépôt est autonome et ne dépend d'aucun fichier au-dessus de sa racine. Il vit en pratique dans un dossier de thème, à côté d'autres outils du même mandat, mais rien dans le code ni dans la documentation ne doit nommer ce dossier ni ses voisins : ils changent, et chaque mention devient fausse au déplacement suivant. Le nom du dossier du dépôt, lui, est la source de vérité du nom du projet.

Une seule conséquence opérationnelle, et elle est réelle : après tout déplacement ou renommage, relancer npm run wire, parce que les liens de .claude/skills/ stockent un chemin absolu. Voir les pièges connus plus bas.

Le contexte métier, qui conditionne tout le reste

Ce dépôt ne contient aucune donnée de mandat, et pas seulement parce que git l'ignore : le dossier d'engagement vit physiquement ailleurs. Son chemin absolu est dans ENGAGEMENT_DIR, une variable du .env, et c'est le seul endroit où une donnée client existe. La frontière est donc le chemin lui-même, et non un sous-dossier d'un arbre qui se pousse. Dans tout ce dépôt, une notation comme engagement/output/ veut dire « dans ce dossier-là », jamais « dans ce dépôt ».

Le client, les instances, les personnes, les comptes de test et les contraintes propres à un engagement vivent dans engagement/CONTEXT.md. Lis-le avant de travailler sur un ticket. S'il est absent, tu travailles sur le dépôt lui-même, pas sur un mandat.

Sans ENGAGEMENT_DIR, les scripts retombent sur engagement/ à la racine du dépôt, qui reste gitignoré. C'est un filet pour une installation neuve, pas la disposition recommandée.

Deux constantes valent pour tout mandat AMS Oracle et justifient la méthode de ce dépôt :

Il n'existe généralement aucun cahier de configuration à jour. La configuration ne vit que dans les instances. Conséquence non négociable : toute hypothèse doit être livrée avec le chemin exact dans l'instance qui permet de la vérifier. Une hypothèse sans chemin de vérification est inutilisable.

Le symptôme et la vérification vivent dans deux instances différentes. Un bug est observé en production ; l'opérateur ne peut lire et modifier qu'un environnement de test, copie de la production avec un décalage. Le détail de ce qui se transpose ou non est dans skills/hcm-debugging/SKILL.md, section « The two environments ».

2. Commandes

npm install          # dependances
npm run build        # tsc -> dist/ ET construit le serveur MCP   <- LE filet principal
npm run ingest -- PROJ-1234      # ou: node dist/jira_ingest.js PROJ-1234
npm run actions      # regenere output/{DO-NOW,MESSAGES,INDEX,ARCHIVE}.md dans ENGAGEMENT_DIR
npm run fusion -- open           # fenetre dediee sur le pod de TEST, l'opérateur se connecte lui-meme
npm run fusion -- rest /hcmRestApi/resources/11.13.18.05/workers?limit=1   # GET seulement
npm run fusion -- snapshot       # la page courante en texte, sans capture d'ecran
npm run fusion -- plan <scenario>     # montre un plan de test (blueprint) avant approbation
npm run fusion -- run <scenario>      # deroule un plan APPROUVE, s'arrete au premier obstacle
npm run fusion -- resume <run-id>     # reprend ou le run s'est arrete, jamais depuis le debut
npm run fusion -- cleanup <run-id>    # retire ce que ce run a cree, selon la section cleanup approuvee
npm run fusion -- run <scenario> --after <run-id>   # partie suivante d'une chaine : reprend les valeurs de ce run
npm run fusion -- evidence <run-id>...  # le document client : chaque etape a cote de sa capture, HTML et PDF
npm run fusion -- suite            # etat de la suite : runs arretes, valeurs a choisir, ce qui peut tourner, par personne
npm run fusion -- rebuild <scenario> --reason "..."   # declare un script rebati sous une approbation par intention (D27)
npm run wire         # (re)cree les liens .claude/skills   <- APRES TOUT DEPLACEMENT
npx tsc --noEmit     # typecheck seul

Dans une conversation Claude Code ouverte dans ce dossier :

/triage PROJ-1234
/triage-batch PROJ-1234 PROJ-1235        (ou un chemin vers worklist.txt)

Il n'y a ni suite de tests, ni linter, ni formateur. C'est assumé (voir D4 dans memory/PROJECT.md). Le seul filet automatisé est tsc. Un tsc vert prouve que ça compile, pas que ça marche : après toute modification de logique, lance le smoke-check (.claude/skills/smoke-check/SKILL.md), qui est le seul contrôle de bout en bout.

3. Architecture

Le flux complet, de gauche à droite. Rien ne saute d'étape. Tous les chemins ci-dessous sont relatifs au dossier d'engagement, donné par ENGAGEMENT_DIR, hors du dépôt.

worklist.txt                   les cles de tickets ouverts, ecrit a la main
      |
      v  node dist/jira_ingest.js            (GET Jira uniquement)
tickets/{KEY}/                 ticket.md + raw.json + images/ + files/
      |
      v  /triage ou /triage-batch            (skill hcm-debugging)
output/tickets/{KEY}.md        le brief dense, frontmatter + sections normalisees
      |
      v  node dist/build_actions.js          (aucun appel reseau)
output/DO-NOW.md               tous les gestes, dans l'ordre de travail
output/MESSAGES.md             tous les textes prets a envoyer
output/INDEX.md                une ligne par ticket : cause racine, mon geste, qui bloque
      |
      v  deplacement a la main, une fois le travail fini
output/closed/{KEY}.md         l'archive, seul lieu de repos d'un ticket termine
output/ARCHIVE.md              genere depuis closed/ : date, numero, theme, cause racine

output/closed/ ne distingue pas ce qui a été envoyé de ce qui ne l'a pas été. Personne ne vient confirmer un envoi, donc l'état de publication n'est pas un dossier. Un brief qui reste dans output/tickets/ continue d'alimenter DO-NOW et MESSAGES : c'est ce qui rend le déplacement nécessaire, et suffisant.

Les scripts

FichierLignesRôle
scripts/jira_ingest.ts826CLI d'ingestion. Seul composant qui touche le réseau Jira.
scripts/build_actions.ts538Agrégateur pur : lit les briefs et l'archive, écrit les quatre fichiers de sortie. Aucun réseau.
scripts/engagement.ts58Résout ENGAGEMENT_DIR et lit le .env. Partagé par les trois autres : un seul endroit décide où vit la donnée client.
scripts/fusion.ts575CLI d'accès à une instance Fusion de test : pilote une fenêtre Edge dédiée par le protocole DevTools. REST en GET, arbre d'accessibilité, clic, saisie, plans de test. Seul composant qui touche une instance Oracle. Voir D18, D23, D24.
scripts/fusion/2900Les modules de fusion.ts, dont ce qui vient de clockwork (D24) : locate.ts (chaîne de résolution par libellé, iframes, ambiguïté refusée), select.ts (listes de valeurs), errors.ts (erreur Oracle après chaque action), blueprint.ts (format v0.2, identique à clockwork, et empreinte d'approbation), runner.ts (déroulé, arrêt, réparation, reprise), repair.ts (réécriture en texte), report.ts (rapport pour l'opérateur), evidence.ts (document client, format de clockwork, D26), approvals.ts (approbation de plan ou par intention, D27), suite.ts (état de la suite, D27), data.ts (profils et générateurs), steps.ts (une action par étape). env.ts porte les gardes et les listes de réglage Oracle, window.ts la fenêtre.
smoke/Faux Oracle synthétique et trois blueprints de contrôle, pour le smoke-check (D24). Aucune donnée client, et le seul endroit du dépôt où un blueprint est accepté.

jira_ingest.ts est sectionné par des bannières // ── : Config, Types, Environnement, HTTP (GET only), Noms de fichiers, Pièces jointes, Stripping de raw.json, Conversion du wiki markup Jira, Rendu du dossier, Filet de pagination des commentaires, Ingestion d'un ticket, Mode batch. Points sensibles : getWithRetry (retry sur 429, 5xx, timeouts), safeMessage (rédaction de l'en-tête Authorization avant tout affichage), ensureAllComments (Jira tronque les commentaires au-delà d'une page et ne le signale pas).

build_actions.ts : Parsing, Arithmétique du temps, Rendu, Main. Il valide les briefs et échoue bruyamment sur un frontmatter incomplet, ce qui est voulu.

Les skills, index universel

Cette table est le point d'entrée pour tout agent qui ne fait pas de sélection automatique. Claude Code choisit la skill seul, à partir de sa description. Ailleurs, lis la ligne qui correspond à ta tâche et ouvre le fichier indiqué : ce sont des fichiers markdown ordinaires.

SkillSe déclenche quandFichier
jira-ticket-ingestionil faut récupérer un ticket et ses captures avant toute analyseskills/jira-ticket-ingestion/SKILL.md
hcm-debuggingquelque chose est cassé : erreur, page qui refuse, action absente, régression après un trimestrielskills/hcm-debugging/SKILL.md
triagel'utilisateur veut le traitement complet d'un ticket, de l'ingestion au messageskills/triage/SKILL.md
triage-batchplusieurs tickets d'un coupskills/triage-batch/SKILL.md
hcm-configurationil faut construire ou modifier quelque chose qui n'est pas cassé : demande de changement, rôle, règle de page, lookup, profil de sécurité, traitement planifiéskills/hcm-configuration/SKILL.md
hcm-architectureon demande un avis : la bonne façon de faire, correctif ou refonte, deux options à départager, ce qu'un changement va entraîner. Jamais de chiffre ni de duréeskills/hcm-architecture/SKILL.md
fusion-instanceil faut lire ou modifier l'instance de test elle-même : rôles d'un utilisateur, contenu d'un profil, retest sous un rôle, modification DEV approuvée. Dernier barreau de l'échelle des preuvesskills/fusion-instance/SKILL.md
fusion-testil faut dérouler un scénario de test dans l'instance de test : expérience contrôlée, reproduction, retest, régression. Écrit le blueprint, le fait approuver une fois, le déroule, répare un libellé dans le plan, rapporteskills/fusion-test/SKILL.md
fusion-suiteil faut dérouler toute une suite de scénarios en boucle, session après session : l'état de la suite, les valeurs à choisir, les chaînes par personne, un script mal conçu rebâti à partir de son intention (D27), les constats, le journal, le document clientskills/fusion-suite/SKILL.md
fusion-referencesocle de connaissance, sans workflow : comment le produit est structuré, où vit la configuration, Redwood contre classique, ce que gouvernent Transaction Design Studio et Visual Builder Studio, la composition de la sécurité, les traitements planifiés. Lu quand une autre skill y renvoie, ou pour une question de pur savoir produitskills/fusion-reference/SKILL.md

Les déclencheurs ne se recouvrent pas : cassé va au débogage, à construire à la configuration, à recommander à l'architecture, à savoir au socle. Chaque SKILL.md est mince et renvoie à des fichiers de fond dans son dossier, lus au besoin et non au démarrage :

DossierFichiers de fond
skills/fusion-reference/product-structure.md, configuration-map.md, pages-and-extensions.md, security-model.md, scheduled-processes.md : le savoir, avec les citations Oracle mot pour mot et leurs URL
skills/hcm-configuration/where-to-configure.md (même effet, plusieurs endroits, lequel choisir), change-note.md (gabarit de la note de changement, écrite dans engagement/output/changes/)
skills/hcm-architecture/decision-structures.md (les décisions récurrentes, signaux, défaut, ce qui le renverse), load-and-dependencies.md (inducteurs de charge et dépendances, sans chiffre)

skills/hcm-debugging/ porte deux fichiers de fond, lus au besoin et non au démarrage :

  • output-format.md — le contrat de format du brief. C'est aussi le contrat que scripts/build_actions.ts parse. Modifier l'un sans l'autre casse npm run actions.
  • patterns.template.md — le gabarit de la bibliothèque de patterns. La vraie bibliothèque est privée et vit dans engagement/patterns.md, parce qu'elle porte des rôles, des tickets et des numéros de SR. Elle est append-only : une entrée fausse n'est pas supprimée, elle est remplacée par une entrée qui la supersede explicitement.

.claude/skills/smoke-check/ est une skill de développement du dépôt, versionnée, hors plugin.

Le serveur MCP embarqué, mcp/

Tout le serveur tient dans mcp/src/index.ts, 376 lignes, sectionné par des bannières // ── : config (MAX_PAGE_CHARS=15000, Jina Reader, timeout 25 s), ResponseCache (LRU mémoire seul), jinaGet (trois tentatives, backoff), un seul outil, le câblage JSON-RPC. Flux de fetch_oracle_page : garde-fou de domaine, cache mémoire, Jina Reader, nettoyage, troncature à 15 000 caractères.

Élagué en 4.0.0, le 2026-09-07, de 1142 lignes à 374. Retirés : search_oracle_docs, list_modules, l'index statique d'environ 410 lignes, et le cache disque. Motif : une recherche web restreinte à docs.oracle.com trouve une page mieux qu'un index tenu à la main, et le cache disque était le piège le plus coûteux du dépôt. Trouver est le travail du web, citer fidèlement est le travail de ce serveur. Ne pas re-proposer d'outil de recherche ici.

Invariants propres au serveur, hérités de son ancien dépôt :

  1. stdout est le canal JSON-RPC. Ne jamais y écrire. Tous les logs passent par console.error. Un seul console.log corrompt le protocole pour tous les clients. Vérification : grep -n "console\.log" mcp/src/index.ts ne doit rien retourner.
  2. Aucun export dans mcp/src/index.ts : c'est un exécutable, pas un module.
  3. Pas de declaration: true dans mcp/tsconfig.json, personne ne consomme de .d.ts.
  4. La vulnérabilité hono signalée par npm audit est ignorée sciemment : dépendance transitive du SDK MCP, sur des chemins HTTP qu'un serveur stdio n'exécute jamais. Ne pas « corriger » sans demande.
  5. L'URL demandée à fetch_oracle_page part chez un tiers, Jina Reader. Ne jamais y router autre chose que docs.oracle.com, et surtout rien qui nomme le client.

Portabilité

Ce dépôt est utilisable par d'autres agents que Claude Code.

CouchePortabilité
AGENTS.md, ce fichieruniverselle, format ouvert de l'Agentic AI Foundation, une vingtaine d'agents le lisent
Le serveur MCP de mcp/universelle, MCP est un standard ouvert
Le contenu des skillsuniverselle, ce sont des fichiers markdown
.claude-plugin/, sélection automatique des skillsspécifique à Claude Code

La valeur de ce dépôt est de la méthode en prose, pas de la machinerie. Un agent sans sélection automatique obtient la même chose en lisant la table ci-dessus.

Le contrat brief / agrégateur

output/tickets/{KEY}.md porte un frontmatter dont build_actions.ts exige les champs : key, summary, status, updated, age_days, family, root_cause, confidence, my_move, status_target, severity, effort_hands_on, eta_elapsed, blocked_on, next_action.

  • my_move vaut exactement send, investigate ou wait.
  • severity vaut P1, P2 ou P3.
  • status_target est le statut Jira à poser une fois le message envoyé. Il est rendu automatiquement dans MESSAGES.md, sous le message, pour qu'un ticket réglé se ferme dans le même geste que son envoi.
  • Les sections parsées sont ## DO NOW (un tableau | # | Action | Where exactly | Done when | Time |) et ## MESSAGE. Une section MESSAGE commençant par none produit un message vide, pas une erreur.
  • Une table DO NOW vide est légale : c'est un ticket dont l'analyse est finie.
  • La colonne Time doit contenir une durée réelle (5m, 20m, 2h), jamais S/M/L.
  • L'ordre de travail est : sévérité d'abord, puis le moins cher d'abord à sévérité égale.

4. Invariants — à ne jamais casser

  1. Jira est strictement en lecture seule. GET uniquement. Jamais de POST, PUT, PATCH ou DELETE, quelle que soit la demande. Pas de commentaire, pas de transition, pas d'édition, jamais. Si l'utilisateur veut poster un commentaire, on lui donne le texte et il le poste lui-même. Vérification : grep -n "method:" scripts/jira_ingest.ts ne doit montrer aucun verbe d'écriture.
  2. Les identifiants ne passent que par des variables d'environnement (JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN). Jamais en dur, jamais loggés, jamais commités. safeMessage() rédige l'en-tête Authorization avant tout affichage : ne pas contourner cette fonction.
  3. tickets/ et output/ sont de la donnée client. Gitignorés, ils ne quittent pas cette machine. Toute nouvelle sortie contenant du contenu de ticket doit être ajoutée au .gitignore dans le même geste qui la crée.
  4. Aucun tiret cadratin dans le texte généré, les skills ou les gabarits de rapport. Utiliser deux-points, virgule ou parenthèses.
  5. Le périmètre de l'opérateur est : reproduire, trouver la cause racine, écrire le message. Il n'est responsable ni des autres bugs de l'instance, ni de ce que le client décide, ni de la production, ni de l'arbitrage métier entre deux correctifs. Une action dont il n'est pas le propriétaire est une phrase dans le message ou une ligne NOT MINE, jamais une étape DO NOW.
  6. Un ticket, un mécanisme. Deux signatures distinctes dans un même ticket se découpent (étape 1b) avant classification. Les fusionner produit une confiance fausse.
  7. Jamais de placeholder dans un message. Un message est envoyable tel quel ou n'est pas écrit.
  8. output-format.md et build_actions.ts sont un seul contrat. Changer les sections ou le frontmatter d'un côté sans l'autre casse npm run actions.
  9. fusion.js ne touche jamais une instance de production, et ne s'authentifie jamais à la place de l'opérateur. Garde-fous dans le code : assertNotProduction sur l'hôte, contrôle que l'onglet visé est sur ce pod, rest en GET seulement, --write exigé pour tout contrôle qui valide, refus des champs de mot de passe, --out limité à engagement/. Le garde-fou qui compte n'est pas dans le code : avant tout --write, l'agent décrit la modification exacte dans la conversation et attend un oui explicite de l'opérateur, une modification à la fois. Seule exception (D23) : un plan de test que l'opérateur a approuvé en entier, fusion approve n'étant lancé qu'après son oui ; run refuse tout plan non approuvé ou modifié depuis, et repair ne change qu'un libellé, jamais une action, une valeur ou une validation. Ne jamais affaiblir assertNotProduction ni ajouter un verbe d'écriture à rest sans décision écrite dans memory/PROJECT.md.

5. Pièges connus

  • Les skills et les commandes sont lues une seule fois, au démarrage de la conversation. Après npm run wire ou après avoir modifié un SKILL.md, il faut ouvrir une nouvelle conversation. Une conversation déjà en cours ne verra jamais le changement, sans aucun message d'erreur.
  • Une jonction Windows stocke un chemin absolu. Déplacer ou renommer le dossier laisse les liens de .claude/skills/ pointer dans le vide, et le plugin cesse silencieusement d'exister. C'est déjà arrivé deux fois, au déplacement du 2026-08-29 et au renommage du dossier de thème constaté le 2026-09-07, où les sept liens pointaient encore vers l'ancien chemin. Symptôme : /triage n'est pas reconnu. Remède : npm run wire, puis nouvelle conversation.
  • Supprimer une jonction avec un outil récursif est dangereux sous Windows : Remove-Item -Recurse en PowerShell 5.1 peut supprimer à travers le lien et vider le vrai dossier skills/. scripts/wire_local.mjs ne retire que ce que lstat identifie comme un lien, et laisse tout vrai dossier en place. Ne pas « simplifier » ce code.
  • ${CLAUDE_PLUGIN_ROOT} n'est substitué que pour un plugin installé. Pour un dépôt ouvert comme projet, .mcp.json doit porter un chemin relatif, sinon le serveur MCP meurt au démarrage avec un CONNECTION_CLOSED sans autre explication. Un plugin installé (installation par la marketplace) attend au contraire ${CLAUDE_PLUGIN_ROOT}/mcp/dist/index.js.
  • Un SKILL.md n'est lu qu'au démarrage, et le nom du dossier doit égaler le champ name (minuscules, chiffres, tirets). Un dossier de skill sans SKILL.md valide est ignoré en silence.
  • Jira tronque les commentaires au-delà d'une page sans le signaler. ensureAllComments() est le filet. Un dossier qui paraît incomplet vient très probablement de là.
  • WARNING: unresolved image reference dans un dossier signifie que Jira n'a pas renvoyé la pièce jointe référencée par le commentaire. L'image manque réellement dans la réponse de l'API : ce n'est pas le script qui l'a perdue.
  • Le cache du MCP est en mémoire uniquement, une heure, cinquante entrées, et il meurt avec le processus. Une doc qui paraît périmée se règle donc en redémarrant le serveur, ce qui revient à ouvrir une nouvelle conversation. Le cache disque qui survivait aux rebuilds a été retiré en 4.0.0 : il était la première cause de « la doc n'a pas changé après ma modification ».
  • fetch_oracle_page tronque à 15 000 caractères. Une page qui « manque » de contenu est tronquée, pas mal parsée : chercher [... truncated. Une page qui ne renvoie que la navigation du site n'a pas été rendue par Jina : essayer une autre version de la page (.../24d/..., .../25b/...) ou un guide voisin, c'est fréquent et ce n'est pas un bug.
  • Un timeout de 25 s sur fetch_oracle_page vient presque toujours d'un proxy d'entreprise ou d'une indisponibilité de r.jina.ai, pas du code.
  • Les accents français disparaissent quand un message est écrit via un script de transformation. Toujours relire les blocs français après une passe automatisée.
  • L'historique git ne porte pas le raisonnement (voir D1 et D28) : le dépôt public repart d'une seule version, et aucun message de commit n'explique un choix. La mémoire des décisions est entièrement dans memory/PROJECT.md. Si tu prends une décision structurante, elle n'est nulle part ailleurs : écris-la.

Le piège de diagnostic Oracle qui revient le plus

Un privilège manquant fait disparaître l'action de la page, il ne la refuse pas. Donc :

  • une action absente oriente vers la sécurité (rôle, privilège, profil de données) ;
  • un message d'erreur signifie que le code s'est exécuté, donc que le privilège était là, et oriente vers la configuration ou un défaut produit.

Corollaire opérationnel : tester sous un rôle administrateur est l'erreur la plus facile à commettre. Elle fait disparaître le symptôme et fait conclure à tort que c'est réparé.

6. Setup

Voir SETUP.md : jeton Jira, .env, build, câblage local, MCP de documentation.

Résumé de ce qui est requis hors dépôt : Node >= 20, un jeton API Jira classique (pas la variante scoped), et un accès réseau sortant vers le Jira du mandat et r.jina.ai.

7. Style de travail attendu avec l'opérateur

Ces règles viennent de corrections explicites de sa part. Elles ne sont pas des préférences cosmétiques : les ignorer produit du travail qu'il doit refaire.

  • Le minimum de ce qui est attendu. Les messages destinés à être envoyés (commentaire Jira, réponse SR, courriel) sont courts et directs, et ne portent que ce qui a été littéralement demandé. Pas d'explication du mécanisme que personne n'a demandée, et jamais d'offre de travail supplémentaire en conclusion (« je peux aussi faire X ») : une offre se lit comme un engagement et génère des demandes qu'il devra absorber seul.
  • Avant d'écrire, cite ce qui a été littéralement demandé, et écris à ça. Erreur type déjà commise : construire une échelle de diagnostic en six étapes alors que la demandeuse voulait seulement un document pour ouvrir un CAB.
  • Garder un fait non demandé seulement s'il change une décision que le destinataire est sur le point de prendre, et alors en une phrase, pas en section. La profondeur diagnostique reste dans le brief sur disque, pas dans le message.
  • Décider seul les détails d'implémentation à faible enjeu (organisation des fichiers, format cosmétique) et les rapporter à la fin, plutôt que de bloquer en cours de route. Réserver les questions aux vrais changements de périmètre. Son arbitrage : « ton jugement ici a autorité sur la spec initiale » pour les détails de présentation.
  • La documentation d'abord, l'environnement en dernier. L'ordre pour trancher une question ouverte: ce que le dossier contient déjà, puis la documentation Oracle, puis un fait que seul le client peut produire, puis une lecture dans DEV1, et seulement en dernier une modification dans DEV1. Ouvrir une instance est le barreau cher de cette échelle et doit se justifier. Demander une extraction au client n'est pas se décharger, c'est adresser la tâche à la seule personne qui peut l'exécuter.
  • Citer Oracle mot pour mot, avec l'URL. Quand une page décrit le comportement observé, la phrase entre guillemets plus le lien valent plus que tout le raisonnement qui y menait. Sur un ticket, une seule phrase documentée a fait passer une déduction à 70 % en constat à 85 %, et a supprimé le besoin de tout test.
  • Pas de retour à la ligne forcé dans un paragraphe de message. Le texte est collé dans un champ Jira, un SR ou un courriel, qui reflue à sa propre largeur. Un paragraphe coupé à 95 caractères arrive haché. Un paragraphe, une ligne, aussi longue soit-elle. Les listes, les URL et la signature gardent leurs lignes, ces coupures-là sont réelles.
  • Hyperfocus sur la cause racine du ticket. Ne pas déborder sur les enjeux adjacents, même réels. Un constat intéressant hors périmètre va dans NOT MINE, pas dans le plan d'action.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.