Cách mở rộng BMad cho tổ chức của bạn

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.

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.

[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.

[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.

[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.

[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:

# _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:

# _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:

[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.

<!-- 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.

# _bmad/custom/bmad-product-brief.toml (cấp workflow)

[workflow]
persistent_facts = ["..."]
brief_template = "{project-root}/docs/enterprise/brief-template.md"
on_complete = """ ... """

# _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.

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.