/acreadiness-generate-instructions — écrire les instructions des agents IA

Utilisez cette compétence chaque fois que l'utilisateur souhaite créer, régénérer ou rafraîchir ses instructions personnalisées pour les agents de codage IA (Copilot, Claude, etc.). C'est l'étape Generate dans la boucle Measure → Generate → Maintain d'AgentRC et l'action au plus fort effet de levier pour le pilier AI Tooling.

Options de sortie

VS Code reconnaît plusieurs types de fichiers d'instructions — AgentRC génère les plus courants :

Stratégies

• flat (par défaut) — un seul .github/copilot-instructions.md au chemin choisi. Simple, facile à examiner.
• nested — hub à .github/copilot-instructions.md + fichiers de détail par thème à .github/instructions/<thème>.instructions.md, chacun avec un glob applyTo pour que VS Code ne charge le thème que quand il est pertinent. Meilleur pour les grands repos ou ceux avec plusieurs stacks.

Pourquoi .github/instructions/ et non .agents/ ? La disposition imbriquée par défaut d'AgentRC écrit dans .agents/, qui est le bon endroit pour les repos agnostiques aux agents (Copilot + Claude + Cursor lisant AGENTS.md). Pour VS Code Copilot spécifiquement, l'emplacement natif est .github/instructions/ avec frontmatter applyTo — c'est ce que Copilot découvre automatiquement. Cette compétence réécrit la sortie imbriquée d'AgentRC à l'emplacement natif VS Code chaque fois que la sortie principale est .github/copilot-instructions.md. Si vous avez plutôt choisi --output AGENTS.md, la disposition imbriquée conserve la structure .agents/ par défaut d'AgentRC.

Pour les monorepos, générez des instructions délimitées par zone avec --areas, --area <nom>, ou --areas-only. Les zones sont définies dans agentrc.config.json. La sortie par zone est écrite sous forme de fichiers VS Code .instructions.md avec un glob applyTo (voir ci-dessous).

Fichiers .instructions.md par thème ou par zone

Les deux se retrouvent dans .github/instructions/ mais répondent à des questions différentes :

Vous pouvez avoir les deux à la fois : un ensemble imbriqué de fichiers par thème plus des fichiers par zone pour un monorepo.

Fichiers par zone avec applyTo

Quand l'utilisateur opte pour les zones, émettez un fichier .instructions.md natif VS Code par zone à .github/instructions/<zone>.instructions.md. Chaque fichier DOIT commencer par du frontmatter déclarant le glob auquel les règles s'appliquent :

---
applyTo: "apps/frontend/**"
---

# Instructions de la zone Frontend

…contenu généré par AgentRC pour cette zone…

Flux de travail :

1. Lisez agentrc.config.json pour découvrir les zones déclarées et leurs paths / globs. Si paths est absent, demandez à l'utilisateur le glob (ex. src/api/**).
2. Exécutez agentrc instructions --areas (ou --area <nom>) pour produire le contenu du corps par zone.
3. Enveloppez chaque contenu de zone dans .github/instructions/<zone>.instructions.md avec le frontmatter applyTo tiré des paths de la zone. Si l'utilisateur a passé --apply-to <glob> sur un appel mono-zone, utilisez ce glob tel quel.
4. Laissez le fichier principal intact — le .github/copilot-instructions.md racine reste les instructions toujours actives ; les fichiers .instructions.md ne s'activent que pour les chemins correspondants.

Nommage : nom de zone en minuscules, kebab-case. Exemples : .github/instructions/frontend.instructions.md, .github/instructions/api.instructions.md, .github/instructions/infra.instructions.md.

Étapes

