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>
3.9 KiB
3.9 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Ngăn xung đột giữa các agent | Cách kiến trúc ngăn xung đột khi nhiều agent cùng triển khai một hệ thống |
|
Khi nhiều agent AI cùng triển khai các phần khác nhau của hệ thống, chúng có thể đưa ra các quyết định kỹ thuật mâu thuẫn nhau. Tài liệu kiến trúc ngăn điều đó bằng cách thiết lập các tiêu chuẩn dùng chung.
Các kiểu xung đột phổ biến
Xung đột về phong cách API
Không có kiến trúc:
- Agent A dùng REST với
/users/{id} - Agent B dùng GraphQL mutations
- Kết quả: pattern API không nhất quán, người dùng API bị rối
Có kiến trúc:
- ADR quy định: "Dùng GraphQL cho mọi giao tiếp client-server"
- Tất cả agent theo cùng một mẫu
Xung đột về thiết kế cơ sở dữ liệu
Không có kiến trúc:
- Agent A dùng tên cột theo snake_case
- Agent B dùng camelCase
- Kết quả: schema không nhất quán, truy vấn khó hiểu
Có kiến trúc:
- Tài liệu standards quy định quy ước đặt tên
- Tất cả agent theo cùng một pattern
Xung đột về quản lý state
Không có kiến trúc:
- Agent A dùng Redux cho global state
- Agent B dùng React Context
- Kết quả: nhiều cách quản lý state song song, độ phức tạp tăng cao
Có kiến trúc:
- ADR quy định cách quản lý state
- Tất cả agent triển khai thống nhất
Kiến trúc ngăn xung đột bằng cách nào
1. Quyết định rõ ràng thông qua ADR
Mỗi lựa chọn công nghệ quan trọng đều được ghi lại với:
- Context (vì sao quyết định này quan trọng)
- Các lựa chọn đã cân nhắc (có những phương án nào)
- Quyết định (ta đã chọn gì)
- Lý do (tại sao lại chọn như vậy)
- Hệ quả (các đánh đổi được chấp nhận)
2. Hướng dẫn riêng cho FR/NFR
Kiến trúc ánh xạ mỗi functional requirement sang cách tiếp cận kỹ thuật:
- FR-001: User Management → GraphQL mutations
- FR-002: Mobile App → Truy vấn tối ưu
3. Tiêu chuẩn và quy ước
Tài liệu hóa rõ ràng về:
- Cấu trúc thư mục
- Quy ước đặt tên
- Cách tổ chức code
- Pattern kiểm thử
Kiến trúc như một bối cảnh dùng chung
Hãy xem kiến trúc là bối cảnh dùng chung mà tất cả agent đều đọc trước khi triển khai:
PRD: "Cần xây gì"
↓
Kiến trúc: "Xây như thế nào"
↓
Agent A đọc kiến trúc → triển khai Epic 1
Agent B đọc kiến trúc → triển khai Epic 2
Agent C đọc kiến trúc → triển khai Epic 3
↓
Kết quả: Triển khai nhất quán
Các chủ đề ADR quan trọng
Những quyết định phổ biến giúp tránh xung đột:
| Chủ đề | Ví dụ quyết định |
|---|---|
| API Style | GraphQL hay REST hay gRPC |
| Database | PostgreSQL hay MongoDB |
| Auth | JWT hay Session |
| State Management | Redux hay Context hay Zustand |
| Styling | CSS Modules hay Tailwind hay Styled Components |
| Testing | Jest + Playwright hay Vitest + Cypress |
Anti-pattern cần tránh
:::caution[Những lỗi thường gặp]
- Quyết định ngầm - "Cứ để đó rồi tính phong cách API sau" sẽ dẫn đến không nhất quán
- Tài liệu hóa quá mức - Ghi lại mọi lựa chọn nhỏ gây tê liệt phân tích
- Kiến trúc lỗi thời - Tài liệu viết một lần rồi không cập nhật khiến agent đi theo pattern cũ :::
:::tip[Cách tiếp cận đúng]
- Tài liệu hóa những quyết định cắt ngang nhiều epic
- Tập trung vào những khu vực dễ phát sinh xung đột
- Cập nhật kiến trúc khi bạn học thêm
- Dùng
bmad-correct-coursecho các thay đổi đáng kể :::