Brian
bb45db4aa4
* feat(bmm): consolidate research trio into bmad-deep-recon
Replace bmad-market-research, bmad-domain-research, and bmad-technical-research
(5,136 lines of near-duplicate legacy step files) with one modern skill,
bmad-deep-recon (~650 lines):
- Research-master-orchestrator persona; conclusions never rest on training
data alone; lead-following rounds with coverage/novelty-exhaustion stops
- Six type packs as ~25-line policy+craft cards (market, domain, technical,
competitive, user-voice, academic-lit) + select decision shape layering a
weighted-matrix method over any type
- Three acquisition modes: Generate (subagent fan-out), Delegate (engine
registry: CLI/MCP, engine-first strategy), Import (provenance-tracked)
- Claims-ledger verification (normal/high/max) with independence rules and
optional red-team pass; cited synthesis with staleness map
- Effort presets (quick/standard/deep) over four knobs (subagents,
sources/round, depth, validation); precedence request > knob > preset
- Plan gate with surface discovery (MCPs/CLIs/engines), routing table, and
time estimate; use_workflows and subagent_models config
- Create/Refresh/Deepen intents, memlog run-folder workspace, headless JSON
- v6 shims forward the three old IDs with type pre-set; analyst menu,
catalog, marketplace, docs and translation mirrors updated
* feat(bmm): runtime output_format for bmad-deep-recon (v7 artifact protocol)
Replace the output_formats array with output_format = auto|html|md|both
(default auto): interactive runs render the HTML briefing, headless or
skill-invoked runs present the canonical markdown only. research.md always
exists in the workspace as the machine-readable report; the briefing is its
regenerable face. First instance of the v7 artifact protocol (memlog = truth,
md = distillation under contract, html = face).
* feat(core): move bmad-deep-recon to core-skills; address review findings
Move: research is not code-project-specific — home it in core-skills
(brainstorming precedent) so CIS and core-only installs get it. Skill ID
unchanged; standalone marketplace plugin added; catalogs moved to Core;
{planning_artifacts} falls back to {output_folder} on core-only installs.
v6 shims stay in bmm-skills (the legacy trio were bmm skills).
Review fixes (CodeRabbit):
- Engine briefs are now file-based: invoke templates substitute
{brief_file} (a skill-generated path), never inline brief text — quotes
and shell metacharacters in researched content can't shape a command.
- Refresh/Deepen preserve verification statuses for out-of-scope claims.
- HTML briefing: http(s)-only source links, escape source-derived text.
- user-voice pack: redact usernames/handles/emails from verbatim quotes;
communities complement surveys (triangulate) rather than beat them.
- engine.md: explicit single-writer rule — digests return to the lead,
which alone writes research.md in plan order.
* feat(core): deep-recon v2 — draft/process/run, faster defaults, research firewall
Rework after first real-run feedback (slow, token-heavy, locally biased
report, end-pass verification degraded quality, digests stranded in
subagent contexts):
- Three modes replace the acquisition-mode machinery: Draft (build a
deep-research prompt the user runs in their own subscribed tool),
Process (file a finished report into imports/, extract to digests/,
distill research.md summary + metadata so downstream never reprocesses),
Run (native fan-out, first-class). Bare research asks get the choice up
front with the trade stated honestly.
- Engine/Delegate registry cut: the Draft->Process round-trip is the
integration with dedicated deep-research tools; engine.md -> run.md.
- Files-first: digests hit {doc_workspace}/digests/ on landing, sections
commit per dimension, synthesis reads files never conversation memory,
dead runs resume from disk.
- Research firewall: persistent_facts default now empty, assistants get
only their brief, project context frames questions but is inadmissible
as evidence.
- Verification at landing, not end-of-run: normal = spot-check
load-bearing claims only; red_team default off; heavy passes behind
high/max. Presets rescaled faster (standard 3 subagents/8 sources/
depth 2).
- Multi-agent research lessons folded into run.md and the plan gate:
decomposition topology (breadth/depth/straightforward), per-assistant
tool-call budgets, query craft with OODA pause, shared source-quality
card, stop-and-write valve, mechanical citation check at finalize.
- Ripple: v6 shims, catalogs, marketplace, docs one-liners (all five
languages), template gains source: provenance field.
* feat(core): deep-recon quality pass — carve SKILL.md, recon_kit scripts, single-source verification
- SKILL.md 3989→2091 tokens: Draft/Process/Refresh+Deepen/Finalize carved to
references/{draft,process,lifecycle,finalize}.md; Run effort knobs + plan
gate moved into run.md; Overview and pack prose trimmed
- verification.md: red-team pass is the single adversarial mechanism (max
runs it at full breadth — no double-spawn); level semantics single-sourced
- scripts/recon_kit.py + tests: citations cross-check, memlog claim tally
(ref=/status= convention, last wins), staleness date math from per-class
windows, deterministic run-folder slugs, escaped source-appendix HTML
- Draft wired with preferred/banned source policies and an open-floor opening
- external_sources examples (Tavily/Sonar/xAI X-Search MCPs); source-quality
card: answer engines are aggregators — chase their citations
* docs: Deep Recon explanation page + integration
- new docs/explanation/deep-recon.md: three modes, mode-choice guidance,
research types, native-run internals diagram, firewall/verification, refresh
- analysis-phase.md research section rewritten for bmad-deep-recon
- core-tools.md: deep-recon in thinking-skills table, full catalog entry,
migration note for the merged market/domain/technical trio
- workflow-map.md + getting-started.md link the new page
- vi-vn developer guide: last stale old-skill flow mention updated
14 KiB
title, description
| title | description |
|---|---|
| Bắt đầu | Cài đặt BMad và xây dựng dự án đầu tiên của bạn |
Xây dựng phần mềm nhanh hơn bằng các workflow vận hành bởi AI, với những agent chuyên biệt hướng dẫn bạn qua các bước lập kế hoạch, kiến trúc và triển khai.
Bạn Sẽ Học Được Gì
- Cài đặt và khởi tạo BMad Method cho một dự án mới
- Dùng BMad-Help — trợ lý thông minh biết bước tiếp theo bạn nên làm gì
- Chọn nhánh lập kế hoạch phù hợp với quy mô dự án
- Đi qua các phase từ yêu cầu đến code chạy được
- Sử dụng agent và workflow hiệu quả
:::note[Điều kiện tiên quyết]
- Node.js 20.12+ — Bắt buộc cho trình cài đặt
- Git — Khuyến nghị để quản lý phiên bản
- IDE có AI — Claude Code, Cursor hoặc công cụ tương tự
- Một ý tưởng dự án — Chỉ cần đơn giản cũng đủ để học :::
:::tip[Cách Dễ Nhất]
Cài đặt → npx bmad-method install
Hỏi → bmad-help what should I do first?
Xây dựng → Để BMad-Help dẫn bạn qua từng workflow
:::
Làm Quen Với BMad-Help: Người Dẫn Đường Thông Minh Của Bạn
BMad-Help là cách nhanh nhất để bắt đầu với BMad. Bạn không cần phải nhớ workflow hay phase nào cả, chỉ cần hỏi, và BMad-Help sẽ:
- Kiểm tra dự án của bạn để xem những gì đã hoàn thành
- Hiển thị các lựa chọn dựa trên những module bạn đã cài
- Đề xuất bước tiếp theo — bao gồm cả tác vụ bắt buộc đầu tiên
- Trả lời câu hỏi như “Tôi có ý tưởng cho một sản phẩm SaaS, tôi nên bắt đầu từ đâu?”
Cách Dùng BMad-Help
Chạy trong AI IDE của bạn bằng cách gọi skill:
bmad-help
Hoặc ghép cùng câu hỏi để nhận hướng dẫn có ngữ cảnh:
bmad-help I have an idea for a SaaS product, I already know all the features I want. where do I get started?
BMad-Help sẽ trả lời:
- Điều gì được khuyến nghị trong tình huống của bạn
- Tác vụ bắt buộc đầu tiên là gì
- Phần còn lại của quy trình sẽ trông như thế nào
Nó Cũng Điều Khiển Workflow
BMad-Help không chỉ trả lời câu hỏi — nó còn tự động chạy ở cuối mỗi workflow để cho bạn biết chính xác bước tiếp theo cần làm là gì. Không phải đoán, không phải lục tài liệu, chỉ có chỉ dẫn rõ ràng về workflow bắt buộc tiếp theo.
:::tip[Bắt Đầu Từ Đây]
Sau khi cài BMad, hãy gọi skill bmad-help ngay. Nó sẽ nhận biết các module bạn đã cài và hướng bạn đến điểm bắt đầu phù hợp cho dự án.
:::
Hiểu Về BMad
BMad giúp bạn xây dựng phần mềm thông qua các workflow có hướng dẫn với những AI agent chuyên biệt. Quy trình gồm bốn phase:
| Phase | Tên | Điều xảy ra |
|---|---|---|
| 1 | Analysis | Brainstorming, nghiên cứu, product brief hoặc PRFAQ (tùy chọn) |
| 2 | Planning | Tạo tài liệu yêu cầu (PRD hoặc spec) |
| 3 | Solutioning | Thiết kế kiến trúc (chỉ dành cho BMad Method/Enterprise) |
| 4 | Implementation | Xây dựng theo từng epic, từng story |
Mở Workflow Map để khám phá các phase, workflow và cách quản lý context.
Dựa trên độ phức tạp của dự án, BMad cung cấp ba nhánh lập kế hoạch:
| Nhánh | Phù hợp nhất với | Tài liệu được tạo |
|---|---|---|
| Quick Flow | Sửa lỗi, tính năng đơn giản, phạm vi rõ ràng (1-15 story) | Chỉ spec |
| BMad Method | Sản phẩm, nền tảng, tính năng phức tạp (10-50+ story) | PRD + Architecture + UX |
| Enterprise | Yêu cầu tuân thủ, hệ thống đa tenant (30+ story) | PRD + Architecture + Security + DevOps |
:::note Số lượng story chỉ là gợi ý, không phải định nghĩa cứng. Hãy chọn nhánh dựa trên nhu cầu lập kế hoạch, không phải phép đếm story. :::
Cài Đặt
Mở terminal trong thư mục dự án và chạy:
npx bmad-method install
Nếu bạn muốn dùng bản prerelease mới nhất thay vì kênh release mặc định, hãy dùng npx bmad-method@next install.
Khi được hỏi chọn module, hãy chọn BMad Method.
Trình cài đặt sẽ tạo hai thư mục:
_bmad/— agents, workflows, tasks và cấu hình_bmad-output/— hiện tại để trống, nhưng đây là nơi các artifact của bạn sẽ được lưu
:::tip[Bước Tiếp Theo Của Bạn] Mở AI IDE trong thư mục dự án rồi chạy:
bmad-help
BMad-Help sẽ nhận biết bạn đã làm đến đâu và đề xuất chính xác bước tiếp theo. Bạn cũng có thể hỏi những câu như “Tôi có những lựa chọn nào?” hoặc “Tôi có ý tưởng SaaS, nên bắt đầu từ đâu?” :::
:::note[Cách Nạp Agent Và Chạy Workflow]
Mỗi workflow có một skill được gọi bằng tên trong IDE của bạn, ví dụ bmad-prd. Công cụ AI sẽ nhận diện tên bmad-* và chạy nó, bạn không cần nạp agent riêng. Bạn cũng có thể gọi trực tiếp skill của agent để trò chuyện tổng quát, ví dụ bmad-agent-pm cho PM agent.
:::
:::caution[Chat Mới] Luôn bắt đầu một chat mới cho mỗi workflow. Điều này tránh các vấn đề do giới hạn context gây ra. :::
Bước 1: Tạo Kế Hoạch
Đi qua các phase 1-3. Dùng chat mới cho từng workflow.
:::tip[Project Context (Tùy chọn)]
Trước khi bắt đầu, hãy cân nhắc tạo project-context.md để ghi lại các ưu tiên kỹ thuật và quy tắc triển khai. Nhờ vậy mọi AI agent sẽ tuân theo cùng một quy ước trong suốt dự án.
Bạn có thể tạo thủ công tại _bmad-output/project-context.md hoặc sinh ra sau phần kiến trúc bằng bmad-generate-project-context. Xem thêm.
:::
Phase 1: Analysis (Tùy chọn)
Tất cả workflow trong phase này đều là tùy chọn. Chưa chắc nên dùng cái nào?
- brainstorming (
bmad-brainstorming) — Gợi ý ý tưởng có hướng dẫn - research (
bmad-deep-recon) — Soạn prompt nghiên cứu chuyên sâu cho công cụ AI của riêng bạn, xử lý báo cáo hoàn chỉnh thành bản tóm tắt sẵn sàng cho các bước sau, hoặc thực hiện nghiên cứu ngay tại đây — thị trường, miền nghiệp vụ, kỹ thuật, cạnh tranh, tiếng nói người dùng và học thuật — kèm kiểm chứng luận điểm và vòng đời làm mới - product-brief (
bmad-product-brief) — Tài liệu nền tảng được khuyến nghị khi concept của bạn đã rõ - prfaq (
bmad-prfaq) — Bài kiểm tra Working Backwards để stress-test và rèn sắc concept sản phẩm của bạn
Phase 2: Planning (Bắt buộc)
Với nhánh BMad Method và Enterprise:
- Gọi PM agent (
bmad-agent-pm) trong một chat mới - Chạy workflow
bmad-prd(bmad-prd) - Kết quả:
PRD.md
Với nhánh Quick Flow:
- Chạy
bmad-quick-dev— workflow này gộp cả planning và implementation trong một lần, nên bạn có thể chuyển thẳng sang triển khai
:::note[Thiết kế UX (Tùy chọn)]
Nếu dự án của bạn có giao diện người dùng, hãy gọi UX-Designer agent (bmad-agent-ux-designer) và chạy workflow thiết kế UX (bmad-ux) sau khi tạo PRD.
:::
Phase 3: Solutioning (BMad Method/Enterprise)
Tạo Architecture
- Gọi Architect agent (
bmad-agent-architect) trong một chat mới - Chạy
bmad-architecture(bmad-architecture) - Kết quả: tài liệu kiến trúc chứa các quyết định kỹ thuật
Tạo Epics và Stories
:::tip[Cải tiến trong V6] Epics và stories giờ được tạo sau kiến trúc. Điều này giúp story có chất lượng tốt hơn vì các quyết định kiến trúc như database, API pattern và tech stack ảnh hưởng trực tiếp đến cách chia nhỏ công việc. :::
- Gọi PM agent (
bmad-agent-pm) trong một chat mới - Chạy
bmad-create-epics-and-stories(bmad-create-epics-and-stories) - Workflow sẽ dùng cả PRD lẫn Architecture để tạo story có đủ ngữ cảnh kỹ thuật
Kiểm tra mức sẵn sàng để triển khai (Rất nên dùng)
- Gọi Architect agent (
bmad-agent-architect) trong một chat mới - Chạy
bmad-check-implementation-readiness(bmad-check-implementation-readiness) - Xác nhận tính nhất quán giữa toàn bộ tài liệu lập kế hoạch
Bước 2: Xây Dựng Dự Án
Sau khi lập kế hoạch xong, chuyển sang implementation. Mỗi workflow nên chạy trong một chat mới.
Khởi Tạo Sprint Planning
Gọi Developer agent (bmad-agent-dev) và chạy bmad-sprint-planning (bmad-sprint-planning). Workflow này sẽ tạo sprint-status.yaml để theo dõi toàn bộ epic và story.
Chu Trình Xây Dựng
Với mỗi story, lặp lại chu trình này trong chat mới:
| Bước | Agent | Workflow | Lệnh | Mục đích |
|---|---|---|---|---|
| 1 | DEV | bmad-create-story |
bmad-create-story |
Tạo file story từ epic |
| 2 | DEV | bmad-dev-story |
bmad-dev-story |
Triển khai story |
| 3 | DEV | bmad-code-review |
bmad-code-review |
Kiểm tra chất lượng (khuyến nghị) |
Sau khi hoàn tất tất cả story trong một epic, hãy gọi Developer agent (bmad-agent-dev) và chạy bmad-retrospective (bmad-retrospective).
Bạn Đã Hoàn Thành Những Gì
Bạn đã nắm được nền tảng để xây dựng với BMad:
- Đã cài BMad và cấu hình cho IDE của bạn
- Đã khởi tạo dự án theo nhánh lập kế hoạch phù hợp
- Đã tạo các tài liệu lập kế hoạch (PRD, Architecture, Epics và Stories)
- Đã hiểu chu trình triển khai trong implementation
Dự án của bạn bây giờ sẽ có dạng:
your-project/
├── _bmad/ # Cấu hình BMad
├── _bmad-output/
│ ├── planning-artifacts/
│ │ ├── PRD.md # Tài liệu yêu cầu của bạn
│ │ ├── architecture.md # Các quyết định kỹ thuật
│ │ └── epics/ # Các file epic và story
│ ├── implementation-artifacts/
│ │ └── sprint-status.yaml # Theo dõi sprint
│ └── project-context.md # Quy tắc triển khai (tùy chọn)
└── ...
Tra Cứu Nhanh
| Workflow | Lệnh | Agent | Mục đích |
|---|---|---|---|
bmad-help ⭐ |
bmad-help |
Bất kỳ | Người dẫn đường thông minh của bạn — hỏi gì cũng được! |
bmad-prd |
bmad-prd |
PM | Tạo tài liệu yêu cầu sản phẩm |
bmad-architecture |
bmad-architecture |
Architect | Tạo tài liệu kiến trúc |
bmad-generate-project-context |
bmad-generate-project-context |
Analyst | Tạo file project context |
bmad-create-epics-and-stories |
bmad-create-epics-and-stories |
PM | Phân rã PRD thành epics |
bmad-check-implementation-readiness |
bmad-check-implementation-readiness |
Architect | Kiểm tra độ nhất quán của kế hoạch |
bmad-sprint-planning |
bmad-sprint-planning |
DEV | Khởi tạo theo dõi sprint |
bmad-create-story |
bmad-create-story |
DEV | Tạo file story |
bmad-dev-story |
bmad-dev-story |
DEV | Triển khai một story |
bmad-code-review |
bmad-code-review |
DEV | Review phần code đã triển khai |
Câu Hỏi Thường Gặp
Lúc nào cũng cần kiến trúc à? Chỉ với nhánh BMad Method và Enterprise. Quick Flow bỏ qua bước kiến trúc và chuyển thẳng từ spec sang implementation.
Tôi có thể đổi kế hoạch về sau không?
Có. Workflow bmad-correct-course (bmad-correct-course) xử lý thay đổi phạm vi giữa chừng.
Nếu tôi muốn brainstorming trước thì sao?
Gọi Analyst agent (bmad-agent-analyst) và chạy bmad-brainstorming (bmad-brainstorming) trước khi bắt đầu PRD.
Tôi có cần tuân theo đúng thứ tự tuyệt đối không? Không hẳn. Khi đã quen flow, bạn có thể chạy workflow trực tiếp bằng bảng Tra Cứu Nhanh ở trên.
Nhận Hỗ Trợ
:::tip[Điểm Dừng Đầu Tiên: BMad-Help]
Hãy gọi bmad-help bất cứ lúc nào — đây là cách nhanh nhất để gỡ vướng. Bạn có thể hỏi:
- "Tôi nên làm gì sau khi cài đặt?"
- "Tôi đang kẹt ở workflow X"
- "Tôi có những lựa chọn nào cho Y?"
- "Cho tôi xem đến giờ đã làm được gì"
BMad-Help sẽ kiểm tra dự án, phát hiện những gì bạn đã hoàn thành và chỉ cho bạn chính xác bước cần làm tiếp theo. :::
- Trong workflow — Các agent sẽ hướng dẫn bạn bằng câu hỏi và giải thích
- Cộng đồng — Discord (#bmad-method-help, #report-bugs-and-issues)
Những Điểm Cần Ghi Nhớ
:::tip[Hãy Nhớ Các Điểm Này]
- Bắt đầu với
bmad-help— Trợ lý thông minh hiểu dự án và các lựa chọn của bạn - Luôn dùng chat mới — Mỗi workflow nên bắt đầu trong một chat riêng
- Nhánh rất quan trọng — Quick Flow dùng
bmad-quick-dev; Method/Enterprise cần PRD và kiến trúc - BMad-Help chạy tự động — Mỗi workflow đều kết thúc bằng hướng dẫn về bước tiếp theo :::
Sẵn sàng bắt đầu chưa? Hãy cài BMad, gọi bmad-help, và để người dẫn đường thông minh của bạn đưa bạn đi tiếp.