Empêcher l’IA de dérailler : une méthode de collaboration vraiment applicable (avec templates)

• Vous demandez à l’IA de corriger un bug, et elle modifie aussi du code hors sujet — puis vous devez revenir en arrière à la main
• Vous écrivez des tonnes de prompts, mais elle ne trouve pas les bons fichiers et finit par “deviner”
• Au milieu d’une longue discussion, elle oublie les contraintes et la qualité chute brutalement

• AGENTS.md : contraintes du repo (lignes rouges, valeurs par défaut, définition de done)
• docs/ai-playbook/index.md : point d’entrée 1 page (haute densité de signal)
• docs/ai-playbook/code-map.md : carte du code (où changer)
• docs/ai-playbook/flows.md : flows clés (comment ça tourne)
• docs/ai-playbook/collab-rules.md : règles de collaboration + template de plan de changement (comment on travaille)

Step 0 : définir les limites et le “done” (ne pas commencer par les prompts)

1. Boundary : ce qui ne doit jamais arriver (privacy/architecture red lines, compatibilité de protocole, guardrails de paramètres critiques)
2. Scope : un objectif par changement, pas de “tant qu’on y est…”
3. Done : build/tests + checklist de régression manuelle à écrire

Un seul objectif, plan d’abord ; ne jamais franchir les red lines privacy/architecture ; done = build OK + checklist de régression.

Anti‑patterns fréquents

1. Demander à l’IA de “modifier le code” sans plan
   • Résultat : 10 fichiers modifiés, puis vous réalisez que la direction était mauvaise — rollback douloureux
   • Mieux : exiger un plan de changement ; implémenter seulement après approbation
2. Tout jeter dans le prompt (overload de contexte)
   • Résultat : surcharge ; l’IA ne voit plus le signal (elle ne retrouve même pas les entry points)
   • Mieux : un index haute-signal + une code-map
3. Laisser l’IA “optimiser au passage”
   • Résultat : un PR mélange plusieurs objectifs ; le coût de review explose ; les bugs sont plus difficiles à revert
   • Mieux : single-scope, changements minimaux et facilement revertables

Step 1 : écrire AGENTS.md (contraintes du repo, réutilisables)

• Plan first : AGENTS.en.md:7
• One change, one purpose : AGENTS.en.md:8
• Privacy & architecture red line : AGENTS.en.md:9
• Docs must stay in sync : AGENTS.en.md:12
• Verification required : AGENTS.en.md:13

# AGENTS — Repo Rules

First Principles

- Plan-first: Propose a change plan and get approval before writing code
- Single-scope: One PR solves one goal; avoid “while I’m here” fixes
- Redlines: Never cross privacy/architecture/protocol/key-parameter guardrails
- Docs-sync: Keep the playbook docs in sync when entry points/flows/interfaces change
- Validation: Must include build/tests and key manual regression checklist

Support multilingue

• Garder AGENTS.en.md comme version canonique
• Ajouter des variantes localisées au besoin (ex. AGENTS.<locale>.md)
• Après le clone, chaque contributeur crée localement un symlink selon sa langue :

# Utilisateurs anglais
ln -s AGENTS.en.md AGENTS.md

• Ajouter AGENTS.md à .gitignore pour éviter les conflits de symlink

Idée clé
Le secret d’une collaboration IA fiable n’est pas “de meilleurs prompts”. C’est “de faire des contraintes une partie du repo”. AGENTS.md rend les règles réutilisables, et l’AI Playbook rend le contexte durable.

Step 2 : docs/ai-playbook/index.md (entrée haute‑signal)

• Se lire en 30 secondes : seulement “project snapshot + link index”
• Offrir une navigation en un clic : emmener le lecteur/l’IA vers code-map / flows / collab-rules

# AI Playbook — Index

## Project Snapshot

- Stack: Next.js / Node / ...
- Red lines: ...

## Document Index

- Code map: docs/ai-playbook/code-map.md
- Key flows: docs/ai-playbook/flows.md
- Collaboration rules: docs/ai-playbook/collab-rules.md

Step 3 : code-map.md (où changer)

• Lister uniquement les dossiers clés et les fichiers d’entrée (entry files)
• Une phrase par entry file : sa responsabilité
• À l’arrivée d’une demande : viser 3–8 fichiers candidats via la code-map, puis lire en profondeur

Routage des demandes courantes

- Nouvelle page / SEO: frontend/app/\*\*/page.tsx + metadata.ts
- Textes i18n: frontend/constants/messages/\*
- Blog: frontend/content/blog/\* + frontend/lib/blog.ts

