Giao diện
Hướng dẫn sử dụng BA AI Workflow — lane ba/ của mind_keep ​
Nguồn gốc: clone từ workflow
ba-ai, đã chuyển đổi để chạy trong monorepo mind_keep:
- Toàn bộ output là thư mục + file
.mdtrongba/projects/(trước đây nằm ẩn trong.claude/projects/).- Dùng được cho dự án bất kỳ: mọi thông tin riêng của hệ thống đích nằm trong 1 file
system-profile.md(hiện cấu hình cho mind_keep).- 3 chế độ: A – tính năng mới · B – viết tài liệu từ code đã triển khai (
/document-existing) · C – sửa tính năng đã có (delta trên baseline).- Impact Analysis / Field Intake /
/document-existingđọc trực tiếp code và API docs thật (chỉ đọc).- Thêm bước Handover (Bước 12) tách việc theo thành phần hệ thống (mind_keep: BE / FE / APP).
- Zip / Confluence chuyển thành tuỳ chọn — chỉ làm khi BA yêu cầu.
Luật của lane:
CLAUDE.md.
Tài liệu này hướng dẫn BA cài đặt môi trường và sử dụng hệ thống BA AI Workflow để thực hiện toàn bộ quy trình phân tích nghiệp vụ — từ làm rõ yêu cầu đến tạo Functional Specification — với sự hỗ trợ của Claude AI.
Mục lục ​
- Tổng quan
- Cài đặt môi trường
- Mở project và hiểu cấu trúc thư mục 3b. Chọn chế độ làm việc
- Hướng dẫn đầy đủ quy trình ba-workflow (Mode A)
- Tham khảo các slash command
- Mẹo và xử lý vấn đề thường gặp 6b. Đọc tài liệu trên web
- Lưu tài liệu vào git
- Phụ lục
1. Tổng quan ​
BA AI Workflow là gì? ​
BA AI Workflow là hệ thống tự động hóa quy trình phân tích nghiệp vụ, chạy trên nền Claude AI bên trong Visual Studio Code. BA giao tiếp với AI qua chat — gõ lệnh, trả lời câu hỏi, duyệt tài liệu — còn AI đảm nhận việc phân tích, soạn thảo và lưu file.
BA không cần biết lập trình. Toàn bộ tương tác là bằng tiếng Việt tự nhiên.
Sơ đồ quy trình ​
| Giai đoạn | Nội dung | Output | Gate duyệt |
|---|---|---|---|
| 1 – Thu thập & làm rõ yêu cầu | Phân tích raw input, làm rõ requirement candidates, câu hỏi mở | Clarified Requirements + Open Questions | — |
| 2 – Business Requirements Document | Tài liệu yêu cầu nghiệp vụ chính thức | brd-v0.1-*.md | Gate 1 |
| 3 – Impact Analysis | Phân tích ảnh hưởng toàn bộ hệ thống (12 vùng) | impact-matrix-v0.1-*.md | Gate 2 |
| 4 – So sánh giải pháp | Đánh giá và chốt phương án thực hiện | solution-comparison-v0.1-*.md | Gate 3 |
| 5 – Functional Specification | Tài liệu đặc tả chức năng chi tiết với User Stories | Thư mục fs/<feature>-v0.1-*/ | Gate 4 |
Gate là điểm dừng bắt buộc: AI không tự chuyển sang giai đoạn tiếp theo cho đến khi BA duyệt rõ ràng.
Điều kiện tiên quyết ​
- Máy tính Windows 10/11 hoặc macOS 12+, RAM tối thiểu 8 GB
- Kết nối internet
- Tài khoản Claude (subscription hoặc API key) — liên hệ admin để được cấp quyền truy cập
2. Cài đặt môi trường ​
2.1 Cài đặt Visual Studio Code ​
Bước 1: Mở trình duyệt, truy cập https://code.visualstudio.com
Bước 2: Click nút "Download for Windows" (nút xanh lớn ở giữa trang). Với macOS chọn "Download for Mac".
Bước 3: Chạy file installer vừa tải. Trong quá trình cài đặt:
- Chấp nhận điều khoản sử dụng
- Giữ nguyên thư mục cài đặt mặc định
- Tại màn hình "Select Additional Tasks", tích chọn:
- "Add to PATH" — bắt buộc
- "Register Code as an editor for supported file types" — khuyến nghị
Bước 4: Click Install và chờ hoàn tất, sau đó click Finish.
Kiểm tra cài đặt thành công: Mở Start Menu (Windows) → gõ "VS Code" → click để mở. Một cửa sổ tối với tab "Get Started" sẽ xuất hiện.
2.2 Cài đặt Claude Code Extension ​
Bước 1: Trong VS Code, click icon Extensions ở thanh sidebar bên trái (biểu tượng 4 ô vuông, ô trên phải tách ra), hoặc nhấn Ctrl+Shift+X.
Bước 2: Trong ô tìm kiếm ở đầu panel Extensions, gõ: Claude Code
Bước 3: Tìm extension "Claude Code" với publisher là Anthropic → click Install.
Bước 4: Sau khi cài xong, một icon Claude sẽ xuất hiện ở thanh Activity Bar bên trái (cùng cột với icon Explorer, Search, Extensions). Icon này là điểm vào chính để dùng BA AI Workflow.
Lưu ý: Nếu không thấy icon Claude sau khi cài, thử restart VS Code (Ctrl+Shift+P → gõ "Reload Window" → Enter).
2.3 Đăng nhập Claude ​
Bước 1: Click icon Claude Code ở Activity Bar bên trái. Panel Claude Code sẽ mở ra ở phía phải hoặc dưới cửa sổ.
Bước 2: Click nút "Sign in with Anthropic" (hoặc "Sign in") trong panel.
Bước 3: Trình duyệt tự động mở trang đăng nhập Anthropic. Đăng nhập bằng email + mật khẩu (hoặc OTP nếu được yêu cầu).
Bước 4: Sau khi đăng nhập thành công trên trình duyệt, quay lại VS Code. Panel Claude Code sẽ hiển thị ô chat input — tức là đã kết nối thành công.
Kiểm tra: Gõ vào ô chat Xin chào và nhấn Enter. Claude sẽ trả lời bằng tiếng Việt.
Nếu trình duyệt không tự đóng: Quay lại VS Code thủ công sau khi đăng nhập xong trên trình duyệt — session vẫn được ghi nhận.
2.4 Cài đặt Git Bash ​
Git Bash là terminal dòng lệnh cho Windows, dùng để lấy bản mới nhất của repo mind_keep và commit tài liệu BA.
Bước 1: Mở trình duyệt, truy cập https://git-scm.com/download/win
Bước 2: File installer tự động tải. Nếu không tự tải, click "Click here to download".
Bước 3: Chạy file installer. Giữ tất cả tùy chọn mặc định và nhấn Next liên tục cho đến khi xuất hiện các màn hình sau — chỉ thay đổi 2 mục này:
- Màn hình "Choosing the default editor": chọn "Use Visual Studio Code as Git's default editor"
- Màn hình "Adjusting your PATH environment": giữ nguyên "Git from the command line and also from 3rd-party software" (mặc định)
Bước 4: Click Install, chờ hoàn tất, click Finish.
Kiểm tra cài đặt thành công: Click chuột phải vào bất kỳ thư mục nào trên máy → menu xuất hiện có mục "Open Git Bash here" → Git Bash đã sẵn sàng.
Cấu hình tên và email một lần (bắt buộc): Mở Git Bash (click chuột phải vào thư mục bất kỳ → "Open Git Bash here"), gõ hai lệnh sau — thay thông tin thực của bạn:
bash
git config --global user.name "Nguyen Van A"
git config --global user.email "vana@sapp.edu.vn"Tên và email này xuất hiện trong lịch sử commit. Chỉ cần cấu hình một lần duy nhất trên máy.
3. Mở project và hiểu cấu trúc thư mục ​
3.1 Mở project folder trong VS Code ​
Bắt buộc: Claude Code chỉ nạp skill /ba-workflow… và cấu hình Playwright khi phiên được mở từ trong thư mục ba/.
Cách mở (khuyến nghị):
- VS Code → File → Open Folder → chọn
mind_keep/ba→ Select Folder. - Hoặc terminal:
cd mind_keep/ba && claude.
Kiểm tra: Explorer hiển thị ba ở trên cùng, bên dưới có .claude/, _workflow/, knowledge-base/, projects/, CLAUDE.md, README.md. Gõ / trong ô chat phải thấy /ba-workflow.
Mở từ root
mind_keep/vẫn chạy được (đường dẫn trong skill viết dạngba/...), nhưng phiên root không có ranh giới lane tự động — xem../CLAUDE.md.
3.2 Cấu trúc thư mục ​
mind_keep/
├── be/ fe/ app/ ← 3 lane code — ba/ CHỈ ĐỌC để lấy context hệ thống
├── shared/api-docs/ ← hợp đồng API thật — ba/ CHỈ ĐỌC
└── ba/
├── CLAUDE.md ← luật của lane ba/
├── README.md ← tài liệu này
├── system-profile.md ← ⭐ hồ sơ hệ thống đích (mind_keep) — file DUY NHẤT phải đổi khi dùng cho dự án khác
├── .claude/
│ ├── settings.json ← chặn ghi ra ngoài ba/
│ └── skills/ ← 13 slash command (/ba-workflow, /generate-fs, ...)
├── .mcp.json ← Playwright MCP (chụp màn hình cho user guide)
├── _workflow/
│ ├── checklists/ ← tiêu chí AI tự kiểm tra
│ └── templates/ ← mẫu tài liệu (BRD, FS, Impact Matrix, Handover...)
├── knowledge-base/
│ ├── 00-index.md ← mục lục KB
│ └── sapp/ ← KB SAPP (LMS-Pro / Ops / HubSpot) clone từ ba-ai
└── projects/ ← ⭐ OUTPUT
├── README.md ← danh sách project + bước hiện tại
└── 2026-MK-TenProject/
├── project-context.md ← BA điền thông tin nền dự án
├── project-decisions.md ← Log quyết định đã chốt
├── working/
│ ├── raw-inputs/ ← Đặt tài liệu đầu vào tại đây
│ ├── ai-drafts/ ← Bản nháp AI tạo ra
│ ├── open-questions/ ← Câu hỏi mở đang chờ trả lời
│ └── meeting-notes/ ← Ghi chú cuộc họp
└── docs/
├── brd/ ← BRD chính thức
├── impact-analysis/ ← Impact Matrix
├── solution-options/ ← So sánh giải pháp
├── fs/ ← FS (nhiều file trong 1 thư mục)
├── test-scenarios/ ← Kịch bản kiểm thử
├── user-guide/ ← Tài liệu hướng dẫn người dùng cuối
└── handover/ ← Việc bàn giao cho BE / FE / APP3.3 Hai file quan trọng nhất ​
project-context.md — AI đọc file này đầu tiên ở mọi lệnh. Điền đầy đủ các mục Background, Objectives, Scope, Stakeholders và Confluence trước khi bắt đầu workflow. Càng nhiều context, AI càng ít phải hỏi lại.
project-decisions.md — AI tra cứu file này để không hỏi lại câu đã có đáp án. Đây là "bộ nhớ" của dự án. Tuyệt đối không xóa file này trong quá trình làm việc.
3.4 Quy tắc đặt tên file artifact ​
Format: <tên-artifact>-v<major>.<minor>-YYYYMMDD.md
| Version | Ý nghĩa |
|---|---|
v0.1 | Bản nháp đầu tiên |
v0.2, v0.3 | Cập nhật trong quá trình làm |
v1.0 | Đã được Gate duyệt chính thức |
v1.1, v1.2 | Cập nhật nhỏ sau khi duyệt |
v2.0 | Thay đổi lớn (thường do Change Request) |
AI tự đặt tên và lưu file — BA không cần làm thủ công.
3b. Chọn chế độ làm việc ​
| Bạn cần… | Mode | Lệnh |
|---|---|---|
| Viết tài liệu cho tính năng mới, bắt đầu từ yêu cầu stakeholder | A | /new-project → /ba-workflow |
| Viết tài liệu cho tính năng đã chạy (thiếu tài liệu, tài liệu cũ, bàn giao người mới) | B | /new-project → /document-existing |
| Sửa / mở rộng một tính năng đã có | C | /new-project → /ba-workflow (chọn C) — AI dựng baseline từ code trước |
| Kiểm tra code đã làm đúng FS chưa | — | /review-output (chế độ đối chiếu code) |
Mode B — viết tài liệu từ code (/document-existing) ​
Ví dụ prompt:
/document-existing 2026-MK-Webhook-docs màn Webhooks trong CMS (/cms/webhooks) và các API /api/v1/webhooksAI sẽ:
- R0 — hỏi phạm vi (dừng truy vết ở đâu), người đọc, và bộ tài liệu cần viết (mặc định FS; tuỳ chọn BRD tóm tắt / Test Scenarios / User Guide).
- R1 — truy vết code theo
system-profile.md§3 (màn → service → API → controller → DTO → entity → job → quyền), dựng Feature Inventory (working/ai-drafts/feature-inventory-*.md): mọi dòng có bằng chứngfile:dòng, kèm Drift (API doc nói khác code) và câu hỏi cho BA. - Gate R1 — BA xác nhận inventory và trả lời 2 loại câu hỏi code không trả lời được: mục đích nghiệp vụ là gì? và hành vi này cố ý hay là bug?
- R2–R3 — lập danh sách US → BA confirm → viết FS as-built (
docs/fs/<feature>-as-built-v0.1-*/), mỗi Business Rule có cột Nguồn code, đóng dấu commit đã đọc. - Gate R2 — BA duyệt FS. FS này thành baseline cho các thay đổi sau (Mode C).
Code thay đổi sau đó? Chạy lại
/document-existing— AI dùnggit log <commit cũ>..HEADđể chỉ cập nhật phần bị đổi.
Mode C — sửa tính năng đã có ​
AI kiểm tra đã có baseline (Feature Inventory hoặc FS as-built) chưa — chưa có thì chạy Mode B tới Gate R1 trước. Sau đó chạy luồng A nhưng: requirement ghi New / Changed / Removed; Impact Matrix tập trung vào delta; FS viết dạng delta (<feature>-change-v0.1-*/, US/BR gắn [NEW] / [CHANGED] / [UNCHANGED]) và link về baseline thay vì chép lại.
Dùng workflow cho một dự án khác ​
- Copy thư mục
ba/sang repo mới (hoặc giữ nguyên nếu tài liệu nằm ngoài repo code). - Thay
system-profile.mdbằng_workflow/templates/system-profile/Template.mdrồi điền §1–§7 (có thể nhờ AI: "đọc cấu trúc repo và dựng nháp system-profile" → BA xác nhận). - Sửa
denytrong.claude/settings.jsoncho khớp §4. - Xoá
projects/*cũ (giữprojects/README.md). Skill, checklist, template không cần sửa.
4. Hướng dẫn đầy đủ quy trình ba-workflow (Mode A) ​
4.0 Sơ đồ tổng quan ​
[Bước 1-3] Làm rõ yêu cầu
↓
[Bước 4] Tạo BRD ──→ [GATE 1: Approved?] ──→ (Need Revision → sửa lại)
↓ Approved
[Bước 5-6] Impact Analysis ──→ [GATE 2: Approved?] ──→ (Need Revision → sửa lại)
↓ Approved
[Bước 7-8] So sánh giải pháp ──→ [GATE 3: Approved?] ──→ (Need Revision → sửa lại)
↓ Approved
[Bước 9] Tạo FS ──→ [GATE 4: Approved?] ──→ (Need Revision → sửa lại)
↓ Approved
[Tuỳ chọn] Test Scenarios / User Guide / Publish Confluence4.1 Khởi động workflow (Bước 0) ​
Mục tiêu: Tạo project và cung cấp thông tin nền để AI hiểu bối cảnh dự án.
Prompt mẫu — tạo project mới:
/new-project 2026-LMS-Thi-cuoi-khoaSau khi tạo xong, mở project-context.md từ Explorer panel và điền:
- Background: Bối cảnh dự án là gì
- Objectives: Mục tiêu cần đạt
- Stakeholders: Ai là người liên quan
Đặt tài liệu đầu vào (email, meeting note, mô tả yêu cầu từ stakeholder) vào:
ba/projects/2026-LMS-Thi-cuoi-khoa/working/raw-inputs/Prompt mẫu — khởi động workflow:
/ba-workflow 2026-LMS-Thi-cuoi-khoaAI echo lại project đã chọn và hỏi "Bắt đầu từ đâu?". Trả lời: Bước 1
Tiếp tục workflow đang dở: Gõ cùng lệnh, AI tự đọc artifacts đã có và hỏi tiếp từ đâu.
4.2 Xác định project ​
Khi gõ /ba-workflow, AI xác định project theo thứ tự ưu tiên:
- Tên nêu rõ trong lệnh:
/ba-workflow 2026-LMS-Thi-cuoi-khoa - File đang mở trong VS Code nằm trong folder project nào → suy ra project đó
- Nếu không rõ hoặc có nhiều project → AI liệt kê để BA chọn, không tự đoán
AI luôn echo lại project đang làm trước khi chạy. Kiểm tra và xác nhận trước khi tiếp tục. Nếu sai, nói "sai rồi, tôi muốn làm project X" — AI chuyển ngay.
Khi làm nhiều dự án song song: Luôn nêu tên project trong lệnh để tránh nhầm.
4.3 Giai đoạn 1 — Làm rõ yêu cầu (Bước 1–3) ​
Mục tiêu: Chuyển đổi input thô (email, meeting note, yêu cầu lộn xộn) thành danh sách requirement candidates có cấu trúc, đồng thời xác định những thông tin còn thiếu cần hỏi thêm.
Bước 1: BA cung cấp input. Nếu chưa có file, AI hướng dẫn đặt vào working/raw-inputs/.
Bước 2: AI phân tích và tạo hai output, lưu tự động:
working/ai-drafts/clarified-requirements-YYYYMMDD.md— bảng requirement candidatesworking/open-questions/open-questions-YYYYMMDD.md— câu hỏi cần BA trả lời
Bước 3: BA trả lời câu hỏi trong chat. Viết tự nhiên — AI tự parse và cập nhật. Vòng lặp tiếp tục cho đến khi hết blocking questions (câu hỏi mà nếu chưa có đáp án thì không thể tạo BRD chính xác).
AI không tự sang Bước 4 khi còn blocking question về: business objective, scope, core business rule, hoặc user/role.
Prompt mẫu:
/clarify-requirements 2026-LMS-Thi-cuoi-khoaHoặc trong khi chạy /ba-workflow, khi AI đang ở Bước 1, trả lời câu hỏi tự nhiên:
Rule này chỉ áp dụng cho học viên CFA, không áp cho ACCA.
Thời gian thi tối đa là 3 giờ.
Không cần tích hợp với LMS cũ, chạy module độc lập.4.4 Giai đoạn 2 — Tạo BRD + Gate 1 (Bước 4) ​
Mục tiêu: Tạo tài liệu yêu cầu nghiệp vụ chính thức làm nền tảng cho toàn bộ workflow. Gate 1 đảm bảo BA đồng thuận với scope và business rules trước khi đi sâu vào phân tích.
BRD chứa gì: Business problem, yêu cầu nghiệp vụ, business rules, scope, assumptions.
BRD KHÔNG chứa: Chi tiết màn hình, luồng điều hướng, giải pháp kỹ thuật, Expected Behavior của từng field. Những thứ đó thuộc FS.
File lưu tại: docs/brd/brd-v0.1-YYYYMMDD.md
Gate 1 — Cách duyệt:
AI tóm tắt: objective, scope, requirements chính, assumptions, open questions còn lại. BA chọn một trong ba phản hồi:
| Phản hồi | Ý nghĩa | Ví dụ |
|---|---|---|
Approved | BRD ổn, tiếp tục | Approved |
Approved with Notes | Ổn nhưng cần ghi chú | Approved with Notes: FR3 cần bổ sung rule timeout |
Need Revision | Cần sửa, chưa tiếp tục | Need Revision: Scope chưa rõ phần A |
Quan trọng: Phải gõ đúng một trong ba keyword trên. Gõ mơ hồ như "ok" hay "được rồi" AI sẽ hỏi lại.
Sau Gate 1, AI gợi ý publish BRD lên Confluence — BA có thể bỏ qua, không bắt buộc.
Prompt mẫu — tạo BRD trực tiếp (không qua workflow):
/generate-brd 2026-LMS-Thi-cuoi-khoa4.5 Giai đoạn 3 — Impact Analysis + Gate 2 (Bước 5–6) ​
Mục tiêu: Xác định đầy đủ phạm vi ảnh hưởng của thay đổi lên hệ thống hiện tại — module, màn hình, data, API, role, business rule. Ngăn ngừa bỏ sót ở giai đoạn FS.
Bước 5 — Chốt phạm vi liên quan (quan trọng):
AI quét BRD + project-context + knowledge base và trình bảng "Related Features & Docs Map" — danh sách module, màn hình, entity, API, role bị ảnh hưởng.
BA action: review bảng, xác nhận đủ chưa, bổ sung nếu sót. Mục ❓BA là những điểm AI chưa chắc — cần BA chốt trước khi phân tích.
Tại sao quan trọng: Field/màn hình được xác nhận là "Existing" ở đây sẽ được xử lý đúng trong FS sau (không bị coi là mới, tránh duplicate hoặc conflict).
Không dựng Impact Matrix cho đến khi BA chốt phạm vi.
Prompt mẫu xác nhận phạm vi:
Bảng đã đủ. Thêm màn hình "Kết quả thi" vào danh sách — hiện chưa có, cần tạo mới.
Module "Ngân hàng câu hỏi" là Existing, không cần thay đổi.Bước 6: Trước khi dựng Impact Matrix, nếu phiên đã dài AI sẽ đề nghị: "Nên gõ /compact trước khi dựng Impact Matrix" — BA gõ /compact, rồi nhắn tiếp tục. AI không tự chạy được lệnh này.
AI tạo Impact Matrix theo 12 vùng phân tích: Business process / Module / Screen / Data / API / Role / Business rule / NFR / Notification / Reporting / Testing / Release.
File lưu tại: docs/impact-analysis/impact-matrix-v0.1-YYYYMMDD.md
Gate 2 — AI trình bày:
- Số impact theo severity (High / Medium / Low)
- Conflict phát hiện được — AI không tự resolve, chỉ ghi nhận để BA/Tech/PO quyết định
- FR/NFR còn thiếu, coverage gaps
- Transition requirements (data migration, cutover)
Phản hồi tương tự Gate 1: Approved / Approved with Notes / Need Revision.
Prompt mẫu — chạy Impact Analysis trực tiếp:
/impact-analysis 2026-LMS-Thi-cuoi-khoa4.6 Giai đoạn 4 — So sánh giải pháp + Gate 3 (Bước 7–8) ​
Mục tiêu: Chốt phương án thực hiện dựa trên đánh giá đa chiều. Gate 3 đảm bảo BA và team đồng thuận về hướng đi trước khi viết FS.
Bước 7: AI hỏi BA: "Đã có định hướng giải pháp chưa?"
- Đã có: AI đánh giá điểm mạnh/yếu và gợi ý 1–2 option thay thế nếu cần
- Chưa có: AI đề xuất 2–3 options dựa trên BRD, Impact Matrix, và best practices
Bước 8: AI so sánh các options theo: business fit / user impact / system impact / effort / risk / dependencies / pros-cons.
File lưu tại: docs/solution-options/solution-comparison-v0.1-YYYYMMDD.md
AI đưa ra Recommendation — đây là gợi ý, không phải quyết định. BA chọn solution.
Gate 3: Ghi rõ solution đã chọn trong phản hồi:
Approved with Notes: Chọn Option A — Standalone Exam ModuleAI tự cập nhật project-decisions.md với quyết định này.
Prompt mẫu — so sánh giải pháp trực tiếp:
/compare-solutions 2026-LMS-Thi-cuoi-khoaNếu đã có định hướng:
/compare-solutions 2026-LMS-Thi-cuoi-khoa
Đã có định hướng: dùng module thi độc lập, không tích hợp vào LMS cũ4.7 Giai đoạn 5 — Tạo FS + Gate 4 (Bước 9) ​
Mục tiêu: Tạo tài liệu đặc tả chức năng chi tiết đủ để Dev/QA triển khai mà không cần hỏi thêm BA. Mỗi User Story là một file riêng với đầy đủ AC, business rule, UI state, và edge case.
FS là output chính của toàn bộ workflow. Trước khi bắt đầu, nếu phiên đã dài AI sẽ đề nghị BA gõ /compact (giúp AI viết toàn bộ US chính xác hơn mà không bị mất context) — gõ xong nhắn tiếp tục.
FS được tạo qua 4 giai đoạn:
Giai đoạn A — Xác nhận danh sách User Stories:
AI trình bảng US (US ID / Tên / Role / Nguồn FR / Priority). BA confirm hoặc điều chỉnh (thêm, bớt, gộp, tách, đổi thứ tự).
Không viết chi tiết FS cho đến khi BA confirm danh sách US.
Prompt mẫu xác nhận US list:
Danh sách ổn. Tách US-03 thành 2 US riêng: một cho Admin tạo đề, một cho Admin duyệt đề.
Thêm US mới: Học viên xem lại bài thi sau khi nộp (priority: Medium).Giai đoạn A2 — Field Intake:
AI gom 1 bảng hỏi tất cả field + rule cho toàn bộ màn hình, pre-fill những gì suy được:
[đề xuất: xxx]= AI gợi ý giá trị, BA chỉ cần xác nhận hoặc sửa❓BA= BA bắt buộc phải điền, AI không đủ thông tin để đề xuất
BA điền một lượt, AI nhận và tiến sang viết chi tiết.
Prompt mẫu điền Field Intake:
- Thời gian thi: [đề xuất: 180 phút] → xác nhận đúng
- Số lần thi lại: ❓BA → tối đa 2 lần trong 30 ngày
- Điểm đạt: ❓BA → 70/100
- Hiển thị đáp án sau thi: [đề xuất: không] → sửa thành "có, sau 24 giờ"Giai đoạn B — Viết chi tiết toàn bộ US:
AI viết liên tục, mỗi US một file riêng. Sau khi xong tất cả, AI tạo Template Conformance Check để xác minh không file nào sót section bắt buộc.
Output structure:
docs/fs/exam-management-v0.1-20260615/
├── 00-overview.md ← Tổng quan + NFR + Open Questions + US index
├── US-01-ten-us.md ← Chi tiết User Story 01
├── US-02-ten-us.md ← Chi tiết User Story 02
└── ...FS là thư mục, không phải một file duy nhất. Mở
00-overview.mdđể xem US index và tìm đúng file cần đọc.
Gate 4 — Cách phản hồi revision hiệu quả:
Dùng format trỏ mã cụ thể để AI sửa đúng chỗ:
- US-02 / AC-M1.3: thiếu case quá hạn → bổ sung
- US-05 / BR-02: "≤2 lần" → sửa thành "≤3 lần"
- [Global] mọi AC: thêm dòng Maps toTránh feedback mơ hồ như "FS chưa đủ" hay "cần rõ hơn" — AI cần biết đúng US nào, AC/BR nào để sửa hiệu quả.
Sau Gate 4: AI gợi ý các bước tiếp: /generate-test-scenarios, /generate-user-guide, Handover (Bước 12 — file docs/handover/handover-v0.1-*.md tách việc cho BE / FE / APP). /publish-confluence chỉ khi BA muốn.
Prompt mẫu — tạo FS trực tiếp:
/generate-fs 2026-LMS-Thi-cuoi-khoa5. Tham khảo các slash command ​
5.0 Bảng tóm tắt ​
| Command | Dùng khi nào | Output |
|---|---|---|
/new-project | Bắt đầu dự án mới từ đầu (chọn Mode A/B/C) | Folder structure + 2 file template |
/document-existing | Viết tài liệu cho tính năng đã có trong code (Mode B) | working/ai-drafts/feature-inventory-*.md + thư mục docs/fs/<feature>-as-built-v0.1-*/ |
/ba-workflow | Chạy toàn bộ quy trình có hướng dẫn | Tất cả artifacts tuần tự |
/clarify-requirements | Làm rõ nhanh, độc lập ngoài workflow | working/ai-drafts/clarified-requirements-*.md |
/generate-brd | Tạo BRD trực tiếp khi đã rõ requirements | docs/brd/brd-v0.1-*.md |
/impact-analysis | Sau khi có BRD đã duyệt | docs/impact-analysis/impact-matrix-v0.1-*.md |
/compare-solutions | Sau khi có Impact Matrix đã duyệt | docs/solution-options/solution-comparison-v0.1-*.md |
/generate-fs | Sau khi chốt solution tại Gate 3 | Thư mục docs/fs/<feature>-v0.1-*/ |
/generate-test-scenarios | Sau khi FS hoàn thiện | docs/test-scenarios/test-scenarios-v0.1-*.md |
/generate-user-guide | Sau khi FS hoàn thiện | docs/user-guide/user-guide-v0.1-*.md |
/review-output | Review bất kỳ artifact nào trước khi duyệt | Report trong chat |
/change-request | Thay đổi yêu cầu sau khi đã có tài liệu | Cập nhật artifacts bị ảnh hưởng |
/publish-confluence | Đẩy artifact đã duyệt lên Confluence | Trang Confluence (tạo hoặc cập nhật) |
5.1 /new-project ​
Khi nào dùng: Trước khi bắt đầu bất kỳ dự án mới nào. Chạy đúng một lần.
Cú pháp:
/new-project 2026-LMS-Nang-cap-thanh-toanFormat tên: YYYY-<BU>-<Ten-ngan>. BU ví dụ: LMS, OPS, HubSpot. Dùng dấu gạch nối, không dấu tiếng Việt, không khoảng trắng.
Nếu không biết tên: Gõ /new-project (không có tên), AI hỏi lần lượt: Năm → BU → Tên ngắn.
Sau khi chạy: Điền thông tin vào project-context.md trước khi bắt đầu workflow.
5.2 /ba-workflow ​
Khi nào dùng: Khi muốn chạy toàn bộ quy trình có hướng dẫn từ đầu đến cuối (recommended cho dự án mới hoặc khi muốn AI dẫn dắt từng bước).
Cú pháp:
/ba-workflow 2026-LMS-Nang-cap-thanh-toanTiếp tục workflow đang dở: Gõ cùng lệnh, AI tự đọc artifacts đã có và hỏi tiếp từ đâu.
Cách trả lời khi AI hỏi "bắt đầu từ đâu":
Bước 1— bắt đầu từ đầuBước 4— nhảy thẳng vào BRDTiếp tục từ Gate 2— AI hiểu và tiếp tục
5.3 /clarify-requirements ​
Khi nào dùng: Khi cần phân tích nhanh input thô mà chưa muốn commit vào workflow chính thức. Cũng dùng khi input quá phức tạp và cần làm rõ trước khi bắt đầu bất cứ thứ gì.
Cú pháp:
/clarify-requirements 2026-LMS-Nang-cap-thanh-toan5.4 /generate-brd ​
Khi nào dùng: Tạo BRD trực tiếp khi đã có requirements đủ rõ, không cần chạy cả workflow từ đầu.
Cú pháp:
/generate-brd 2026-LMS-Nang-cap-thanh-toanCần có sẵn: working/ai-drafts/clarified-requirements-*.md hoặc cung cấp context đầy đủ trong chat.
5.5 /impact-analysis ​
Khi nào dùng: Sau khi BRD đã được Gate 1 duyệt.
Cú pháp:
/impact-analysis 2026-LMS-Nang-cap-thanh-toanLưu ý: Bước 5 (chốt phạm vi liên quan) là bước cần BA tham gia nhiều nhất. Chuẩn bị sẵn danh sách module, màn hình, API liên quan để xác nhận nhanh hơn.
5.6 /compare-solutions ​
Khi nào dùng: Sau khi Impact Matrix đã được Gate 2 duyệt.
Cú pháp:
/compare-solutions 2026-LMS-Nang-cap-thanh-toanNếu đã có định hướng giải pháp, mô tả ngắn gọn trong lệnh hoặc khi AI hỏi:
/compare-solutions 2026-LMS-Nang-cap-thanh-toan
Đã có định hướng: dùng module thi độc lập, không tích hợp vào LMS cũ5.7 /generate-fs ​
Khi nào dùng: Sau khi Gate 3 đã duyệt và solution đã được chốt.
Cú pháp:
/generate-fs 2026-LMS-Nang-cap-thanh-toanLưu ý: Skill này có 4 giai đoạn (A → A2 → B → C) với nhiều điểm dừng để BA confirm. Không rời khỏi máy trong giai đoạn A và A2 vì AI đang chờ phản hồi.
5.8 /generate-test-scenarios ​
Khi nào dùng: Sau khi FS hoàn thiện, để tạo test cases cho QA.
Cú pháp:
/generate-test-scenarios 2026-LMS-Nang-cap-thanh-toan5.9 /generate-user-guide ​
Khi nào dùng: Sau khi FS hoàn thiện, để tạo tài liệu hướng dẫn cho người dùng cuối theo chuẩn Gitbook v3, có thể kèm ảnh chụp màn hình thực tế từ hệ thống.
Cú pháp:
/generate-user-guide 2026-LMS-Nang-cap-thanh-toanNêu thêm đối tượng nếu biết:
/generate-user-guide 2026-LMS-Nang-cap-thanh-toan cho role Admin và Học viênQuy trình AI thực hiện (7 bước):
Bước 0 – Phân tích FS, trình kế hoạch & hỏi thông tin đăng nhập: AI đọc toàn bộ FS, sau đó trình bảng kế hoạch gồm: cấu trúc tài liệu, phạm vi hướng dẫn (sub-module × hành động × role), số tài liệu cần tạo và danh sách màn hình cần chụp (kèm state cụ thể). Trong cùng message đó, AI hỏi luôn:
- URL hệ thống cần chụp màn hình (ưu tiên UAT/staging)
- Tài khoản đăng nhập (email/username) — nên dùng tài khoản test; nhiều role thì mỗi role một tài khoản
- Mật khẩu
BA trả lời OK kèm thông tin đăng nhập để AI bắt đầu. Nếu không muốn chụp ảnh thực tế, gõ skip-screenshot — AI dùng placeholder <!-- TODO: screenshot --> thay thế. Yêu cầu Playwright MCP — đã cấu hình trong ba/.mcp.json, được nạp khi mở Claude Code từ trong ba/.
Bước 1 – Capture màn hình (Playwright): AI tự động mở trình duyệt, đăng nhập, điều hướng và chụp từng màn hình theo danh sách đã chốt. Ảnh lưu tại docs/user-guide/screenshots/ với tên NN-<role>-<mo-ta>.png. Chỉ đọc/mở màn hình — không Submit/Delete trên dữ liệu thật. Màn không chụp được → ghi vào pending-screenshots.md kèm lý do.
Bước 2 – Viết user guide theo template chuẩn SAPP Academy: mỗi tài liệu gồm 4 section cố định (Record of changes / I. Thông tin chung / II. Hướng dẫn chi tiết / III. Lưu ý & Quy tắc nghiệp vụ / IV. Các lỗi thường gặp & Cách xử lý). Trong Section II, mỗi hành động = {% details summary="[Tên hành động]" %} bọc trọn (Kết quả + hint + {% stepper %} + hint success), đóng {% enddetails %} sau success — KHÔNG dùng heading ### N.. Các bước nằm trong {% stepper %}; ảnh dạng  đứng một mình, caption viết trong alt text (không dán dòng *italic* dưới ảnh).
Bước 3 – Tách tài liệu theo role: Nếu có nhiều role, AI tạo file riêng cho từng role (<module>-ops.md, <module>-student.md...), ảnh đặt tên có prefix role.
Bước 4 (tuỳ chọn) – Đóng gói file zip: mặc định bỏ qua — output chuẩn là file md + screenshots/. Chỉ khi BA yêu cầu (vd để import GitBook), AI nén mỗi file md kèm đúng các ảnh nó tham chiếu thành 1 zip cùng tên.
Bước 5 – Tự kiểm tra chất lượng: AI chạy checklist (đủ 4 section, mỗi hành động = expandable {% details %} + stepper theo FS, tag cân bằng, mỗi hành động có ảnh hoặc TODO, đường dẫn ảnh hợp lệ, zip đủ ảnh dấu /...) trước khi trình BA.
Bước 6 – Báo cáo & xin duyệt: AI tóm tắt: tài liệu md (+ zip nếu có) đã tạo, phạm vi, số ảnh đã capture / còn pending. Dùng gate tương tự các command khác: Approved / Approved with Notes / Need Revision. Sau khi Approved, muốn chia sẻ ra ngoài thì chạy /publish-confluence (tuỳ chọn).
Output lưu tại: ba/projects/<project>/docs/user-guide/
| File / Thư mục | Nội dung |
|---|---|
<module>-<role>.md | Tài liệu user guide theo role (đủ 4 section) |
screenshots/NN-<role>-<mo-ta>.png | Ảnh chụp màn hình thực tế |
<module>-<role>.zip | (chỉ khi BA yêu cầu) Gói import: file md + các ảnh được tham chiếu |
pending-screenshots.md | Màn hình chưa capture được: lý do + cách xử lý (nếu có) |
Update mode (Change Request): Khi chạy lại sau Change Request, AI chỉ sửa section/expandable bị ảnh hưởng và capture lại những màn hình thay đổi — không tạo lại từ đầu.
5.10 /review-output ​
Khi nào dùng: Bất cứ khi nào muốn AI review lại một artifact trước khi duyệt chính thức, hoặc khi muốn kiểm tra chất lượng tài liệu đã có.
Cú pháp:
/review-output 2026-LMS-Nang-cap-thanh-toanHoặc mở file cần review trong VS Code trước, rồi gõ /review-output — AI tự nhận ra file đang mở.
Input Readiness Gate (kiểm tra đầu vào trước khi review): mỗi loại tài liệu có input bắt buộc riêng — ví dụ review Test Scenarios hoặc User Guide bắt buộc phải có FS (thiếu → AI dừng và hỏi, không review "chay"); BRD phải tự chứa vấn đề hiện tại / mong muốn / in-out scope (thiếu → tính là finding). Test Scenarios / User Guide viết từ FS phiên bản cũ hơn bản mới nhất sẽ bị flag stale.
Review FS ngoại lai (file FS không sinh từ workflow): AI đọc và tóm tắt FS trước (bài toán, phạm vi, roles, luồng chính, business rules cốt lõi, dữ liệu & tích hợp, trạng thái tài liệu — thuần theo những gì FS viết), rồi chạy ngầm lại chuỗi phân tích (làm rõ yêu cầu → impact analysis → solution check) dựa trên tài liệu bạn cung cấp, tự trả lời open question khi rút được đáp án từ tài liệu, rồi so với FS để tìm phần thiếu / thừa / mâu thuẫn. Đọc phần Tóm tắt FS đầu tiên — nếu AI tóm tắt sai tức là hiểu sai tài liệu, các findings phía sau cần xem lại. Kết quả kèm 2 phụ lục để audit:
- Phụ lục A — nhật ký nguồn AI đã đọc khi phân tích impact (file/section + mục đích đọc)
- Phụ lục B — các open question AI đã tự trả lời (câu trả lời + nguồn + Fact/Assumption)
Câu hỏi mang tính quyết định (scope, trade-off, rule không có nguồn) AI sẽ không tự trả lời — trả về cho bạn trong "Open Questions còn lại".
Output trong chat:
- Status tổng thể: Pass / Pass with Notes / Fail
- Bảng Input Readiness: input nào có / thiếu + giới hạn review
- Tóm tắt FS (khi review FS ngoại lai)
- Bảng findings: Section / Tài liệu hiện viết / Issue / Severity / Recommendation — mỗi finding trích nội dung hiện tại của tài liệu trước, rồi mới chỉ ra issue, để đọc hiểu được ngay mà không phải mở tài liệu gốc
- Phụ lục A + B (khi review FS ngoại lai)
- Decision: Approved / Approved with Notes / Need Revision
5.11 /change-request ​
Khi nào dùng: Khi yêu cầu thay đổi sau khi đã có ít nhất một artifact.
Tự kích hoạt khi BA nói trong chat những cụm từ:
- "tôi có thay đổi yêu cầu"
- "bổ sung yêu cầu"
- "đổi scope"
- "thêm một rule"
- "khách yêu cầu thêm"
Hoặc gõ thủ công:
/change-request 2026-LMS-Nang-cap-thanh-toanSau đó mô tả thay đổi trong chat.
Quy trình AI sẽ làm:
- Ghi nhận CR vào
working/raw-inputs/change-requests.md(CR-001, CR-002...) - Đề xuất re-entry point — tầng thấp nhất bị ảnh hưởng (BRD / Impact / Solution / FS)
- Chờ BA confirm re-entry point trước khi chạy lại
- Cập nhật chỉ phần bị ảnh hưởng, bump MINOR version (v0.2, v0.3...), thêm Change Log
Sau khi chạy lại, mọi Gate sau re-entry point cần được duyệt lại.
5.12 /publish-confluence ​
Khi nào dùng: Sau khi BRD hoặc FS đã được duyệt và muốn publish lên Confluence.
Điều kiện tiên quyết: project-context.md phải có mục Confluence với Space key và Parent Page. Nếu chưa có, AI sẽ hỏi và tự điền vào.
Chỉ publish artifact đã Approved — AI từ chối publish bản còn Draft.
Cú pháp:
/publish-confluence 2026-LMS-Nang-cap-thanh-toanAI sẽ:
- Xác nhận với BA: artifact nào, Space nào, Parent page nào, create hay update
- Chờ BA confirm — BA có thể skip, không bắt buộc publish ngay
- Publish và fetch lại để verify không mất section
- Cập nhật
project-context.mdvới page ID và URL để lần sau update đúng trang
FS: AI tạo 1 trang cha (từ 00-overview.md) + mỗi US một trang con.
6. Mẹo và xử lý vấn đề thường gặp ​
6.1 Mẹo làm việc hiệu quả ​
Luôn nêu tên project trong lệnh khi làm nhiều dự án song song. Nếu không nêu, AI có thể suy nhầm project từ file đang mở trong VS Code.
Điền đầy đủ project-context.md trước khi chạy workflow. Càng nhiều background, AI càng ít câu hỏi qua lại, tiết kiệm thời gian đáng kể.
Đặt tài liệu đầu vào vào đúng folder. Tất cả yêu cầu thô, meeting note, email cần phân tích → đặt vào working/raw-inputs/ trước khi gọi AI.
Trả lời câu hỏi AI không cần format đặc biệt. Viết tự nhiên bằng tiếng Việt là đủ. Ví dụ: "Rule này chỉ áp dụng cho học viên CFA, không áp cho ACCA" — AI tự parse và cập nhật đúng chỗ.
Workflow có thể dừng bất kỳ lúc nào. Đóng VS Code, tắt máy — không sao. Để tiếp tục, mở lại VS Code, gõ /ba-workflow <tên-project>, AI đọc lại artifacts đã có và hỏi tiếp từ đâu.
Khi không chắc bước tiếp theo là gì: Hỏi trực tiếp: "Bước tiếp theo của workflow là gì?" — AI nhìn context hiện tại và trả lời cụ thể.
6.2 Những điều AI không tự làm ​
- Không tự chuyển Gate mà không có BA xác nhận rõ ràng
- Không tự publish Confluence — luôn hỏi BA xác nhận trước
- Không tự resolve conflict phát hiện trong Impact Matrix — chỉ ghi nhận để BA/Tech/PO quyết định
- Không ghi đè file đã có — luôn tạo version mới (v0.2, v0.3...)
- Không bịa thông tin — field chưa biết ghi
❓BA, thông tin chưa chắc ghi Assumption
6.3 Xử lý vấn đề thường gặp ​
AI không tìm thấy project
Nguyên nhân: folder đang mở trong VS Code không phải mind_keep/ba, hoặc chưa tạo project bằng /new-project.
Giải pháp: kiểm tra phần tiêu đề Explorer panel bên trái — phải thấy tên ba. Nếu mở sai, File → Open Folder → chọn lại thư mục mind_keep/ba.
AI hỏi lại câu đã trả lời
Nguyên nhân: quyết định chưa được ghi vào project-decisions.md, hoặc cuộc trò chuyện quá dài làm AI mất context.
Giải pháp: kiểm tra project-decisions.md có ghi quyết định đó chưa. Nếu chưa, thêm vào file rồi nhắc AI: "Quyết định này đã ghi trong project-decisions.md, bạn có thể đọc lại."
BRD còn nhiều Assumption
Đây là hành vi đúng — không phải lỗi. Assumption = thông tin AI suy luận nhưng chưa được BA xác nhận. Đọc danh sách Assumption, xác nhận từng cái. Sau khi BA confirm, AI cập nhật thành Fact.
FS rất nhiều file, khó tìm
FS được tách để dễ quản lý. Cách navigate: mở 00-overview.md để xem bảng US index, tìm US ID cần xem, rồi mở file US-XX-*.md tương ứng từ Explorer panel.
Lỗi "Cannot read file" khi chạy command
Nguyên nhân: tên project trong lệnh không khớp với tên folder thực tế (phân biệt chữ hoa/thường).
Giải pháp: trong Explorer panel, mở thư mục ba/projects/ để xem tên folder chính xác, copy nguyên vào lệnh.
Claude Code không kết nối được (panel trống hoặc báo lỗi)
Giải pháp theo thứ tự:
- Kiểm tra kết nối internet
- Restart VS Code: Ctrl+Shift+P → "Reload Window" → Enter
- Đăng xuất và đăng nhập lại: click biểu tượng tài khoản trong panel Claude Code
- Liên hệ admin nếu vẫn không được
AI đề nghị gõ /compact rồi dừng lại
Đây là hành vi bình thường. Trước hai bước nặng nhất (Impact Matrix và FS), nếu phiên đã dài AI sẽ đề nghị compact để tránh bỏ sót nội dung. BA gõ /compact, sau đó nhắn tiếp tục. Phiên còn ngắn thì có thể bỏ qua và nhắn tiếp tục luôn.
AI không nhận trigger tự động /change-request
Giải pháp: gõ thủ công /change-request rồi mô tả thay đổi trong chat.
6.4 Khi nào dùng skill riêng lẻ thay vì /ba-workflow? ​
| Tình huống | Lệnh khuyên dùng |
|---|---|
| Dự án mới, bắt đầu từ đầu | /ba-workflow |
| Cần làm rõ input nhanh, không commit vào workflow | /clarify-requirements |
| BRD đã có, cần Impact Matrix gấp | /impact-analysis |
| FS đã có, muốn tạo test cases | /generate-test-scenarios |
| Muốn review artifact trước khi họp với stakeholder | /review-output |
| Stakeholder thay đổi yêu cầu giữa chừng | /change-request |
| Muốn đẩy tài liệu đã duyệt lên Confluence | /publish-confluence |
| Tính năng đã chạy nhưng chưa có tài liệu | /document-existing |
| Kiểm tra code có khớp FS không | /review-output (chế độ đối chiếu code) |
6b. Đọc tài liệu trên web ​
Thư mục ba/ cũng là một site tài liệu (VitePress): mọi file .md thành trang web, có menu theo project, tìm kiếm toàn văn, hiển thị đúng cú pháp GitBook ({% hint %}, {% stepper %}, {% details %}, {% tabs %}, {% cards %}) và ảnh chụp màn hình.
| Việc | Lệnh (trong ba/) |
|---|---|
| Xem trên máy mình, tự reload khi sửa | npm install (lần đầu) rồi npm run dev → http://localhost:5173 |
| Kiểm tra site build được trước khi push | npm run build |
| Build + deploy tay trên VPS | cp env.example .env (điền port, user/mật khẩu) rồi ./deploy.sh --pull — xem ./deploy.sh --help |
- Người khác đọc qua URL site sau khi deploy (
ci-ba.yml, bật bằng secretBA_PORT; khoá bằngBA_DOCS_USER/BA_DOCS_PASSWORD). - Link trong tài liệu trỏ ra ngoài
ba/(codebe/,shared/api-docs/…) tự mở trên GitHub. - Ảnh chưa chụp (pending) hiện thành ô "Ảnh chưa có", không làm hỏng site.
- Không cần sửa cấu hình khi thêm tài liệu — push lên
mainlà site cập nhật.
7. Lưu tài liệu vào git ​
Tài liệu BA nằm trong repo mind_keep (ba/projects/), commit chung với code. Thay đổi chỉ trong ba/ không kích hoạt CI nào (ci-be / ci-fe / ci-app lọc theo path).
bash
git pull # lấy bản mới nhất (gồm cả api-docs / code mới của các lane)
git add ba/ # chỉ stage thư mục ba/
git commit -m "docs(ba): <project> – BRD v0.2"
git pushChỉ
git add ba/— không commit lẫn file của lane khác, và không bao giờ commitsecrets.envở root.
Conflict: mở file trong VS Code → Accept Current / Incoming / Both → lưu → git add ba/ && git commit.
8. Phụ lục ​
8.1 Glossary ​
| Thuật ngữ | Giải thích |
|---|---|
| Gate | Điểm dừng bắt buộc chờ BA duyệt trước khi tiếp tục bước tiếp theo. Có 4 gate trong workflow (BRD / Impact / Solution / FS). |
| Blocking question | Câu hỏi mà nếu chưa có đáp án thì AI không thể tạo artifact chính xác. AI dừng lại và chờ BA trả lời. |
| Fact | Thông tin đã được BA xác nhận là đúng. |
| Assumption | Thông tin AI suy luận nhưng chưa được BA xác nhận. BA cần review và confirm. |
| Open Question (OQ) | Câu hỏi chưa có đáp án, cần BA hoặc stakeholder giải đáp. |
| Recommendation | Đề xuất của AI dựa trên phân tích — không phải quyết định, BA phải confirm. |
| CR (Change Request) | Yêu cầu thay đổi sau khi đã có tài liệu. Trigger workflow chạy lại từ tầng thấp nhất bị ảnh hưởng. |
| Re-entry point | Bước mà Change Request bắt đầu ảnh hưởng — workflow chạy lại từ đây trở xuống. |
| Related Features & Docs Map | Bảng AI lập ở Bước 5, liệt kê tất cả module/màn hình/entity/API liên quan. BA phải review và confirm trước khi AI dựng Impact Matrix. |
| Compact | BA gõ /compact (khi AI đề nghị) để dọn context window trước các bước nặng (Impact Matrix, FS), rồi nhắn tiếp tục. |
| Handover | File docs/handover/*.md tách việc triển khai theo lane BE / FE / APP, tạo sau Gate 4. |
| Lane | Một trong bốn thư mục làm việc của monorepo (be/, fe/, app/, ba/). Lane ba/ chỉ ghi trong ba/. |
8.2 Naming convention cheat sheet ​
| Artifact | Format tên file | Ví dụ |
|---|---|---|
| BRD | brd-v0.1-YYYYMMDD.md | brd-v0.1-20260612.md |
| Impact Matrix | impact-matrix-v0.1-YYYYMMDD.md | impact-matrix-v0.1-20260614.md |
| Solution Comparison | solution-comparison-v0.1-YYYYMMDD.md | solution-comparison-v0.1-20260616.md |
| FS (thư mục) | <feature>-v0.1-YYYYMMDD/ | exam-management-v0.1-20260618/ |
| FS Overview | 00-overview.md | (trong thư mục FS) |
| FS User Story | US-XX-<slug>.md | US-01-tao-de-thi.md |
| Test Scenarios | test-scenarios-v0.1-YYYYMMDD.md | test-scenarios-v0.1-20260620.md |
| User Guide | user-guide-v0.1-YYYYMMDD.md | user-guide-v0.1-20260622.md |
| Handover | handover-v0.1-YYYYMMDD.md | (trong docs/handover/) |
| Change Requests | change-requests.md | (append-only, không đổi tên) |
| Clarified Requirements | clarified-requirements-YYYYMMDD.md | (trong working/ai-drafts/) |
8.3 Thứ tự đọc file của AI ​
Khi bắt đầu bất kỳ lệnh nào, AI đọc theo thứ tự ưu tiên này:
projects/<project>/project-context.mdprojects/<project>/project-decisions.mdprojects/<project>/working/(raw-inputs, open-questions, meeting-notes)projects/<project>/docs/(artifacts đã có)system-profile.md→ nguồn sự thật của hệ thống đích (API doc, code — chỉ đọc) +knowledge-base/(KB SAPP)_workflow/templates/(mẫu tài liệu) +_workflow/checklists/(tự kiểm tra)
Điền đầy đủ file 1 và 2 là cách hiệu quả nhất để giảm số câu hỏi AI phải hỏi lại.