Cách BA-kit hoạt động

BA-kit vận hành theo một lifecycle có gate — mỗi bước chỉ chạy khi bước trước đã sẵn sàng. Cơ chế này giống như dây chuyền sản xuất: trạm sau không chạy khi trạm trước chưa xong. Nhờ vậy, tài liệu sinh ra luôn nhất quán và truy ngược được về nguồn.

Lifecycle tổng quan

Input thô (file yêu cầu, PDF, ghi chú)
    |
    v
1. INTAKE — Chuẩn hóa input, phát hiện gap
    |
    v
2. OPTIONS (nếu cần) — So sánh các hướng giải pháp
    |
    v
3. BACKBONE — Khóa source of truth cấp dự án
    |
    v
4. MODULE ARTIFACTS — Sinh tài liệu theo module
   (stories → FRD → SRS canon → wireframes)
    |
    v
5. COMPILE — Tổng hợp SRS từ source set
    |
    v
6. PACKAGE — Đóng gói HTML để bàn giao

Ngoài ra còn có reverse lane cho dự án đã có code/hệ thống: reverse → baseline lock → backbone → SRS.

Cấu trúc thư mục output

Mọi output của BA-kit nằm trong plans/{slug}-{date}/:

plans/warehouse-rfp-260529-1030/
├── PROJECT-HOME.md               # Dashboard cho BA: đang ở đâu, làm gì tiếp
├── COLLAB-HOME.md                # Dashboard cộng tác: ai làm module nào
├── 00_source/                    # Input đã extract (nếu input lớn)
│   ├── summary.md
│   ├── manifest.json
│   └── chunk-index.md
├── 01_intake/                    # Intake + plan
│   ├── intake.md
│   ├── plan.md
│   └── options/                  # Các phương án giải pháp (nếu có)
├── 02_backbone/                  # Source of truth cấp dự án
│   ├── backbone.md
│   ├── backbone-index.md
│   ├── common-rules.md           # Rule dùng chung (CR-*)
│   ├── message-list.md           # Message dùng chung (MSG-*)
│   ├── shared-shell-contract.md  # Shared shell/portal/menu contract
│   ├── project-memory.md         # Bộ nhớ dự án (compact, 1 file)
│   └── project-memory/           # Bộ nhớ dự án (shard, nhiều module)
│       ├── index.md
│       ├── hot/                   # Global hot shards
│       ├── warm/modules/          # Per-module warm shards
│       └── cold/                  # Archived cold shards
├── 03_modules/                   # Mỗi module một thư mục
│   └── auth-flow/
│       ├── MODULE-HOME.md        # Dashboard riêng cho Module BA
│       ├── frd.md
│       ├── userstories/          # User story canon (từng file)
│       ├── usecases/             # Use case canon (từng file)
│       ├── ascii-screen/         # Screen canon với ASCII wireframe
│       ├── srs/                  # SRS slices (canon source set)
│       ├── srs-index.md          # SRS navigator cho agent
│       ├── srs.md                # SRS đã compile
│       ├── srs-compile-receipt.json  # Compile receipt
│       ├── data/                 # Optional data/ERD canon
│       │   └── erd.md
│       ├── wireframes/           # Legacy wireframe artifacts
│       ├── qc-review/            # QC review reports
│       └── tool-lanes/           # Tool lane artifacts
│           └── figma-make/
│               ├── screen-field-contract.yaml
│               ├── make-guidelines.md
│               └── make-prompt-pack.md
├── 04_compiled/                  # Bàn giao
│   ├── compiled-frd.html
│   └── compiled-srs.html
├── figma-sync/                   # Figma sync reports
│   ├── figma-sync-report.md
│   └── figma-mismatch-report.md
└── delegation/                   # Review packet (nếu có team)
    └── review-packets/

Ngoài ra, designs/{slug}/DESIGN.md nằm ngoài plans/, ở thư mục gốc của repo — đây là nơi lưu quyết định thiết kế của dự án.

10 nguyên tắc vận hành

1. Backbone-first

Sau intake, backbone.md là source of truth chính. Mọi artifact sau phải bám theo backbone. Giống như xây nhà — backbone là móng, mọi thứ khác xây trên đó.

2. Gated emission

Không phải dự án nào cũng cần mọi artifact. BA-kit chỉ sinh FRD, stories, SRS khi điều kiện phù hợp. Dùng hybrid làm mode mặc định — vừa đủ, không thừa.

3. Index-first navigation

Với artifact lớn, BA-kit không đọc toàn bộ. Nó đọc index trước, giống như bạn xem mục lục sách trước khi đọc:

• chunk-index.md → chọn chunk cần đọc
• backbone-index.md → chọn section cần đọc
• Source set index → chọn item cần xử lý

4. Project memory không thay backbone

project-memory.md ghi nhớ vocabulary, decision, assumption đã chốt — giống như sổ tay ghi chép. Nhưng backbone.md vẫn là source of truth. Memory giúp chống drift, không thay thế backbone.

5. Impact-first cho thay đổi

Khi stakeholder đổi requirement, đừng sửa thẳng SRS. Chạy impact trước để biết chính xác file nào bị ảnh hưởng. Giống như bạn kéo một sợi dây — cần biết nó dính vào những đâu trước khi kéo.

6. Source set → Compile

Sửa behavior trong source set (userstories/, usecases/, ascii-screen/, srs/), sau đó compile lại srs.md. Không sửa thẳng srs.md khi source set đã tồn tại. Giống như sửa bản thảo, không sửa bản in.

7. Shared rules trước, module reference sau

CR-* và MSG-* phải được khai báo ở 02_backbone/ trước. Module chỉ được reference, không tự định nghĩa. Một nhà một nóc.

8. Figma sync một chiều

Figma sync đọc từ SRS source set và ghi ra figma-sync/. Nó không bao giờ được sửa SRS source set. Nếu Figma khác canon → sửa canon trước, sync lại sau.

9. BA-friendly collaboration

Team BA dùng ba-collab để nhận module, gửi review, approve — bằng tiếng Việt tự nhiên. Git branch/PR là việc của agent, không phải thứ BA phải tự làm. Bạn không cần biết Git sâu.

10. Runtime-neutral

Claude Code, Codex, Antigravity có syntax khác nhau nhưng phải giữ cùng behavior: path resolution, prerequisite check, overwrite approval, impact routing. Chọn runtime bạn quen, behavior không đổi.

Memory model

BA-kit có 2 chế độ memory:

cold/ không được đọc mặc định — chỉ đọc khi cần tra cứu lịch sử.

Tiếp theo

• Danh sách skill — 11 skill và cách dùng
• Hướng dẫn từng bước — flow thực tế
• Collaboration — làm việc nhóm với BA-kit