![](/blog-assets/ai-collaboration-playbook.webp) Vous avez déjà vécu ça ? - 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 Si vous utilisez l’IA comme “une recherche plus rapide”, ces problèmes restent invisibles. Mais dès que vous la considérez comme “un coéquipier”, ils impactent directement la qualité de livraison. Cet article présente une **méthode d’ingénierie exécutable** pour transformer la collaboration IA — de la “magie de prompts” vers un **processus reproductible**. Dans PrivyDrop, après adoption, l’ajout de features et les bugfixes sont devenus plus rapides et plus stables : non pas en prenant plus de risques, mais en réduisant les retours en arrière. À la fin, vous obtenez une structure minimale copiable dans n’importe quel repo : - `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) Tous les exemples viennent du repo open source PrivyDrop : [**https://github.com/david-bai00/PrivyDrop**](https://github.com/david-bai00/PrivyDrop) OpenAI a aussi publié un retour d’expérience très proche dans l’esprit : [**https://openai.com/index/shipping-sora-for-android-with-codex/**](https://openai.com/index/shipping-sora-for-android-with-codex/) --- ## Step 0 : définir les limites et le “done” (ne pas commencer par les prompts) Ce step fait une seule chose : rendre explicite ce que “terminé” veut dire. Sinon, l’IA optimise pour “ça marche”, pas pour “ça marche durablement et maintenablement”. Trois contraintes minimales : 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 À mettre en une phrase en tête de chaque demande : ```text 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 Avant de commencer, voici les 3 erreurs les plus courantes : 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) Pensez à `AGENTS.md` comme à une version “machine-readable” des “valeurs par défaut” et des “lignes rouges” de votre équipe. Son rôle n’est pas d’expliquer la théorie : c’est d’être **réappliqué à chaque session**. Dans PrivyDrop, cinq lignes suffisent pour capturer l’essentiel : - 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` Fichier : [**AGENTS.en.md**](https://github.com/david-bai00/PrivyDrop/blob/main/AGENTS.en.md) Si vous partez de zéro, voici une forme minimale (courte, stricte, actionnable) : ```md # 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 Si votre repo doit fonctionner dans plusieurs langues, un pattern pragmatique : - Garder `AGENTS.en.md` comme version canonique - Ajouter des variantes localisées au besoin (ex. `AGENTS..md`) - Après le clone, chaque contributeur crée localement un symlink selon sa langue : ```bash # 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) L’une des raisons les plus fréquentes du “drift” : **l’IA ne connaît pas vos vrais entry points**. Du coup, elle “devine” où changer. Votre index doit faire deux choses : - 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 Référence : [**docs/ai-playbook/index.md**](https://github.com/david-bai00/PrivyDrop/blob/main/docs/ai-playbook/index.md) Template minimal (copiable) : ```md # 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) La code-map sert à “se repérer vite”, pas à “vous apprendre à implémenter”. Les règles d’écriture sont simples : - 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 Référence : [**docs/ai-playbook/code-map.md**](https://github.com/david-bai00/PrivyDrop/blob/main/docs/ai-playbook/code-map.md) Optionnel : ajouter un mini “requêtes courantes → entry points” pour réduire encore le coût de recherche : ```md 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 ``` Comment générer (et itérer) une code-map : - 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 la code-map répond à “où changer”, `flows.md` répond à “comment ça tourne”. C’est extrêmement précieux pour l’IA : - 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 Référence : [**docs/ai-playbook/flows.md**](https://github.com/david-bai00/PrivyDrop/blob/main/docs/ai-playbook/flows.md) Au minimum, inclure : 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) Comment générer (et itérer) les flows : - 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 C’est là que l’accélération devient réelle : déplacer la review plus tôt — de “lire un diff” à “lire un plan”. Mettez le template de plan dans `collab-rules.md` et traitez-le comme une contrainte dure. Template PrivyDrop : [**docs/ai-playbook/collab-rules.md**](https://github.com/david-bai00/PrivyDrop/blob/main/docs/ai-playbook/collab-rules.md) Vous pouvez réutiliser directement cette structure (goals/scope/approach/risks/acceptance/rollback/validation) : ```text Title: Goals - Scope / Files - Approach - Risks & Mitigations - → Acceptance Criteria - Rollback - Docs to Update - docs/ai-playbook/index.md / code-map.md / flows.md / collab-rules.md / others? Validation - Build: next build - Manual: ``` En pratique, un workflow plus stable : 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) Sur une tâche longue, la baisse de qualité est presque inévitable. Transformez l’“endurance” en réflexe : quand vous voyez du guessing, des contraintes oubliées, ou du drift — écrivez l’état dans un fichier puis repartez dans une nouvelle conversation ; ou faites un passage “compress/summarize” pour réduire le contexte avant de continuer. Template de handoff minimal (à mettre dans `docs/ai-playbook/handoff.md` ou un fichier temporaire) : ```md # 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 ``` Le but n’est pas “une belle doc”, mais de déplacer le contexte de la fenêtre de chat vers un fichier que la session suivante peut relire de façon fiable. --- ## Step 6 : boucler la boucle (traiter l’agent comme un nouveau coéquipier) Une fois les pièces ci-dessus en place, la collaboration devient un pipeline stable : 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 Le bénéfice le plus visible : livrer des features et corriger des bugs devient plus rapide et plus stable. Surtout, le “rapide” vient de **moins de rework**, pas de plus de risque : - 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 Si vous voulez ajouter une “barrière”, mettez ces deux questions dans votre template de PR : - 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) Une fois votre AI Playbook prêt, vous pouvez lancer une session avec quelque chose comme ça : --- **Role** You are a senior Next.js full-stack engineer with strong product instincts. Your collaboration quality determines whether this repo can iterate sustainably—be thorough and professional. **Task kickoff** Please read `docs/ai-playbook/index.md` to understand the project context, code map, and collaboration rules. The current request is: "xxx". **Working style** Please deeply read relevant docs/code. Think systematically, ask clarifying questions, then propose analysis + a change plan for review. Implement only after approval. --- **Pourquoi ça marche** - **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 Dans “How we used Codex to build Sora for Android in 28 days”, OpenAI décrit un workflow très proche de ce playbook : [**https://openai.com/index/shipping-sora-for-android-with-codex/**](https://openai.com/index/shipping-sora-for-android-with-codex/) Points clés à aligner : - 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 Android et le web sont différents, mais la méthode transfère : **améliorez les inputs, et les outputs se stabilisent**. --- ## Structure minimale de dossiers (copiable) ```text AGENTS.en.md # Canonical rules (English) AGENTS..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 ``` --- Si vos docs sont déjà dispersées partout : commencez par `index.md` pour rassembler les entry points, puis complétez code-map/flows/templates. --- ## 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**](https://github.com/david-bai00/PrivyDrop) 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 Le développement assisté par IA ne réduit pas l’exigence de rigueur : il l’augmente. La vitesse durable vient de contraintes claires, de plans approuvés, de flows documentés et d’un contexte qui survit aux conversations. Si vous voulez aller plus loin, vous pouvez faire évoluer cette méthode en “scaffold de repo copiable” : templates de PR, templates d’issues, et un starter kit `AGENTS.md` + playbook prêt à l’emploi.

Étiquette: Codex

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