Un développeur sage ne « commence pas à coder en espérant. » Il fait avancer un nouveau projet via brainstorming, discussion d’équipe, prototypage, diagrammes, propositions, ADR, MR/PR et GitOps — avec des Review Bots qui génèrent automatiquement des commentaires de PR pour que les humains se concentrent sur l’essentiel. Voici le playbook de niveau production. Un FDE peut installer le système ; la Claude Architect Certification mérite d’être poursuivie si vous voulez le concevoir et le défendre.
1. Ce que « sage » signifie sur un nouveau projet
La sagesse, ce n’est pas plus de réunions. C’est un apprentissage peu coûteux tôt et des erreurs coûteuses tard rendues rares. La séquence ci-dessous est ordonnée pour que chaque étape réduise le rayon d’explosion de la suivante :
Brainstorm → Discuss → Prototype → Diagram → Propose → ADR
→ Implement in small slices → MR/PR + Review Bot → Merge
→ GitOps promote (dev → staging → prod) → Observe → Iterate
Ne sautez des étapes qu’avec intention (ex. un correctif de config d’une ligne). Ne sautez jamais Review Bot + CI sur tout ce qui peut atteindre la production.
2. Brainstorming (seul d’abord, puis structuré)
Avant de demander du temps à quiconque, passez 30–90 minutes seul :
- Résultat : quel changement utilisateur/métier doit être vrai quand nous aurons terminé ?
- Contraintes : temps, budget, conformité, plateformes existantes, compétences de l’équipe.
- Non-objectifs : ce que nous ne construirons pas en v1 (protège le périmètre).
- Risques : données, sécurité, performance, dépendance fournisseur, charge opérationnelle.
- Métriques de succès : latence, taux d’erreur, adoption, coût — choisissez-en deux qui comptent.
Capturez cela dans une note courte (Notion/Confluence/markdown dans le dépôt sous docs/ideas/). Un brainstorming sans artefact écrit n’est qu’une conversation qui s’évapore.
3. Discussions avec les collègues
Invitez le plus petit cercle utile : un pair qui implémentera avec vous, une personne qui possède le système adjacent, et (si besoin) sécurité ou SRE. Règles pour rester sage :
- Time-box (25–45 minutes). Terminez par des décisions ou des questions ouvertes — pas des vibes.
- Désaccord sur les options, pas sur les personnes. Forcez « option A vs B vs reporter. »
- Désignez un scribe. La note devient la graine de la proposition.
- Pas de veto silencieux. Si quelqu’un est mal à l’aise, écrivez la préoccupation comme risque dans l’ADR plus tard.
L’async fonctionne aussi : un court fil de commentaires RFC bat souvent une réunion — mais quelqu’un doit quand même clôturer la boucle.
4. Prototypage (spikes avec date d’expiration)
Prototypez quand l’incertitude est élevée : une nouvelle API, un service cloud peu familier, une question de performance, ou un comportement IA/agent. Règles sages :
- Nommez-le spike dans le ticket ; fixez une date d’arrêt calendaire (1–3 jours typiques).
- Gardez le code sur une branche jetable ou un dossier
spikes/; ne peaufinez pas. - Notez ce que vous avez appris en 10 puces — surtout ce qui a échoué.
- Décidez : promouvoir (refactorer dans le produit), réécrire, ou abandonner.
Les prototypes qui deviennent silencieusement de la production sans ADR sont la façon dont les équipes héritent d’une architecture accidentelle.
5. Diagrammes (assez pour argumenter)
Vous n’avez pas besoin d’un roman UML. Préférez trois croquis qui tiennent chacun sur un écran :
| Diagramme | Répond à |
|---|---|
| Contexte (C4 L1) | Qui parle à quoi ? Frontières de confiance ? |
| Séquence | Chemin heureux + un chemin d’échec |
| Déploiement | Où cela s’exécute ; comment config et secrets circulent |
Stockez Mermaid ou images à côté de la proposition (docs/architecture/). Mettez à jour les diagrammes quand les ADR changent — des images obsolètes sont pires qu’aucune.
6. Propositions (RFC léger)
Une bonne proposition fait une à trois pages :
- Problème et pourquoi maintenant
- Options envisagées (au moins deux)
- Recommandation et pourquoi
- Impact : sécurité, coût, ops, migration
- Déploiement et rollback
- Questions ouvertes
Demandez une revue avec une échéance claire. Une fois approuvée (ou avec amendements), transformez la décision en ADR — ne laissez pas la « source de vérité » dans le chat.
7. ADR — Architecture Decision Records
Un ADR est un enregistrement court, immuable par convention, d’une décision. Modèle :
# ADR-00XX: Title Status: Proposed | Accepted | Superseded by ADR-00YY Date: YYYY-MM-DD Deciders: @alice @bob ## Context What forces are in play? ## Decision What we will do. ## Consequences Positive, negative, and follow-ups. ## Alternatives considered Option A — why not Option B — why not
Gardez les ADR dans git (docs/adr/). Liez-les depuis les PR. Remplacez plutôt que de réécrire l’historique — votre moi futur a besoin de la piste.
8. MR et PR — l’unité de livraison
MR (Merge Request, GitLab) et PR (Pull Request, GitHub/Bitbucket) sont la même idée : un ensemble de changements revuable. Habitudes sages :
- Petit : idéalement <400 lignes de diff significatif ; découpez en tranches verticales.
- Une intention : une fonctionnalité, un correctif ou une chore — pas « misc. »
- Description : pourquoi, comment tester, captures/logs, risque, rollback.
- Liens : ticket + ADR + diagramme de conception.
- Draft d’abord quand vous voulez un retour anticipé sans impliquer « prêt à merger. »
- Ne forcez jamais le merge autour d’un CI rouge ou de findings bot haute sévérité non résolus sans exception écrite.
Exemple de checklist du corps de PR
## Summary - … ## Test plan - [ ] Unit tests - [ ] Manual path … - [ ] Feature flag / config … ## Risk & rollback - Risk: … - Rollback: revert this PR / GitOps revert commit … ## References - ADR-00XX - Ticket ABC-123
9. Usage du Review Bot — commentaires PR auto-générés
Un Review Bot est un relecteur automatisé qui publie des commentaires inline et des résumés sur chaque MR/PR. Il ne remplace pas les humains ; il anticipe le banal et le dangereux.
9.1 Sur quoi le bot doit commenter
- Sécurité : injection, lacunes d’authz, fuite de secrets, défauts non sécurisés
- Correctness : chemins null, conditions de course, migrations cassées
- Tests : couverture manquante sur de nouvelles branches, abus de snapshots
- API/contrat : changements cassants sans bump de version
- Ops : timeouts manquants, pas d’idempotence, retries non bornés
- Style seulement quand il a échappé au formatter/linter (éviter le bruit)
9.2 Comment cela simplifie la vie du développeur
- L’auteur ouvre la PR → le bot s’exécute en secondes à minutes.
- L’auteur corrige ou répond aux fils du bot avant de demander des humains.
- Le relecteur humain lit le résumé du bot + se concentre sur le design et le risque produit.
- Moins de rounds de « nits » ; merge plus rapide ; moins d’incidents du vendredi soir dus à des pièges manqués.
9.3 Options de setup typiques
| Approche | Notes |
|---|---|
| SaaS Review Bot (ex. CodeRabbit, bots vendeurs) | Rapide à activer ; réglez sévérité et filtres de chemins |
| Cursor Bugbot / revue liée à l’IDE | Fort sur les diffs de PR dans les équipes centrées Cursor |
| GitHub Action custom + Claude / LLM | Contrôle total ; nécessite prompt + politique + plafonds de coût |
| Pipeline en couches (lint → SAST → LLM) | Meilleure posture production — voir le guide pipeline de revue de code IA |
9.4 Politique qui garde le bot utile
- Labels de sévérité : blocker / should-fix / nit — les nits ne doivent pas bloquer le merge.
- Ignorer les chemins générés (
vendor/, bruit des lockfiles, dumps protobuf). - Exiger une approbation humaine pour les chemins sensibles sécurité (
auth/,infra/, IAM). - Journaliser les faux positifs ; les réinjecter dans les règles d’ignore mensuellement.
- Ne jamais laisser le bot être le seul relecteur sur des services critiques production.
9.5 Esquisse minimale de GitHub Action
# .github/workflows/review-bot.yml
name: review-bot
on:
pull_request:
types: [opened, synchronize, reopened]
jobs:
review:
runs-on: ubuntu-latest
permissions:
contents: read
pull-requests: write
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Run Review Bot
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
run: |
# Fetch diff, call your review CLI, post review comments via gh api
./scripts/review-bot.sh
Implémentez review-bot.sh pour : calculer le diff de la PR, appeler votre modèle avec un prompt système strict (sécurité + correctness d’abord), et publier des commentaires via l’API GitHub/GitLab. Plafonnez les tokens et sautez les drafts si le coût est un souci.
10. Bonnes pratiques GitOps pour une qualité production-grade
GitOps signifie : l’état désiré vit dans git ; un réconciliateur (Argo CD, Flux, etc.) aligne le cluster ; la promotion est un merge ; le rollback est un revert.
- Séparer le code app et la config d’env (ou dossiers clairs :
apps/vsenvs/dev|staging|prod). - Pas de kubectl apply en prod comme chemin heureux — break-glass seulement, audité.
- Livraison progressive : auto-sync en dev ; sync manuelle ou gated pour prod.
- Digests d’image plutôt que des tags mutables dans les manifests prod.
- Policy as code : OPA/Kyverno pour privilèges, registries, limites de ressources.
- Commits signés / provenance là où votre modèle de menace l’exige.
- Observer après sync : health checks, budgets d’erreur, hooks de rollback automatique quand prêts.
La qualité du code n’est pas seulement des « fonctions propres. » C’est aussi comment le changement entre en production. GitOps rend ce chemin revuable, réversible et répétable.
11. Gates de qualité de bout en bout (optimisés pour la production)
Local: pre-commit (fmt, lint, secrets) + unit tests PR open: CI (build, test, SAST) + Review Bot comments PR merge: human approve + branch protection + required checks Main: build immutable artifact (image digest) GitOps: update env repo / overlay → sync → verify Prod: SLOs + alerts + runbook linked from ADR/PR
12. Rôle FDE — qui installe ce système
Un Forward Deployed Engineer est idéal pour installer le système du développeur sage dans une vraie équipe :
- Templates de dépôt :
docs/adr/, template PR, CODEOWNERS, branch protection - Review Bot + secrets + contrôles de coût
- Checks CI requis et protections d’environnement
- Apps GitOps (dev/staging/prod) et docs de promotion
- Coaching de deux semaines : premier ADR, première PR tunée par le bot, premier drill de rollback GitOps
Calendrier indicatif pour un enablement mené par FDE sur un dépôt produit : 1–2 semaines pour le scaffolding et la politique du bot ; +1–2 semaines pour le chemin de promotion GitOps et un rollback à blanc. Le changement culturel prend plus longtemps — mesurez le temps de merge et les défauts échappés, pas les installs d’outils.
13. Claude Architect Certification — à poursuivre
Si vous concevez des systèmes où humains et agents IA co-écrivent le code, la Claude Architect Certification mérite d’être poursuivie. Elle signale que vous pouvez :
- Architecturer une livraison assistée par IA sans traiter le modèle comme infaillible
- Spécifier politiques de revue, garde-fous et évaluation pour les workflows agentiques
- Communiquer les arbitrages (latence, coût, confidentialité, précision) aux parties prenantes
- Coacher les équipes sur ADR, discipline PR et gates production aux côtés des outils IA
Associez le credential à une vraie livraison : déployez un Review Bot, écrivez trois ADR, et menez un drill de rollback GitOps. Le papier sans pratique ne vous rend pas sage ; la pratique plus un langage partagé, si.
14. Anti-patterns (à quoi ressemble l’imprudence)
- PR géante avec « WIP please approve ASAP »
- Architecture décidée seulement dans Slack, jamais en ADR
- Prototype mergé en prod sans tests
- Désactiver le Review Bot parce qu’« il râle »
- Hotfix en prod hors GitOps sans plan de revert
- Humains qui répètent des nits de formatter que le bot a déjà attrapés
15. Checklist starter copy-paste pour un nouveau projet
- Créer
docs/ideas/,docs/architecture/,docs/adr/ - Ajouter template PR/MR + CODEOWNERS
- Activer pre-commit + checks CI requis
- Installer Review Bot ; régler filtres de chemins et sévérités
- Écrire ADR-0001 : « We use GitOps for deploy »
- Définir environnements et règles de promotion
- Planifier un game day rollback de 30 minutes
- Réserver du temps FDE pour le coaching du premier mois ; considérer Claude Architect Certification pour les leads
16. Conclusion
Un développeur sage traite un nouveau projet comme une séquence d’artefacts d’apprentissage — notes, diagrammes, propositions, ADR — puis livre via de petits MR/PR surveillés par un Review Bot et promus par GitOps. C’est ainsi que la qualité du code est optimisée pour le niveau production sans brûler l’équipe sur d’interminables nits. Laissez un FDE installer les rails ; laissez des architectes certifiés garder le système honnête tandis que l’IA accélère la vitesse d’écriture du code.
Publié par Workstation.