• Première version : demander à l’IA de résumer “répertoires + entry points clés” pour naviguer — pas pour être exhaustif.
• Itération : la traiter comme un document vivant. La mettre à jour par incréments à chaque PR/commit (liste de fichiers), plutôt que de la réécrire.

Step 4 : flows.md (comment ça tourne)

• Si vous écrivez la séquence et les invariants, l’IA arrête de “patcher au feeling”
• Vous pouvez condenser les pièges historiques en checklist de debug réutilisable

1. Key flow / sequence (Mermaid si utile)
2. Debug checklist (logs/états les plus importants)
3. Micro-plan template (forcer plan-first avant de coder)

• Première version : demander à l’IA de reformuler le flux end-to-end + séquence + invariants. Vous relisez/corrigez (surtout les red lines et invariants), puis vous le figez en doc.
• Itération : le maintenir à jour par incréments dès qu’une interface/séquence change.

Step 5 : rendre “plan first” obligatoire

Title: <short, clear title>

Goals
- <what you want to achieve>

Scope / Files
- <list of files you’ll change/add + why>

Approach
- <implementation plan and key design points>

Risks & Mitigations
- <risk> → <mitigation>

Acceptance Criteria
- <verifiable acceptance items>

Rollback
- <how to revert quickly>

Docs to Update
- docs/ai-playbook/index.md / code-map.md / flows.md / collab-rules.md / others?

Validation
- Build: next build
- Manual: <key cases & regression points>

1. Lire l’index + code-map + flows (read-only, pas de changement de code)
2. Reformuler l’état actuel et les contraintes avec vos mots (vous corrigez une fois)
3. Produire un plan de changement (implémentation seulement après approbation)

Guide anti‑pièges
Corriger la direction au stade du plan, éviter de construire puis démolir ; le single-scope rend le rollback moins coûteux et les merges plus simples.

Step 5.1 : endurance du contexte (checkpoint → nouveau chat)

# Handoff

## Problem statement (3–5 sentences)

## Confirmed plan (bullets)

## Done / Not done

## Key files and entry points

## Red lines and invariants

## Acceptance & regression checklist

## Next-step checklist

Step 6 : boucler la boucle (traiter l’agent comme un nouveau coéquipier)

1. Demande → contraintes (citer AGENTS.md)
2. Navigation → entry points (citer index + code-map)
3. Alignement → séquences (citer flows)
4. Planification → mini design doc (citer le template collab-rules)
5. Implémentation → petit changement single-scope (rollback facile)
6. Vérification → next build + points de régression manuelle clés
7. Sync → garder les docs playbook à jour

• Corriger la direction au stade du plan ; éviter de jeter du travail
• Le single-scope garde le rollback peu coûteux et les merges faciles
• Les flows transforment les pièges passés en checklist réutilisable

• Est-ce que ce PR inclut un lien/résumé de plan de changement ?
• Est-ce que docs/ai-playbook/* a été mis à jour (si entry points/flows/interfaces ont changé) ?

Exemples de prompt (copiables)

• Role : fixe la barre de qualité et les responsabilités
• Task kickoff : force la lecture du playbook au lieu de deviner
• Working style : rend “plan first” obligatoire dans le workflow

Référence du secteur : comment OpenAI utilise Codex pour organiser un sprint

• Traiter l’agent comme un nouveau senior : capable, mais a besoin d’une architecture/contraintes explicites
• Externaliser les règles : un AGENTS.md solide paie sur la durée
• Plan avant changements réels : un plan est une mini design doc — on debug le plan avant le code
• Endurance du contexte : quand on atteint la limite, on écrit le plan dans un fichier pour la session suivante
• Parallélisme multi-session : plus proche de “manager une équipe” que d’utiliser un seul outil

Structure minimale de dossiers (copiable)

AGENTS.en.md             # Canonical rules (English)
AGENTS.<locale>.md       # Optional localized rules
AGENTS.md                # Symlink (created locally after git clone)
docs/
  ai-playbook/
    index.md             # High-signal entry point
    code-map.md
    flows.md
    collab-rules.md

Prochaines étapes

1. Commencer maintenant : copiez la structure minimale dans votre repo et démarrez par AGENTS.md
2. Implémentation de référence : visitez PrivyDrop GitHub et parcourez l’AI Playbook complet
3. Feedback : si ça vous aide (ou si vous tombez sur des pièges), ouvrez un issue GitHub ou laissez un commentaire
4. Star : si ça a de la valeur, mettez une étoile à PrivyDrop 🌟

Conclusion