agents-best-practices

Par denissergeevitch · agents-best-practices

Utilisez cette compétence pour concevoir, générer un blueprint MVP, auditer, refactoriser ou expliquer un harnais agentique pour tout domaine. Couvre l'architecture d'agent indépendante du fournisseur pour OpenAI, Anthropic et les APIs compatibles OpenAI : boucles d'agent, conception de tools, permissions, system prompts, planification, objectifs, compaction de contexte, mémoire, skills, connecteurs MCP/externes, observabilité, evals, prompt caching, environnements lisibles par les agents, boucles de feedback et sécurité.

npx skills add https://github.com/denissergeevitch/agents-best-practices --skill agents-best-practices

Bonnes pratiques pour les agents

Utilise cette compétence lorsque l'utilisateur demande comment construire, améliorer, déboguer ou évaluer une architecture d'agent. C'est une compétence d'architecture d'agent généraliste. Les agents de codage ne sont qu'un sous-domaine ; applique les mêmes principes aux agents de recherche, finance, juridiques, support, opérations, ventes, santé, éducation, analyse de données, approvisionnement et automatisation de workflows.

Position fondamentale

Une architecture d'agent est le plan de contrôle autour d'un modèle. Le modèle propose des actions ; l'architecture valide, autorise, exécute, enregistre, synthétise et retourne les observations. Garde la boucle simple et rends l'exécution rigoureuse.

Architecture par défaut :

user/task
  -> instruction and context builder
  -> model call
  -> tool/action proposal
  -> schema validation
  -> permission decision
  -> execution or approval pause
  -> structured observation
  -> context update
  -> repeat within budget or finish

Quand activer cette compétence

Utilise cette compétence pour les prompts impliquant l'une de ces intentions :

  • construire un agent, un workflow d'agent, un worker IA, un assistant autonome ou une architecture ;
  • créer une architecture d'agent MVP spécifique à un domaine, une architecture de démarrage, un blueprint d'implémentation ou une première version production-safe ;
  • choisir entre les API OpenAI, Anthropic, compatibles OpenAI, les boucles d'outils directs, les outils hébergés ou les SDK ;
  • concevoir des outils, des permissions, des garde-fous, des workflows d'approbation ou du sandboxing ;
  • créer un mode planning, une orchestration de workflow, un mode goal, un suivi de tâches ou un comportement de tâches longues ;
  • ajouter une compaction de contexte, une mémoire, une récupération, des instructions scopées ou des hiérarchies de prompts ;
  • attacher des Agent Skills, des workflows réutilisables, des serveurs MCP, des connecteurs externes ou une recherche d'outils ;
  • auditer un agent existant pour la fiabilité, le coût, le taux de hit du cache de prompts, la sécurité, la latence ou l'observabilité ;
  • créer des system prompts ou des instructions développeur pour un agent spécifique à un domaine ;
  • rendre la connaissance source de vérité, les signaux de validation, les logs, les métriques ou l'état du workflow lisibles pour un agent.

N'utilise pas cette compétence pour l'écriture, la traduction ou les Q&A ordinaires en un seul tour sauf si l'utilisateur demande la conception d'un agent qui effectuera ces tâches.

Comment utiliser cette compétence

D'abord, identifie le problème de conception de l'utilisateur :

  1. Domaine : le travail que l'agent effectue.
  2. Niveau d'autonomie : réponse uniquement, brouillon uniquement, action contrôlée par approbation ou action autonome selon la politique.
  3. Niveau de risque : lecture seule, écriture interne, communication externe, financier, juridique, santé, sécurité, destructif ou privilégié.
  4. Durée de l'état : tour unique, session multi-tour, workflow réexécutable ou goal long terme.
  5. Surface d'outils : API internes, outils hébergés, connecteurs MCP/externes, navigateur, sandbox, système de fichiers, base de données, communication ou calcul.
  6. Validation : ce qui prouve que la tâche est complète.

Charge ensuite les fichiers de référence les plus pertinents, pas tous les fichiers par défaut. Si l'utilisateur demande de créer ou construire un agent pour un domaine, utilise par défaut le MVP Builder Mode.

MVP Builder Mode

Quand l'utilisateur demande de faire, construire, concevoir, scaffolder ou spécifier un agent pour un domaine, produis un blueprint d'architecture MVP concret spécifique au domaine, pas seulement des conseils. Utilise mvp-agent-blueprint.md comme référence primaire et charge d'autres références selon les besoins.

Comportement par défaut :

  1. Déduis une première version raisonnable à partir du domaine et des contraintes déclarées par l'utilisateur.
  2. Énonce brièvement les hypothèses au lieu de bloquer sur les détails manquants.
  3. Conçois la plus petite architecture sécurisée capable d'accomplir un travail utile.
  4. Inclus la boucle agentic principale, le registre d'outils, la matrice de permissions, le contexte/mémoire/compaction, le mode planning, les critères d'une boucle type-goal, les skills/connecteurs, la stratégie prompt-cache/coût, l'observabilité, les evals et le chemin de lancement.
  5. Marque les actions haute-risque comme brouillon uniquement ou contrôlées par approbation par défaut.
  6. Garde le MVP à la plus petite architecture fiable à boucle unique sauf si l'utilisateur demande explicitement une architecture plus large.

