mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-08-28 19:20:41 +08:00
Emmanuel Atsé
cede485217
* feat(docs): add sidebar order validator
Adds tools/validate-sidebar-order.js to validate sidebar.order values
in YAML frontmatter across English and translated docs.
Checks for duplicate orders, gaps in sequence, and missing order fields.
For translations, also warns on order drift from English counterparts.
Wired into the quality script as docs:validate-sidebar.
* fix(validate-sidebar): tighten language detection and drift guard, add docstrings
* fix(validate-sidebar): replace subdirectory heuristic with locale pattern matching
detectLanguageDirs() previously classified any top-level docs/ directory
containing subdirectories as a translation language. This was too broad —
if an English section ever gained nested subfolders it would be silently
excluded from validation.
Replaced with a BCP 47 locale-code regex (/^[a-z]{2}(?:-[a-zA-Z]{2})?$/)
that matches known patterns (cs, fr, vi-vn, zh-cn) and won't falsely
classify content sections like explanation/ or reference/.
* fix(validate-sidebar): guard drift check against undefined order values
extractSidebarOrder() returns { hasSidebar: false } when no sidebar block
exists, leaving order as undefined rather than null. The drift check only
guarded against null, allowing undefined values to emit noisy warnings
like "Order drift: ... order undefined".
Changed the guard to typeof === 'number' which correctly excludes both
undefined and null without relying on a specific sentinel value.
* chore(validate-sidebar): add JSDoc docstrings to all functions
Adds @param and @returns annotations to extractSidebarOrder,
detectLanguageDirs, getEnglishSections, checkDirectory,
checkTranslationDrift, and relativePath.
* fix(validate-sidebar): add to pre-commit hook
* refactor(validate-sidebar): harden parsing and edge-case handling
Refactor to main() wrapper with pure return-based APIs, single directory
scan, and shared reporting. Harden frontmatter parsing (anchored delimiter,
direct-child-only order extraction, flow mapping support) and validation
(Infinity/zero guard, gap flood cap, multi-segment locales, graceful ENOENT).
* docs: fix sidebar.order duplicates and gaps across all locales
Resolves all validator errors flagged by the new
tools/validate-sidebar-order.js check.
English (docs/{explanation,how-to,reference}/):
- Renumbered to remove duplicates; established reading order
for new explanation pages added since orders were last set.
Translations (cs, fr, vi-vn, zh-cn):
- Mirrored English structural ordering where files exist, then
compacted to 1..N within each directory to eliminate gaps
caused by missing translation files.
Non-blocking drift warnings remain where translation directories
have fewer files than English; these are expected per the
validator's design.
---------
Co-authored-by: Brian Madison <bmadcode@gmail.com>
4.5 KiB
4.5 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Prévention des conflits entre agents | Comment l'architecture empêche les conflits lorsque plusieurs agents implémentent un système |
|
Lorsque plusieurs agents IA implémentent différentes parties d'un système, ils peuvent prendre des décisions techniques contradictoires. La documentation d'architecture prévient cela en établissant des standards partagés.
Types de conflits courants
Conflits de style d'API
Sans architecture :
- L'agent A utilise REST avec
/users/{id} - L'agent B utilise des mutations GraphQL
- Résultat : Patterns d'API incohérents, consommateurs confus
Avec architecture :
- L'ADR1 spécifie : « Utiliser GraphQL pour toute communication client-serveur »
- Tous les agents suivent le même pattern
Conflits de conception de base de données
Sans architecture :
- L'agent A utilise des noms de colonnes en snake_case
- L'agent B utilise des noms de colonnes en camelCase
- Résultat : Schéma incohérent, requêtes illisibles
Avec architecture :
- Un document de standards spécifie les conventions de nommage
- Tous les agents suivent les mêmes patterns
Conflits de gestion d'état
Sans architecture :
- L'agent A utilise Redux pour l'état global
- L'agent B utilise React Context
- Résultat : Multiples approches de gestion d'état, complexité
Avec architecture :
- L'ADR spécifie l'approche de gestion d'état
- Tous les agents implémentent de manière cohérente
Comment l'architecture prévient les conflits
1. Décisions explicites via les ADR1
Chaque choix technologique significatif est documenté avec :
- Contexte (pourquoi cette décision est importante)
- Options considérées (quelles alternatives existent)
- Décision (ce qui a été choisi)
- Justification (pourquoi cela a-t-il été choisi)
- Conséquences (compromis acceptés)
2. Guidance spécifique aux FR/NFR2
L'architecture associe chaque exigence fonctionnelle à une approche technique :
- FR-001 : Gestion des utilisateurs → Mutations GraphQL
- FR-002 : Application mobile → Requêtes optimisées
3. Standards et conventions
Documentation explicite de :
- La structure des répertoires
- Les conventions de nommage
- L'organisation du code
- Les patterns de test
L'architecture comme contexte partagé
Considérez l'architecture comme le contexte partagé que tous les agents lisent avant d'implémenter :
PRD : "Que construire"
↓
Architecture : "Comment le construire"
↓
L'agent A lit l'architecture → implémente l'Epic 1
L'agent B lit l'architecture → implémente l'Epic 2
L'agent C lit l'architecture → implémente l'Epic 3
↓
Résultat : Implémentation cohérente
Sujets clés des ADR
Décisions courantes qui préviennent les conflits :
| Sujet | Exemple de décision |
|---|---|
| Style d'API | GraphQL vs REST vs gRPC |
| Base de données | PostgreSQL vs MongoDB |
| Authentification | JWT vs Sessions |
| Gestion d'état | Redux vs Context vs Zustand |
| Styling | CSS Modules vs Tailwind vs Styled Components |
| Tests | Jest + Playwright vs Vitest + Cypress |
Anti-patterns à éviter
:::caution[Erreurs courantes]
- Décisions implicites — « On décidera du style d'API au fur et à mesure » mène à l'incohérence
- Sur-documentation — Documenter chaque choix mineur cause une paralysie analytique
- Architecture obsolète — Les documents écrits une fois et jamais mis à jour poussent les agents à suivre des patterns dépassés :::
:::tip[Approche correcte]
- Documenter les décisions qui traversent les frontières des epics
- Se concentrer sur les zones sujettes aux conflits
- Mettre à jour l'architecture au fur et à mesure des apprentissages
- Utiliser
bmad-correct-coursepour les changements significatifs :::
Glossaire
-
ADR (Architecture Decision Record) : document qui consigne une décision d’architecture, son contexte, les options envisagées, le choix retenu et ses conséquences, afin d’assurer la traçabilité et la compréhension des décisions techniques dans le temps. ↩︎
-
FR / NFR (Functional / Non-Functional Requirement) : exigences décrivant respectivement ce que le système doit faire (fonctionnalités, comportements attendus) et comment il doit le faire (contraintes de performance, sécurité, fiabilité, ergonomie, etc.). ↩︎