mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-09-19 08:11:52 +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>
3.7 KiB
3.7 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Předcházení konfliktům agentů | Jak architektura zabraňuje konfliktům, když více agentů implementuje systém |
|
Když více AI agentů implementuje různé části systému, mohou dělat protichůdná technická rozhodnutí. Dokumentace architektury tomu zabraňuje stanovením sdílených standardů.
Běžné typy konfliktů
Konflikty stylu API
Bez architektury:
- Agent A používá REST s
/users/{id} - Agent B používá GraphQL mutations
- Výsledek: Nekonzistentní vzory API, zmatení konzumenti
S architekturou:
- ADR specifikuje: „Použít GraphQL pro veškerou komunikaci klient-server“
- Všichni agenti dodržují stejný vzor
Konflikty návrhu databáze
Bez architektury:
- Agent A používá snake_case pro názvy sloupců
- Agent B používá camelCase pro názvy sloupců
- Výsledek: Nekonzistentní schéma, matoucí dotazy
S architekturou:
- Dokument standardů specifikuje konvence pojmenování
- Všichni agenti dodržují stejné vzory
Konflikty řízení stavu
Bez architektury:
- Agent A používá Redux pro globální stav
- Agent B používá React Context
- Výsledek: Více přístupů k řízení stavu, složitost
S architekturou:
- ADR specifikuje přístup k řízení stavu
- Všichni agenti implementují konzistentně
Jak architektura zabraňuje konfliktům
1. Explicitní rozhodnutí skrze ADR
Každé významné technologické rozhodnutí je zdokumentováno s:
- Kontext (proč toto rozhodnutí záleží)
- Zvažované možnosti (jaké alternativy existují)
- Rozhodnutí (co jsme zvolili)
- Zdůvodnění (proč jsme to zvolili)
- Důsledky (přijaté kompromisy)
2. Specifické pokyny pro FR/NFR
Architektura mapuje každý funkční požadavek na technický přístup:
- FR-001: Správa uživatelů → GraphQL mutations
- FR-002: Mobilní aplikace → Optimalizované dotazy
3. Standardy a konvence
Explicitní dokumentace:
- Struktura adresářů
- Konvence pojmenování
- Organizace kódu
- Vzory testování
Architektura jako sdílený kontext
Představte si architekturu jako sdílený kontext, který všichni agenti čtou před implementací:
PRD: "Co budovat"
↓
Architektura: "Jak to budovat"
↓
Agent A čte architekturu → implementuje Epic 1
Agent B čte architekturu → implementuje Epic 2
Agent C čte architekturu → implementuje Epic 3
↓
Výsledek: Konzistentní implementace
Klíčová témata ADR
Běžná rozhodnutí, která zabraňují konfliktům:
| Téma | Příklad rozhodnutí |
|---|---|
| Styl API | GraphQL vs REST vs gRPC |
| Databáze | PostgreSQL vs MongoDB |
| Autentizace | JWT vs Sessions |
| Řízení stavu | Redux vs Context vs Zustand |
| Stylování | CSS Modules vs Tailwind vs Styled Components |
| Testování | Jest + Playwright vs Vitest + Cypress |
Anti-vzory, kterým se vyhnout
:::caution[Běžné chyby]
- Implicitní rozhodnutí — „Styl API vyřešíme průběžně“ vede k nekonzistenci
- Nadměrná dokumentace — Dokumentování každého drobného rozhodnutí způsobuje paralýzu analýzou
- Zastaralá architektura — Dokumenty napsané jednou a nikdy neaktualizované způsobují, že agenti následují zastaralé vzory :::
:::tip[Správný přístup]
- Dokumentujte rozhodnutí, která přesahují hranice epiců
- Zaměřte se na oblasti náchylné ke konfliktům
- Aktualizujte architekturu, jak se učíte
- Použijte
bmad-correct-coursepro významné změny :::