docs(vi-vn): sync and update Vietnamese documentation
This commit is contained in:
miendinh
parent
87292cd86a
commit
e53170f034
|
|
@ -0,0 +1,826 @@
|
|||
---
|
||||
title: Hướng dẫn BMAD cho Developer
|
||||
description: Tài liệu tổng quan bằng tiếng Việt dành cho developer muốn áp dụng BMAD Method từ ý tưởng đến triển khai
|
||||
---
|
||||
|
||||
# BMAD Method — Hướng dẫn toàn diện cho Developer
|
||||
|
||||
> **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ả.
|
||||
|
||||
---
|
||||
|
||||
## Mục lục
|
||||
|
||||
1. [BMAD là gì?](#1-bmad-là-gì)
|
||||
2. [Nguyên lý cốt lõi](#2-nguyên-lý-cốt-lõi)
|
||||
3. [Kiến trúc hệ thống — Các Agent](#3-kiến-trúc-hệ-thống--các-agent)
|
||||
4. [Quy trình làm việc — 4 Giai đoạn](#4-quy-trình-làm-việc--4-giai-đoạn)
|
||||
5. [Chọn nhánh phù hợp](#5-chọn-nhánh-phù-hợp)
|
||||
6. [Hướng dẫn từng bước áp dụng BMAD](#6-hướng-dẫn-từng-bước-áp-dụng-bmad)
|
||||
7. [Kiểm thử với BMAD — Hướng dẫn cho QC](#7-kiểm-thử-với-bmad--hướng-dẫn-cho-qc)
|
||||
8. [Các công cụ hỗ trợ](#8-các-công-cụ-hỗ-trợ)
|
||||
9. [Cấu trúc thư mục dự án](#9-cấu-trúc-thư-mục-dự-án)
|
||||
10. [Mẹo và Best Practices](#10-mẹo-và-best-practices)
|
||||
|
||||
---
|
||||
|
||||
## 1. BMAD là gì?
|
||||
|
||||
**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ử.
|
||||
|
||||
### Điểm khác biệt so với cách dùng AI thông thường
|
||||
|
||||
| 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 |
|
||||
|
||||
### BMAD phù hợp với ai?
|
||||
|
||||
- **Developer** cần xây dựng tính năng nhanh, chất lượng cao
|
||||
- **Tech Lead / Architect** cần thiết kế hệ thống và phân rã công việc
|
||||
- **Product Manager** cần định nghĩa yêu cầu rõ ràng
|
||||
- **QC/Tester** cần sinh test case có truy vết yêu cầu
|
||||
- **Team nhỏ** muốn áp dụng quy trình chuẩn không cần nhiều overhead
|
||||
|
||||
---
|
||||
|
||||
## 2. Nguyên lý cốt lõi
|
||||
|
||||
### 2.1. Tài liệu là "ngôn ngữ chung" giữa con người và AI
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
### 2.2. Phân tách "XÂY GÌ" và "XÂY NHƯ THẾ NÀO"
|
||||
|
||||
BMAD tách bạch rõ ràng hai câu hỏi quan trọng nhất:
|
||||
|
||||
- **Planning (Giai đoạn 2)**: Trả lời **"XÂY GÌ và vì sao?"** → Đầu ra: PRD
|
||||
- **Solutioning (Giai đoạn 3)**: Trả lời **"XÂY NHƯ THẾ NÀO?"** → Đầu ra: Architecture + Epics/Stories
|
||||
|
||||
> Đâ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".
|
||||
|
||||
### 2.3. Agent chuyên biệt — mỗi vai trò một chuyên gia
|
||||
|
||||
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.
|
||||
|
||||
### 2.4. Con người chỉ tham gia tại các điểm kiểm tra quan trọng
|
||||
|
||||
BMAD được thiết kế để AI tự chủ trong phạm vi đã định nghĩa, chỉ đưa con người vào:
|
||||
|
||||
- Phê duyệt chuyển giai đoạn (PRD xong → Architect làm việc)
|
||||
- Review kết quả tổng thể (sau Dev Story, sau epic)
|
||||
- Quyết định thay đổi hướng (Correct Course)
|
||||
|
||||
### 2.5. Có thể mở rộng theo nhu cầu
|
||||
|
||||
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 |
|
||||
|
||||
---
|
||||
|
||||
## 3. Kiến trúc hệ thống — Các Agent
|
||||
|
||||
### 3.1. Các Agent chính
|
||||
|
||||
| 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 |
|
||||
|
||||
### 3.2. Cách gọi Agent
|
||||
|
||||
**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 |
|
||||
|
||||
---
|
||||
|
||||
## 4. Quy trình làm việc — 4 Giai đoạn
|
||||
|
||||
```
|
||||
┌─────────────────┐ ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
|
||||
│ 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 1: Phân tích (Tùy chọn)
|
||||
|
||||
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)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Giai đoạn 2: Lập kế hoạch (Bắt buộc)
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
### Giai đoạn 3: Định hình giải pháp (Bắt buộc với BMad Method / Enterprise)
|
||||
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
### Giai đoạn 4: Triển khai (Bắt buộc)
|
||||
|
||||
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](#7-kiểm-thử-với-bmad--hướng-dẫn-cho-qc).
|
||||
|
||||
**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.
|
||||
|
||||
---
|
||||
|
||||
## 5. Chọn nhánh phù hợp
|
||||
|
||||
### Quick Flow — Nhánh nhanh
|
||||
|
||||
**Khi nào dùng:**
|
||||
- Bug fix
|
||||
- Tính năng nhỏ, phạm vi rõ ràng
|
||||
- Cập nhật đơn lẻ (1–15 stories)
|
||||
- Bạn đã hiểu đầy đủ yêu cầu
|
||||
|
||||
**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ả.
|
||||
|
||||
---
|
||||
|
||||
### BMad Method — Nhánh đầy đủ
|
||||
|
||||
**Khi nào dùng:**
|
||||
- Sản phẩm mới hoặc nền tảng
|
||||
- Tính năng phức tạp với nhiều dependencies
|
||||
- 10–50+ stories cần phối hợp nhiều developer
|
||||
|
||||
**Đi qua:** Giai đoạn 1 (tùy chọn) → 2 → 3 → 4
|
||||
|
||||
---
|
||||
|
||||
### Enterprise — Nhánh mở rộng
|
||||
|
||||
**Khi nào dùng:**
|
||||
- Hệ thống đa tenant
|
||||
- Yêu cầu tuân thủ (compliance), security audit
|
||||
- 30+ stories, nhiều team
|
||||
- Cần truy vết yêu cầu đầy đủ
|
||||
|
||||
**Thêm vào:** Security review, DevOps pipeline, NFR assessment, Test Architect Module (TEA)
|
||||
|
||||
---
|
||||
|
||||
## 6. Hướng dẫn từng bước áp dụng BMAD
|
||||
|
||||
### 6.1. Dự án mới
|
||||
|
||||
#### Bước 1: Cài đặt BMAD
|
||||
|
||||
```bash
|
||||
# Yêu cầu: Node.js 20+, Git
|
||||
npx bmad-method install
|
||||
```
|
||||
|
||||
Trình cài đặt sẽ hỏi:
|
||||
- IDE đang dùng (Claude Code, Cursor, hoặc tương tự)
|
||||
- Modules muốn cài (core bắt buộc, thêm TEA nếu cần test nâng cao)
|
||||
- Nhánh lập kế hoạch (Quick Flow / BMad Method / Enterprise)
|
||||
|
||||
#### Bước 2: Khởi động với bmad-help
|
||||
|
||||
```
|
||||
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 đủ?
|
||||
```
|
||||
|
||||
#### Bước 3: Tạo Project Context (khuyến nghị mạnh)
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```markdown
|
||||
# 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
|
||||
```
|
||||
|
||||
#### Bước 4: Chạy Analysis (nếu cần)
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
#### Bước 5: Tạo PRD
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
#### Bước 6: Tạo Architecture (BMad Method / Enterprise)
|
||||
|
||||
```bash
|
||||
# Mở agent Architect
|
||||
bmad-architect
|
||||
|
||||
# Trigger
|
||||
CA # Create Architecture
|
||||
IR # Implementation Readiness Check
|
||||
```
|
||||
|
||||
#### Bước 7: Tạo Epics & Stories
|
||||
|
||||
```bash
|
||||
# Mở agent PM
|
||||
bmad-pm
|
||||
|
||||
# Trigger
|
||||
EP # Create Epics and Stories
|
||||
```
|
||||
|
||||
#### Bước 8: Triển khai theo Stories
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6.2. Dự án đã tồn tại
|
||||
|
||||
#### Bước 1: Tạo Project Context từ codebase hiện tại
|
||||
|
||||
```bash
|
||||
# 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 files
|
||||
- Cấu trúc thư mục
|
||||
- Conventions hiện có trong code
|
||||
|
||||
#### Bước 2: Tạo tài liệu index
|
||||
|
||||
Tạo hoặc cập nhật `docs/index.md` với:
|
||||
- Mục tiêu kinh doanh của dự án
|
||||
- Architecture overview
|
||||
- Các quy tắc quan trọng cần giữ
|
||||
|
||||
#### Bước 3: Chọn cách tiếp cận phù hợp
|
||||
|
||||
- **Thay đổi nhỏ** (bug fix, tính năng nhỏ): Dùng `bmad-quick-dev` trực tiếp
|
||||
- **Thay đổi lớn** (module mới, refactor lớn): Dùng BMad Method đầy đủ từ Giai đoạn 2
|
||||
|
||||
#### Bước 4: Quick Dev cho việc nhỏ
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 6.3. Luồng làm việc mẫu — Tính năng mới (BMad Method)
|
||||
|
||||
```
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Kiểm thử với BMAD — Hướng dẫn cho QC
|
||||
|
||||
BMAD cung cấp hai hướng tiếp cận kiểm thử:
|
||||
|
||||
### 7.1. QA tích hợp sẵn — Nhẹ nhàng (Developer Agent)
|
||||
|
||||
**Phù hợp với:** Dự án nhỏ–trung bình, cần bao phủ test nhanh
|
||||
|
||||
**Kích hoạt:**
|
||||
```bash
|
||||
# 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:**
|
||||
|
||||
1. **Phát hiện framework**: Agent tự nhận diện Jest, Vitest, Playwright, Cypress từ codebase
|
||||
2. **Xác định tính năng cần test**: Dựa vào stories và acceptance criteria của epic vừa hoàn tất
|
||||
3. **Tạo API tests**: Status codes, cấu trúc response, happy path, edge cases
|
||||
4. **Tạo E2E tests**: User workflows, semantic locators (role/label/text — không dùng CSS selector)
|
||||
5. **Chạy và xác minh**: Tự chạy tests, phát hiện và sửa lỗi ngay
|
||||
|
||||
**Các nguyên tắc khi sinh test:**
|
||||
|
||||
```typescript
|
||||
// ✅ Dùng semantic locator
|
||||
await page.getByRole('button', { name: 'Đăng nhập' }).click()
|
||||
await page.getByLabel('Email').fill('user@example.com')
|
||||
|
||||
// ❌ 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:**
|
||||
- Cần bao phủ test nhanh cho tính năng mới
|
||||
- Dự án nhỏ–trung bình không cần chiến lược kiểm thử nâng cao
|
||||
- Muốn tự động hóa kiểm thử mà không cần thiết lập phức tạp
|
||||
|
||||
---
|
||||
|
||||
### 7.2. Module Test Architect (TEA) — Nâng cao
|
||||
|
||||
**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:**
|
||||
```bash
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 7.3. So sánh hai hướng tiếp cận
|
||||
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
### 7.4. Vị trí kiểm thử trong vòng đời dự án
|
||||
|
||||
```
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
### 7.5. Edge Case Hunter — Công cụ tìm trường hợp biên
|
||||
|
||||
Ngoài QA workflow, Developer Agent còn hỗ trợ:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
- Trường hợp biên chưa được xử lý
|
||||
- Null/undefined checks bị thiếu
|
||||
- Điều kiện race condition
|
||||
- Input validation gaps
|
||||
|
||||
---
|
||||
|
||||
## 8. Các công cụ hỗ trợ
|
||||
|
||||
### 8.1. Party Mode — Thảo luận đa agent
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
- **Kiến trúc**: PM + Architect + Developer cùng đánh giá trade-off
|
||||
- **Tính năng phức tạp**: UX Designer + Architect + PM
|
||||
- **Post-mortem**: Tất cả agent cùng phân tích sự cố
|
||||
- **Sprint retrospective**: PM + Developer + QC
|
||||
|
||||
### 8.2. Advanced Elicitation — Tinh luyện đầu ra
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
### 8.3. Adversarial Review — Review hoài nghi
|
||||
|
||||
```bash
|
||||
bmad-review-adversarial-general
|
||||
```
|
||||
|
||||
Review kiểu "devil's advocate" — giả định vấn đề luôn tồn tại:
|
||||
- Phải tìm được tối thiểu 10 vấn đề
|
||||
- Tìm những gì **còn thiếu**, không chỉ những gì sai
|
||||
- Trực giao với Edge Case Hunter
|
||||
|
||||
### 8.4. Distillator — Nén tài liệu cho LLM
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
### 8.5. Shard Large Documents — Tách file lớn
|
||||
|
||||
```bash
|
||||
bmad-shard-doc
|
||||
```
|
||||
|
||||
Tách file markdown lớn thành các file phần nhỏ hơn, với index tự động.
|
||||
|
||||
---
|
||||
|
||||
## 9. Cấu trúc thư mục dự án
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. Mẹo và Best Practices
|
||||
|
||||
### Chat mới cho mỗi workflow
|
||||
|
||||
> 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.
|
||||
|
||||
### Đọc kỹ `project-context.md` trước khi bắt đầu sprint
|
||||
|
||||
Tấ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:
|
||||
- Tech stack và phiên bản chính xác
|
||||
- Quy tắc implementation quan trọng
|
||||
- Patterns đang dùng trong codebase
|
||||
|
||||
### Kiến trúc là bắt buộc khi có nhiều developer
|
||||
|
||||
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.
|
||||
|
||||
### Dùng bmad-help khi không chắc
|
||||
|
||||
```
|
||||
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 Flow không có nghĩa là không có chất lượng
|
||||
|
||||
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 agent theo nhu cầu team
|
||||
|
||||
```yaml
|
||||
# .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"
|
||||
```
|
||||
|
||||
### Vị trí QA trong workflow
|
||||
|
||||
```
|
||||
❌ 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 tham khảo
|
||||
|
||||
| Tài liệu | Đường dẫn |
|
||||
|---|---|
|
||||
| Getting Started | [tutorials/getting-started.md](tutorials/getting-started.md) |
|
||||
| Danh sách Agents | [reference/agents.md](reference/agents.md) |
|
||||
| Workflow Map | [reference/workflow-map.md](reference/workflow-map.md) |
|
||||
| Testing Reference | [reference/testing.md](reference/testing.md) |
|
||||
| Core Tools | [reference/core-tools.md](reference/core-tools.md) |
|
||||
| Modules | [reference/modules.md](reference/modules.md) |
|
||||
| Dự án đã tồn tại | [how-to/established-projects.md](how-to/established-projects.md) |
|
||||
| Project Context | [explanation/project-context.md](explanation/project-context.md) |
|
||||
| Quick Dev | [explanation/quick-dev.md](explanation/quick-dev.md) |
|
||||
| Why Solutioning Matters | [explanation/why-solutioning-matters.md](explanation/why-solutioning-matters.md) |
|
||||
| Cài đặt BMAD | [how-to/install-bmad.md](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.*
|
||||
|
|
@ -0,0 +1,92 @@
|
|||
---
|
||||
title: "Xem trước Checkpoint"
|
||||
description: Review có người trong vòng lặp với hỗ trợ của LLM, dẫn bạn đi qua thay đổi từ mục đích đến chi tiết
|
||||
sidebar:
|
||||
order: 3
|
||||
---
|
||||
|
||||
`bmad-checkpoint-preview` là một workflow review tương tác có người trong vòng lặp với hỗ trợ của LLM. Nó dẫn bạn đi qua một thay đổi mã nguồn, từ mục đích và bối cảnh đến các chi tiết quan trọng, để bạn có thể quyết định có nên phát hành, làm lại, hay đào sâu thêm.
|
||||
|
||||
|
||||
|
||||
## Luồng điển hình
|
||||
|
||||
Bạn chạy `bmad-quick-dev`. Nó làm rõ ý định của bạn, dựng spec, triển khai thay đổi, rồi khi xong sẽ nối thêm một review trail vào file spec và mở file đó trong editor. Bạn nhìn vào spec và thấy thay đổi này chạm tới 20 file, trải trên nhiều module.
|
||||
|
||||
Bạn có thể tự liếc diff. Nhưng khoảng 20 file là lúc cách đó bắt đầu kém hiệu quả: bạn mất mạch, bỏ sót liên hệ giữa hai thay đổi ở xa nhau, hoặc duyệt một thứ mà bạn chưa thực sự hiểu. Thay vì vậy, bạn nói "checkpoint" và LLM sẽ dẫn bạn đi qua thay đổi.
|
||||
|
||||
Điểm bàn giao đó, từ triển khai tự động quay lại phán đoán của con người, chính là tình huống sử dụng chính. Quick-dev có thể chạy khá lâu với rất ít giám sát. Checkpoint Preview là nơi bạn cầm lại tay lái.
|
||||
|
||||
## Vì sao nó tồn tại
|
||||
|
||||
Code review có hai kiểu thất bại. Kiểu đầu là người review lướt qua diff, không thấy gì nổi bật và bấm duyệt. Kiểu thứ hai là họ đọc rất kỹ từng file nhưng lại mất mạch tổng thể, thấy từng cái cây mà bỏ lỡ cả khu rừng. Cả hai đều dẫn tới cùng một kết quả: lần review đã không bắt được điều thực sự quan trọng.
|
||||
|
||||
Vấn đề cốt lõi nằm ở thứ tự tiếp nhận. Một raw diff trình bày thay đổi theo thứ tự file, gần như không bao giờ là thứ tự giúp xây dựng hiểu biết. Bạn thấy một helper function trước khi biết vì sao nó tồn tại. Bạn thấy một schema change trước khi hiểu tính năng nào đang dùng nó. Người review phải tự dựng lại ý đồ của tác giả từ những manh mối rời rạc, và chính ở bước dựng lại đó sự tập trung thường bị đứt.
|
||||
|
||||
Checkpoint Preview giải quyết việc này bằng cách để LLM làm phần dựng lại. Nó đọc diff, spec nếu có, và codebase xung quanh, rồi trình bày thay đổi theo một thứ tự phục vụ việc hiểu, chứ không theo `git diff`.
|
||||
|
||||
## Nó hoạt động như thế nào
|
||||
|
||||
Workflow này có năm bước. Mỗi bước xây trên bước trước, dần dần chuyển từ "đây là gì?" sang "chúng ta có nên phát hành nó không?"
|
||||
|
||||
### 1. Định hướng
|
||||
|
||||
Workflow xác định thay đổi đó là gì, từ PR, commit, branch, file spec, hoặc trạng thái git hiện tại, rồi tạo một câu tóm tắt ý định và vài số liệu bề mặt: số file thay đổi, số module bị chạm tới, số dòng logic, số lần băng qua ranh giới, và các public interface mới.
|
||||
|
||||
Đây là khoảnh khắc "đúng là thứ tôi đang nghĩ tới chứ?". Trước khi đọc mã, người review xác nhận mình đang nhìn đúng thay đổi và cân chỉnh kỳ vọng về phạm vi.
|
||||
|
||||
### 2. Dẫn giải thay đổi (Walkthrough)
|
||||
|
||||
Thay đổi được tổ chức theo **mối quan tâm** như validation đầu vào hay API contract, thay vì theo file. Mỗi mối quan tâm có một giải thích ngắn về *vì sao* cách tiếp cận này được chọn, kèm theo các điểm dừng `path:line` có thể bấm để người review đi theo xuyên suốt code.
|
||||
|
||||
Đây là bước dùng phán đoán về thiết kế. Người review đánh giá xem hướng tiếp cận có đúng với hệ thống hay không, chứ chưa phải xem code có chính xác tuyệt đối hay không. Các mối quan tâm được sắp từ trên xuống: ý định cấp cao trước, phần triển khai hỗ trợ sau. Người review sẽ không gặp tham chiếu tới thứ mà họ chưa thấy.
|
||||
|
||||
### 3. Soi chi tiết
|
||||
|
||||
Sau khi người review đã hiểu thiết kế, workflow sẽ đưa ra 2 đến 5 điểm mà nếu sai thì hậu quả lan rộng nhất. Chúng được gắn nhãn theo loại rủi ro như `[auth]`, `[schema]`, `[billing]`, `[public API]`, `[security]` và các nhãn khác, đồng thời được sắp theo mức độ thiệt hại nếu sai.
|
||||
|
||||
Đây không phải là một cuộc săn bug. Tính đúng đắn được CI và test tự động lo phần lớn. Bước soi chi tiết nhằm kích hoạt ý thức về rủi ro: "đây là những chỗ mà nếu sai thì cái giá phải trả cao nhất". Nếu muốn đào sâu một khu vực cụ thể, bạn có thể nói "đào sâu vào [khu vực]" để chạy một lần review lại tập trung vào tính đúng đắn.
|
||||
|
||||
Nếu spec trước đó đã đi qua các vòng adversarial review, các phát hiện liên quan cũng được đưa ra ở đây. Không phải các bug đã được sửa, mà là những quyết định mà vòng review đó từng gắn cờ để người review hiện tại biết.
|
||||
|
||||
### 4. Kiểm thử
|
||||
|
||||
Workflow gợi ý 2 đến 5 cách quan sát thủ công để thấy thay đổi thực sự hoạt động. Không phải lệnh test tự động, mà là các quan sát tay giúp tăng niềm tin theo cách test suite không cho bạn được. Một tương tác UI để thử, một lệnh CLI để chạy, một request API để gửi, kèm kết quả kỳ vọng cho từng mục.
|
||||
|
||||
Nếu thay đổi không có hành vi nào nhìn thấy được từ phía người dùng, workflow sẽ nói thẳng như vậy. Không bịa thêm việc cho có.
|
||||
|
||||
### 5. Kết thúc
|
||||
|
||||
Người review đưa ra quyết định: duyệt, làm lại, hay tiếp tục thảo luận. Nếu đang duyệt PR, workflow có thể hỗ trợ với `gh pr review --approve`. Nếu cần làm lại, nó sẽ giúp chẩn đoán vấn đề nằm ở cách tiếp cận, spec, hay phần triển khai, đồng thời hỗ trợ soạn phản hồi có thể hành động được và gắn với vị trí code cụ thể.
|
||||
|
||||
## Đây là một cuộc hội thoại, không phải bản báo cáo
|
||||
|
||||
Workflow trình bày từng bước như một điểm khởi đầu, không phải lời kết luận cuối cùng. Giữa các bước, hoặc ngay giữa một bước, bạn có thể trao đổi với LLM, hỏi thêm, phản biện cách nó đóng khung vấn đề, hoặc kéo thêm skill khác để lấy một góc nhìn khác:
|
||||
|
||||
- **"run advanced elicitation on the error handling"** - ép LLM xem xét lại và tinh chỉnh phân tích cho một khu vực cụ thể
|
||||
- **"party mode on whether this schema migration is safe"** - kéo nhiều góc nhìn agent vào một cuộc tranh luận tập trung
|
||||
- **"run code review"** - tạo ra các phát hiện có cấu trúc với phân tích đối kháng và edge case
|
||||
|
||||
Workflow checkpoint không khóa bạn vào một đường đi tuyến tính. Nó cho bạn cấu trúc khi bạn cần, và tránh cản đường khi bạn muốn tự khám phá. Năm bước ở đây để bảo đảm bạn nhìn được toàn cảnh, còn việc đi sâu đến mức nào ở mỗi bước và gọi thêm công cụ nào hoàn toàn là do bạn quyết định.
|
||||
|
||||
## Lộ trình review (Review Trail)
|
||||
|
||||
Bước dẫn giải thay đổi hoạt động tốt nhất khi nó có một **thứ tự review gợi ý (Suggested Review Order)**, tức một danh sách các điểm dừng do tác giả spec viết ra để dẫn người review đi qua thay đổi. Nếu spec có phần này, workflow sẽ dùng trực tiếp.
|
||||
|
||||
Nếu không có review trail do tác giả tạo, workflow sẽ tự sinh một trail từ diff và bối cảnh codebase. Trail do máy sinh ra vẫn kém hơn trail do tác giả viết, nhưng vẫn tốt hơn rất nhiều so với việc đọc thay đổi theo thứ tự file.
|
||||
|
||||
## Khi nào nên dùng
|
||||
|
||||
Tình huống chính là bước bàn giao sau `bmad-quick-dev`: phần triển khai đã xong, file spec đang mở trong editor với review trail đã được nối thêm, và bạn cần quyết định có nên phát hành hay không. Lúc đó chỉ cần nói "checkpoint" là bắt đầu.
|
||||
|
||||
Nó cũng hoạt động độc lập:
|
||||
|
||||
- **Review một PR** - đặc biệt hữu ích khi PR có nhiều hơn vài file hoặc có thay đổi cắt ngang nhiều khu vực
|
||||
- **Làm quen với một thay đổi (onboard to a change)** - khi bạn cần hiểu chuyện gì đã xảy ra trên một branch mà bạn không phải người viết
|
||||
- **Review sprint (sprint review)** - workflow có thể nhặt các story được đánh dấu `review` trong file trạng thái sprint của bạn
|
||||
|
||||
Bạn có thể gọi nó bằng cách nói "checkpoint" hoặc "dẫn tôi đi qua thay đổi này". Nó chạy được trong mọi terminal, nhưng sẽ phát huy tốt nhất trong IDE như VS Code, Cursor hoặc công cụ tương tự, vì workflow tạo tham chiếu `path:line` ở mọi bước. Trong terminal tích hợp của IDE, các tham chiếu đó có thể bấm được, nên bạn có thể nhảy qua lại giữa các file khi đi theo review trail.
|
||||
|
||||
## Nó không phải là gì
|
||||
|
||||
Checkpoint Preview không thay thế review tự động. Nó không chạy linter, type checker, hay test suite. Nó không chấm mức độ nghiêm trọng hay đưa ra kết luận pass/fail. Nó là một bản hướng dẫn đọc để giúp con người áp dụng phán đoán của mình vào đúng những chỗ đáng chú ý nhất.
|
||||
|
|
@ -0,0 +1,94 @@
|
|||
---
|
||||
title: "Agent có tên riêng (Named Agents)"
|
||||
description: Vì sao các agent của BMad có tên, persona và bề mặt tùy chỉnh riêng, và điều đó mở khóa điều gì so với cách tiếp cận dựa trên menu hoặc prompt trống
|
||||
sidebar:
|
||||
order: 1
|
||||
---
|
||||
|
||||
Bạn nói: "Hey Mary, brainstorm với tôi nhé", và Mary được kích hoạt. Cô ấy chào bạn theo tên, bằng ngôn ngữ bạn đã cấu hình, với persona đặc trưng của riêng mình. Cô ấy nhắc rằng `bmad-help` luôn sẵn sàng. Rồi cô ấy bỏ qua menu và đi thẳng vào brainstorming vì ý định của bạn đã đủ rõ.
|
||||
|
||||
Trang này giải thích điều gì thực sự đang diễn ra và vì sao BMad được thiết kế theo cách đó.
|
||||
|
||||
## Chiếc ghế ba chân
|
||||
|
||||
Mô hình agent của BMad đứng trên ba primitive kết hợp với nhau:
|
||||
|
||||
| Thành phần nền (primitive) | Nó cung cấp gì | Nó nằm ở đâu |
|
||||
|---|---|---|
|
||||
| **Skill** | Năng lực, tức một việc rời rạc mà assistant có thể làm như brainstorming, viết PRD hay triển khai story | `.claude/skills/{skill-name}/SKILL.md` hoặc vị trí tương đương theo IDE |
|
||||
| **Named agent** | Tính liên tục của persona, tức một danh tính dễ nhận ra bọc quanh một nhóm skill có cùng giọng điệu, nguyên tắc và dấu hiệu nhận biết | Các skill có thư mục bắt đầu bằng `bmad-agent-*` |
|
||||
| **Customization** | Khả năng biến nó thành của riêng bạn: override để đổi hành vi của agent, thêm tích hợp MCP, thay template, chồng convention của tổ chức | `_bmad/custom/{skill-name}.toml` cho team và `.user.toml` cho cá nhân |
|
||||
|
||||
Chỉ cần bỏ đi một chân là trải nghiệm sẽ sụp:
|
||||
|
||||
- Skill mà không có agent sẽ thành danh sách khả năng mà người dùng phải tự nhớ tên hoặc mã
|
||||
- Agent mà không có skill sẽ chỉ là persona không có gì để làm
|
||||
- Không có customization thì mọi người đều nhận cùng một hành vi mặc định, và muốn thêm convention nội bộ là phải fork
|
||||
|
||||
## Named agents mang lại điều gì
|
||||
|
||||
BMad hiện có sáu named agent, mỗi agent gắn với một phase trong BMad Method:
|
||||
|
||||
| Agent | Phase | Module |
|
||||
|---|---|---|
|
||||
| 📊 **Mary**, Chuyên viên phân tích nghiệp vụ (Business Analyst) | Analysis | market research, brainstorming, product briefs, PRFAQs |
|
||||
| 📚 **Paige**, Technical Writer | Analysis | project documentation, diagrams, doc validation |
|
||||
| 📋 **John**, Quản lý sản phẩm (Product Manager) | Planning | PRD creation, epic/story breakdown, implementation readiness |
|
||||
| 🎨 **Sally**, Nhà thiết kế UX (UX Designer) | Planning | UX design specifications |
|
||||
| 🏗️ **Winston**, Kiến trúc sư hệ thống (System Architect) | Solutioning | technical architecture, alignment checks |
|
||||
| 💻 **Amelia**, Kỹ sư cấp cao (Senior Engineer) | Implementation | story execution, quick-dev, code review, sprint planning |
|
||||
|
||||
Mỗi agent có một danh tính hardcode gồm tên, chức danh, domain, và một lớp có thể tùy chỉnh gồm vai trò, nguyên tắc, phong cách giao tiếp, icon và menu. Bạn có thể viết lại nguyên tắc của Mary hoặc thêm menu item cho cô ấy, nhưng bạn không thể đổi tên cô ấy. Đó là chủ ý thiết kế. Nhận diện thương hiệu của agent phải sống sót qua lớp tùy chỉnh để câu "hey Mary" luôn kích hoạt đúng analyst, bất kể team đã nắn hành vi của cô ấy theo cách nào.
|
||||
|
||||
## Luồng kích hoạt
|
||||
|
||||
Khi bạn gọi một named agent, tám bước sau sẽ chạy theo thứ tự:
|
||||
|
||||
1. **Resolve cấu hình agent**: merge `customize.toml` gốc với override của team và cá nhân qua một Python resolver dùng `tomllib`
|
||||
2. **Chạy các bước tiền xử lý (prepend steps)**: mọi hành vi pre-flight mà team đã cấu hình
|
||||
3. **Nhập persona**: danh tính hardcode cộng với vai trò, phong cách giao tiếp và nguyên tắc đã tùy chỉnh
|
||||
4. **Nạp persistent facts**: quy tắc tổ chức, ghi chú compliance, hoặc cả file được nạp qua tiền tố `file:`
|
||||
5. **Nạp config**: tên người dùng, ngôn ngữ giao tiếp, ngôn ngữ đầu ra, đường dẫn artifact
|
||||
6. **Chào người dùng**: lời chào cá nhân hóa, đúng ngôn ngữ cấu hình và có emoji prefix của agent để bạn nhìn là biết ai đang nói
|
||||
7. **Chạy các bước hậu xử lý (append steps)**: mọi bước thiết lập sau lời chào mà team đã cấu hình
|
||||
8. **Dispatch hoặc hiện menu**: nếu tin nhắn mở đầu của bạn khớp một menu item thì agent đi thẳng vào đó, nếu không thì hiện menu và chờ input
|
||||
|
||||
Bước 8 là nơi ý định gặp năng lực. Câu "Hey Mary, brainstorm với tôi nhé" bỏ qua phần render menu vì `bmad-brainstorming` là một mapping quá rõ với mục `BP` trong menu của Mary. Nếu bạn nói mơ hồ, cô ấy chỉ hỏi lại một lần, ngắn gọn, chứ không biến xác nhận thành nghi thức. Nếu chẳng có mục nào phù hợp, cô ấy tiếp tục cuộc hội thoại như bình thường.
|
||||
|
||||
## Vì sao không chỉ dùng menu
|
||||
|
||||
Menu buộc người dùng phải chủ động học công cụ. Bạn phải nhớ brainstorming nằm dưới mã `BP` của analyst chứ không phải PM, và phải nhớ persona nào sở hữu nhóm khả năng nào. Toàn bộ gánh nặng nhận thức đó do công cụ đẩy sang cho người dùng.
|
||||
|
||||
Named agents đảo ngược điều đó. Bạn chỉ cần nói điều mình muốn, với đúng người mình nghĩ tới, bằng ngôn từ tự nhiên. Agent biết họ là ai và họ làm gì. Khi ý định của bạn đủ rõ, họ chỉ việc bắt đầu.
|
||||
|
||||
Menu vẫn còn đó như một phương án dự phòng, hiện ra khi bạn đang khám phá, và biến mất khi bạn không cần nó.
|
||||
|
||||
## Vì sao không chỉ dùng prompt trống
|
||||
|
||||
Prompt trống giả định rằng bạn biết "câu thần chú". "Giúp tôi brainstorm" có thể hiệu quả, nhưng "hãy ideate giúp tôi một ý tưởng SaaS" có thể cho kết quả khác, và đầu ra phụ thuộc khá nhiều vào cách bạn diễn đạt. Khi đó người dùng gần như phải kiêm luôn vai trò kỹ sư prompt (prompt engineer).
|
||||
|
||||
Named agents thêm cấu trúc mà không đóng mất sự tự do. Persona giữ ổn định, năng lực thì dễ khám phá, và `bmad-help` luôn chỉ cách bạn một lệnh. Bạn không phải đoán agent làm được gì, nhưng cũng không cần học thuộc một cuốn manual để dùng nó.
|
||||
|
||||
## Tùy chỉnh là công dân hạng nhất
|
||||
|
||||
Chính mô hình customization làm cho cách tiếp cận này mở rộng được ra ngoài phạm vi của một lập trình viên đơn lẻ.
|
||||
|
||||
Mỗi agent đi kèm một `customize.toml` với mặc định hợp lý. Team có thể commit override vào `_bmad/custom/bmad-agent-{role}.toml`. Mỗi cá nhân có thể chồng thêm sở thích riêng trong `.user.toml` bị gitignore. Resolver sẽ merge cả ba lớp tại thời điểm kích hoạt theo các quy tắc có tính dự đoán.
|
||||
|
||||
Đa số người dùng không cần tự tay viết các file đó. Skill `bmad-customize` sẽ dẫn họ qua việc chọn đúng mục tiêu, quyết định override ở mức agent hay workflow, viết file và xác minh merge. Nhờ vậy bề mặt tùy chỉnh vẫn tiếp cận được với bất cứ ai hiểu ý định của mình, chứ không chỉ người rành TOML.
|
||||
|
||||
Ví dụ cụ thể: một team commit một file yêu cầu Amelia luôn dùng Context7 MCP tool khi tra tài liệu thư viện, và fallback sang Linear nếu story không xuất hiện trong danh sách epic cục bộ. Từ đó mọi dev workflow mà Amelia dispatch như `dev-story`, `quick-dev`, `create-story`, `code-review` đều tự động thừa hưởng hành vi này mà không cần sửa source hay lặp lại cấu hình từng workflow.
|
||||
|
||||
Ngoài ra còn có một bề mặt tùy chỉnh thứ hai cho các mối quan tâm *xuyên suốt*: `_bmad/config.toml`, `_bmad/config.user.toml`, `_bmad/custom/config.toml` và `_bmad/custom/config.user.toml`. Đây là nơi **agent roster** sống, tức các descriptor gọn nhẹ mà những skill như `bmad-party-mode`, `bmad-retrospective` và `bmad-advanced-elicitation` dùng để biết ai có mặt và phải nhập vai họ thế nào. Bạn có thể rebrand một agent cho cả tổ chức bằng team override, hoặc thêm những giọng hư cấu như Kirk, Spock hay một persona chuyên gia domain qua `.user.toml`, tất cả mà không cần đụng vào thư mục skill. File per-skill quyết định Mary *hành xử* như thế nào khi cô ấy kích hoạt; cấu hình trung tâm quyết định các skill khác *nhìn thấy* cô ấy ra sao khi quan sát toàn bộ đội hình.
|
||||
|
||||
Để xem toàn bộ bề mặt tùy chỉnh và ví dụ thực tế:
|
||||
|
||||
- [Cách tùy chỉnh BMad](../how-to/customize-bmad.md): tài liệu tham chiếu cho những gì có thể tùy chỉnh và merge diễn ra thế nào
|
||||
- [Cách mở rộng BMad cho tổ chức của bạn](../how-to/expand-bmad-for-your-org.md): năm recipe hoàn chỉnh trải từ quy tắc ở cấp agent, convention workflow, publish ra hệ thống ngoài, thay template đầu ra đến tùy chỉnh roster agent
|
||||
- Skill `bmad-customize`: trợ lý soạn cấu hình (authoring helper) có hướng dẫn để biến ý định thành một file override đúng chỗ và đã được kiểm chứng
|
||||
|
||||
## Ý tưởng lớn hơn phía sau
|
||||
|
||||
Hầu hết các trợ lý AI (AI assistant) ngày nay hoặc là menu, hoặc là prompt, và cả hai đều chuyển phần gánh nặng nhận thức sang người dùng. Agent có tên riêng kết hợp với skill có thể tùy chỉnh cho phép bạn trò chuyện với một đồng đội đã hiểu công việc, đồng thời cho phép tổ chức của bạn nắn đồng đội đó theo nhu cầu mà không cần fork.
|
||||
|
||||
Lần tới khi bạn gõ "Hey Mary, brainstorm với tôi nhé" và cô ấy chỉ việc bắt tay vào làm, hãy để ý thứ đã *không* xảy ra. Không có slash command. Không có menu phải điều hướng. Không có lời nhắc gượng gạo về những gì cô ấy có thể làm. Chính sự vắng mặt đó mới là thiết kế.
|
||||
|
|
@ -1,171 +1,395 @@
|
|||
---
|
||||
title: "Cách tùy chỉnh BMad"
|
||||
description: Tùy chỉnh agent, workflow và module trong khi vẫn giữ khả năng tương thích khi cập nhật
|
||||
title: 'Cách tùy chỉnh BMad'
|
||||
description: Tùy chỉnh agent và workflow trong khi vẫn giữ khả năng tương thích khi cập nhật
|
||||
sidebar:
|
||||
order: 7
|
||||
order: 8
|
||||
---
|
||||
|
||||
Sử dụng các tệp `.customize.yaml` để điều chỉnh hành vi, persona và menu của agent, đồng thời giữ lại thay đổi của bạn qua các lần cập nhật.
|
||||
Điều chỉnh persona của agent, chèn ngữ cảnh theo domain, thêm khả năng mới và cấu hình hành vi workflow mà không cần sửa các file đã cài. Các tùy chỉnh của bạn sẽ được giữ nguyên qua mọi lần cập nhật.
|
||||
|
||||
:::tip[Không muốn tự viết TOML? Hãy dùng `bmad-customize`]
|
||||
Skill `bmad-customize` là trợ lý tạo cấu hình có hướng dẫn cho **bề mặt override agent/workflow theo từng skill** được mô tả trong tài liệu này. Nó quét những gì có thể tùy chỉnh trong bản cài đặt của bạn, giúp bạn chọn đúng bề mặt (agent hay workflow), ghi file override và xác minh merge đã áp dụng. Override ở mức cấu hình trung tâm (`_bmad/custom/config.toml`) chưa nằm trong phạm vi v1, nên phần đó vẫn cần viết tay theo mục Cấu hình trung tâm bên dưới. Hãy chạy skill này khi bạn muốn thay đổi theo từng skill; tài liệu này là phần tham chiếu cho *có thể tùy chỉnh gì* và merge hoạt động ra sao.
|
||||
:::
|
||||
|
||||
## Khi nào nên dùng
|
||||
|
||||
- Bạn muốn thay đổi tên, tính cách hoặc phong cách giao tiếp của một agent
|
||||
- Bạn cần agent ghi nhớ bối cảnh riêng của dự án
|
||||
- Bạn muốn thêm các mục menu tùy chỉnh để kích hoạt workflow hoặc prompt của riêng mình
|
||||
- Bạn muốn agent luôn thực hiện một số hành động cụ thể mỗi khi khởi động
|
||||
- Bạn muốn thay đổi tính cách hoặc phong cách giao tiếp của agent
|
||||
- Bạn cần cung cấp cho agent các "persistent facts" để luôn nhớ, ví dụ "tổ chức của chúng tôi chỉ dùng AWS"
|
||||
- Bạn muốn thêm các bước khởi động có tính thủ tục mà agent phải chạy mỗi phiên
|
||||
- Bạn muốn thêm menu item tùy chỉnh để gọi skill hoặc prompt riêng
|
||||
- Team của bạn cần các tùy chỉnh dùng chung được commit vào git, đồng thời vẫn cho phép mỗi cá nhân chồng thêm sở thích riêng
|
||||
|
||||
:::note[Điều kiện tiên quyết]
|
||||
|
||||
- BMad đã được cài trong dự án của bạn (xem [Cách cài đặt BMad](./install-bmad.md))
|
||||
- Trình soạn thảo văn bản để chỉnh sửa tệp YAML
|
||||
- Python 3.11+ có trên PATH của bạn (để chạy resolver; dùng stdlib `tomllib`, không cần `pip install`, `uv` hay virtualenv)
|
||||
- Một trình soạn thảo văn bản cho file TOML
|
||||
:::
|
||||
|
||||
:::caution[Giữ an toàn cho các tùy chỉnh của bạn]
|
||||
Luôn sử dụng các tệp `.customize.yaml` được mô tả trong tài liệu này thay vì sửa trực tiếp tệp agent. Trình cài đặt sẽ ghi đè các tệp agent khi cập nhật, nhưng vẫn giữ nguyên các thay đổi trong `.customize.yaml`.
|
||||
:::
|
||||
## Cách hoạt động
|
||||
|
||||
Mỗi skill có thể tùy chỉnh đều đi kèm một file `customize.toml` chứa cấu hình mặc định. File này định nghĩa toàn bộ bề mặt tùy chỉnh của skill, nên hãy đọc nó để biết có thể chỉnh gì. Bạn **không bao giờ** sửa trực tiếp file này. Thay vào đó, bạn tạo các file override dạng thưa, chỉ chứa những trường bạn muốn đổi.
|
||||
|
||||
### Mô hình override ba lớp
|
||||
|
||||
```text
|
||||
Ưu tiên 1 (thắng): _bmad/custom/{skill-name}.user.toml (cá nhân, bị gitignore)
|
||||
Ưu tiên 2: _bmad/custom/{skill-name}.toml (team/tổ chức, được commit)
|
||||
Ưu tiên 3 (gốc): customize.toml của chính skill (mặc định)
|
||||
```
|
||||
|
||||
Thư mục `_bmad/custom/` ban đầu là rỗng. File chỉ xuất hiện khi ai đó thực sự bắt đầu tùy chỉnh.
|
||||
|
||||
### Quy tắc merge theo hình dạng, không theo tên trường
|
||||
|
||||
Resolver áp dụng bốn quy tắc cấu trúc. Tên trường không được hardcode riêng; hành vi hoàn toàn được quyết định bởi dạng dữ liệu:
|
||||
|
||||
| Dạng | Quy tắc |
|
||||
|---|---|
|
||||
| Scalar (string, int, bool, float) | Giá trị override sẽ thắng |
|
||||
| Table | Deep merge, tức merge đệ quy theo các quy tắc này |
|
||||
| Mảng các table mà mọi phần tử đều dùng cùng **một** trường định danh (`code` ở tất cả phần tử, hoặc `id` ở tất cả phần tử) | Merge theo khóa đó, phần tử trùng khóa sẽ **thay tại chỗ**, phần tử mới sẽ **append** |
|
||||
| Mọi mảng khác (mảng scalar, table không có định danh, hoặc trộn `code` và `id`) | **Append**: phần tử gốc trước, rồi team, rồi user |
|
||||
|
||||
**Không có cơ chế xóa.** Override không thể xóa phần tử mặc định. Nếu bạn cần vô hiệu hóa một menu item mặc định, hãy override nó theo `code` bằng mô tả hoặc prompt no-op. Nếu cần tái cấu trúc mảng sâu hơn, bạn phải fork skill.
|
||||
|
||||
**Quy ước `code` / `id`.** BMad dùng `code` (định danh ngắn như `"BP"` hoặc `"R1"`) và `id` (định danh ổn định dài hơn) làm merge key cho mảng các table. Nếu bạn tự tạo một mảng table muốn có khả năng replace-by-key thay vì append-only, hãy chọn **một** quy ước duy nhất và dùng nhất quán cho toàn bộ mảng. Nếu trộn `code` ở phần tử này và `id` ở phần tử khác, resolver sẽ rơi về chế độ append vì nó không đoán merge theo khóa nào.
|
||||
|
||||
### Một số trường của agent là chỉ đọc
|
||||
|
||||
`agent.name` và `agent.title` vẫn nằm trong `customize.toml` như metadata nguồn gốc, nhưng `SKILL.md` của agent không đọc hai trường này ở runtime, vì danh tính của agent được hardcode. Bạn đặt `name = "Bob"` trong file override cũng sẽ không có tác dụng. Nếu bạn thật sự cần một agent với tên khác, hãy copy thư mục skill, đổi tên và phát hành nó như một custom skill.
|
||||
|
||||
## Các bước thực hiện
|
||||
|
||||
### 1. Xác định vị trí các tệp tùy chỉnh
|
||||
### 1. Tìm bề mặt tùy chỉnh của skill
|
||||
|
||||
Sau khi cài đặt, bạn sẽ tìm thấy một tệp `.customize.yaml` cho mỗi agent tại:
|
||||
Hãy mở file `customize.toml` trong thư mục skill đã được cài. Ví dụ với PM agent:
|
||||
|
||||
```text
|
||||
_bmad/_config/agents/
|
||||
├── core-bmad-master.customize.yaml
|
||||
├── bmm-dev.customize.yaml
|
||||
├── bmm-pm.customize.yaml
|
||||
└── ... (một tệp cho mỗi agent đã cài)
|
||||
.claude/skills/bmad-agent-pm/customize.toml
|
||||
```
|
||||
|
||||
### 2. Chỉnh sửa tệp tùy chỉnh
|
||||
(Đường dẫn cụ thể thay đổi theo IDE: Cursor dùng `.cursor/skills/`, Cline dùng `.cline/skills/`, v.v.)
|
||||
|
||||
Mở tệp `.customize.yaml` của agent mà bạn muốn sửa. Mỗi phần đều là tùy chọn, chỉ tùy chỉnh những gì bạn cần.
|
||||
Đây là schema chính thức. Mọi trường bạn nhìn thấy trong file này đều có thể tùy chỉnh, ngoại trừ các trường danh tính chỉ đọc đã nêu ở trên.
|
||||
|
||||
| Phần | Cách hoạt động | Mục đích |
|
||||
| --- | --- | --- |
|
||||
| `agent.metadata` | Thay thế | Ghi đè tên hiển thị của agent |
|
||||
| `persona` | Thay thế | Đặt vai trò, danh tính, phong cách và các nguyên tắc |
|
||||
| `memories` | Nối thêm | Thêm bối cảnh cố định mà agent luôn ghi nhớ |
|
||||
| `menu` | Nối thêm | Thêm mục menu tùy chỉnh cho workflow hoặc prompt |
|
||||
| `critical_actions` | Nối thêm | Định nghĩa hướng dẫn khởi động cho agent |
|
||||
| `prompts` | Nối thêm | Tạo các prompt tái sử dụng cho các hành động trong menu |
|
||||
### 2. Tạo file override của bạn
|
||||
|
||||
Những phần được đánh dấu **Thay thế** sẽ ghi đè hoàn toàn cấu hình mặc định của agent. Những phần được đánh dấu **Nối thêm** sẽ bổ sung vào cấu hình hiện có.
|
||||
Tạo thư mục `_bmad/custom/` ở root dự án nếu nó chưa tồn tại. Sau đó tạo file đặt theo tên skill:
|
||||
|
||||
**Tên agent**
|
||||
|
||||
Thay đổi cách agent tự giới thiệu:
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
name: 'Spongebob' # Mặc định: "Amelia"
|
||||
```text
|
||||
_bmad/custom/
|
||||
bmad-agent-pm.toml # override của team (commit vào git)
|
||||
bmad-agent-pm.user.toml # sở thích cá nhân (gitignore)
|
||||
```
|
||||
|
||||
**Persona**
|
||||
:::caution[KHÔNG copy nguyên file `customize.toml`]
|
||||
File override phải **thưa**. Chỉ đưa vào những trường bạn thực sự muốn đổi, không hơn.
|
||||
|
||||
Thay thế tính cách, vai trò và phong cách giao tiếp của agent:
|
||||
Mọi trường bạn bỏ qua sẽ tự động được kế thừa từ lớp bên dưới. Nếu bạn copy toàn bộ `customize.toml` vào file override, những bản cập nhật sau này sẽ không chảy vào các giá trị mặc định mới nữa và bạn sẽ âm thầm bị lệch qua mỗi release.
|
||||
:::
|
||||
|
||||
```yaml
|
||||
persona:
|
||||
role: 'Senior Full-Stack Engineer'
|
||||
identity: 'Sống trong quả dứa (dưới đáy biển)'
|
||||
communication_style: 'Spongebob gây phiền'
|
||||
principles:
|
||||
- 'Không lồng quá sâu, dev Spongebob ghét nesting quá 2 cấp'
|
||||
- 'Ưu tiên composition hơn inheritance'
|
||||
**Ví dụ: đổi icon và thêm một principle**
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-agent-pm.toml
|
||||
# Chỉ ghi những trường cần đổi. Phần còn lại vẫn kế thừa.
|
||||
|
||||
[agent]
|
||||
icon = "🏥"
|
||||
principles = [
|
||||
"Không phát hành bất cứ thứ gì không thể vượt qua kiểm toán của FDA.",
|
||||
]
|
||||
```
|
||||
|
||||
Phần `persona` sẽ thay thế toàn bộ persona mặc định, vì vậy nếu đặt phần này bạn nên cung cấp đầy đủ cả bốn trường.
|
||||
Ví dụ này append thêm principle mới vào danh sách mặc định và thay icon. Mọi trường khác vẫn giữ nguyên như bản gốc.
|
||||
|
||||
**Memories**
|
||||
### 3. Tùy chỉnh đúng phần bạn cần
|
||||
|
||||
Thêm bối cảnh cố định mà agent sẽ luôn nhớ:
|
||||
Mọi ví dụ bên dưới đều giả định schema agent phẳng của BMad. Các trường nằm trực tiếp trong `[agent]`, không có các sub-table như `metadata` hay `persona`.
|
||||
|
||||
```yaml
|
||||
memories:
|
||||
- 'Làm việc tại Krusty Krab'
|
||||
- 'Người nổi tiếng yêu thích: David Hasselhoff'
|
||||
- 'Đã học ở Epic 1 rằng giả vờ test đã pass là không ổn'
|
||||
**Scalar (`icon`, `role`, `identity`, `communication_style`).** Scalar override sẽ thắng, nên bạn chỉ cần đặt những trường đang muốn đổi:
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-agent-pm.toml
|
||||
|
||||
[agent]
|
||||
icon = "🏥"
|
||||
role = "Dẫn dắt product discovery cho domain healthcare có ràng buộc pháp lý."
|
||||
communication_style = "Chính xác, nhạy với compliance, đặt các câu hỏi mang hình dạng kiểm soát ngay từ sớm."
|
||||
```
|
||||
|
||||
**Mục menu**
|
||||
**Persistent facts, principles, activation hooks (các mảng append).** Bốn mảng dưới đây đều là append-only. Phần tử của team được thêm sau mặc định, phần tử user được thêm cuối cùng.
|
||||
|
||||
Thêm các mục tùy chỉnh vào menu hiển thị của agent. Mỗi mục cần có `trigger`, đích đến (`workflow` hoặc `action`) và `description`:
|
||||
```toml
|
||||
[agent]
|
||||
# Các fact tĩnh mà agent luôn giữ trong đầu trong cả phiên: quy tắc tổ chức,
|
||||
# hằng số domain, sở thích của người dùng. Khác với runtime memory sidecar.
|
||||
#
|
||||
# Mỗi mục có thể là một câu literal, hoặc tham chiếu `file:` để nạp nội dung
|
||||
# file làm facts (hỗ trợ cả glob).
|
||||
persistent_facts = [
|
||||
"Tổ chức của chúng tôi chỉ dùng AWS, không đề xuất GCP hay Azure.",
|
||||
"Mọi PRD đều phải có legal sign-off trước khi engineering kickoff.",
|
||||
"Người dùng mục tiêu là bác sĩ lâm sàng, không phải bệnh nhân, nên ví dụ phải bám theo đối tượng đó.",
|
||||
"file:{project-root}/docs/compliance/hipaa-overview.md",
|
||||
"file:{project-root}/_bmad/custom/company-glossary.md",
|
||||
]
|
||||
|
||||
```yaml
|
||||
menu:
|
||||
- trigger: my-workflow
|
||||
workflow: 'my-custom/workflows/my-workflow.yaml'
|
||||
description: Workflow tùy chỉnh của tôi
|
||||
- trigger: deploy
|
||||
action: '#deploy-prompt'
|
||||
description: Triển khai lên production
|
||||
# Thêm vào hệ giá trị của agent
|
||||
principles = [
|
||||
"Không phát hành bất cứ thứ gì không thể vượt qua kiểm toán của FDA.",
|
||||
"Giá trị người dùng là trước hết, compliance là luôn luôn.",
|
||||
]
|
||||
|
||||
# Chạy TRƯỚC activation tiêu chuẩn (persona, persistent_facts, config, greet).
|
||||
# Dùng cho pre-flight load, compliance checks, hoặc thứ gì cần có sẵn trong
|
||||
# context trước khi agent tự giới thiệu.
|
||||
activation_steps_prepend = [
|
||||
"Quét {project-root}/docs/compliance/ và nạp mọi tài liệu liên quan HIPAA vào context.",
|
||||
]
|
||||
|
||||
# Chạy SAU khi greet, TRƯỚC menu. Dùng cho thiết lập nặng về context mà bạn
|
||||
# muốn chạy sau khi người dùng đã được chào.
|
||||
activation_steps_append = [
|
||||
"Đọc {project-root}/_bmad/custom/company-glossary.md nếu file tồn tại.",
|
||||
]
|
||||
```
|
||||
|
||||
**Critical Actions**
|
||||
**Hai hook này có vai trò khác nhau.** `prepend` chạy trước lời chào để agent có thể nạp ngữ cảnh cần thiết ngay cả khi cá nhân hóa lời chào. `append` chạy sau lời chào để người dùng không phải nhìn màn hình trống trong lúc agent quét một lượng lớn context.
|
||||
|
||||
Định nghĩa các hướng dẫn sẽ chạy khi agent khởi động:
|
||||
**Tùy chỉnh menu (merge theo `code`).** Menu là một mảng table. Mỗi item có trường `code`, nên resolver merge theo mã này: item có `code` trùng sẽ thay tại chỗ, item mới sẽ được append.
|
||||
|
||||
```yaml
|
||||
critical_actions:
|
||||
- 'Kiểm tra pipeline CI bằng XYZ Skill và cảnh báo người dùng ngay khi khởi động nếu có việc khẩn cấp cần xử lý'
|
||||
Với TOML array-of-tables, mỗi item dùng cú pháp `[[agent.menu]]`:
|
||||
|
||||
```toml
|
||||
# Thay item CE hiện có bằng một custom skill
|
||||
[[agent.menu]]
|
||||
code = "CE"
|
||||
description = "Tạo Epic theo framework delivery của tổ chức"
|
||||
skill = "custom-create-epics"
|
||||
|
||||
# Thêm item mới (RC chưa tồn tại trong mặc định)
|
||||
[[agent.menu]]
|
||||
code = "RC"
|
||||
description = "Chạy compliance pre-check"
|
||||
prompt = """
|
||||
Đọc {project-root}/_bmad/custom/compliance-checklist.md
|
||||
và quét toàn bộ tài liệu trong {planning_artifacts} theo checklist đó.
|
||||
Báo cáo mọi khoảng trống và trích dẫn điều khoản quy định tương ứng.
|
||||
"""
|
||||
```
|
||||
|
||||
**Prompt tùy chỉnh**
|
||||
Mỗi menu item chỉ có đúng một trong hai trường `skill` hoặc `prompt`. Những item không xuất hiện trong file override của bạn sẽ giữ nguyên mặc định.
|
||||
|
||||
Tạo các prompt tái sử dụng để mục menu có thể tham chiếu bằng `action="#id"`:
|
||||
**Tham chiếu file.** Khi một trường văn bản cần trỏ tới file (trong `persistent_facts`, `activation_steps_prepend`, `activation_steps_append`, hoặc `prompt` của menu item), hãy dùng đường dẫn đầy đủ dựa trên `{project-root}`. Dù file nằm cạnh override trong `_bmad/custom/`, bạn vẫn nên viết rõ là `{project-root}/_bmad/custom/info.md`. Agent sẽ resolve `{project-root}` ở runtime.
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: deploy-prompt
|
||||
content: |
|
||||
Triển khai nhánh hiện tại lên production:
|
||||
1. Chạy toàn bộ test
|
||||
2. Build dự án
|
||||
3. Thực thi script triển khai
|
||||
### 4. Cá nhân và team
|
||||
|
||||
**File của team** (`bmad-agent-pm.toml`): commit vào git, áp dụng cho cả tổ chức. Dùng cho compliance rules, company persona, năng lực tùy chỉnh dùng chung.
|
||||
|
||||
**File cá nhân** (`bmad-agent-pm.user.toml`): tự động bị gitignore. Dùng cho điều chỉnh giọng điệu, sở thích workflow cá nhân và các fact riêng mà agent cần lưu ý cho riêng bạn.
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-agent-pm.user.toml
|
||||
|
||||
[agent]
|
||||
persistent_facts = [
|
||||
"Khi trình bày phương án, luôn kèm ước lượng độ phức tạp ở mức thô (low/medium/high).",
|
||||
]
|
||||
```
|
||||
|
||||
### 3. Áp dụng thay đổi
|
||||
## Cách quá trình resolve diễn ra
|
||||
|
||||
Sau khi chỉnh sửa, cài đặt lại để áp dụng thay đổi:
|
||||
Khi agent được kích hoạt, `SKILL.md` của nó sẽ gọi một shared Python script để merge ba lớp nói trên và trả về block kết quả ở dạng JSON. Script này dùng `tomllib` của Python stdlib, nên `python3` thuần là đủ:
|
||||
|
||||
```bash
|
||||
npx bmad-method install
|
||||
python3 {project-root}/_bmad/scripts/resolve_customization.py \
|
||||
--skill {skill-root} \
|
||||
--key agent
|
||||
```
|
||||
|
||||
Trình cài đặt sẽ nhận diện bản cài đặt hiện có và đưa ra các lựa chọn sau:
|
||||
**Yêu cầu**: Python 3.11+ vì các phiên bản cũ hơn không có `tomllib`. Không cần `pip install`, không cần `uv`, không cần virtualenv. Bạn có thể kiểm tra bằng `python3 --version`. Trên một số nền tảng, `python3` mặc định vẫn là 3.10 hoặc thấp hơn, nên có thể bạn sẽ phải cài 3.11+ riêng.
|
||||
|
||||
| Lựa chọn | Tác dụng |
|
||||
| --- | --- |
|
||||
| **Quick Update** | Cập nhật tất cả module lên phiên bản mới nhất và áp dụng các tùy chỉnh |
|
||||
| **Modify BMad Installation** | Chạy lại quy trình cài đặt đầy đủ để thêm hoặc gỡ bỏ module |
|
||||
`--skill` trỏ vào thư mục skill đã cài, nơi có file `customize.toml`. Tên skill được lấy từ basename của thư mục, sau đó script sẽ tự tìm `_bmad/custom/{skill-name}.toml` và `{skill-name}.user.toml`.
|
||||
|
||||
Nếu chỉ thay đổi phần tùy chỉnh, **Quick Update** là lựa chọn nhanh nhất.
|
||||
Một số lệnh hữu ích:
|
||||
|
||||
## Khắc phục sự cố
|
||||
```bash
|
||||
# Resolve toàn bộ block agent
|
||||
python3 {project-root}/_bmad/scripts/resolve_customization.py \
|
||||
--skill /duong-dan/tuyet-doi/toi/bmad-agent-pm \
|
||||
--key agent
|
||||
|
||||
**Thay đổi không xuất hiện?**
|
||||
# Resolve một trường cụ thể
|
||||
python3 {project-root}/_bmad/scripts/resolve_customization.py \
|
||||
--skill /duong-dan/tuyet-doi/toi/bmad-agent-pm \
|
||||
--key agent.icon
|
||||
|
||||
- Chạy `npx bmad-method install` và chọn **Quick Update** để áp dụng thay đổi
|
||||
- Kiểm tra YAML có hợp lệ không (thụt lề rất quan trọng)
|
||||
- Xác minh bạn đã sửa đúng tệp `.customize.yaml` của agent cần thiết
|
||||
# Dump toàn bộ
|
||||
python3 {project-root}/_bmad/scripts/resolve_customization.py \
|
||||
--skill /duong-dan/tuyet-doi/toi/bmad-agent-pm
|
||||
```
|
||||
|
||||
**Agent không tải lên được?**
|
||||
|
||||
- Kiểm tra lỗi cú pháp YAML bằng một công cụ kiểm tra YAML trực tuyến
|
||||
- Đảm bảo bạn không để trống trường nào sau khi bỏ comment
|
||||
- Thử khôi phục mẫu gốc rồi build lại
|
||||
|
||||
**Cần đặt lại một agent?**
|
||||
|
||||
- Xóa nội dung hoặc xóa tệp `.customize.yaml` của agent đó
|
||||
- Chạy `npx bmad-method install` và chọn **Quick Update** để khôi phục mặc định
|
||||
Đầu ra luôn là JSON. Nếu script này không khả dụng trên một nền tảng nào đó, `SKILL.md` sẽ hướng dẫn agent đọc trực tiếp ba file TOML và áp dụng cùng các quy tắc merge.
|
||||
|
||||
## Tùy chỉnh workflow
|
||||
|
||||
Tài liệu về cách tùy chỉnh các workflow và skill sẵn có trong BMad Method sẽ được bổ sung trong thời gian tới.
|
||||
Workflow, tức các skill điều phối tiến trình nhiều bước như `bmad-product-brief`, dùng cùng cơ chế override như agent. Khác biệt là bề mặt tùy chỉnh của chúng nằm dưới `[workflow]` thay vì `[agent]`:
|
||||
|
||||
## Tùy chỉnh module
|
||||
```toml
|
||||
# _bmad/custom/bmad-product-brief.toml
|
||||
|
||||
Hướng dẫn xây dựng expansion module và tùy chỉnh các module hiện có sẽ được bổ sung trong thời gian tới.
|
||||
[workflow]
|
||||
# Giống agent: prepend/append chạy trước và sau activation mặc định của
|
||||
# workflow. Override sẽ append vào mặc định.
|
||||
activation_steps_prepend = [
|
||||
"Nạp {project-root}/docs/product/north-star-principles.md làm context.",
|
||||
]
|
||||
|
||||
activation_steps_append = []
|
||||
|
||||
# Cũng dùng semantics literal-hoặc-file: như phía agent. Những fact này được
|
||||
# nạp làm context nền tảng trong suốt lần chạy workflow.
|
||||
persistent_facts = [
|
||||
"Mọi brief đều phải có một mục explicit về regulatory risk.",
|
||||
"file:{project-root}/docs/compliance/product-brief-checklist.md",
|
||||
]
|
||||
|
||||
# Scalar: chạy đúng một lần khi workflow hoàn tất output chính. Override thắng.
|
||||
on_complete = "Tóm tắt brief trong ba gạch đầu dòng rồi hỏi người dùng có muốn gửi email qua skill gws-gmail-send không."
|
||||
```
|
||||
|
||||
Cùng một quy ước trường có thể đi xuyên qua ranh giới agent/workflow: `activation_steps_prepend`, `activation_steps_append`, `persistent_facts` với tham chiếu `file:`, và các table kiểu menu `[[...]]` dùng `code` hoặc `id` làm khóa merge. Resolver áp dụng đúng bốn quy tắc cấu trúc đã nêu bất kể top-level key là gì. Tham chiếu từ `SKILL.md` cũng theo namespace tương ứng: `{workflow.activation_steps_prepend}`, `{workflow.persistent_facts}`, `{workflow.on_complete}`. Mọi trường bổ sung mà một workflow tự expose, ví dụ output path, toggle, review setting hay stage flag, cũng sẽ đi theo cùng cơ chế merge dựa trên shape. Muốn biết chính xác workflow đó cho chỉnh gì, hãy đọc `customize.toml` của nó.
|
||||
|
||||
### Thứ tự activation
|
||||
|
||||
Workflow có thể tùy chỉnh sẽ chạy activation theo thứ tự cố định để bạn biết hook của mình được kích hoạt khi nào:
|
||||
|
||||
1. Resolve block `[workflow]` bằng merge base -> team -> user
|
||||
2. Chạy `activation_steps_prepend` theo đúng thứ tự
|
||||
3. Nạp `persistent_facts` làm ngữ cảnh nền tảng cho cả lần chạy
|
||||
4. Nạp config (`_bmad/bmm/config.yaml`) và resolve các biến chuẩn như tên dự án, ngôn ngữ, đường dẫn, ngày tháng
|
||||
5. Chào người dùng
|
||||
6. Chạy `activation_steps_append` theo đúng thứ tự
|
||||
|
||||
Sau bước 6, phần thân chính của workflow mới bắt đầu. Hãy dùng `activation_steps_prepend` khi bạn cần load context trước cả lúc cá nhân hóa lời chào; dùng `activation_steps_append` khi phần thiết lập khá nặng và bạn muốn người dùng thấy lời chào trước.
|
||||
|
||||
### Phạm vi của đợt triển khai đầu tiên này
|
||||
|
||||
Khả năng tùy chỉnh đang được mở rộng dần. Những trường đã mô tả ở trên, gồm `activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete`, là **bề mặt nền tảng** mà mọi workflow có thể tùy chỉnh đều sẽ hỗ trợ, và chúng sẽ ổn định qua các phiên bản. Ngày hôm nay, chỉ với những trường này bạn đã có thể kiểm soát những điểm lớn: thêm bước trước/sau, ghim context nền tảng, kích hoạt hành động tiếp theo sau khi workflow hoàn tất.
|
||||
|
||||
Theo thời gian, từng workflow sẽ expose thêm **các điểm tùy chỉnh chuyên biệt hơn** gắn với chính công việc của workflow đó, ví dụ toggle ở từng bước, stage flag, đường dẫn template đầu ra hoặc review gate. Khi những trường đó xuất hiện, chúng sẽ được chồng thêm lên bề mặt nền tảng chứ không thay thế nó, nên những tùy chỉnh bạn viết hôm nay vẫn tiếp tục dùng được.
|
||||
|
||||
Nếu bạn đang cần một "núm tinh chỉnh" chi tiết hơn nhưng workflow chưa expose, hãy tạm dùng `activation_steps_*` và `persistent_facts` để điều hướng hành vi, hoặc mở issue mô tả chính xác điểm tùy chỉnh bạn muốn. Chính những nhu cầu đó sẽ quyết định trường nào được bổ sung tiếp theo.
|
||||
|
||||
## Cấu hình trung tâm
|
||||
|
||||
`customize.toml` theo từng skill bao phủ **hành vi sâu** như hook, menu, `persistent_facts`, override persona cho một agent hay workflow đơn lẻ. Một bề mặt khác sẽ bao phủ **trạng thái cắt ngang** như các câu trả lời lúc cài đặt và roster agent mà những skill bên ngoài như `bmad-party-mode`, `bmad-retrospective` và `bmad-advanced-elicitation` sử dụng. Bề mặt đó nằm trong bốn file TOML ở root dự án:
|
||||
|
||||
```text
|
||||
_bmad/config.toml (do installer quản lý) team scope: câu trả lời lúc cài đặt + agent roster
|
||||
_bmad/config.user.toml (do installer quản lý) user scope: user_name, language, skill level
|
||||
_bmad/custom/config.toml (do con người viết) team overrides (commit vào git)
|
||||
_bmad/custom/config.user.toml (do con người viết) personal overrides (gitignore)
|
||||
```
|
||||
|
||||
### Merge bốn lớp
|
||||
|
||||
```text
|
||||
Ưu tiên 1 (thắng): _bmad/custom/config.user.toml
|
||||
Ưu tiên 2: _bmad/custom/config.toml
|
||||
Ưu tiên 3: _bmad/config.user.toml
|
||||
Ưu tiên 4 (gốc): _bmad/config.toml
|
||||
```
|
||||
|
||||
Các quy tắc cấu trúc hoàn toàn giống phần per-skill customize: scalar override, table deep-merge, mảng dùng `code` hoặc `id` sẽ merge theo khóa, các mảng khác thì append.
|
||||
|
||||
### Cái gì nằm ở đâu
|
||||
|
||||
Installer sẽ phân chia câu trả lời theo `scope:` khai báo trên từng prompt trong `module.yaml`:
|
||||
|
||||
- Các section `[core]` và `[modules.<code>]`: chứa câu trả lời khi cài. `scope = team` sẽ được ghi vào `_bmad/config.toml`; `scope = user` sẽ nằm trong `_bmad/config.user.toml`
|
||||
- Section `[agents.<code>]`: "bản chất" của agent gồm code, name, title, icon, description, team, được chưng cất từ khối `agents:` trong `module.yaml` của từng module. Phần này luôn ở scope team
|
||||
|
||||
### Quy tắc chỉnh sửa
|
||||
|
||||
- `_bmad/config.toml` và `_bmad/config.user.toml` sẽ **được tạo lại sau mỗi lần cài đặt** từ những câu trả lời mà installer thu thập. Hãy coi chúng là output chỉ đọc; mọi chỉnh sửa trực tiếp sẽ bị ghi đè ở lần cài tiếp theo. Nếu muốn thay đổi bền vững một giá trị cài đặt, hãy chạy lại installer hoặc chồng giá trị đó bằng `_bmad/custom/config.toml`
|
||||
- `_bmad/custom/config.toml` và `_bmad/custom/config.user.toml` sẽ **không bao giờ** bị installer động vào. Đây mới là bề mặt đúng để thêm custom agent, override descriptor của agent, ép các thiết lập dùng chung cho team và ghim mọi giá trị bạn muốn giữ nguyên bất kể câu trả lời lúc cài là gì
|
||||
|
||||
### Ví dụ: đổi thương hiệu cho một agent
|
||||
|
||||
```toml
|
||||
# _bmad/custom/config.toml (commit vào git, áp dụng cho mọi developer)
|
||||
|
||||
[agents.bmad-agent-pm]
|
||||
description = "PM trong domain healthcare, nhạy với compliance, luôn đặt câu hỏi theo hướng FDA ngay từ đầu."
|
||||
icon = "🏥"
|
||||
```
|
||||
|
||||
Resolver sẽ merge đè lên `[agents.bmad-agent-pm]` do installer sinh ra. `bmad-party-mode` và mọi roster consumer khác sẽ tự động thấy description mới này.
|
||||
|
||||
### Ví dụ: thêm một agent hư cấu
|
||||
|
||||
```toml
|
||||
# _bmad/custom/config.user.toml (cá nhân, gitignore)
|
||||
|
||||
[agents.kirk]
|
||||
team = "startrek"
|
||||
name = "Captain James T. Kirk"
|
||||
title = "Starship Captain"
|
||||
icon = "🖖"
|
||||
description = "Một chỉ huy táo bạo, thích bẻ luật. Nói chuyện có các quãng ngắt đầy kịch tính. Suy nghĩ thành tiếng về gánh nặng của quyền chỉ huy."
|
||||
```
|
||||
|
||||
Không cần tạo thư mục skill. Chỉ riêng "essence" này cũng đủ để party-mode spawn Kirk như một giọng nói trong cuộc bàn tròn. Bạn có thể lọc theo trường `team` để chỉ mời nhóm Enterprise.
|
||||
|
||||
### Ví dụ: override thiết lập cài đặt của module
|
||||
|
||||
```toml
|
||||
# _bmad/custom/config.toml
|
||||
|
||||
[modules.bmm]
|
||||
planning_artifacts = "/shared/org-planning-artifacts"
|
||||
```
|
||||
|
||||
Giá trị override này sẽ thắng mọi câu trả lời mà từng developer đã nhập khi cài trên máy của họ. Rất hữu ích khi bạn muốn ghim convention của cả team.
|
||||
|
||||
### Khi nào dùng bề mặt nào
|
||||
|
||||
| Nhu cầu | Bề mặt nên dùng |
|
||||
|---|---|
|
||||
| Thêm lời nhắc gọi MCP tool vào mọi dev workflow | Theo từng skill: `_bmad/custom/bmad-agent-dev.toml` trong `persistent_facts` |
|
||||
| Thêm menu item cho một agent | Theo từng skill: `_bmad/custom/bmad-agent-{role}.toml` với `[[agent.menu]]` |
|
||||
| Đổi template đầu ra của một workflow | Theo từng skill: `_bmad/custom/{workflow}.toml` bằng scalar override |
|
||||
| Đổi descriptor công khai của một agent | **Cấu hình trung tâm**: `_bmad/custom/config.toml` ở `[agents.<code>]` |
|
||||
| Thêm custom agent hoặc agent hư cấu vào roster | **Cấu hình trung tâm**: `_bmad/custom/config*.toml` với entry mới `[agents.<code>]` |
|
||||
| Ghim thiết lập cài đặt dùng chung của team | **Cấu hình trung tâm**: `_bmad/custom/config.toml` trong `[modules.<code>]` hoặc `[core]` |
|
||||
|
||||
Trong cùng một dự án, bạn hoàn toàn có thể dùng đồng thời cả hai bề mặt này.
|
||||
|
||||
## Ví dụ thực chiến
|
||||
|
||||
Để xem các recipe thiên về doanh nghiệp như định hình một agent trên mọi workflow mà nó dispatch, ép workflow tuân thủ convention nội bộ, publish output lên Confluence và Jira, tùy chỉnh agent roster, hoặc thay template đầu ra bằng template riêng của tổ chức, hãy xem [Cách mở rộng BMad cho tổ chức của bạn](./expand-bmad-for-your-org.md).
|
||||
|
||||
## Khắc phục sự cố
|
||||
|
||||
**Tùy chỉnh không xuất hiện?**
|
||||
|
||||
- Kiểm tra file của bạn có nằm đúng trong `_bmad/custom/` và dùng đúng tên skill không
|
||||
- Kiểm tra cú pháp TOML: string phải có ngoặc kép, table header dùng `[section]`, array-of-tables dùng `[[section]]`, và mọi khóa scalar hay array của một table phải xuất hiện *trước* bất kỳ `[[subtables]]` nào của table đó trong file
|
||||
- Với agent, phần tùy chỉnh phải nằm dưới `[agent]`, và các trường bên dưới header đó sẽ thuộc `agent` cho tới khi bạn mở table header khác
|
||||
- Hãy nhớ rằng `agent.name` và `agent.title` là chỉ đọc, override vào đó sẽ không có tác dụng
|
||||
|
||||
**Tùy chỉnh bị hỏng sau khi update?**
|
||||
|
||||
- Bạn có copy nguyên file `customize.toml` vào file override không? **Đừng làm vậy.** File override chỉ nên chứa phần chênh lệch. Nếu copy nguyên file, bạn sẽ khóa cứng mặc định cũ và dần lệch khỏi các bản phát hành mới.
|
||||
|
||||
**Muốn biết có thể tùy chỉnh gì?**
|
||||
|
||||
- Chạy skill `bmad-customize`. Nó sẽ liệt kê mọi skill có thể tùy chỉnh trong dự án, cho biết skill nào đã có override, rồi dẫn bạn qua quá trình thêm hoặc sửa một override
|
||||
- Hoặc đọc trực tiếp `customize.toml` của skill. Mọi trường ở đó đều có thể tùy chỉnh, trừ `name` và `title`
|
||||
|
||||
**Muốn reset?**
|
||||
|
||||
- Xóa file override của bạn trong `_bmad/custom/`, skill sẽ tự động rơi về cấu hình mặc định tích hợp sẵn
|
||||
|
|
|
|||
|
|
@ -0,0 +1,266 @@
|
|||
---
|
||||
title: 'Cách mở rộng BMad cho tổ chức của bạn'
|
||||
description: Năm mẫu tùy chỉnh giúp thay đổi BMad mà không cần fork, gồm quy tắc ở cấp agent, quy ước workflow, xuất bản ra hệ thống ngoài, thay template và điều chỉnh danh sách agent
|
||||
sidebar:
|
||||
order: 9
|
||||
---
|
||||
|
||||
Bề mặt tùy chỉnh của BMad cho phép một tổ chức định hình lại hành vi mà không phải sửa file đã cài hay fork skill. Hướng dẫn này trình bày năm công thức mẫu (recipe) bao phủ phần lớn nhu cầu ở môi trường doanh nghiệp.
|
||||
|
||||
:::note[Điều kiện tiên quyết]
|
||||
|
||||
- BMad đã được cài trong dự án của bạn (xem [Cách cài đặt BMad](./install-bmad.md))
|
||||
- Đã quen với mô hình tùy chỉnh (xem [Cách tùy chỉnh BMad](./customize-bmad.md))
|
||||
- Python 3.11+ có trên PATH để chạy resolver, chỉ dùng stdlib, không cần `pip install`
|
||||
:::
|
||||
|
||||
:::tip[Cách áp dụng các công thức mẫu này]
|
||||
Những **công thức mẫu theo từng skill** bên dưới, tức Recipe 1 đến Recipe 4, có thể được áp dụng bằng cách chạy skill `bmad-customize` rồi mô tả ý định. Skill này sẽ tự chọn đúng bề mặt, viết file override và xác minh kết quả merge. Riêng Recipe 5, tức override cấu hình trung tâm để chỉnh danh sách agent (agent roster), hiện chưa nằm trong phạm vi v1 của skill nên vẫn cần viết tay. Các recipe trong trang này là nguồn sự thật cho phần *nên override cái gì*; `bmad-customize` phụ trách phần *thực hiện ra sao* ở lớp agent/workflow.
|
||||
:::
|
||||
|
||||
## Mô hình ba lớp để suy nghĩ
|
||||
|
||||
Trước khi chọn recipe, bạn cần biết override của mình sẽ rơi vào đâu:
|
||||
|
||||
| Lớp | Nơi override sống | Phạm vi |
|
||||
|---|---|---|
|
||||
| **Agent** như Amelia, Mary, John | section `[agent]` trong `_bmad/custom/bmad-agent-{role}.toml` | Đi cùng persona vào **mọi workflow mà agent đó dispatch** |
|
||||
| **Workflow** như `product-brief`, `create-prd` | section `[workflow]` trong `_bmad/custom/{workflow-name}.toml` | Chỉ áp dụng cho lần chạy của workflow đó |
|
||||
| **Cấu hình trung tâm** | `[agents.*]`, `[core]`, `[modules.*]` trong `_bmad/custom/config.toml` | Agent roster và các thiết lập lúc cài đặt cần ghim cho cả tổ chức |
|
||||
|
||||
Nguyên tắc ngón tay cái:
|
||||
|
||||
- Nếu quy tắc nên áp dụng ở mọi nơi một engineer làm dev work, hãy tùy chỉnh **dev agent**
|
||||
- Nếu nó chỉ áp dụng khi ai đó viết product brief, hãy tùy chỉnh **workflow product-brief**
|
||||
- Nếu nó thay đổi *ai đang ngồi trong phòng* như đổi thương hiệu agent, thêm custom voice hoặc ép chung một artifact path, hãy sửa **cấu hình trung tâm**
|
||||
|
||||
## Recipe 1: định hình một agent trên mọi workflow mà nó điều phối (dispatch)
|
||||
|
||||
**Trường hợp dùng (use case):** Chuẩn hóa việc dùng công cụ và tích hợp với hệ thống bên ngoài để mọi workflow được dispatch qua agent đó tự động thừa hưởng cùng hành vi. Đây là mẫu áp dụng (pattern) có sức ảnh hưởng lớn nhất.
|
||||
|
||||
**Ví dụ:** Amelia, tức dev agent, luôn dùng Context7 cho tài liệu thư viện và fallback sang Linear nếu không tìm thấy story trong danh sách epic.
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-agent-dev.toml
|
||||
|
||||
[agent]
|
||||
|
||||
# Áp dụng ở mọi lần kích hoạt. Theo Amelia đi vào dev-story, quick-dev,
|
||||
# create-story, code-review, qa-generate và mọi skill cô ấy dispatch.
|
||||
persistent_facts = [
|
||||
"Với mọi truy vấn tài liệu thư viện như React, TypeScript, Zod, Prisma..., hãy gọi Context7 MCP tool (`mcp__context7__resolve_library_id` rồi `mcp__context7__get_library_docs`) trước khi dựa vào kiến thức trong dữ liệu huấn luyện (training data). Tài liệu cập nhật phải thắng API đã ghi nhớ.",
|
||||
"Khi không tìm thấy tham chiếu story trong {planning_artifacts}/epics-and-stories.md, hãy tìm trong Linear bằng `mcp__linear__search_issues` theo ID hoặc tiêu đề story trước khi yêu cầu người dùng làm rõ. Nếu Linear trả về kết quả khớp, coi đó là nguồn story có thẩm quyền.",
|
||||
]
|
||||
```
|
||||
|
||||
**Vì sao cách này hiệu quả:** Chỉ với hai câu, bạn đã thay đổi mọi dev workflow trong tổ chức mà không lặp config từng nơi và không sửa source. Mọi engineer mới kéo repo về đều tự động thừa hưởng convention đó.
|
||||
|
||||
**File của team và file cá nhân**
|
||||
|
||||
- `bmad-agent-dev.toml`: commit vào git, áp dụng cho cả team
|
||||
- `bmad-agent-dev.user.toml`: bị gitignore, dùng cho sở thích cá nhân chồng thêm lên trên
|
||||
|
||||
## Recipe 2: ép convention của tổ chức bên trong một workflow cụ thể
|
||||
|
||||
**Trường hợp dùng (use case):** Định hình *nội dung đầu ra* của một workflow để nó đáp ứng yêu cầu compliance, audit hoặc hệ thống downstream.
|
||||
|
||||
**Ví dụ:** mọi product brief đều phải có các trường compliance, và agent biết convention xuất bản của tổ chức.
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-product-brief.toml
|
||||
|
||||
[workflow]
|
||||
|
||||
persistent_facts = [
|
||||
"Mọi brief phải có trường 'Owner', 'Target Release' và 'Security Review Status'.",
|
||||
"Các brief không mang tính thương mại như công cụ nội bộ hoặc dự án nghiên cứu vẫn phải có phần user value, nhưng có thể bỏ phân biệt cạnh tranh thị trường.",
|
||||
"file:{project-root}/docs/enterprise/brief-publishing-conventions.md",
|
||||
]
|
||||
```
|
||||
|
||||
**Điều gì xảy ra:** Những fact này được nạp trong quá trình activation của workflow. Khi agent soạn brief, nó đã biết các trường bắt buộc và tài liệu convention nội bộ. Mặc định có sẵn, ví dụ `file:{project-root}/**/project-context.md`, vẫn tiếp tục được nạp vì phần này chỉ append thêm.
|
||||
|
||||
## Recipe 3: xuất bản kết quả hoàn tất sang hệ thống ngoài
|
||||
|
||||
**Trường hợp dùng (use case):** Sau khi workflow tạo ra output chính, tự động đẩy nó sang hệ thống nguồn sự thật của doanh nghiệp như Confluence, Notion, SharePoint, rồi mở tiếp công việc follow-up trong Jira, Linear hoặc Asana.
|
||||
|
||||
**Ví dụ:** brief được tự động publish lên Confluence và tùy chọn mở Jira epic.
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-product-brief.toml
|
||||
|
||||
[workflow]
|
||||
|
||||
# Hook ở giai đoạn cuối. Scalar override sẽ thay hẳn mặc định rỗng.
|
||||
on_complete = """
|
||||
Publish và đề nghị bước tiếp theo:
|
||||
|
||||
1. Đọc đường dẫn file brief đã hoàn tất từ bước trước.
|
||||
2. Gọi `mcp__atlassian__confluence_create_page` với:
|
||||
- space: "PRODUCT"
|
||||
- parent: "Product Briefs"
|
||||
- title: tiêu đề của brief
|
||||
- body: nội dung markdown của brief
|
||||
Lưu lại URL trang được trả về.
|
||||
3. Thông báo cho người dùng: "Brief đã được publish lên Confluence: <url>".
|
||||
4. Hỏi: "Bạn có muốn tôi mở Jira epic cho brief này ngay bây giờ không?"
|
||||
5. Nếu có, gọi `mcp__atlassian__jira_create_issue` với:
|
||||
- type: "Epic"
|
||||
- project: "PROD"
|
||||
- summary: tiêu đề của brief
|
||||
- description: tóm tắt ngắn cùng liên kết ngược về trang Confluence.
|
||||
Sau đó báo lại epic key và URL.
|
||||
6. Nếu không, thoát sạch.
|
||||
|
||||
Nếu một trong các MCP tool bị lỗi, hãy báo lỗi, in ra đường dẫn brief
|
||||
và yêu cầu người dùng publish thủ công.
|
||||
"""
|
||||
```
|
||||
|
||||
**Vì sao dùng `on_complete` thay vì `activation_steps_append`:** `on_complete` chỉ chạy đúng một lần ở cuối, sau khi output chính của workflow đã được ghi ra. Đó là thời điểm đúng để publish artifact. `activation_steps_append` thì chạy mỗi lần kích hoạt, trước khi workflow làm công việc chính của nó.
|
||||
|
||||
**Điểm đánh đổi (trade-offs)**
|
||||
|
||||
- Publish lên Confluence là hành động không phá hủy, nên có thể luôn chạy khi hoàn tất
|
||||
- Tạo Jira epic là hành động hiển thị cho cả team và kích hoạt các tín hiệu sprint planning, nên nên chặn bởi một bước xác nhận từ người dùng
|
||||
- Nếu MCP tool lỗi, workflow phải có phương án dự phòng (fallback) rõ ràng thay vì âm thầm làm mất output
|
||||
|
||||
## Recipe 4: thay output template bằng template của riêng bạn
|
||||
|
||||
**Trường hợp dùng (use case):** Cấu trúc đầu ra mặc định không khớp định dạng mà tổ chức mong muốn, hoặc trong cùng một repo có nhiều tổ chức cần template riêng.
|
||||
|
||||
**Ví dụ:** trỏ workflow product-brief sang template do doanh nghiệp sở hữu.
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-product-brief.toml
|
||||
|
||||
[workflow]
|
||||
brief_template = "{project-root}/docs/enterprise/brief-template.md"
|
||||
```
|
||||
|
||||
**Cách nó hoạt động:** `customize.toml` của workflow đi kèm `brief_template = "resources/brief-template.md"` dưới dạng đường dẫn tương đối tới skill root. Override của bạn lại trỏ tới một file trong `{project-root}`, nên agent sẽ đọc template của bạn trong bước tương ứng thay vì dùng template mặc định đi kèm.
|
||||
|
||||
**Mẹo viết template**
|
||||
|
||||
- Giữ template trong `{project-root}/docs/` hoặc `{project-root}/_bmad/custom/templates/` để nó được version cùng với file override
|
||||
- Nên dùng cùng convention cấu trúc với template mặc định, ví dụ heading và frontmatter, để agent có điểm tựa ổn định
|
||||
- Với repo đa tổ chức, hãy dùng `.user.toml` để từng nhóm nhỏ có thể trỏ sang template riêng mà không cần sửa file dùng chung của team
|
||||
|
||||
## Recipe 5: tùy chỉnh danh sách agent (agent roster)
|
||||
|
||||
**Trường hợp dùng (use case):** Thay đổi *ai đang ngồi trong phòng* cho những skill dựa trên roster như `bmad-party-mode`, `bmad-retrospective` và `bmad-advanced-elicitation`, mà không cần sửa source hay fork. Dưới đây là ba biến thể thường gặp.
|
||||
|
||||
### 5a. Rebrand một agent của BMad trên toàn tổ chức
|
||||
|
||||
Mỗi agent thật đều có một descriptor được installer tổng hợp từ `module.yaml`. Bạn có thể override descriptor này để đổi giọng điệu và framing ở mọi roster consumer:
|
||||
|
||||
```toml
|
||||
# _bmad/custom/config.toml (commit vào git, áp dụng cho mọi developer)
|
||||
|
||||
[agents.bmad-agent-analyst]
|
||||
description = "Mary, nhà phân tích nghiệp vụ giàu nhận thức pháp lý, pha trộn Porter với Minto nhưng sống cùng các audit trail của FDA. Cô ấy nói như một điều tra viên pháp chứng đang trình bày hồ sơ vụ án."
|
||||
```
|
||||
|
||||
Party mode sẽ spawn Mary với description mới này. Bản thân activation của analyst vẫn chạy bình thường vì hành vi của Mary sống trong `customize.toml` theo từng skill. Override này chỉ thay đổi cách **các skill bên ngoài nhìn thấy và giới thiệu cô ấy**, chứ không thay đổi cách cô ấy hoạt động bên trong.
|
||||
|
||||
### 5b. Thêm một agent hư cấu hoặc agent tự định nghĩa
|
||||
|
||||
Chỉ cần một descriptor đầy đủ là đủ cho các tính năng dựa trên roster, không cần thư mục skill. Điều này rất phù hợp nếu bạn muốn tăng màu sắc tính cách cho party mode hay các buổi brainstorming:
|
||||
|
||||
```toml
|
||||
# _bmad/custom/config.user.toml (cá nhân, gitignore)
|
||||
|
||||
[agents.spock]
|
||||
team = "startrek"
|
||||
name = "Commander Spock"
|
||||
title = "Science Officer"
|
||||
icon = "🖖"
|
||||
description = "Logic là trên hết, cảm xúc bị nén lại. Mở đầu nhận xét bằng 'Fascinating.' Không bao giờ làm tròn lên. Là đối trọng với mọi lập luận chỉ dựa vào linh cảm."
|
||||
|
||||
[agents.mccoy]
|
||||
team = "startrek"
|
||||
name = "Dr. Leonard McCoy"
|
||||
title = "Chief Medical Officer"
|
||||
icon = "⚕️"
|
||||
description = "Sự ấm áp của một bác sĩ miền quê, đi kèm với tính nóng nảy. 'Dammit Jim, I'm a doctor not a ___.' Là đối trọng đạo đức với Spock."
|
||||
```
|
||||
|
||||
Khi bạn yêu cầu party-mode "mời nhóm Star Trek" hoặc "mời phi hành đoàn Enterprise", nó sẽ lọc theo `team = "startrek"` và spawn Spock cùng McCoy dựa trên các descriptor đó. Các agent thật của BMad như Mary hay Amelia vẫn có thể ngồi cùng bàn nếu bạn muốn.
|
||||
|
||||
### 5c. Ghim thiết lập cài đặt dùng chung cho cả team
|
||||
|
||||
Installer sẽ hỏi từng developer các giá trị như đường dẫn `planning_artifacts`. Khi tổ chức muốn có một câu trả lời thống nhất, hãy ghim nó trong cấu hình trung tâm. Khi đó, mọi câu trả lời cục bộ của từng người sẽ bị override lúc resolve:
|
||||
|
||||
```toml
|
||||
# _bmad/custom/config.toml
|
||||
|
||||
[modules.bmm]
|
||||
planning_artifacts = "{project-root}/shared/planning"
|
||||
implementation_artifacts = "{project-root}/shared/implementation"
|
||||
|
||||
[core]
|
||||
document_output_language = "English"
|
||||
```
|
||||
|
||||
Những thiết lập cá nhân như `user_name`, `communication_language` hoặc `user_skill_level` nên vẫn nằm trong `_bmad/config.user.toml` riêng của từng developer. File chung của team không nên đụng vào các giá trị đó.
|
||||
|
||||
**Vì sao việc này nằm ở cấu hình trung tâm thay vì per-agent customize.toml:** File per-agent chỉ định hình cách *một* agent hành xử khi nó được kích hoạt. Cấu hình trung tâm lại định hình những gì các roster consumer *nhìn thấy khi quan sát cánh đồng chung*: agent nào tồn tại, tên gì, thuộc team nào và các thiết lập cài đặt dùng chung mà toàn repo đã thống nhất. Hai bề mặt khác nhau, hai công việc khác nhau.
|
||||
|
||||
## Củng cố các quy tắc toàn cục trong file hướng dẫn phiên của IDE
|
||||
|
||||
Tùy chỉnh của BMad chỉ được nạp khi một skill được kích hoạt. Trong khi đó, nhiều công cụ IDE còn nạp một file hướng dẫn toàn cục ở **đầu mọi phiên**, trước cả khi skill nào chạy, như `CLAUDE.md`, `AGENTS.md`, `.cursor/rules/` hay `.github/copilot-instructions.md`. Với những quy tắc phải đúng cả khi bạn đang chat thường, hãy lặp lại phiên bản rút gọn của chúng trong file đó nữa.
|
||||
|
||||
**Khi nào nên "đánh đôi"**
|
||||
|
||||
- Quy tắc đó đủ quan trọng đến mức một cuộc chat thường, chưa kích hoạt BMad skill nào, cũng vẫn phải tuân theo
|
||||
- Bạn muốn áp dụng kiểu "gia cố hai lớp" (belt-and-suspenders) vì hành vi mặc định từ dữ liệu huấn luyện (training data) có thể kéo model đi chệch
|
||||
- Quy tắc đủ ngắn để lặp lại mà không làm file hướng dẫn đầu phiên trở nên phình to
|
||||
|
||||
**Ví dụ:** một dòng trong `CLAUDE.md` của repo để củng cố quy tắc ở Recipe 1.
|
||||
|
||||
```markdown
|
||||
<!-- Mọi lần đọc tài liệu thư viện phải đi qua Context7 MCP tool
|
||||
(`mcp__context7__resolve_library_id` rồi `mcp__context7__get_library_docs`)
|
||||
trước khi dựa vào kiến thức từ dữ liệu huấn luyện (training data). -->
|
||||
```
|
||||
|
||||
Chỉ một câu, nhưng được nạp ở mọi phiên. Nó kết hợp với cấu hình `bmad-agent-dev.toml` để quy tắc có hiệu lực cả trong workflow của Amelia lẫn trong các cuộc trò chuyện ad-hoc với assistant. Mỗi lớp giữ đúng phạm vi của mình:
|
||||
|
||||
| Lớp | Phạm vi | Dùng cho |
|
||||
|---|---|---|
|
||||
| File hướng dẫn phiên của IDE như `CLAUDE.md` hoặc `AGENTS.md` | Mọi phiên, trước khi bất kỳ skill nào chạy | Quy tắc ngắn, phổ quát, phải sống cả ngoài BMad |
|
||||
| Tùy chỉnh agent của BMad | Mọi workflow mà agent đó dispatch | Hành vi riêng theo persona/agent |
|
||||
| Tùy chỉnh workflow của BMad | Một lần chạy workflow | Dạng đầu ra, hook publish, template và logic riêng của workflow |
|
||||
| Cấu hình trung tâm của BMad | Agent roster và thiết lập cài đặt dùng chung | Ai đang ngồi trong phòng và đường dẫn nào cả team dùng chung |
|
||||
|
||||
Hãy giữ file hướng dẫn của IDE **ngắn gọn**. Một tá dòng được chọn kỹ sẽ hiệu quả hơn một danh sách dài lê thê. Model phải đọc file đó ở mọi lượt, và càng nhiều nhiễu thì càng ít tín hiệu.
|
||||
|
||||
## Kết hợp các recipe
|
||||
|
||||
Cả năm recipe này có thể kết hợp song song. Một cấu hình doanh nghiệp thực tế cho `bmad-product-brief` hoàn toàn có thể đặt `persistent_facts` theo Recipe 2, `on_complete` theo Recipe 3 và `brief_template` theo Recipe 4 trong cùng một file. Quy tắc ở cấp agent theo Recipe 1 sẽ nằm trong file của agent tương ứng, còn cấu hình trung tâm theo Recipe 5 thì ghim roster và thiết lập chung. Tất cả cùng hoạt động đồng thời.
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-product-brief.toml (cấp workflow)
|
||||
|
||||
[workflow]
|
||||
persistent_facts = ["..."]
|
||||
brief_template = "{project-root}/docs/enterprise/brief-template.md"
|
||||
on_complete = """ ... """
|
||||
```
|
||||
|
||||
```toml
|
||||
# _bmad/custom/bmad-agent-analyst.toml (cấp agent, Mary sẽ dispatch product-brief)
|
||||
|
||||
[agent]
|
||||
persistent_facts = ["Luôn thêm mục 'Regulatory Review' khi domain liên quan tới healthcare, finance hoặc dữ liệu trẻ em."]
|
||||
```
|
||||
|
||||
Kết quả là Mary nạp quy tắc review pháp lý ngay ở lúc kích hoạt persona. Khi người dùng chọn menu item product-brief, workflow sẽ nạp các convention riêng của nó chồng lên, ghi ra template của doanh nghiệp và publish lên Confluence khi hoàn tất. Mỗi lớp đều đóng góp một phần và không lớp nào đòi hỏi sửa source của BMad.
|
||||
|
||||
## Khắc phục sự cố
|
||||
|
||||
**Override không có tác dụng?** Hãy kiểm tra file có nằm trong `_bmad/custom/` và dùng đúng tên thư mục skill không, ví dụ `bmad-agent-dev.toml`, chứ không phải `bmad-dev.toml`. Nếu cần, xem lại [Cách tùy chỉnh BMad](./customize-bmad.md).
|
||||
|
||||
**Không chắc tên MCP tool?** Hãy dùng đúng tên mà MCP server hiện tại expose trong phiên của bạn. Nếu chưa chắc, hãy yêu cầu Claude Code liệt kê các MCP tool đang có. Những tên hardcode trong `persistent_facts` hay `on_complete` sẽ không chạy nếu MCP server chưa được kết nối.
|
||||
|
||||
**Mẫu áp dụng (pattern) trong ví dụ không khớp setup của tôi?** Các recipe trên chỉ là ví dụ mẫu. Cơ chế bên dưới, gồm merge ba lớp, quy tắc cấu trúc và mô hình agent-span-workflow, vẫn hỗ trợ nhiều pattern khác. Hãy kết hợp chúng theo nhu cầu thực tế của bạn.
|
||||
|
|
@ -0,0 +1,180 @@
|
|||
---
|
||||
title: 'Cài đặt module tùy chỉnh và module cộng đồng'
|
||||
description: Cài các module bên thứ ba từ kho cộng đồng (community registry), kho Git hoặc đường dẫn cục bộ
|
||||
sidebar:
|
||||
order: 3
|
||||
---
|
||||
|
||||
Sử dụng trình cài đặt BMad để thêm module từ kho cộng đồng (community registry), kho Git của bên thứ ba hoặc đường dẫn file cục bộ.
|
||||
|
||||
## Khi nào nên dùng
|
||||
|
||||
- Cài một module do cộng đồng đóng góp từ BMad registry
|
||||
- Cài module từ kho Git của bên thứ ba như GitHub, GitLab, Bitbucket hoặc máy chủ tự host
|
||||
- Kiểm thử một module bạn đang phát triển cục bộ với BMad Builder
|
||||
- Cài module từ máy chủ Git riêng tư hoặc tự host
|
||||
|
||||
:::note[Điều kiện tiên quyết]
|
||||
Yêu cầu [Node.js](https://nodejs.org) v20+ và `npx` đi kèm npm. Bạn có thể chọn module tùy chỉnh và module cộng đồng trong lúc cài mới, hoặc thêm chúng vào một bản cài hiện có.
|
||||
:::
|
||||
|
||||
## Module cộng đồng
|
||||
|
||||
Các module cộng đồng được tuyển chọn trong [BMad plugins marketplace](https://github.com/bmad-code-org/bmad-plugins-marketplace). Chúng được sắp theo danh mục và được ghim vào commit đã được phê duyệt để tăng độ an toàn.
|
||||
|
||||
### 1. Chạy trình cài đặt
|
||||
|
||||
```bash
|
||||
npx bmad-method install
|
||||
```
|
||||
|
||||
### 2. Duyệt danh mục (catalog) cộng đồng
|
||||
|
||||
Sau khi chọn module chính thức, trình cài đặt sẽ hỏi:
|
||||
|
||||
```
|
||||
Would you like to browse community modules?
|
||||
```
|
||||
|
||||
Chọn **Yes** để vào màn hình duyệt catalog. Tại đây bạn có thể:
|
||||
|
||||
- Duyệt theo danh mục
|
||||
- Xem các module nổi bật
|
||||
- Xem toàn bộ module khả dụng
|
||||
- Tìm kiếm theo từ khóa
|
||||
|
||||
### 3. Chọn module
|
||||
|
||||
Chọn module từ bất kỳ danh mục nào. Trình cài đặt sẽ hiển thị mô tả, phiên bản và mức độ tin cậy (trust tier). Những module đã cài sẽ được tick sẵn để tiện cập nhật.
|
||||
|
||||
### 4. Tiếp tục quá trình cài đặt
|
||||
|
||||
Sau khi chọn xong module cộng đồng, trình cài đặt sẽ chuyển sang bước nguồn tùy chỉnh (custom source), rồi tới cấu hình tool/IDE và phần còn lại của luồng cài đặt.
|
||||
|
||||
## Nguồn tùy chỉnh: Git URL và đường dẫn cục bộ
|
||||
|
||||
Module tùy chỉnh có thể đến từ bất kỳ kho Git nào hoặc từ một thư mục cục bộ trên máy bạn. Trình cài đặt sẽ resolve nguồn, phân tích cấu trúc module rồi cài nó song song với các module khác.
|
||||
|
||||
### Cài đặt tương tác
|
||||
|
||||
Trong quá trình cài, sau bước chọn community module, trình cài đặt sẽ hỏi:
|
||||
|
||||
```
|
||||
Would you like to install from a custom source (Git URL or local path)?
|
||||
```
|
||||
|
||||
Chọn **Yes**, rồi nhập nguồn:
|
||||
|
||||
| Loại đầu vào | Ví dụ |
|
||||
| --------------------- | ------------------------------------------------- |
|
||||
| HTTPS URL trên bất kỳ host nào | `https://github.com/org/repo` |
|
||||
| HTTPS URL trỏ vào một thư mục con | `https://github.com/org/repo/tree/main/my-module` |
|
||||
| SSH URL | `git@github.com:org/repo.git` |
|
||||
| Đường dẫn cục bộ | `/Users/me/projects/my-module` |
|
||||
| Đường dẫn cục bộ dùng `~` | `~/projects/my-module` |
|
||||
|
||||
Với URL, trình cài đặt sẽ clone repository. Với đường dẫn cục bộ, nó sẽ đọc trực tiếp từ đĩa. Sau đó nó sẽ hiển thị các module tìm thấy để bạn chọn cài.
|
||||
|
||||
### Cài đặt không tương tác
|
||||
|
||||
Dùng cờ `--custom-source` để cài module tùy chỉnh từ dòng lệnh:
|
||||
|
||||
```bash
|
||||
npx bmad-method install \
|
||||
--directory . \
|
||||
--custom-source /path/to/my-module \
|
||||
--tools claude-code \
|
||||
--yes
|
||||
```
|
||||
|
||||
Khi cung cấp `--custom-source` mà không kèm `--modules`, hệ thống chỉ cài core và các module tùy chỉnh. Nếu muốn cài cả module chính thức, hãy thêm `--modules`:
|
||||
|
||||
```bash
|
||||
npx bmad-method install \
|
||||
--directory . \
|
||||
--modules bmm \
|
||||
--custom-source https://gitlab.com/myorg/my-module \
|
||||
--tools claude-code \
|
||||
--yes
|
||||
```
|
||||
|
||||
Bạn có thể truyền nhiều nguồn bằng cách ngăn cách chúng bằng dấu phẩy:
|
||||
|
||||
```bash
|
||||
--custom-source /path/one,https://github.com/org/repo,/path/two
|
||||
```
|
||||
|
||||
## Cơ chế phát hiện module
|
||||
|
||||
Trình cài đặt dùng hai chế độ để tìm module có thể cài trong một nguồn:
|
||||
|
||||
| Chế độ | Điều kiện kích hoạt | Hành vi |
|
||||
| --------- | ------------------------------------------------- | -------------------------------------------------------------------------------------------- |
|
||||
| Discovery | Nguồn chứa `.claude-plugin/marketplace.json` | Liệt kê toàn bộ plugin trong manifest để bạn chọn cái nào cần cài |
|
||||
| Direct | Không tìm thấy `marketplace.json` | Quét thư mục để tìm các skill, tức các thư mục con chứa `SKILL.md`, rồi coi toàn bộ như một module duy nhất |
|
||||
|
||||
Discovery là chế độ phát hiện qua manifest. Direct là chế độ quét trực tiếp thư mục. Discovery phù hợp với module đã publish, còn Direct thuận tiện khi bạn đang trỏ vào một thư mục skills trong quá trình phát triển cục bộ.
|
||||
|
||||
:::note[Về thư mục `.claude-plugin/`]
|
||||
Đường dẫn `.claude-plugin/marketplace.json` là một quy ước tiêu chuẩn được nhiều trình cài đặt AI tool cùng dùng để hỗ trợ khả năng khám phá plugin. Nó không đòi hỏi Claude, không dùng Claude API và cũng không ảnh hưởng tới việc bạn đang dùng công cụ AI nào. Bất kỳ module nào có file này đều có thể được khám phá bởi những trình cài đặt tuân theo cùng quy ước.
|
||||
:::
|
||||
|
||||
## Quy trình phát triển cục bộ
|
||||
|
||||
Nếu bạn đang xây một module bằng [BMad Builder](https://github.com/bmad-code-org/bmad-builder), bạn có thể cài trực tiếp từ thư mục đang làm việc:
|
||||
|
||||
```bash
|
||||
npx bmad-method install \
|
||||
--directory ~/my-project \
|
||||
--custom-source ~/my-module-repo/skills \
|
||||
--tools claude-code \
|
||||
--yes
|
||||
```
|
||||
|
||||
Nguồn cục bộ được tham chiếu theo đường dẫn, không bị copy vào cache. Khi bạn sửa source của module rồi cài lại, trình cài đặt sẽ lấy đúng các thay đổi mới nhất.
|
||||
|
||||
:::caution[Xóa nguồn sau khi cài]
|
||||
Nếu bạn xóa thư mục nguồn cục bộ sau khi cài, các file module đã được cài bên trong `_bmad/` vẫn được giữ nguyên. Tuy vậy, module đó sẽ bị bỏ qua trong các lần cập nhật cho tới khi đường dẫn nguồn được khôi phục.
|
||||
:::
|
||||
|
||||
## Bạn sẽ nhận được gì
|
||||
|
||||
Sau khi cài, các module tùy chỉnh sẽ xuất hiện trong `_bmad/` cùng với module chính thức:
|
||||
|
||||
```text
|
||||
your-project/
|
||||
├── _bmad/
|
||||
│ ├── core/ # Module core tích hợp
|
||||
│ ├── bmm/ # Module chính thức, nếu bạn chọn
|
||||
│ ├── my-module/ # Module tùy chỉnh của bạn
|
||||
│ │ ├── my-skill/
|
||||
│ │ │ └── SKILL.md
|
||||
│ │ └── module-help.csv
|
||||
│ └── _config/
|
||||
│ └── manifest.yaml # Theo dõi mọi module, phiên bản và nguồn
|
||||
└── ...
|
||||
```
|
||||
|
||||
Manifest sẽ ghi lại nguồn của từng module tùy chỉnh, dùng `repoUrl` cho nguồn Git và `localPath` cho nguồn cục bộ, để quá trình cập nhật nhanh (quick update) sau này có thể tìm lại nguồn chính xác.
|
||||
|
||||
## Cập nhật module tùy chỉnh
|
||||
|
||||
Module tùy chỉnh tham gia vào luồng cập nhật bình thường:
|
||||
|
||||
- **Cập nhật nhanh (quick update)** với `--action quick-update`: làm mới mọi module từ đúng nguồn ban đầu. Module dựa trên Git sẽ được fetch lại, còn module cục bộ sẽ được đọc lại từ đường dẫn nguồn
|
||||
- **Cập nhật đầy đủ (full update)**: chạy lại bước chọn module để bạn có thể thêm hoặc gỡ module tùy chỉnh
|
||||
|
||||
## Tạo module của riêng bạn
|
||||
|
||||
Hãy dùng [BMad Builder](https://github.com/bmad-code-org/bmad-builder) để tạo module mà người khác có thể cài:
|
||||
|
||||
1. Chạy `bmad-module-builder` để sinh skeleton cho module
|
||||
2. Thêm skill, agent và workflow bằng các công cụ builder tương ứng
|
||||
3. Publish lên một kho Git hoặc chia sẻ cả thư mục
|
||||
4. Người khác có thể cài bằng `--custom-source <url-kho-cua-ban>`
|
||||
|
||||
Nếu muốn module hỗ trợ chế độ Discovery, hãy thêm `.claude-plugin/marketplace.json` ở root repository. Đây là quy ước chung giữa nhiều công cụ, không dành riêng cho Claude. Hãy xem [tài liệu của BMad Builder](https://github.com/bmad-code-org/bmad-builder) để biết định dạng của `marketplace.json`.
|
||||
|
||||
:::tip[Hãy thử cục bộ trước]
|
||||
Trong quá trình phát triển, hãy cài module bằng đường dẫn cục bộ để lặp nhanh trước khi publish lên kho Git.
|
||||
:::
|
||||
|
|
@ -28,6 +28,7 @@ Yêu cầu [Node.js](https://nodejs.org) v20+ và `npx` (đi kèm với npm).
|
|||
| `--modules <modules>` | Danh sách ID module, cách nhau bởi dấu phẩy | `--modules bmm,bmb` |
|
||||
| `--tools <tools>` | Danh sách ID công cụ/IDE, cách nhau bởi dấu phẩy (dùng `none` để bỏ qua) | `--tools claude-code,cursor` hoặc `--tools none` |
|
||||
| `--action <type>` | Hành động cho bản cài đặt hiện có: `install` (mặc định), `update`, hoặc `quick-update` | `--action quick-update` |
|
||||
| `--custom-source <sources>` | Danh sách Git URL hoặc đường dẫn cục bộ cho module tùy chỉnh, cách nhau bởi dấu phẩy | `--custom-source /path/to/module` |
|
||||
|
||||
### Cấu hình cốt lõi
|
||||
|
||||
|
|
@ -81,6 +82,7 @@ Chạy `npx bmad-method install` một lần ở chế độ tương tác để
|
|||
| Hoàn toàn không tương tác | Cung cấp đầy đủ cờ để bỏ qua tất cả prompt | `npx bmad-method install --directory . --modules bmm --tools claude-code --yes` |
|
||||
| Bán tương tác | Cung cấp một số cờ, BMad hỏi thêm phần còn lại | `npx bmad-method install --directory . --modules bmm` |
|
||||
| Chỉ dùng mặc định | Chấp nhận tất cả giá trị mặc định với `-y` | `npx bmad-method install --yes` |
|
||||
| Chỉ dùng custom source | Chỉ cài core và module tùy chỉnh | `npx bmad-method install --directory . --custom-source /path/to/module --tools claude-code --yes` |
|
||||
| Không cấu hình công cụ | Bỏ qua cấu hình công cụ/IDE | `npx bmad-method install --modules bmm --tools none` |
|
||||
|
||||
## Ví dụ
|
||||
|
|
@ -119,6 +121,33 @@ npx bmad-method install \
|
|||
--action quick-update
|
||||
```
|
||||
|
||||
### Cài từ custom source
|
||||
|
||||
Cài một module từ đường dẫn cục bộ hoặc từ bất kỳ Git host nào:
|
||||
|
||||
```bash
|
||||
npx bmad-method install \
|
||||
--directory . \
|
||||
--custom-source /path/to/my-module \
|
||||
--tools claude-code \
|
||||
--yes
|
||||
```
|
||||
|
||||
Kết hợp cùng module chính thức:
|
||||
|
||||
```bash
|
||||
npx bmad-method install \
|
||||
--directory . \
|
||||
--modules bmm \
|
||||
--custom-source https://gitlab.com/myorg/my-module \
|
||||
--tools claude-code \
|
||||
--yes
|
||||
```
|
||||
|
||||
:::note[Hành vi của `custom-source`]
|
||||
Khi dùng `--custom-source` mà không kèm `--modules`, hệ thống chỉ cài core và các module tùy chỉnh. Nếu muốn cài cả module chính thức, hãy thêm `--modules`. Xem thêm [Cài đặt module tùy chỉnh và module cộng đồng](./install-custom-modules.md) để biết chi tiết.
|
||||
:::
|
||||
|
||||
## Bạn nhận được gì
|
||||
|
||||
- Thư mục `_bmad/` đã được cấu hình đầy đủ trong dự án của bạn
|
||||
|
|
|
|||
Loading…
Reference in New Issue