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

Trang này dành cho người mới dùng Bakit 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

Bakit 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 spec (tài liệu chi tiết cho từng module)
→ use-case → userflow → wireframe (canon rời rạc từng bước)
→ render-html / test-checklist / test-cases / bpmn / prototype / preview (tùy nhu cầu)
→ package-frd (nếu cần gửi FRD sớm cho stakeholder, không cần đợi SRS)
→ compile SRS (tổng hợp từ các mảnh canon)
→ Figma Make prompt (nếu có UI)
→ package bàn giao (đóng gói HTML, gửi stakeholder)

Quy tắc vàng:

• Không biết làm gì → ba-start next
• Muốn xem có gì → ba-start status
• Muốn xem trực quan → ba-start preview
• Stakeholder đổi yêu cầu → impact trước, duyệt plan, rồi impact-cook
• Sửa SRS → sửa canon (userstories/, usecases/, ascii-wireframe/, 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 — từ v2.1.0, ba-start tự route yêu cầu của bạn đến đúng bước (thay cho ba-do đã xoá):

Claude Code:

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

Codex:

$ba-start 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 spec (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. Từ v2.1.0, srs chỉ sinh spec — các phần còn lại là bước riêng chạy sau.

Kết quả:

03_modules/{module_slug}/srs/spec.md        # SRS spec — FR, NFR, BR, Error Matrix
03_modules/{module_slug}/srs/flows.md       # Optional: sequence diagrams
03_modules/{module_slug}/srs/states.md      # Optional: state transitions
03_modules/{module_slug}/srs/erd.md         # Optional: ERD
03_modules/{module_slug}/srs.md             # Compiled SRS (spec-scope)

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: Use case canon

/ba-start use-case --slug <slug> --module <module_slug>

Sinh use case canon từ spec: usecases/index.md + uc-*.md + diagrams. Mỗi UC link về user stories và screens, dùng đúng terminology của stories/FRD. Behavior review phải approved trước khi đi tiếp.

Bước 8: Userflow — duyệt flow split

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

Sinh srs/userflow.md — artifact keystone: screen list, flow split, transitions, primary_device. Bạn phải duyệt userflow trước khi chạy wireframe/render-html — hai bước đó từ chối chạy khi userflow chưa approved.

Bước 9: Wireframe ASCII per-flow

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

Sinh ASCII wireframe canon theo flow: ascii-wireframe/index.md + 1 file/flow (bảng 5 cột, Description 6 lớp). Yêu cầu userflow approved + DESIGN.md + shared-shell-contract.md.

Dự án cũ có ascii-screen/ thì migrate: ba-kit run-script migrate-ascii-per-flow.py per module.

Bước 10: Render HTML, test, BPMN, prototype, preview (tùy nhu cầu)

/ba-start render-html --slug <slug> --module <module_slug>      # HTML từ canon
/ba-start test-checklist --slug <slug> --module <module_slug>   # Scenario outline
/ba-start test-cases --slug <slug> --module <module_slug>       # Test cases 1:1 từ checklist
/ba-start bpmn --slug <slug> --module <module_slug>             # BPMN 2.0 (cần node)
/ba-start prototype --slug <slug> --module <module_slug>        # Clickable prototype hi-fi
/ba-start preview --slug <slug> --module <module_slug>          # Whole-module viewer

Đây là các lane bổ sung — chạy khi cần, không bắt buộc theo thứ tự. test-cases đòi hỏi test-checklist trước; bpmn cần node trên PATH.

Bước 11: Figma Make prompt (nếu có UI)

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

Sinh prompt text paste-ready cho Figma Make từ SRS canon. Không dùng MCP. Sau khi chạy, paste prompt vào Figma Make theo thứ tự trong hướng dẫn. Nếu Figma Make khác canon → sửa canon trước, chạy lại /ba-figma-sync.

Bước 12: Package FRD sớm (nếu cần)

/ba-start package-frd --slug <slug>

Nếu stakeholder cần xem FRD trước khi SRS hoàn thành, dùng package-frd để đóng gói riêng FRD. Không cần đợi stories hay SRS.

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

Bước 13: 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.

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 sinh change plan (impacts/CR-{id}-plan.md) với closure set — tập đầy đủ artifact phải cập nhật cùng nhau. Duyệt plan xong thì thực thi:

/ba-start impact-cook --slug <slug> --cr <change_id>

Cook cập nhật nhất quán toàn bộ closure set — artifact governed đi qua lifecycle command của nó (giữ review gates), artifact derived ghi trực tiếp.

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. Làm dự án nhiều module

Khóa module list trong backbone trước:

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

Sau đó chạy từng module rõ ràng:

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

ba-collab, module claim, review packet và collaboration dashboard đã bị xoá từ v1.4.0. Nếu nhiều người cùng làm, quản lý ownership bằng Git/PM tool bên ngoài và không cho hai người sửa cùng artifact.

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 use-case --slug <slug> --module <module>
/ba-start userflow --slug <slug> --module <module>
/ba-start wireframe --slug <slug> --module <module>
/ba-start package-frd --slug <slug>
/ba-start package --slug <slug>

Render, test, prototype:

/ba-start render-html --slug <slug> --module <module>
/ba-start test-checklist --slug <slug> --module <module>
/ba-start test-cases --slug <slug> --module <module>
/ba-start bpmn --slug <slug> --module <module>
/ba-start prototype --slug <slug> --module <module>
/ba-start preview --slug <slug> --module <module>

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"
/ba-start impact-cook --slug <slug> [--cr <change_id>] [--auto]

Figma:

/ba-figma-sync --slug <slug> --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
• Nhiều người sửa cùng artifact → Bakit không còn workflow claim module; phải khóa ownership bằng quy trình ngoài

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.