tderoussel/fleet-brief

Fleet brief

Les agents parallèles échouent sur les terrains partagés — deux voies modifiant le même fichier. Le briefing existe pour rendre cette collision impossible avant le lancement. Dérivez les frontières à partir de la carte réelle des fichiers ; ne les supposez jamais.

Construire le briefing dans cet ordre

1. Cartographier d'abord les fichiers

Avant de définir les voies, listez les fichiers que chaque modification proposée toucherait. Lisez-les. Une voie définie sans avoir lu ses fichiers est une collision en attente.

2. Attribuer une propriété exclusive

Chaque fichier a exactement une voie propriétaire. Produisez ce tableau :

Voie	Possède (écrit)	Lecture seule
W1 —	path/a.ts, path/b.ts	path/shared.ts

Si deux voies doivent écrire dans un même fichier, vous avez trois options — choisissez-en une explicitement, ne laissez jamais l'ambiguïté :

• Séquencer (W2 attend la fusion de W1)
• Fusionner les deux en une seule voie
• Coudre : une voie ajoute un point d'extension, l'autre le consomme

3. Nommer le terrain partagé

Listez chaque fichier que plus d'une voie lit, et indiquez qui peut l'écrire.

Dérivez cette liste de la base de code que vous avez sous les yeux — ne rapportez pas la liste d'un autre projet. Les formes récurrentes à vérifier :

• Le chemin entrant actif. Tout ce qui reçoit des webhooks ou du trafic utilisateur. Les modifications concurrentes ici échouent en production, pas dans les tests.
• Les modules moteur et répartiteur que plusieurs fonctionnalités appellent.
• Les manifestes en ajout seul — configs de déploiement, tables de routage, listes de fonctions. Les plateformes imposent des limites (nombre de fonctions, tailles de fichiers) ; deux voies ajoutant indépendamment peuvent les dépasser.
• Les exports largement importés. Ajoutez de manière additive ; un renommage se répercute sur tous les appelants.
• Les fichiers générés ou vendus qu'aucune voie ne doit modifier à la main.

Un fichier qui a déjà causé une collision est définitivement un terrain partagé. Enregistrez-le dans le briefing pour que la prochaine flotte hérite de la connaissance.

4. Dériver la liste DO-NOT

Chaque DO-NOT nomme un fichier ou un comportement et la raison. Les interdictions nues sont ignorées ; celles ancrées tiennent.

Les entrées qui se généralisent à la plupart des bases de code :

• Ne jamais git add -A pendant la résolution de conflit — cela ajoute les marqueurs de conflit et le travail des autres voies.
• Les travailleurs ne commitent pas dans les worktrees liés ; l'orchestrateur commit.
• Si la suite de tests mocke la base de données globalement, un test unitaire vert ne prouve rien sur la base de données. Dites-le explicitement.
• N'ajoutez pas de dépendances sans justification d'une ligne.
• N'appliquez pas de migrations de schéma depuis une voie. Reportez-les à une étape unique révisée.
• Méfiez-vous des appels CLI qui échouent silencieusement — par exemple gh pr create nécessite un --base explicite, et les heredocs chaînés peuvent avaler les erreurs.

Ajoutez ensuite les entrées spécifiques au projet. Chaque incident qui vous a coûté une nuit a sa place ici, avec sa raison attachée.

5. Définir la validation

Indiquez explicitement, par voie : ce que signifie « terminé », quelles preuves l'attestent, et qui révise avant fusion.

La valeur par défaut à garder est révision avant mise en ligne — construire, puis révision indépendante en ligne, puis cycles de corrections obligatoires, puis fusion. Ne fusionnez jamais une voie sur la seule parole de son auteur. L'agent de l'auteur est le pire possible pour réviser sa propre diff.

6. Marquer ce qui est en attente

Une section « Volontairement PAS fait — nécessite un humain ». Les éléments gardés pour un go explicite sont gardés intentionnellement. Ne laissez pas une voie exécuter un élément parce qu'il semble prêt.

Isolation

Exécutez les builds dans des worktrees git, jamais dans le checkout principal — une flotte qui partage un répertoire de travail va entrelacer les modifications. Si les voies modifient des fichiers qui se chevauchent malgré la carte, donnez à chacune son propre worktree.

Dimensionnement

Les voies doivent pouvoir être fusionnées indépendamment. Si une voie ne peut pas fusionner sans la PR d'une autre voie, ce n'est pas une voie — c'est une phase. Séquencez les phases ; parallélisez les voies.

Sortie

Écrivez le briefing à l'endroit où le projet conserve ses plans, et ouvrez-le avec un avertissement « vérifier, ne jamais supposer ». Les lignes d'état dans tout document source sont des points de contrôle, pas une autorité — revérifiez le commit en direct, l'état de la base de données, les vérifications de PR et les têtes de worktree avant de dispatcher en fonction de celles-ci.