Travailler avec les agents IA de programmation — Guide pratique (2026)

Niveau 1 (Impact élevé — Toujours inclure)

• Présentation du projet — stack technique, versions, objectif
• Commandes — build, test, lint, deploy (exactes, prêtes à copier-coller)
• Style de code et conventions — formatage, nommage, patterns
• Standards de logging — niveaux, format, ce qui doit être logué

Niveau 2 (Impact moyen)

• Repères d'architecture — structure des dossiers, responsabilités des modules
• Règles « À faire » et « À ne pas faire » — les erreurs les plus fréquentes de l'agent
• Exigences de test — framework, couverture minimale, conventions

Niveau 3 (Rendements décroissants)

• Guide PR/Commit — format, conventions de messages
• Notes de sécurité — informations sensibles, pratiques à éviter
• Instructions de persona — ton, niveau de détail

Couche Enforce — Hooks et portes CI

Déterministes. Des commandes shell qui s'exécutent à des points spécifiques du cycle de vie. L'agent ne peut pas les contourner. Code de sortie 2 = bloqué, sans négociation.

• À utiliser pour : formatage, linting, exécution de tests, analyse de sécurité, blocage des écritures dans les fichiers sensibles

Couche Advise — Fichiers de configuration (AGENTS.md / CLAUDE.md)

Consultatifs. L'agent les lit et les suit la plupart du temps, mais sous pression de contexte ou signaux conflictuels, il peut dévier.

• À utiliser pour : style de code, guide d'architecture, patterns de logging, conventions de nommage

Couche Suggest — Instructions dans le prompt

Éphémères. Des instructions contextuelles dans votre prompt. Priorité maximale pour la tâche en cours, mais disparaissent à la session suivante.

• À utiliser pour : exigences ponctuelles, contraintes spécifiques à la tâche

Le pattern de logging en cinq parties

Chaque opération significative devrait produire une trace structurée de logs suivant ces cinq composantes :

# 1. EN-TÊTE DE RUN — Ce qui démarre, avec quels paramètres
logger.info("=== Début du traitement des demandes ===")
logger.info(f"  Environnement : {env}")
logger.info(f"  Fichier d'entrée : {input_file}")
logger.info(f"  Total enregistrements : {total}")

# 2. PROGRESSION PAR LOT — Visibilité au niveau du lot
for i, batch in enumerate(batches):
    logger.info(f"  Lot {i+1}/{len(batches)} : traitement de {len(batch)} éléments...")

# 3. DÉLIMITEURS D'ÉLÉMENT — Chaque élément significatif est logué
for item in batch:
    logger.info(f"    [{item.id}] Traitement : {item.name}")
    # ... logique
    logger.info(f"    [{item.id}] Terminé : status={result.status}")

# 4. SORTIE CONSOLE — Résumé lisible par un humain
print(f"\n✓ Traités {success}/{total} demandes ({elapsed:.1f}s)")

# 5. RÉSUMÉ DE RUN — Totaux finaux structurés
logger.info("=== Résumé du run ===")
logger.info(f"  Réussis : {success}")
logger.info(f"  Échoués : {failed}")
logger.info(f"  Durée : {elapsed:.1f}s")

Qualité des messages de log

Les messages de log opaques sont aussi inutiles que l'absence totale de logs. Comparez :

Quand utiliser le logging JSON structuré

Le logging JSON structuré est le plus adapté lorsque les logs sont consommés par des machines (agrégateurs, alertes, tableaux de bord). Pour les scripts et outils CLI, les logs textuels lisibles par un humain sont généralement plus pratiques. Utilisez le logging JSON structuré quand : vous exploitez des microservices avec une agrégation centralisée des logs, vous avez besoin de champs de recherche cohérents entre plusieurs services, ou les exigences de conformité imposent des formats de log auditables.

Commandes utiles pour l'analyse des logs

# Trouver tous les échecs dans un run
grep "ÉCHEC\|ERROR\|Échoués" app.log

# Compter les éléments traités
grep -c "Traitement :" app.log

# Extraire les résumés de run
grep -A 5 "Résumé du run" app.log

# Suivre la progression en temps réel
tail -f app.log | grep "Lot"

Exemple : Auto-formatage après chaque édition

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write|edit",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Exemple : Bloquer les écritures dans les fichiers sensibles

// .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "write|edit",
        "command": "echo $CLAUDE_FILE_PATH | grep -qE '\\.(env|pem|key)$' && exit 2 || exit 0"
      }
    ]
  }
}

Fonctionne vraiment

Avec des nuances

Surestimé

Étape 1 : Créer votre AGENTS.md (30 min)

Commencez avec un template minimal et ajoutez au fur et à mesure que vous découvrez ce qui manque. Un fichier de 40 lignes qui couvre les commandes, le style de code et le logging vaut plus qu'un manifeste de 300 lignes que l'agent ignore à moitié.