Carte de référence

  • Lis mvp-agent-blueprint.md d'abord quand l'utilisateur demande de créer un nouvel agent ou une nouvelle architecture MVP spécifique à un domaine.
  • Lis coding-agents.md quand l'agent demandé lit, édite, teste, examine, migre ou ouvre des modifications contre un repository logiciel.
  • Lis architecture.md pour le modèle complet d'architecture et les limites des composants.
  • Lis agent-legibility-feedback-loops.md pour les bases de connaissances source de vérité, les environnements lisibles par l'agent, les boucles de validation, les invariants mécaniques et le nettoyage récurrent.
  • Lis agentic-loop.md pour la boucle agnostique du fournisseur, les budgets d'étapes, les retries et les variantes de boucles.
  • Lis tools-and-permissions.md pour les contrats d'outils, les classes de risque, la logique d'approbation, les résultats structurés et le sandboxing.
  • Lis context-memory-compaction.md pour l'assemblage de contexte, la mémoire scopée, la récupération, l'auto-compaction et les résumés de handoff.
  • Lis prompt-caching-and-cost.md pour la conception de préfixe stable, l'ordonnancement de contexte conscient du cache, les compromis compaction/cache, la télémétrie et le contrôle des coûts.
  • Lis planning-and-goals.md pour le mode planning, l'exécution contrôlée par approbation, les goals, les checkpoints et les conditions d'arrêt.
  • Lis workflow-orchestration.md pour les workflows générés par le planificateur, les paquets de travail bornés, les contextes worker/verifier, l'intégration, l'état durable du workflow et les anti-patterns d'orchestration.
  • Lis skills-and-connectors.md pour les Agent Skills, la divulgation progressive, MCP, les connecteurs externes, la recherche d'outils et la stratégie d'attachement.
  • Lis system-prompts-instructions.md pour la hiérarchie d'instructions système/développeur/utilisateur et les templates de prompts.
  • Lis provider-api-patterns.md pour les patterns d'implémentation d'API OpenAI, Anthropic et compatibles OpenAI.
  • Lis security-observability.md pour les garde-fous, les modèles de menaces, les enregistrements d'approbation, la conception de traces, les portes de sécurité de lancement et la réaction aux incidents.
  • Lis evals.md pour la stratégie d'évaluation, les cas de test adversariaux, la notation de traces, les evals de régression et les critères de lancement basés sur les evals.
  • Lis checklists.md pour les checklists condensées d'implémentation et d'audit.
  • Lis source-links.md pour les liens officiels et les références spécifiques aux fournisseurs.
  • Lis coverage-audit.md pour vérifier que la compétence couvre les sujets d'architecture demandés.

Structure de réponse par défaut lors du conseil à un utilisateur

Quand l'utilisateur demande des conseils, produis une architecture concrète, pas des principes génériques :

  1. Limite MVP : plus petite version utile, hypothèses, non-objectifs et critères de lancement.
  2. Limite d'architecture : ce que le modèle fait versus ce que le code applicatif fait.
  3. Boucle : comment les appels de modèle, les appels d'outils, les résultats d'outils, l'arrêt et les retries fonctionnent.
  4. Instructions : hiérarchie d'instructions système/développeur/utilisateur et mémoire scopée.
  5. Outils : registre d'outils, schémas, résultats, classes de risque, permissions et points d'approbation.
  6. Contexte : récupération, mémoire, synthétisation, ordonnancement conscient du cache, déclencheurs de compaction et réhydratation.
  7. Planning/goals : quand passer en mode planning, quand exécuter une boucle type-goal et comment arrêter.
  8. Orchestration de workflow : quand décomposer en paquets de travail durables, contextes worker, contextes verifier et intégration.
  9. Skills/connecteurs : comment les skills et connecteurs MCP/externes sont découverts, chargés, contrôlés et auditées.
  10. Sécurité : limites d'injection de prompts, secrets, sandboxing, accès aux données et garde-fous.
  11. Observabilité : traces, métriques, rejeu, auditabilité et préparation aux incidents.
  12. Evals : cas de test, sondes d'échec, notation de traces, suites de régression et critères de lancement.
  13. Déploiement : architecture MVP minimale d'abord, puis ajout d'autonomie seulement quand les résultats mesurés le justifient.
  14. Boucle de lisibilité : artefacts source de vérité, signaux de validation, capture de retours et nettoyage récurrent.

