Nếu bạn chưa quen GitHub, hãy đọc [GitHub cơ bản cho BA](github-for-ba-beginners.md) trước. Nếu bạn muốn vận hành bằng ngôn ngữ BA trước khi đụng branch/PR, hãy đọc [Workflow cộng

Làm việc theo module với GitHub

Nên đọc tài liệu này sau khi đọc gì

Nếu bạn chưa quen GitHub, hãy đọc GitHub cơ bản cho BA trước. Nếu bạn muốn vận hành bằng ngôn ngữ BA trước khi đụng branch/PR, hãy đọc Workflow cộng tác thân thiện cho BA trước trang này.

Tài liệu hiện tại giả định bạn đã hiểu ở mức cơ bản:

repo là nơi chứa tài liệu
main là nhánh chính
branch là nhánh làm việc riêng
PR là nơi xin review và merge

Nếu bạn đang xử lý Change Request, core update, đề xuất UI/UX từ BA Member, conflict hoặc lỗi sau merge, hãy đọc thêm Scenario xử lý thay đổi cho BA team.

Mục tiêu của tài liệu này

Tài liệu này mô tả cách team BA dùng BA-kit để cùng làm trên một initiative nhưng vẫn giữ được:

một source of truth rõ ràng
phân vai lead và member không chồng chéo
review có kiểm soát
lịch sử thay đổi rõ
khả năng package và handoff ổn định ở cuối vòng làm việc

Từ BA-kit core commit dcb4b9f ngày 2026-04-28, workflow khuyến nghị là dùng ba-collab và các dashboard cộng tác để điều phối BA trước. GitHub vẫn quan trọng, nhưng là lớp handoff/transport optional sau khi user approve rõ.

Mô hình này phù hợp khi initiative có nhiều module như:

auth-flow
payment
inventory
reporting

Bức tranh tổng quát rất ngắn

Luồng BA-friendly mới là:

BA Lead chuẩn bị phần hệ thống.
BA Lead tạo hoặc refresh PROJECT-HOME.md và COLLAB-HOME.md.
BA Lead giao module; BA Member nhận module qua ba-collab.
Mỗi member chỉ làm trong module được giao.
Member gửi review bằng review packet.
Lead review và yêu cầu chỉnh sửa nếu cần.
Nếu cần local sync, agent có thể chạy Git nội bộ sau plan ngắn và sau khi kiểm tra không có local changes.
Nếu cần publish, agent chỉ commit/push/tạo PR/merge PR sau approval rõ.
Lead tổng hợp các module đã approve và package.

Nếu muốn nhớ một câu duy nhất, hãy nhớ câu này:

Core trước, module sau. BA nói intent, agent xử lý Git local. Publish chỉ sau approval.

Lớp BA-friendly trước GitHub

BA team không cần bắt đầu bằng branch hoặc PR. Cùng một intent được gọi khác nhau theo runtime.

Claude Code:

/ba-collab Tôi nhận module auth-flow
/ba-collab Kiểm tra module payment trước khi gửi review
/ba-collab Tôi làm xong module payment, gửi Lead BA review
/ba-collab Lead BA approve module inventory

Codex:

$ba-collab Tôi nhận module auth-flow
$ba-collab Kiểm tra module payment trước khi gửi review
$ba-collab Tôi làm xong module payment, gửi Lead BA review
$ba-collab Lead BA approve module inventory

Antigravity:

Đọc BA-kit collaboration workflow và chạy intent:
Tôi nhận module auth-flow.

Không commit, push, tạo PR hoặc merge PR nếu tôi chưa approve rõ.

Các file cộng tác liên quan:

PROJECT-HOME.md: dashboard dự án và bước tiếp theo.
COLLAB-HOME.md: dashboard module ownership, review state, blocker và next action.
MODULE-HOME.md: dashboard riêng cho BA Member, gồm scope được sửa và checklist trước review.
Module review packet: gói gửi Lead BA review trước khi cần PR thật.

GitHub vẫn được dùng khi team cần lịch sử commit, Pull Request hoặc merge PR thật. Khi đó ba-collab phải xin approval trước các publish actions như commit, push, tạo PR, request reviewer hoặc merge PR.

Local Git sync là implementation detail của agent. Nếu agent đang chạy trong môi trường có quyền Git, BA nên nói:

Đồng bộ module reporting với main trước khi tôi làm tiếp
Cập nhật module payment theo bản mới nhất

Agent sẽ tự kiểm tra branch, local changes, cập nhật main, switch sang branch module và merge/rebase theo policy. Nếu có local changes chưa commit hoặc conflict nghiệp vụ, agent phải dừng và hỏi, không tự stash/overwrite hoặc tự resolve requirement docs.

Phân vai rõ ràng

BA Lead chịu trách nhiệm gì

BA Lead chịu trách nhiệm:

nhận raw input và chốt intake
khóa scope và engagement mode
tạo plan
tạo backbone cấp hệ thống
chốt actor map, portal ownership, global rule, shared navigation direction
quyết định module nào được tách cho BA Member
giao việc theo module
theo dõi COLLAB-HOME.md và review packet
review PR của BA Member
quyết định khi nào requirement change cần rerun
chạy package hoặc duyệt package cuối

BA Member chịu trách nhiệm gì

BA Member chịu trách nhiệm:

chỉ làm trong module được giao
bám đúng plan, backbone, DESIGN.md đã được merge
tạo hoặc cập nhật artifact nằm trong thư mục module của mình
gửi review packet hoặc mở PR để lead review khi đã được approve
sửa lại PR theo review comment

Điều BA Member không nên tự quyết

BA Member không tự ý đổi:

global actor
portal ownership
menu hoặc navigation toàn cục
business rule dùng chung nhiều module
shared UX direction
cấu trúc backbone cấp hệ thống

Nếu thấy các phần này cần đổi, member phải báo lead. Không sửa lặng lẽ trong module rồi hy vọng lead sẽ tự thấy.

Nếu thay đổi chạm requirement, scope, actor, navigation hoặc shared rule, không xử lý như việc review module thông thường. Route qua ba-impact trước để đánh giá ảnh hưởng lên source of truth và module khác.

Source of truth theo thứ tự ưu tiên

Trong teamwork mode, source of truth phải được đọc theo đúng thứ tự:

01_intake/intake.md
01_intake/plan.md
02_backbone/backbone.md
designs/{slug}/DESIGN.md nếu initiative có UI scope
artifact cấp module trong 03_modules/{module_slug}/

Ý nghĩa thực tế:

file ở trên có quyền “định hướng” file ở dưới
file ở dưới không được âm thầm phủ định file ở trên
nếu có mâu thuẫn, ưu tiên xử lý ở lớp trên trước

Cấu trúc thư mục khi làm việc theo module

plans/{slug}-{date}/
  01_intake/
  02_backbone/
  03_modules/
    auth-flow/
    payment/
    inventory/
  04_compiled/

designs/{slug}/DESIGN.md

Artifact cấp module đi đúng vào thư mục module đó, ví dụ:

frd.md
user-stories.md
srs.md
wireframe-input.md
wireframe-map.md
wireframe-state.md

Một BA Member nếu phụ trách auth-flow thì gần như chỉ nên chạm:

plans/{slug}-{date}/03_modules/auth-flow/

Đây là nguyên tắc cực kỳ quan trọng để PR gọn và dễ review.

BA-kit có thể bổ sung các file cộng tác ở cấp project/module:

plans/{slug}-{date}/
  PROJECT-HOME.md
  COLLAB-HOME.md
  03_modules/
    auth-flow/
      MODULE-HOME.md
      review-packet.md

Tên file review packet có thể khác tùy runtime hoặc template, nhưng mục đích vẫn là tóm tắt thay đổi, artifact đã chạm, trace IDs và cross-module risk.

Branching model khuyến nghị

Branch chính

main: chỉ chứa nội dung đã review và đã được merge

Branch của lead

Lead nên có branch riêng cho phần core ban đầu, ví dụ:

lead/warehouse-rfp-core
lead/warehouse-rfp-260423-core

Branch của member

Mỗi member dùng một branch riêng cho một module chính:

ba/warehouse-rfp/auth-flow
ba/warehouse-rfp/payment
ba/warehouse-rfp/inventory

Quy tắc bắt buộc:

một branch chỉ gắn với một module chính
một PR chỉ gắn với một mục tiêu rõ ràng
branch của member luôn được tách từ main sau khi core artifacts đã merge

Trước khi member bắt đầu làm, lead phải chuẩn bị gì

Đây là bước rất hay bị làm tắt. Không nên làm tắt.

Lead cần chuẩn bị đủ các phần sau:

Repo đã tồn tại và đúng người đã được mời vào repo.
Core artifacts đã được tạo xong trên branch riêng.
Core artifacts đã được merge vào main.
Module boundaries đã được chốt.
Mỗi module đã có owner rõ ràng.
Các câu hỏi mở quan trọng đã được ghi lại.

Kết quả tối thiểu nên có trước khi BA Member bắt đầu:

01_intake/intake.md
01_intake/plan.md
02_backbone/backbone.md
designs/{slug}/DESIGN.md nếu cần

Nếu chưa có các file này mà đã giao member chạy module, rất dễ xảy ra:

mỗi người hiểu scope theo một kiểu
rule chung bị tự phát sinh trong module
PR sau này đụng nhau

Packet giao việc lead nên gửi cho member

Khi giao module, lead không nên chỉ nói miệng kiểu “em làm payment nhé”.

Packet giao việc tối thiểu nên có:

slug
date set
module_slug
đường dẫn exact của plan.md
đường dẫn exact của backbone.md
đường dẫn DESIGN.md nếu có UI scope
danh sách artifact phải làm
out-of-scope rõ ràng
deadline
open questions còn treo

Ví dụ packet ngắn:

Slug: warehouse-rfp
Date set: 2026-04-23
Module: auth-flow

Read first:
- plans/warehouse-rfp-260423/01_intake/plan.md
- plans/warehouse-rfp-260423/02_backbone/backbone.md
- designs/warehouse-rfp/DESIGN.md

You own:
- frd.md
- user-stories.md
- srs.md

Do not change:
- shared navigation
- actor map
- cross-module business rules

Quy trình end-to-end cực chi tiết

Bước 1. Lead tạo core artifact trên branch riêng

Lead làm trên branch core và hoàn thiện các lớp hệ thống trước:

chạy intake
hoàn thiện plan
chạy backbone
nếu có UI scope, chốt DESIGN.md ở mức hệ thống
chốt danh sách module sẽ tách ra cho team

Lead sau đó mở PR từ branch core vào main.

Nếu repo dùng GitHub web để review:

mở repo
vào tab Pull requests
bấm New pull request
chọn base là main
chọn compare là branch core của lead
viết PR title và description rõ ràng
review hoặc nhờ peer review
merge khi đã sẵn sàng

Chỉ sau bước này member mới nên bắt đầu.

Bước 2. Member đồng bộ từ `main` rồi mới làm module

BA Member không cần tự chạy lệnh Git nếu agent có quyền trong workspace. Hãy nói bằng NLP:

Tôi nhận module auth-flow, tạo workspace module từ main mới nhất.
Đồng bộ module auth-flow với main trước khi tôi làm tiếp.

Agent nên hiển thị plan ngắn, ví dụ:

Tôi sẽ:
1. Kiểm tra branch hiện tại và thay đổi local.
2. Cập nhật main từ origin.
3. Tạo hoặc chuyển sang branch module auth-flow.
4. Nếu có conflict hoặc local changes chưa commit, tôi sẽ dừng và báo rõ.

Không commit/push trong bước này.

Nếu agent báo hoàn tất:

Module auth-flow đã đồng bộ với main.
Không có conflict.
Bạn có thể tiếp tục viết SRS/auth-flow.

Nếu agent báo conflict:

Module reporting bị conflict ở:
- 02_backbone/backbone.md: Portal Matrix
- 03_modules/reporting/srs.md: SCR-07 filter behavior

Đây là conflict nghiệp vụ, cần Lead BA quyết định. Tôi chưa sửa file.

Với người làm trực tiếp trên GitHub web:

mở repo
xác nhận đang đứng ở main
mở menu branch
tạo branch mới từ main
đặt đúng tên branch module

Vì branch là bản chụp của main tại thời điểm tạo nhánh, bước này giúp member bắt đầu từ bản mới nhất đã được lead chốt. Khi có agent, Git là implementation detail; BA chỉ cần nêu intent đồng bộ.

Bước 3. Member chỉ làm trong phạm vi module được giao

Ví dụ member phụ trách auth-flow, phạm vi chính là:

plans/{slug}-{date}/03_modules/auth-flow/

Member có thể chạy các tác vụ BA-kit phù hợp scope, ví dụ:

frd
stories
srs
wireframes

Ví dụ trong Claude Code:

/ba-start frd --slug warehouse-rfp --module auth-flow
/ba-start stories --slug warehouse-rfp --module auth-flow
/ba-start srs --slug warehouse-rfp --module auth-flow

Ví dụ trong Codex:

Use AGENTS.md and skills/ba-start/SKILL.md.
Run stories for slug warehouse-rfp module auth-flow.
Read only the resolved backbone and module prerequisites.
Do not scan unrelated modules.

Ví dụ trong Antigravity:

Đọc BA-kit workflow đã cài và chạy bước stories cho slug warehouse-rfp, module auth-flow.
Chỉ đọc backbone đã resolve và prerequisite của module này.
Không scan module không liên quan.

Những điều member phải tự kiểm soát:

không sửa module khác
không sửa 02_backbone nếu lead chưa giao
không tự thêm rule dùng chung cho toàn hệ thống
không tự đổi shared navigation

Bước 4. Member tự kiểm tra trước khi mở PR

Trước khi mở PR, member nên tự rà rất kỹ:

file có nằm đúng thư mục module không
có file ngoài module nào bị chạm nhầm không
acceptance criteria có đủ chưa
nội dung có mâu thuẫn với backbone không
nếu có UI scope, screen ID có nhất quán không
có assumption hoặc câu hỏi mở nào cần nêu rõ trong PR không

Mục tiêu của bước này là để lead review nội dung, không phải tốn thời gian bắt lỗi phạm vi.

Bước 5. Member mở Pull Request

5.1. Kiểm tra đúng cặp branch

Khi tạo PR, member phải kiểm tra:

base branch là main
compare branch là branch module của mình

Nếu chọn sai base, PR sẽ hiển thị diff sai hoặc xin merge vào nhánh không đúng.

5.2. Viết tiêu đề PR rõ ràng

Ví dụ:

docs(auth-flow): add FRD, stories, and SRS for warehouse-rfp

5.3. Viết description đủ thông tin cho lead

PR description nên có:

module đang làm
artifact đã thêm hoặc sửa
điều gì cố ý không đụng tới
assumption
open questions
điểm cần lead review kỹ

Mẫu PR description:

Scope:
- module: auth-flow
- slug: warehouse-rfp

Artifacts:
- frd.md
- user-stories.md
- srs.md

Out of scope:
- no backbone change
- no shared navigation change

Open questions:
- waiting lead confirm audit-log wording in UC-03

5.4. Khi nào nên mở Draft PR

Hãy mở Draft pull request nếu:

bạn mới làm được một phần
muốn lead xác nhận hướng đi trước
còn nhiều assumption
chưa muốn được approve ngay

Khi đã hoàn tất phần chính và sẵn sàng review, đổi sang Ready for review.

Bước 6. Lead review PR

Lead review PR nên đi theo trình tự này trên GitHub:

đọc Conversation để hiểu scope và assumption
mở Files changed để xem đúng file, đúng phạm vi
comment trực tiếp vào đoạn cần sửa
nếu PR lớn, đánh dấu file là Viewed sau khi xem xong
chọn một trong ba hướng:
- Comment khi chỉ muốn góp ý
- Approve khi đạt chuẩn
- Request changes khi chưa đủ điều kiện merge

Checklist review của lead:

có đúng module scope không
có đụng artifact hệ thống không
có mâu thuẫn với backbone hoặc DESIGN.md không
có lôi file module khác vào PR không
use case, AC và screen behavior có trace được không

Bước 7. Member xử lý review comment

Sau khi lead review:

member không mở PR mới nếu vẫn là cùng một scope
member sửa tiếp trên chính branch đang mở PR
commit thêm thay đổi
quay lại PR để xác nhận đã xử lý comment

Nếu lead Request changes, member nên phản hồi rõ:

đã sửa chỗ nào
còn điểm nào cần lead xác nhận lại
có assumption mới phát sinh không

Bước 8. Merge vào `main`

Khi PR đạt chuẩn:

lead hoặc maintainer xác nhận PR đã đúng scope
kiểm tra branch đang merge vào main
merge PR
thông báo cho team pull bản mới nhất từ main

Khuyến nghị merge method:

ưu tiên Squash and merge nếu muốn lịch sử gọn, dễ đọc theo từng module
dùng merge commit nếu team thực sự cần giữ nguyên lịch sử nhiều commit nhỏ
không nên ưu tiên rebase merge cho team non-tech vì luồng này khó giải thích hơn và có thể kéo theo thao tác dòng lệnh phức tạp

GitHub Docs nêu rõ việc merge PR yêu cầu quyền ghi vào repo. Với repo dùng personal account, collaborator có quyền ghi có thể tạo, review và merge PR theo quyền được cấp.

Bước 9. Sau khi merge

Sau khi PR đã merge:

member cập nhật lại main
nếu tiếp tục làm module mới, tạo branch mới từ main
nếu branch cũ không còn dùng, có thể xóa để repo gọn hơn

Nếu repo bật Automatically delete head branches, GitHub có thể tự xóa branch sau khi merge. Nếu không bật, maintainer hoặc owner có thể xóa thủ công.

Bước 10. Lead chạy package hoặc final review

Sau khi các module quan trọng đã merge, lead chạy:

status để xem artifact set hiện tại
package để compile HTML

Chỉ lead hoặc người lead ủy quyền mới nên chạy package cuối khi có nhiều module song song.

Khi nào member được phép sửa core artifact

Mặc định: không.

Chỉ cho phép khi:

lead giao explicit task sửa backbone
hoặc lead yêu cầu tách một PR riêng cho backbone hoặc DESIGN.md

Không nên gộp trong cùng một PR:

thay đổi 02_backbone
thay đổi 03_modules/{module_slug}

Nếu vừa có system-level change vừa có module-level change, nên tách 2 PR:

PR core artifact
PR module artifact rebase trên main sau khi PR core đã merge

Xử lý requirement change khi nhiều người đang làm song song

Nếu có change mới khi nhiều member đang làm:

lead chạy impact
lead xác định affected artifacts
lead thông báo rõ module nào bị ảnh hưởng
nếu change chạm backbone, lead merge core change trước
member yêu cầu agent đồng bộ module với main mới nhất bằng NLP
member chỉ rerun phần module bị ảnh hưởng

Mục tiêu là tránh việc mỗi module tự diễn giải change theo cách khác nhau.

Cấu hình GitHub khuyến nghị cho workflow này

1. Repository access

Nếu repo thuộc personal account:

owner là người sở hữu repo
thành viên khác vào repo dưới dạng collaborator

GitHub Docs hiện nêu rằng personal private repository không có collaborator read-only; collaborator có quyền ghi thay đổi. Vì vậy lead cần rất rõ ai được mời vào repo.

2. Default branch

dùng main làm branch chính
không làm việc thường ngày trực tiếp trên main

3. Pull request merge options

Khuyến nghị cho team BA non-tech:

bật Squash and merge
chỉ giữ thêm merge commit nếu team thực sự cần

Lý do:

lịch sử gọn hơn
mỗi PR thường thành một commit rõ ràng
dễ đọc khi nhìn lại theo module hoặc đợt bàn giao

4. Branch protection

Nếu plan GitHub của repo hỗ trợ protected branches cho repo private, nên áp dụng tối thiểu:

chặn push trực tiếp vào main
yêu cầu review trước khi merge
chỉ người phù hợp mới có quyền push vào branch được bảo vệ

Nếu plan không hỗ trợ, hãy thay bằng quy ước vận hành:

không ai sửa trực tiếp main
mọi thay đổi đi qua PR
chỉ lead hoặc maintainer merge

Các tình huống hay gặp và cách xử lý

Phần dưới đây chỉ là checklist ngắn. Với hướng dẫn từng bước cho CR, UI/UX proposal, core update, conflict và lỗi sau merge, dùng Scenario xử lý thay đổi cho BA team.

Tình huống 1. PR của bạn lẫn file module khác

Xử lý:

dừng mở PR nếu chưa mở
nếu đã mở PR, báo lead ngay
tách lại thay đổi để PR chỉ còn đúng module scope

Tình huống 2. Bạn phát hiện `backbone` có vẻ thiếu hoặc sai

Xử lý:

không tự sửa trong PR module
ghi rõ vấn đề
raise lại cho lead
chờ lead quyết định có cần impact hoặc core PR riêng không

Tình huống 3. Bạn đã mở PR nhưng tiếp tục phải sửa thêm

Điều này là bình thường.

Bạn chỉ cần:

sửa tiếp trên cùng branch
commit thêm
quay lại PR

GitHub sẽ tự cập nhật PR với commit mới.

Tình huống 4. Bạn không chắc nên mở PR thường hay Draft PR

Quy tắc đơn giản:

nếu đang xin định hướng hoặc còn dang dở, mở Draft
nếu đã sẵn sàng cho lead approve, mở PR thường

Tình huống 5. Bạn bị conflict

Nếu bạn không quen Git, đừng cố tự xử bằng nhiều lệnh dòng lệnh. Hãy yêu cầu agent:

Giải thích conflict của module reporting bằng ngôn ngữ BA. Không tự sửa file.

Agent phải liệt kê file/section bị conflict và dừng. Với conflict requirement docs, agent không được tự đoán resolution; Lead BA hoặc owner phải quyết định.

Checklist cực ngắn cho BA Member

Trước khi bắt đầu:

đã đọc plan
đã đọc backbone
đã biết chính xác module của mình
đã yêu cầu agent đồng bộ module với main, hoặc đã tạo branch từ main nếu tự làm GitHub web

Trước khi mở PR:

file nằm đúng thư mục module
không chạm core artifact
title và description PR rõ ràng
đã nêu assumption và open questions

Sau khi nhận review:

sửa trên chính branch đó
trả lời comment quan trọng
chỉ coi task xong khi PR đã merge

Nguồn tham khảo chính thức

Tài liệu này được đối chiếu với GitHub Docs chính thức ngày 2026-04-23:

Hello World: https://docs.github.com/en/get-started/start-your-journey/hello-world
About pull requests: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests
Creating a pull request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request
Reviewing proposed changes in a pull request: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/reviewing-proposed-changes-in-a-pull-request
Managing access to your personal repositories: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/repository-access-and-collaboration
Permission levels for a personal account repository: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/repository-access-and-collaboration/permission-levels-for-a-personal-account-repository
About protected branches: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
About merge methods on GitHub: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github

Làm việc theo module với GitHub

On this page