# AGENTS.md

## Présentation du projet
- Stack : Next.js 16, TypeScript, Tailwind CSS v4, Sanity CMS
- Gestionnaire de paquets : pnpm
- Node : >=20

## Commandes
```bash
pnpm dev          # Serveur de développement
pnpm build        # Build de production
pnpm lint         # ESLint
pnpm test         # Vitest
```

## Style de code
- Formatage : prettier (appliqué à la sauvegarde)
- Imports : absolus avec alias @/
- Composants : fonctionnels, avec TypeScript strict
- Nommage : camelCase pour les variables, PascalCase pour les composants, kebab-case pour les fichiers

## Standards de logging
- Utiliser console.error() pour les échecs avec contexte
- Chaque fonction async a un try/catch avec des messages d'erreur descriptifs
- En-tête de run à l'entrée des opérations batch
- Toujours inclure : quel élément, quelle opération, quel résultat

## Règles
- NE PAS modifier .env, .env.local ou les fichiers .pem
- NE PAS utiliser `any` en TypeScript
- NE PAS ajouter de dépendances sans approbation explicite
- TOUJOURS exécuter pnpm lint avant de considérer une tâche comme terminée

Étape 2 : Configurer les liens symboliques (5 min)

Créez des liens symboliques depuis AGENTS.md vers les fichiers spécifiques à chaque outil :

# Depuis la racine du projet
ln -sf AGENTS.md CLAUDE.md
ln -sf AGENTS.md .windsurfrules
mkdir -p .github
ln -sf ../AGENTS.md .github/copilot-instructions.md

# Ajouter au .gitignore si vous ne voulez pas les symlinks dans le repo
echo "CLAUDE.md" >> .gitignore
echo ".windsurfrules" >> .gitignore

Étape 3 : Ajouter des hooks pour les règles critiques (15 min)

Configurez des hooks dans Claude Code pour garantir les règles qui ne peuvent pas être enfreintes :

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "write|edit",
        "command": "npx prettier --write $CLAUDE_FILE_PATH 2>/dev/null || true"
      }
    ],
    "PreToolUse": [
      {
        "matcher": "write|edit",
        "command": "echo $CLAUDE_FILE_PATH | grep -qE '\\.(env|pem|key)$' && exit 2 || exit 0"
      }
    ],
    "Stop": [
      {
        "command": "pnpm lint --quiet 2>&1 | tail -20"
      }
    ]
  }
}

Étape 4 : Ajouter des règles glob Cursor (optionnel, 15 min)

Cursor supporte l'activation automatique basée sur des globs, où les règles ne s'appliquent qu'aux fichiers correspondant à un pattern :

---
globs: ["**/*.ts", "**/*.tsx"]
alwaysApply: false
---

# Règles TypeScript

- Mode strict activé, pas de `any`
- Exporter les types explicitement
- Utiliser les patterns zod pour la validation

Étape 5 : Traiter comme du code (continu)

AGENTS.md a les mêmes problèmes de maintenance que n'importe quelle documentation. Sans entretien actif, les règles deviennent obsolètes et trompeuses.

• Versionner AGENTS.md dans Git
• Revoir les modifications en code review
• Nettoyer trimestriellement : supprimer les règles obsolètes
• Tester : après des modifications, lancer une session agent et vérifier si elle suit les nouvelles règles
• Rester sous 150 lignes — si ça dépasse, prioriser

Observabilité du code généré

Un logging adéquat, une gestion des erreurs, des métriques — exactement ce que couvre la Section 7. C'est la priorité pour la plupart des équipes qui utilisent des agents de programmation pour écrire du code applicatif.

Observabilité de l'agent lui-même

Tracer le raisonnement, suivre la consommation de tokens, évaluer la qualité des outputs — des outils comme LangSmith, Langfuse, etc. Cela ne devient pertinent que si vous construisez des applications basées sur des LLM (chatbots, pipelines RAG, workflows autonomes).

FAITES CES SIX CHOSES

• Créez un AGENTS.md à la racine de chaque projet actif (moins de 150 lignes, concentrez-vous sur les commandes, le style de code, le logging).
• Configurez des liens symboliques vers CLAUDE.md, .windsurfrules, etc.
• Ajoutez les standards de logging de la Section 7.
• Ajoutez des hooks pour tout ce qui doit être déterministe.
• Déléguez aux outils existants — linters, formateurs, vérificateurs de types sont des sources uniques de vérité.
• Traitez AGENTS.md comme du code : versionnez-le, revoyez-le, nettoyez-le trimestriellement.

À REPORTER POUR L'INSTANT

• Hiérarchies complexes de règles sur plusieurs fichiers
• Plateformes d'observabilité des agents (sauf si vous construisez des systèmes de production basés sur des LLM)
• Labels de persona simples
• Documentation détaillée des chemins de fichiers