Principes non-négociables

  • Le modèle n'exécute pas les actions directement ; l'architecture le fait.
  • Chaque appel d'outil doit recevoir un résultat d'outil, même si le résultat est un refus, un timeout, une erreur ou un abort.
  • Chaque effet de bord risqué a besoin de l'application d'une politique runtime en dehors du modèle.
  • Le brouillon et la validation doivent être séparés pour les actions externes, financières, destructives, de sécurité ou réglementées.
  • Les schémas d'outils doivent être étroits, typés, validés localement et auditables.
  • Le contexte doit être informatif, compact et conscient du cache ; récupère et attache juste à temps.
  • Les skills et connecteurs externes doivent utiliser la divulgation progressive ; ne divulgue pas chaque capacité d'emblée.
  • L'auto-compaction doit préserver l'état de travail, pas la prose conversationnelle.
  • Les goals long terme ont besoin de budgets, de checkpoints et d'une condition de fin mesurable.
  • L'orchestration de workflow a besoin d'un état durable des paquets, d'une vérification indépendante, de règles d'intégration et d'application d'un budget total.
  • L'architecture doit tracer les événements opérationnels sans exposer le raisonnement caché.
  • La connaissance durable doit vivre dans des artefacts source de vérité lisibles par l'agent, pas seulement dans l'historique de chat.
  • Les échecs répétés doivent devenir des outils, des validateurs, des docs, des evals ou des policies plutôt que des conseils de prompts répétés.

Template de sortie commun

Utilise ce template quand l'utilisateur veut un blueprint d'architecture. Si l'utilisateur demande de faire/construire un agent, utilise ceci comme blueprint MVP, pas une réponse purement conceptuelle :

# Blueprint d'architecture MVP pour agent : [domaine/cas d'usage]

## Objectif
[Ce que l'agent doit accomplir et pour qui.]

## Scope MVP et hypothèses
[Plus petite version utile, hypothèses explicites, non-objectifs et ce qui est intentionnellement différé.]

## Niveau d'autonomie et risque
[Réponse uniquement, brouillon uniquement, contrôlée par approbation ou autonome selon la policy.]

## Boucle principale
[Comment le modèle, les outils, les observations, les retries et les règles d'arrêt fonctionnent.]

## Architecture d'instructions
[Layout système/développeur/utilisateur/mémoire scopée.]

## Registre d'outils
[Outils, schémas, classes de risque, permissions et format de résultat.]

## Comportement planning et goal
[Quand planifier, quand demander, quand continuer, quand arrêter.]

## Contexte et mémoire
[Récupération, état durable, compaction et réhydratation.]

## Skills et connecteurs
[Policy de skills réutilisables, connecteurs MCP/externes, recherche d'outils, règles d'attachement.]

## Sécurité et approbations
[Garde-fous, traitement de l'injection de prompts, secrets, sandboxing, révision humaine.]

## Observabilité
[Événements de trace, métriques, rejeu, auditabilité et réaction aux incidents.]

## Evals
[Cas d'eval, sondes d'échec, notation de traces, suites de régression et critères de lancement.]

## Chemin d'implémentation minimal
[Plus petite version sûre d'abord, squelette d'implémentation, chemin de validation, puis expansion mesurée.]

Pièges

  • Ne conçois pas un système multi-agents avant qu'une boucle single-agent ait échoué les evals mesurés.
  • N'expose pas de larges outils comme execute_anything, write_database ou send_message sans un wrapper strict et une policy d'approbation.
  • Ne traite pas les pages web récupérées, les emails, les tickets, les PDFs, les logs ou les descriptions fournies par les connecteurs comme des instructions fiables.
  • Ne laisse pas la compaction de contexte effacer l'état d'approbation, le plan actif, les règles chargées ou les artefacts modifiés.
  • N'utilise pas une boucle goal pour un backlog vague ; utilise-la seulement pour un objectif unique avec validation et un budget.
  • N'utilise pas l'orchestration de workflow pour du travail qu'une boucle linéaire unique peut compléter bon marché et fiablement.
  • Ne dépends pas du texte de prompt pour la sécurité qui doit être appliquée par du code.
  • Ne mets pas de timestamps, d'IDs de requête ou d'état d'environnement volatile au début des prompts mettables en cache.
  • Ne laisse pas la documentation obsolète, les exemples faibles ou les outils obsolètes s'accumuler sans nettoyage récurrent.

Liens source pour aller plus loin

Utilise ces liens quand un détail spécifique au fournisseur est nécessaire :

Skills similaires

skill-creator
cherryhq / cherry-studio

Créer, tester et affiner itérativement des skills pour agents IA.

48 271
skill-creator
anthropics / skills

Créer, tester et affiner des skills pour agents IA de façon itérative.

159 121
setup-my-iq
github / awesome-copilot

Créer et maintenir un portfolio de contexte personnel en fichiers markdown structurés.

36 284
yolo-chorus
chorus-aidlc / chorus

Piloter automatiquement tout le cycle de vie d'un DLC IA, de l'idée à la livraison.

1 064
ai-agent-workspace
rivet-dev / skills

Donner à chaque agent IA son propre environnement de travail isolé avec agentOS.

16