docs/vi-vn/bmad-developer-guide.md
BMAD (Build More Architect Dreams) là framework phát triển phần mềm hỗ trợ bởi AI, giúp team đi từ ý tưởng đến sản phẩm một cách có cấu trúc, nhất quán và hiệu quả.
BMAD Method là một hệ thống phối hợp nhiều AI agent chuyên biệt để hỗ trợ toàn bộ vòng đời phát triển phần mềm — từ phân tích ý tưởng, lập kế hoạch, thiết kế kiến trúc, đến triển khai code và kiểm thử.
| Cách thông thường | BMAD Method |
|---|---|
| Hỏi AI từng câu rời rạc | Workflow có cấu trúc, mỗi bước tạo đầu ra cho bước kế tiếp |
| Một AI làm tất cả | Nhiều agent chuyên biệt, mỗi agent hiểu sâu vai trò của mình |
| Không có tài liệu hóa | Mỗi giai đoạn sinh ra tài liệu chuẩn (PRD, Architecture, Stories) |
| Developer phải giám sát liên tục | Agent tự chủ dài hơn, chỉ cần con người tại các điểm kiểm tra quan trọng |
Mỗi giai đoạn trong BMAD sinh ra một tài liệu chuẩn. Tài liệu đó trở thành đầu vào cho giai đoạn kế tiếp. Agent AI đọc tài liệu để hiểu context, thay vì phụ thuộc vào lịch sử hội thoại có thể bị mất.
Ý tưởng → [Brief/PRFAQ] → PRD → Architecture → Epics/Stories → Code → Tests
BMAD tách bạch rõ ràng hai câu hỏi quan trọng nhất:
Đây là nguyên lý quan trọng nhất. Nhiều dự án thất bại vì triển khai khi chưa thống nhất được "XÂY GÌ", hoặc bắt đầu code mà chưa quyết định "XÂY NHƯ THẾ NÀO".
BMAD không dùng một AI đa năng mà dùng các agent được cấu hình để đóng vai chuyên gia cụ thể: PM, Architect, Developer, UX Designer, Technical Writer. Mỗi agent có phong cách tư duy, ưu tiên, và workflow riêng.
BMAD được thiết kế để AI tự chủ trong phạm vi đã định nghĩa, chỉ đưa con người vào:
Ba nhánh lập kế hoạch với độ phức tạp tăng dần:
| Nhánh | Phù hợp với | Story ước tính |
|---|---|---|
| Quick Flow | Bug fix, tính năng nhỏ, phạm vi rõ | 1–15 stories |
| BMad Method | Sản phẩm, nền tảng, tính năng phức tạp | 10–50+ stories |
| Enterprise | Hệ thống tuân thủ, đa tenant, đa team | 30+ stories |
| Agent | Tên nhân vật | Skill ID | Vai trò |
|---|---|---|---|
| Analyst | Mary | bmad-analyst | Brainstorm, nghiên cứu thị trường/kỹ thuật, tạo Product Brief và PRFAQ |
| Product Manager | John | bmad-pm | Tạo và quản lý PRD, Epics, Stories, kiểm tra Implementation Readiness |
| Architect | Winston | bmad-architect | Thiết kế Architecture, ADR, kiểm tra Implementation Readiness |
| Developer | Amelia | bmad-agent-dev | Triển khai story, tạo test, code review, sprint planning |
| UX Designer | Sally | bmad-ux-designer | Thiết kế UX specification |
| Technical Writer | Paige | bmad-tech-writer | Viết tài liệu, cập nhật standards, giải thích khái niệm |
Qua Skill (Claude Code / Cursor):
bmad-analyst
bmad-pm
bmad-architect
bmad-agent-dev
Qua Trigger (sau khi đã nạp agent, gõ mã ngắn trong hội thoại):
| Trigger | Agent | Workflow |
|---|---|---|
BP | Analyst | Brainstorm |
CB | Analyst | Create Brief |
CP | PM | Create PRD |
VP | PM | Validate PRD |
EP | PM | Create Epics & Stories |
CA | Architect | Create Architecture |
IR | PM / Architect | Implementation Readiness |
SP | Developer | Sprint Planning |
DS | Developer | Dev Story |
QA | Developer | QA Test Generation |
CR | Developer | Code Review |
┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Giai đoạn 1 │ │ Giai đoạn 2 │ │ Giai đoạn 3 │ │ Giai đoạn 4 │
│ PHÂN TÍCH │───▶│ LẬP KẾ HOẠCH │───▶│ ĐỊNH HÌNH GIẢI │───▶│ TRIỂN KHAI │
│ (Tùy chọn) │ │ (Bắt buộc) │ │ PHÁP (BMad/Ent) │ │ (Bắt buộc) │
│ │ │ │ │ │ │ │
│ Brief, PRFAQ │ │ PRD, UX Spec │ │ Architecture, │ │ Sprint, Stories, │
│ Research │ │ │ │ Epics, Stories │ │ Code, Test, QA │
└─────────────────┘ └─────────────────┘ └──────────────────┘ └─────────────────┘
Giai đoạn này giúp khám phá và xác nhận ý tưởng trước khi cam kết lập kế hoạch chi tiết. Bỏ qua nếu yêu cầu đã rõ.
Các công cụ:
Brainstorming — Khi cần khai phá ý tưởng
Trigger: BP (trong agent Analyst)
Đầu ra: brainstorming-report.md
Sử dụng 60+ kỹ thuật brainstorming, tạo 100+ ý tưởng đa dạng, sau đó phân tích, lọc và đề xuất hướng tiếp cận.
Product Brief — Khi concept đã tương đối rõ
Trigger: CB (trong agent Analyst)
Đầu ra: product-brief.md
Tóm tắt điều hành 1–2 trang: vấn đề, giải pháp, đối tượng, lợi thế cạnh tranh, rủi ro.
PRFAQ — Khi cần stress-test concept
Trigger: (hỏi Analyst về PRFAQ)
Đầu ra: prfaq.md
Phương pháp "Working Backwards" của Amazon: viết thông cáo báo chí như thể sản phẩm đã tồn tại, sau đó trả lời các câu hỏi khó nhất từ khách hàng. Buộc phải rõ ràng theo hướng lấy khách hàng làm trung tâm.
Nghiên cứu — Xác thực giả định
Trigger: MR (Market Research), DR (Domain Research), TR (Technical Research)
Xác định rõ cần xây gì và cho ai.
Tạo PRD — PM Agent
Trigger: CP
Đầu ra: PRD.md
PRD bao gồm: mục tiêu sản phẩm, functional requirements (FR), non-functional requirements (NFR), user stories cấp cao, acceptance criteria.
Thiết kế UX — UX Designer Agent (Tùy chọn)
Trigger: CU
Đầu ra: ux-spec.md
Dùng khi UX/UI là yếu tố quan trọng. Bao gồm user flows, component specs, interaction patterns.
Validate PRD — PM Agent
Trigger: VP
Kiểm tra tính đầy đủ, nhất quán, và khả năng triển khai của PRD trước khi chuyển sang giai đoạn 3.
Quyết định xây như thế nào và phân rã công việc.
Tạo Architecture — Architect Agent
Trigger: CA
Đầu ra: architecture.md + ADR (Architecture Decision Records)
Bao gồm: tech stack, component design, data models, API contracts, deployment strategy, ADR cho các quyết định quan trọng.
Tạo Epics & Stories — PM Agent
Trigger: EP
Đầu ra: epics/ thư mục với các file story
Phân rã PRD và Architecture thành Epics (nhóm tính năng) và Stories (đơn vị công việc cụ thể). Mỗi story có: mô tả, acceptance criteria, technical notes.
Implementation Readiness Check — Architect Agent
Trigger: IR
Kết quả: PASS / CONCERNS / FAIL
Cổng kiểm tra trước khi bắt đầu triển khai. Đảm bảo mọi thứ đã đủ rõ ràng để developer có thể làm việc độc lập.
Xây dựng từng story một theo thứ tự ưu tiên.
Sprint Planning — Developer Agent
Trigger: SP
Đầu ra: sprint-status.yaml
Xác định stories sẽ làm trong sprint, thứ tự ưu tiên và tracking.
Dev Story — Developer Agent
Trigger: DS
Đầu ra: Code chạy được + unit/integration tests
Agent tự chủ triển khai story theo acceptance criteria. Đọc architecture và project-context để đảm bảo nhất quán.
Code Review — Developer Agent
Trigger: CR
Kết quả: Approved / Changes Requested
Review tự động: correctness, style, security, performance, test coverage.
QA Test Generation — Developer Agent
Trigger: QA
Đầu ra: API tests + E2E tests
Sinh test case cho API và E2E sau khi epic hoàn tất. Chi tiết ở Mục 7.
Correct Course — PM Agent
Trigger: CC
Xử lý thay đổi yêu cầu lớn giữa sprint mà không phá vỡ quy trình.
Retrospective — Developer Agent
Trigger: ER (Epic Retrospective)
Review sau khi hoàn tất một epic. Ghi lại bài học, pattern tốt, vấn đề gặp phải.
Khi nào dùng:
Bỏ qua: Giai đoạn 1, 2, 3 hoàn toàn
Dùng: Quick Dev (bmad-quick-dev)
Mô tả yêu cầu → Làm rõ ý định → Sinh spec → Triển khai → Review → Done
Quick Dev gộp tất cả vào một workflow: làm rõ yêu cầu, lập kế hoạch mini, triển khai, code review, và trình bày kết quả.
Khi nào dùng:
Đi qua: Giai đoạn 1 (tùy chọn) → 2 → 3 → 4
Khi nào dùng:
Thêm vào: Security review, DevOps pipeline, NFR assessment, Test Architect Module (TEA)
# Yêu cầu: Node.js 20+, Git
npx bmad-method install
Trình cài đặt sẽ hỏi:
bmad-help
Đây là điểm bắt đầu thông minh. Agent sẽ hỏi về dự án của bạn và dẫn bạn đến đúng workflow.
bmad-help Tôi có ý tưởng về ứng dụng SaaS quản lý task, bắt đầu từ đâu?
bmad-help Tôi cần thêm tính năng export PDF, dùng quick flow hay đầy đủ?
# Tạo tự động sau khi có architecture
bmad-generate-project-context
# Hoặc tạo thủ công
touch _bmad-output/project-context.md
File project-context.md là "bản hiến pháp" kỹ thuật của dự án — được tất cả agent tự động nạp:
# Project Context
## Technology Stack
- Node.js 20.x, TypeScript 5.3
- React 18.2, Zustand (không dùng Redux)
- PostgreSQL 15, Prisma ORM
- Testing: Vitest, Playwright, MSW
## Critical Implementation Rules
- Bật strict mode — không dùng `any`
- Dùng `interface` cho public API, `type` cho union/intersection
- API calls phải qua `apiClient` singleton
- Components đặt trong `/src/components/` với co-located tests
# Mở agent Analyst
bmad-analyst
# Trong hội thoại, gõ trigger:
BP # Brainstorm ý tưởng
CB # Tạo Product Brief
MR # Research thị trường
# Mở agent PM
bmad-pm
# Trigger tạo PRD
CP # Create PRD (có hướng dẫn từng bước)
VP # Validate PRD sau khi hoàn thiện
# Mở agent Architect
bmad-architect
# Trigger
CA # Create Architecture
IR # Implementation Readiness Check
# Mở agent PM
bmad-pm
# Trigger
EP # Create Epics and Stories
# Mở agent Developer
bmad-agent-dev
# Mỗi sprint
SP # Sprint Planning
DS # Dev Story (làm từng story)
CR # Code Review
QA # Tạo tests (sau khi epic hoàn tất)
ER # Epic Retrospective
# Chạy trong agent Developer hoặc Architect
bmad-generate-project-context
Agent sẽ khám phá codebase và tạo project-context.md từ:
package.json, pyproject.toml, hoặc build filesTạo hoặc cập nhật docs/index.md với:
bmad-quick-dev trực tiếp# Mở skill Quick Dev
bmad-quick-dev
# Mô tả yêu cầu, agent sẽ:
# 1. Làm rõ ý định (có người trong vòng lặp)
# 2. Tạo mini-spec nếu cần
# 3. Triển khai tự động
# 4. Code review
# 5. Trình bày kết quả để bạn approve
Ngày 1-2: Analysis
├── bmad-analyst → CB → product-brief.md
└── (tùy chọn) bmad-analyst → MR → market-research.md
Ngày 2-3: Planning
├── bmad-pm → CP → PRD.md
├── bmad-pm → VP (validate)
└── (nếu có UI) bmad-ux-designer → CU → ux-spec.md
Ngày 3-4: Solutioning
├── bmad-architect → CA → architecture.md
├── bmad-pm → EP → epics/ (stories)
└── bmad-architect → IR → PASS ✓
Ngày 5+: Implementation (lặp lại cho mỗi story)
├── bmad-agent-dev → SP → sprint-status.yaml
├── bmad-agent-dev → DS → code + tests
├── bmad-agent-dev → CR → approved
└── (sau epic) bmad-agent-dev → QA → e2e tests
BMAD cung cấp hai hướng tiếp cận kiểm thử:
Phù hợp với: Dự án nhỏ–trung bình, cần bao phủ test nhanh
Kích hoạt:
# Trong agent Developer
bmad-agent-dev
# Sau khi hoàn tất một epic (tất cả stories đã dev + review xong)
QA # QA Test Generation
5 bước workflow QA:
Các nguyên tắc khi sinh test:
// ✅ Dùng semantic locator
await page.getByRole('button', { name: 'Đăng nhập' }).click()
await page.getByLabel('Email').fill('[email protected]')
// ❌ Không dùng CSS selector cứng
await page.locator('.btn-primary#login').click()
// ✅ Test độc lập, không phụ thuộc thứ tự
test('create task', async () => {
// setup riêng cho test này
})
// ❌ Không hardcode wait/sleep
await page.waitForTimeout(3000) // Không làm thế này
Khi nào dùng:
Phù hợp với: Dự án lớn, miền nghiệp vụ phức tạp, cần truy vết yêu cầu
Cài đặt:
npx bmad-method install
# Chọn thêm module: TEA (Test Architect)
Agent TEA: Murat (Master Test Architect)
9 workflow của TEA:
| # | Workflow | Mục đích |
|---|---|---|
| 1 | Test Design | Tạo chiến lược kiểm thử gắn với yêu cầu (PRD/AC) |
| 2 | ATDD | Phát triển hướng Acceptance Test — viết test trước khi code |
| 3 | Automate | Tạo automated test với pattern nâng cao |
| 4 | Test Review | Kiểm tra chất lượng và độ bao phủ của bộ test |
| 5 | Traceability | Liên kết test ngược về yêu cầu trong PRD |
| 6 | NFR Assessment | Đánh giá yêu cầu phi chức năng (performance, security, reliability) |
| 7 | CI Setup | Cấu hình thực thi test trong CI/CD pipeline |
| 8 | Framework Scaffolding | Dựng hạ tầng test cho dự án mới |
| 9 | Release Gate | Ra quyết định go/no-go dựa trên chất lượng |
Hệ thống ưu tiên P0–P3:
| Mức | Ý nghĩa | Ví dụ |
|---|---|---|
| P0 | Critical — phải pass 100% | Thanh toán, xác thực, bảo mật |
| P1 | High — phải pass cho release | Core business flow |
| P2 | Medium — nên pass | Tính năng phụ, edge cases |
| P3 | Low — test khi có thể | UI detail, minor UX |
Luồng ATDD với TEA:
QC viết Acceptance Criteria (AC) →
TEA tạo test từ AC (trước khi code) →
Developer implement để test pass →
TEA verify traceability (AC ↔ test ↔ requirement) →
Release Gate go/no-go
| Yếu tố | QA tích hợp sẵn | Module TEA |
|---|---|---|
| Thời điểm test | Sau khi epic hoàn tất | Có thể trước khi code (ATDD) |
| Thiết lập | Không cần cài thêm | Cài module riêng |
| Loại test | API + E2E | API, E2E, ATDD, NFR, Performance |
| Truy vết yêu cầu | Không | Có (Traceability workflow) |
| Release gate | Không | Có (go/no-go) |
| Phù hợp nhất | Dự án nhỏ–trung bình | Dự án lớn, có compliance |
Story 1: Dev → Code Review → ✓
Story 2: Dev → Code Review → ✓
Story 3: Dev → Code Review → ✓
...
Epic hoàn tất → QA Test Generation → Tests pass → Epic Retrospective
Lưu ý: QA Test Generation chạy sau khi toàn bộ epic hoàn tất, không phải sau từng story. Mục đích là kiểm thử tích hợp các stories với nhau.
Ngoài QA workflow, Developer Agent còn hỗ trợ:
# Trong hội thoại với Developer Agent
bmad-review-edge-case-hunter
Phân tích toàn bộ nhánh điều kiện trong code để tìm:
bmad-party-mode
Triệu tập nhiều agent vào cùng một hội thoại để thảo luận các quyết định quan trọng:
bmad-advanced-elicitation
Buộc AI xem xét lại đầu ra bằng các phương pháp:
| Phương pháp | Mục đích |
|---|---|
| Pre-mortem | Giả sử thất bại → lần ngược nguyên nhân |
| First Principles | Loại bỏ giả định, bắt đầu từ sự thật cơ bản |
| Red Team / Blue Team | Tự tấn công, tự bảo vệ |
| Socratic Questioning | Chất vấn mọi khẳng định |
| Constraint Removal | Bỏ ràng buộc → thấy giải pháp khác |
| Stakeholder Mapping | Đánh giá từ góc nhìn từng bên liên quan |
Dùng sau khi có một tài liệu quan trọng (PRD, Architecture) để tìm điểm yếu trước khi tiếp tục.
bmad-review-adversarial-general
Review kiểu "devil's advocate" — giả định vấn đề luôn tồn tại:
bmad-distillator
Khi tài liệu quá lớn (PRD dài, Architecture phức tạp), Distillator nén nội dung tối ưu cho LLM mà không mất thông tin quan trọng.
bmad-shard-doc
Tách file markdown lớn thành các file phần nhỏ hơn, với index tự động.
Sau khi cài BMAD và chạy qua các giai đoạn, dự án sẽ có cấu trúc:
your-project/
├── _bmad/ # Cấu hình BMAD (không chỉnh sửa thủ công)
│ ├── core/ # Module core
│ └── bmm/ # Modules đã cài (TEA, v.v.)
│
├── _bmad-output/ # Tất cả artifacts sinh ra
│ ├── project-context.md # Bản hiến pháp kỹ thuật của dự án
│ ├── planning-artifacts/
│ │ ├── product-brief.md # Giai đoạn 1 output
│ │ ├── PRD.md # Giai đoạn 2 output
│ │ ├── ux-spec.md # Giai đoạn 2 output (nếu có)
│ │ ├── architecture.md # Giai đoạn 3 output
│ │ └── epics/ # Giai đoạn 3 output
│ │ ├── epic-1-auth/
│ │ │ ├── story-1-login.md
│ │ │ ├── story-2-register.md
│ │ │ └── story-3-reset-password.md
│ │ └── epic-2-dashboard/
│ └── implementation-artifacts/
│ └── sprint-status.yaml # Tracking sprint
│
├── .claude/skills/ # Skills cho Claude Code
│ ├── bmad-pm.md
│ ├── bmad-architect.md
│ └── ...
│
├── docs/ # Tài liệu dự án
│ └── index.md # Overview, goals, architecture notes
│
└── src/ # Source code dự án
Luôn bắt đầu một hội thoại mới khi chuyển sang workflow khác.
Mỗi workflow của BMAD thiết kế để chạy trong context rõ ràng. Việc tiếp tục hội thoại cũ có thể gây ra nhiễu context, đặc biệt với các workflow dài.
project-context.md trước khi bắt đầu sprintTất cả agent developer tự động nạp project-context.md. Đảm bảo file này luôn cập nhật với:
Nếu nhiều agent (hoặc developer) làm việc song song trên các stories khác nhau, kiến trúc phải được định nghĩa trước. Thiếu kiến trúc → các agent tạo ra code xung đột nhau.
bmad-help Tôi đang ở đâu trong workflow?
bmad-help Story này nên dùng Quick Flow hay Dev Story?
bmad-help Implementation Readiness check thất bại, làm gì tiếp?
Quick Dev vẫn có code review, vẫn tạo spec (mini), vẫn yêu cầu người approve kết quả. "Nhanh" ở đây là bỏ overhead lập kế hoạch không cần thiết, không phải bỏ qua chất lượng.
# .customize.yaml
agents:
bmad-agent-dev:
persona: "Senior developer theo hướng TDD, luôn viết test trước"
rules:
- "Mọi function public phải có unit test"
- "Không dùng any trong TypeScript"
❌ Sai: Test sau mỗi story ngay lập tức
✅ Đúng: Test sau khi toàn bộ epic hoàn tất (Dev + Code Review cho tất cả stories)
E2E test cần toàn bộ tính năng của epic để test integration. Test sớm hơn sẽ gặp dependency chưa sẵn sàng.
| Tài liệu | Đường dẫn |
|---|---|
| Getting Started | tutorials/getting-started.md |
| Danh sách Agents | reference/agents.md |
| Workflow Map | reference/workflow-map.md |
| Testing Reference | reference/testing.md |
| Core Tools | reference/core-tools.md |
| Modules | reference/modules.md |
| Dự án đã tồn tại | how-to/established-projects.md |
| Project Context | explanation/project-context.md |
| Quick Dev | explanation/quick-dev.md |
| Why Solutioning Matters | explanation/why-solutioning-matters.md |
| Cài đặt BMAD | how-to/install-bmad.md |
Tài liệu này được tổng hợp từ bản dịch tiếng Việt của BMAD Method Documentation. Cập nhật lần cuối: 2026-04-15.