Hướng dẫn từng bước

Trang này dành cho người mới dùng BA-kit lần đầu. Bạn không cần nhớ hết command. Cách làm đúng rất đơn giản: xem mình đang ở đâu, chạy bước tiếp theo, sửa đúng chỗ cần sửa.

Nếu bạn chưa từng dùng CLI (dòng lệnh) bao giờ — đừng lo. Bạn chỉ cần gõ hoặc nói intent bằng tiếng Việt, agent sẽ lo phần còn lại.

0. Cách nghĩ trước khi dùng

BA-kit giống như một dây chuyền làm tài liệu BA, mỗi công đoạn có một cánh cửa kiểm soát (gate). Bạn không thể qua cửa sau nếu cửa trước chưa xong:

Input yêu cầu (file PDF, ghi chú, email)
→ intake (chuẩn hóa yêu cầu thành một bản rõ ràng)
→ options (nếu có nhiều hướng giải pháp, so sánh trước khi chọn)
→ backbone (khóa source of truth — đây là "hiến pháp" của dự án)
→ shared rules/messages (nếu team cần quy tắc dùng chung)
→ module stories / FRD / SRS canon (tài liệu chi tiết cho từng module)
→ compile SRS (tổng hợp từ các mảnh canon)
→ Figma sync (nếu có thiết kế giao diện)
→ package bàn giao (đóng gói HTML, gửi stakeholder)
→ qc-export (nếu có QC team — xuất artifact sang định dạng QC-kit)

Quy tắc vàng:

• Không biết làm gì → ba-start next
• Muốn xem có gì → ba-start status
• Stakeholder đổi yêu cầu → impact trước, sửa sau
• Sửa SRS → sửa canon (userstories/, usecases/, srs/) trước, compile sau
• Nhiều BA → mỗi người một module, không đụng module người khác

1. Bắt đầu bằng ngôn ngữ tự nhiên

Bạn không cần biết command đúng. Cứ nói bằng tiếng Việt:

Claude Code:

/ba-do Tôi có tài liệu yêu cầu mới, hãy tạo dự án BA

Codex:

$ba-do Tôi có tài liệu yêu cầu mới, hãy tạo dự án BA

Antigravity:

Đọc BA-kit workflow đã cài và chạy intake cho dự án mới

Nếu đã có file yêu cầu cụ thể:

/ba-start intake /path/to/requirements.pdf

Kết quả: PROJECT-HOME.md (dashboard — nhìn một cái biết đang ở đâu) + 01_intake/intake.md (yêu cầu đã được chuẩn hóa, rõ ràng).

2. Luôn biết bước tiếp theo

/ba-start status --slug <slug>
/ba-start next --slug <slug>

next giống như GPS — nó sẽ đề xuất chính xác command tiếp theo. Đừng đoán. Cứ làm theo next.

3. Flow solo BA từ đầu đến cuối

Bước 1: Intake — chuẩn hóa yêu cầu

/ba-start intake /path/to/source.pdf

Bước này giống như bạn đang dịch yêu cầu thô thành một bản tóm tắt có cấu trúc. Agent sẽ đọc file của bạn và hỏi những gì còn thiếu.

Review 01_intake/intake.md:

• Stakeholder là ai
• Business goal là gì
• Scope và out of scope rõ chưa
• Mode: hybrid (mặc định, phù hợp nhất cho hầu hết dự án)

Bước 2: Options — nếu có nhiều hướng giải pháp

/ba-start options --slug <slug>
/ba-start options --slug <slug> --select option-02

Bước này giống như bạn đang cân nhắc các con đường khác nhau trước khi chọn một con đường để đi.

Nếu chỉ có một hướng rõ ràng, không cần so sánh:

/ba-start options --slug <slug> --skip

Bước 3: Backbone — khóa source of truth

/ba-start backbone --slug <slug>

Bước này giống như bạn đang viết "hiến pháp" cho dự án. Mọi thứ làm sau đều phải tuân theo backbone.

Backbone phải chốt: business goals, actors, feature map, module split, assumptions, constraints. Nếu có UI: portal matrix, shared shell/menu.

Bước 4: User Stories

/ba-start stories --slug <slug> --module <module_slug>

Bước này giống như bạn đang kể chuyện người dùng: ai muốn gì, để làm gì, kết quả mong đợi là gì.

Mỗi story phải có: actor rõ, acceptance criteria test được, priority rõ, trace về business goal.

Bước 5: FRD (nếu stakeholder business cần review)

/ba-start frd --slug <slug> --module <module_slug>

FRD là tài liệu dành cho người không chuyên kỹ thuật đọc — stakeholder, manager, client. Ngôn ngữ business, không có code.

Bước 6: SRS canon (quan trọng nhất)

/ba-start srs --slug <slug> --module <module_slug>

Bước này giống như bạn đang viết bản thiết kế chi tiết cho developer. Đây là bước tốn nhiều công sức nhất, và cũng quan trọng nhất.

Kết quả:

03_modules/{module_slug}/usecases/*.md      # Use case canon — từng luồng nghiệp vụ
03_modules/{module_slug}/ascii-screen/*.md   # Screen canon — từng màn hình
03_modules/{module_slug}/srs/*.md            # SRS slices — các mảnh SRS
03_modules/{module_slug}/srs.md              # Compiled SRS — bản tổng hợp

Quy tắc sửa SRS: sửa source set trước → compile lại srs.md sau. Không sửa thẳng srs.md — giống như bạn không sửa bản in mà phải sửa bản thảo gốc.

Nếu dùng shared rule/message, reference code từ backbone:

Validation Rules: CR-VAL-01
Error Message: MSG-ERR-01

Bước 7: Figma sync (nếu có UI)

/ba-figma-sync --slug <slug> --module <module_slug>

Figma sync chỉ đọc từ SRS canon để đồng bộ một chiều lên Figma. Nếu Figma khác canon → sửa canon trước, sync lại sau. Không làm ngược.

Bước 8: Package bàn giao

/ba-start package --slug <slug>

Bước cuối cùng — đóng gói mọi thứ thành file HTML. Mở bằng browser, gửi link cho stakeholder. Không cần tool gì đặc biệt.

Kết quả: 04_compiled/compiled-frd.html và compiled-srs.html.

Bước 9: Xuất cho QC (không bắt buộc)

Bước này chỉ dành cho dự án có QC team riêng. Nếu dự án bạn không có QC, bỏ qua bước này — không ảnh hưởng gì đến flow chính.

Khi SRS đã hoàn chỉnh, bạn có thể xuất toàn bộ artifact sang định dạng QC-kit chỉ bằng một lệnh. Giống như bạn in một bản sao sạch sẽ từ bản thảo gửi cho bên kiểm tra — bản gốc vẫn giữ nguyên, không bị đụng vào.

ba-kit qc-export --slug <slug> --date <YYMMDD-HHmm> --module <module_slug>

Hoặc nói bằng tiếng Việt, agent tự tìm đúng slug/date/module:

/ba-do xuất QC cho module <module_slug>

Kết quả nằm trong 04_compiled/qc-kit/docs/BA/. Mỗi UC được xuất thành một file markdown 6 phần, đúng định dạng QC-kit cần:

1. Mô tả Use Case — actor, luồng chính, luồng phụ, luồng lỗi
2. Mô tả màn hình — danh sách màn hình, bảng field, trạng thái
3. Tổng hợp validation — rule và message đã dịch từ mã (CR-VAL-01) thành text
4. Cross-References — bảng FR, BR, Functional Integration
5. Open Questions — câu hỏi mở
6. Changelog — lịch sử thay đổi

Quan trọng: tất cả mã CR-*, MSG-*, BR-* đều được dịch tự động thành text đầy đủ. QC không cần mở thêm file nào khác.

Nếu muốn gửi thẳng vào QC-kit repo:

ba-kit qc-export --slug <slug> --date <YYMMDD-HHmm> --module <module> --external-output ../qc-kit

Cần nhớ: QC-export chỉ đọc, không sửa canon. File gốc an toàn tuyệt đối. QC phát hiện vấn đề → bạn sửa canon → xuất lại. Chạy lại bao nhiêu lần cũng được.

4. Khi có thay đổi requirement

Đừng sửa thẳng SRS. Chạy impact trước — giống như bạn kiểm tra xem thay đổi này sẽ "dây" ra những đâu:

/ba-start impact --slug <slug> "Export CSV phải có audit log"

Impact sẽ cho biết thay đổi chạm vào đâu: backbone, stories, SRS, screen source, Figma, package. Rồi chạy đúng command được đề xuất.

5. Reverse BA (từ hệ thống đang chạy)

/ba-start reverse --slug <slug>

Reverse giống như bạn đang mổ xẻ một hệ thống đang chạy để hiểu nó hoạt động thế nào. Nó ghi nhận evidence từ code/hệ thống — không tự suy diễn thành requirement. Future-state request không đi reverse — dùng impact hoặc forward flow.

6. Multi-BA collaboration

Lead BA (người chủ trì):

/ba-start intake requirements.pdf
/ba-start backbone --slug <slug>

Module BA (người phụ trách từng phần):

/ba-collab Tôi nhận module <module_slug>
/ba-start stories --slug <slug> --module <module_slug>
/ba-start srs --slug <slug> --module <module_slug>
/ba-collab Gửi module <module_slug> cho Lead BA review

Xem chi tiết: Collaboration

7. Cheat sheet

Lifecycle:

/ba-start intake <file>
/ba-start options --slug <slug> [--select option-0x | --skip]
/ba-start backbone --slug <slug>
/ba-start stories --slug <slug> --module <module>
/ba-start frd --slug <slug> --module <module>
/ba-start srs --slug <slug> --module <module>
/ba-start package --slug <slug>

Trạng thái & thay đổi:

/ba-start status --slug <slug>
/ba-start next --slug <slug>
/ba-start impact --slug <slug> "nội dung thay đổi"

Figma:

/ba-figma-sync --slug <slug> --module <module>

QC Export (không bắt buộc):

ba-kit qc-export --slug <slug> --date <YYMMDD-HHmm> --module <module>

/ba-do xuất QC cho module <module>

8. Những lỗi người mới hay mắc

• Sửa thẳng srs.md khi module đã có canon → sửa source set trước, compile sau. Giống như sửa bản thảo, không sửa bản in
• Mỗi module tự định nghĩa menu/global layout → shared UI phải ở backbone. Một nhà một nóc
• Bỏ qua empty/loading/error states trên màn hình — màn hình không chỉ có happy path
• Stakeholder đổi requirement, sửa SRS ngay → chạy impact trước để biết "dây" ra những đâu
• Multi-BA không claim module rõ ràng → dùng ba-collab để claim trước khi làm

9. Rule cuối cùng

Nếu bối rối:

/ba-start status --slug <slug>
/ba-start next --slug <slug>

Làm theo command next đề xuất. Đừng đoán.