mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-09-17 17:17:48 +08:00
Emmanuel AtséandBrian Madison
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>
3.4 KiB
3.4 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Preventing Agent Conflicts | How architecture prevents conflicts when multiple agents implement a system |
|
When multiple AI agents implement different parts of a system, they can make conflicting technical decisions. Architecture documentation prevents this by establishing shared standards.
Common Conflict Types
API Style Conflicts
Without architecture:
- Agent A uses REST with
/users/{id} - Agent B uses GraphQL mutations
- Result: Inconsistent API patterns, confused consumers
With architecture:
- ADR specifies: "Use GraphQL for all client-server communication"
- All agents follow the same pattern
Database Design Conflicts
Without architecture:
- Agent A uses snake_case column names
- Agent B uses camelCase column names
- Result: Inconsistent schema, confusing queries
With architecture:
- Standards document specifies naming conventions
- All agents follow the same patterns
State Management Conflicts
Without architecture:
- Agent A uses Redux for global state
- Agent B uses React Context
- Result: Multiple state management approaches, complexity
With architecture:
- ADR specifies state management approach
- All agents implement consistently
How Architecture Prevents Conflicts
1. Explicit Decisions via ADRs
Every significant technology choice is documented with:
- Context (why this decision matters)
- Options considered (what alternatives exist)
- Decision (what we chose)
- Rationale (why we chose it)
- Consequences (trade-offs accepted)
2. FR/NFR-Specific Guidance
Architecture maps each functional requirement to technical approach:
- FR-001: User Management → GraphQL mutations
- FR-002: Mobile App → Optimized queries
3. Standards and Conventions
Explicit documentation of:
- Directory structure
- Naming conventions
- Code organization
- Testing patterns
Architecture as Shared Context
Think of architecture as the shared context that all agents read before implementing:
PRD: "What to build"
↓
Architecture: "How to build it"
↓
Agent A reads architecture → implements Epic 1
Agent B reads architecture → implements Epic 2
Agent C reads architecture → implements Epic 3
↓
Result: Consistent implementation
Key ADR Topics
Common decisions that prevent conflicts:
| Topic | Example Decision |
|---|---|
| API Style | GraphQL vs REST vs gRPC |
| Database | PostgreSQL vs MongoDB |
| Auth | JWT vs Sessions |
| State Management | Redux vs Context vs Zustand |
| Styling | CSS Modules vs Tailwind vs Styled Components |
| Testing | Jest + Playwright vs Vitest + Cypress |
Anti-Patterns to Avoid
:::caution[Common Mistakes]
- Implicit Decisions — "We'll figure out the API style as we go" leads to inconsistency
- Over-Documentation — Documenting every minor choice causes analysis paralysis
- Stale Architecture — Documents written once and never updated cause agents to follow outdated patterns :::
:::tip[Correct Approach]
- Document decisions that cross epic boundaries
- Focus on conflict-prone areas
- Update architecture as you learn
- Use
bmad-correct-coursefor significant changes :::