Aller au contenu

ADR-010 — Convention de PR et review croisée sur les repos Bricks AI Analyst
Statut Proposed
Date 12/05/2026 (S20)
Décideurs Nicolas Léonard, Romain BAZIL
Origine Conversation Nicolas × Claude Code 11-12/05/2026, alignement final S20 (synchro hebdo 12/05)

Contexte

Le produit Bricks AI Analyst vit sur trois repos complémentaires :

  • bricks-os — contexte, doctrine, ADR, wiki, ways of working
  • brickssas/project-analysis — App TS, front React + back Express, Drizzle/Neon
  • brickssas/IA-analyse-API — Agents Python, orchestration FastAPI, RAG Qdrant

Chaque évolution structurante du produit touche au moins un de ces repos, parfois plusieurs (ex : une nouvelle convention agent → spec dans bricks-os + implémentation TS + adapter Python).

Aujourd'hui les pratiques divergent : project-analysis et IA-analyse-API ont une convention de PR vivante (format business → tech, validé via PR exemple BRI-706). bricks-os n'en avait aucune jusqu'à la PR #13 (12/05/2026, ouverture du sujet). Aucun mécanisme de review croisée entre Nicolas et Romain n'est formalisé, alors qu'ils sont les deux contributeurs principaux et travaillent sur des moitiés complémentaires du système (PM/business × tech/archi).

Conséquence : les décisions structurantes peuvent être prises et mergées sans qu'aucune trace business+tech ne soit produite, et sans qu'un second cerveau ait challengé l'approche.

Décision

Tous les repos Bricks AI Analyst (bricks-os, project-analysis, IA-analyse-API) adoptent une convention unique de Pull Request, et un mécanisme de review croisée sélective entre Nicolas et Romain.

1. Convention de description de PR (obligatoire sur les 3 repos)

## Lien Linear              ← optionnel, si ticket associé. Format : "BRI-XXX — titre"
## Ce qu'on observe         ← problème observé côté user/process (1 paragraphe concis)
## Ce qu'on peut attendre   ← bullets de l'effet du merge (cas particuliers explicités)
## Détails techniques       ← bullets par fichier modifié + sous-bullets pour étapes internes
## Risques résiduels        ← uniquement si un vrai risque à signaler. Sinon, retirer la section.

L'audit fichier-par-fichier est implicite dans les bullets de Détails techniques (chaque bullet mentionne le fichier, son type — nouveau / modifié —, et l'impact). Pas de tableau séparé, pas de check final en cases à cocher.

2. Pas de push direct sur main

Tout changement non-trivial passe par une Pull Request. Définition de « non-trivial » :

  • Touche plusieurs fichiers, ou
  • Touche une zone sensible : doctrine, ADR, wiki, CLAUDE.md, skills, schéma DB, conventions API publiques

Les commits direct sur main restent acceptables uniquement pour : - typos, corrections de liens cassés, mise à jour d'une seule métrique dans wiki/status/ - hotfix urgent en production avec post-mortem documenté

3. Review croisée sélective (pas systématique)

L'auteur d'une PR décide d'ajouter l'autre en reviewer quand :

  1. La PR matérialise une décision prise en synchro Romain × Nicolas (atterrissage d'un alignement)
  2. La PR change le way of working ou une convention (ADR, skill, hook, format)
  3. La PR touche à la doctrine ou à un sujet doctrinal (wiki/doctrine/)
  4. La PR introduit un sujet cross-domaine (PM/business × tech/archi)
  5. L'auteur veut explicitement le regard de l'autre sur un arbitrage qu'il a hésité à trancher seul

En dehors de ces 5 cas, pas d'attribution automatique — la review reste un signal de pertinence, pas une gate de merge.

4. Asynchronisme assumé

Une PR n'attend pas de review pour merger, sauf si l'auteur le demande explicitement. Le reviewer peut commenter post-merge — ses remarques alimentent les ADR suivants ou des ajustements futurs.

Rationale

  • Cohérence cross-repo : un même produit, trois repos. Lire une PR doit être uniforme quel que soit le repo où elle vit. Sans convention unique, le contributeur perd du temps à se rappeler quelle règle s'applique où.
  • Mémoire collective : le format business → tech force l'explicitation. Il capture l'info qui ne tiendrait pas dans un message de commit, et qui se perd à 3 mois.
  • Review croisée comme signal, pas comme gate : le but n'est pas de bloquer mais de marquer ce qui mérite l'attention de l'autre. Le volume de PRs n'est pas review-able dans son intégralité — la sélection rend la review utile plutôt que formelle.
  • Bricks-OS comme source de vérité cross-repo : les conventions vivent canoniquement ici, et les CLAUDE.md des deux autres repos pointent vers cet ADR. Évite la duplication et le drift entre repos.

Conséquences

Ce qui change

  1. Les 3 repos (bricks-os, project-analysis, IA-analyse-API) adoptent le format de PR documenté ici
  2. Le mécanisme « ajout reviewer » devient un geste réflexe selon les 5 critères ci-dessus
  3. bricks-os devient le repo canonique pour les conventions cross-repo — les CLAUDE.md de project-analysis et IA-analyse-API pointent vers cet ADR (à faire dans des PR de suivi)

Ce qu'il faut faire

  • Cadrer en synchro hebdo S20 (12/05) — valider la convention + le scope du « non-trivial »
  • Ouvrir une PR sur project-analysis et sur IA-analyse-API pour ajouter dans leurs CLAUDE.md un pointeur vers cet ADR
  • Pas de protection technique GitHub demandée à ce stade — c'est une convention partagée, pas un blocage tooling

Ce qu'il faut éviter

  • Mettre l'autre en reviewer systématiquement sur tout (anti-pattern « review = formalité »)
  • Bloquer un merge en attente de review (sauf demande explicite de l'auteur)
  • Squash merge qui perd l'historique des commits intermédiaires et de leurs verbatims

Alternatives écartées

  • Review systématique cross-repo : irréaliste au regard du volume et des délais. Transforme la review en formalité bâclée et tue la vélocité — pire que pas de review du tout.
  • CODEOWNERS automatique : trop rigide. Définir un « owner » par fichier ne reflète pas la nature transverse des décisions produit Bricks (un ADR doctrinal n'a pas un owner-fichier, il a deux décideurs humains).
  • Une convention par repo, chacun la sienne : génère du drift, force le contributeur à se rappeler quelle règle s'applique où. Anti-pattern d'OS unifié.

Verbatims

« On ne parle pas que du fait de pousser directement sur main pour ce repo bricks-os mais sur l'ensemble des repos (app TS, API agents). Le but ici est d'introduire et officialiser un process de relecture et documentation de ce qui évolue sur le produit au global. » — Nicolas, 12/05/2026

« On ne va probablement pas avoir le temps de review toutes les PR poussées par un autre contributeur. Mais sur certaines PR ça peut être pertinent de mettre l'autre en review (si Romain est à l'origine de la PR → mettre Nicolas en reviewer, et vice-versa). » — Nicolas, 12/05/2026

« Détails techniques: c'est ok. Pas besoin d'un grand tableau d'audit mais gardons cette idée, juste de façon + concise. Risques résiduels: retirons sauf si tu penses que c'est pertinent de l'avoir dans la description de 100% des PRs. » — Nicolas, 12/05/2026, formalisation finale du format

Voir aussi

Sources