1. Choisissez le fichier cible. Par défaut .github/copilot-instructions.md. Basculez vers AGENTS.md seulement si l'utilisateur mentionne multi-agents / Claude / support Cursor.
2. Demandez toujours quelle stratégie utiliser — flat ou nested — sauf si l'utilisateur l'a déjà spécifiée dans son message ou via --strategy. Présentez brièvement le compromis :
   • Flat (par défaut) — un seul .github/copilot-instructions.md. Simple, facile à examiner dans une seule PR. Meilleur pour les petits/moyens repos avec un seul stack.
   • Nested — hub .github/copilot-instructions.md + fichiers de détail par thème .github/instructions/<thème>.instructions.md (chacun avec un glob applyTo pour que VS Code ne les charge que quand ils sont pertinents). Meilleur pour les gros repos ou ceux avec plusieurs stacks. Ajoutez --claude-md pour émettre aussi CLAUDE.md. Recommandez nested de manière proactive quand le repo a > 5 répertoires de niveau supérieur, plusieurs stacks, ou utilise déjà un outil de monorepo (turbo/nx/pnpm workspaces).
3. Détectez les zones du monorepo en lisant agentrc.config.json. Si des zones existent, demandez à l'utilisateur s'il souhaite des fichiers .instructions.md par zone avec applyTo en plus du fichier racine. Par défaut "oui" quand agentrc.config.json déclare des zones.
4. Exécutez d'abord une exécution sèche pour que l'utilisateur puisse prévisualiser :

   npx -y github:microsoft/agentrc instructions --output <fichier> --strategy <flat|nested> [--areas|--area <nom>] [--claude-md] --dry-run

5. Montrez un court résumé de ce qui changerait — fichiers qui seraient créés ou écrasés, nombre de zones + leurs globs applyTo, modèle utilisé (par défaut claude-sonnet-4.6).
6. À la confirmation, exécutez la même commande sans --dry-run (et optionnellement --force si des fichiers existent déjà).
7. Post-traitement de la disposition pour la sortie Copilot :
   • Si --output se termine par copilot-instructions.md et la stratégie est nested : déplacez/réécrivez les fichiers .agents/<thème>.md d'AgentRC vers .github/instructions/<thème>.instructions.md. Ajoutez du frontmatter à chaque fichier avec un glob applyTo approprié (voir « Défauts applyTo par thème » ci-dessous). Supprimez le répertoire .agents/ maintenant vide.
   • Si --areas a été utilisé : écrivez aussi .github/instructions/<zone>.instructions.md pour chaque zone, en utilisant les paths de chaque zone de agentrc.config.json comme glob applyTo (remplacez par --apply-to pour des appels mono-zone).
   • Si --output AGENTS.md a été choisi : conservez la disposition native .agents/ d'AgentRC pour l'imbriqué — les lecteurs agnostiques aux agents s'y attendent. Créez le répertoire .github/instructions/ s'il manque.

Défauts applyTo par thème

Lors de la promotion des fichiers de thème imbriqués d'AgentRC vers .instructions.md, utilisez ces défauts sauf si l'utilisateur en spécifie d'autres :

8. Vérifiez en relisant le(s) fichier(s) généré(s) et montrez à l'utilisateur un synopsis d'un paragraphe : stack détecté, conventions capturées, longueur, liste des fichiers .instructions.md avec leurs globs.
9. Suggérez les prochaines étapes :
   • Réexécutez la compétence assess pour confirmer que le score du pilier AI Tooling s'est amélioré.
   • Si l'utilisateur a déjà à la fois copilot-instructions.md et AGENTS.md, recommandez de consolider vers une seule source de vérité (AgentRC le signale aux niveaux de maturité 2+).

Notes

• AgentRC lit votre code réel — pas de templates. La sortie reflète les langages, frameworks et conventions détectés.
• --claude-md (stratégie imbriquée seulement) émet aussi CLAUDE.md.
• VS Code applique automatiquement les fichiers .instructions.md quand le fichier actif correspond à applyTo. Le .github/copilot-instructions.md racine charge toujours.
• N'exécutez jamais cette compétence de manière non-interactive en CI ; les instructions font partie du repo et doivent arriver via PR.