DOCUMENTATION / FRAMEWORK GUIDELINE
A PRACTICAL GUIDE TO AI-DRIVEN DELIVERY

Từ ý tưởng.
Đến living truth.

Bạn định hướng sản phẩm. AI thực hiện từng sprint. Mỗi bước tiến được xác nhận bằng tài liệu, code và bằng chứng.

Bắt đầu với BSA Khám phá cách gate hoạt động
THE BSA LOOPAGENT-DRIVEN
YOUstart sprint 1
01
Định nghĩaBrainstorm · Product · Arch · Design
02
Thực hiện & kiểm chứngPlan · Implement · Test · Review
03
Living truthReconcile → Seal → Phiên bản chuẩn
Mỗi kết quả đều có nguồn gốc.
01 lần setupSau đó, chỉ cần trò chuyện
Trong một dự ánCode, tài liệu, skill và workflow
Bằng chứng trướcKhông hoàn thành chỉ vì có file
02 / GET STARTED

Một lần setup.
Phần còn lại, nói với agent.

1

Tạo project-meta

Chạy setup trong thư mục framework. Mặc định tạo project-meta/; bạn cũng có thể truyền đường dẫn đích.

2

Mở đúng thư mục gốc

Mở project-meta trong Claude/Codex để agent đọc hướng dẫn và skill của dự án.

3

Gửi mục tiêu sprint

Agent tự cấu hình kiểm tra phù hợp, thực hiện các phase và lưu tiến độ. Bạn không cần tự gọi CLI sau setup.

TERMINAL · CHỈ MỘT LẦN
$ bash setup.sh

Hoặc: bash setup.sh /path/to/project-meta

TRONG CUỘC HỘI THOẠI VỚI AGENT

start sprint 1: xây ứng dụng quản lý công việc cá nhân

Tôi sẽ bắt đầu sprint 1 và thực hiện đến khi sẵn sàng đóng.

Python 3.10+ · macOS / Linux · Không cần cài package để chạy BSA.

Bạn kiểm soát phạm vi. start dừng khi sẵn sàng đóng. Nhắn seal sprint 1 để xuất bản; hoặc thêm “và tự đóng khi xong” ngay từ đầu.
03 / PROJECT MAP

Mọi thứ ở đúng chỗ.

Một thư mục gốc có thể di chuyển cùng dự án. Tài liệu ở docs; ứng dụng ở apps; công cụ và năng lực AI được lưu cục bộ.

project-meta/ PROJECT ROOT
docs/ Tài liệu dự án

framework/ Workflow & Guideline

sprints/S001/ Tài liệu + evidence

.truth/versions/ Phiên bản đã seal

truth/ Chuẩn hiện tại

apps/ Ứng dụng & code

services/admin-bff/

frontends/admin-portal/

shared/ Thư viện dùng chung

tools/ & scripts/ Công cụ dự án

tools/bsa/ Runtime + template độc lập

scripts/ Build / kiểm tra liên ứng dụng

.agents/ & .claude/ Skill project-scoped

.agents/skills/bsa-*/

.claude/skills/bsa-*/

.bsa/ State & cấu hình vận hành
AGENTS.md · CLAUDE.md · bsa.sh
BACKEND

services/admin-bff

API, worker hoặc backend phục vụ một frontend. Mỗi service sở hữu source, dependency và test.

FRONTEND

frontends/admin-portal

Web hoặc mobile client có ranh giới rõ ràng. Test giao diện nằm cùng ứng dụng.

SHARED

Chia sẻ có chủ đích

Đặt thư viện dùng chung trong apps/shared. Với Node.js, agent thiết lập pnpm workspace khi cần.

admin-bff và admin-portal là ví dụ tổ chức, không phải ứng dụng đã được setup tạo sẵn.

04 / SPRINT LIFECYCLE

Mỗi phase có một hợp đồng.

Chọn một phase để xem công việc, đầu ra và điều kiện hoàn thành.

04PHASE CONTRACT

Design

ĐẦU RA
    GATE HOÀN THÀNH

    BẠN CHỈ CẦN NHẮNdesign sprint 2
    05 / CONVERSATIONAL CONTROL

    Ý định của bạn.
    Hành động của agent.

    Không cần nhớ cú pháp terminal. Agent hiện tại thực hiện công việc theo phạm vi bạn yêu cầu.

    /
    Không tự mở rộng yêu cầu. “Chỉ brainstorm”, “dừng sau plan”, “chỉ ghi feedback” và “chỉ xem trước seal” đều giới hạn công việc tương ứng.
    06 / STATE & QUALITY GATES

    Không bỏ qua bước.
    Không dùng bằng chứng cũ.

    Trạng thái được lưu trên đĩa, không phụ thuộc trí nhớ của phiên chat. Framework trả về phase cần làm tiếp và kiểm tra prerequisite trước khi cho phép chuyển bước.

    THỬ TRỰC TIẾP

    Sprint 2 đang ở design.

    MÔ PHỎNG

    Đây là mô phỏng trên trang, không chạy agent, test thật hoặc thay đổi dự án của bạn.

      S002 / DESIGN

      Nếu yêu cầu implement ngay lúc này, gate sẽ yêu cầu hoàn thành design và plan trước.

      pendingin_progresscompletedstalefailed

      Code thay đổi?
      Implement, test, review và reconcile hết hiệu lực. Agent kiểm chứng lại trước khi đóng sprint.

      Feedback mới?
      Các gate trước đó được vô hiệu hóa bảo thủ. Nội dung không đổi có thể tái sử dụng, nhưng cần đánh giá lại.

      QUALITY REVIEW

      Validate từng phase

      Gõ validate design sprint 2. Agent đánh giá nội dung theo tiêu chí của phase, ghi findings có bằng chứng và kiểm tra lại sau khi sửa. Validate không tự chuyển phase hoặc đóng sprint.

      Lỗi đơn giản → AI tự sửa.

      Thiếu trạng thái, mô tả mâu thuẫn với spec đã chốt, hoặc thiếu bằng chứng: agent sửa trong phạm vi đã thống nhất và validate lại.

      Quyết định quan trọng → bạn chọn.

      Thay đổi scope, dữ liệu, bảo mật, chi phí hay kiến trúc khó đảo ngược: agent trình bày phương án và tradeoff. Pipeline chờ câu trả lời; ghi quyết định chưa đồng nghĩa đã xử lý xong.

      Findings được lưu trong docs/sprints/<id>/validation.json. Report mới không xóa finding còn mở. Agent phải áp dụng quyết định, bổ sung evidence và validate lại; phase phụ thuộc và seal bị chặn cho đến khi đạt gate.

      Đánh giá chất lượng do agent thực hiện; runtime kiểm tra cấu trúc, digest và evidence. Validate không thay thế lệnh test thực tế.

      Assessment là gate bắt buộc.

      complete <phase> và seal từ chối phase không có assessment hiện hành đúng input_digest, và từ chối assessment do chính tác giả của phase nộp: phải chấm bằng một danh tính khác. Runtime ghi lại danh tính người chấm — đó là bản ghi trách nhiệm, không phải xác thực ai thực sự chạy phiên nào. Test cũng vậy: test --run cung cấp bằng chứng, assessment hoàn thành phase.

      07 / THE LIVING TRUTH

      Tài liệu chuẩn phải phản ánh
      điều đã thực sự được xây.

      BASELINE

      Truth đã seal

      Hành vi hiện tại
      Quyết định còn áp dụng

      VERIFIED CHANGE

      Sprint mới

      Yêu cầu đã triển khai
      Code, test, review

      RECONCILE → SEAL

      Truth phiên bản mới

      Đầy đủ · Có nguồn gốc
      Giữ nguyên lịch sử

      Agent hợp nhất nội dung.

      Product, spec, architecture, design, contracts và quyết định được đối chiếu với kết quả thực tế. Không đưa ý tưởng chưa triển khai vào tài liệu chuẩn. Không xóa ngầm yêu cầu cũ.

      CLI kiểm tra và xuất bản.

      Seal kiểm tra gate, lưu hash của source và evidence, tạo snapshot rồi chuyển con trỏ truth. Journal cho phép phục hồi khi bị ngắt. Plan, task và feedback ở lại lịch sử sprint.

      MỘT NGUỒN CHUẨN, NHIỀU PHIÊN BẢN
      docs/truth  →  docs/.truth/versions/S002
                  ├── S001/  giữ nguyên
                  └── S002/  chuẩn hiện tại
      08 / PROJECT-SCOPED BY DEFAULT

      Năng lực đi cùng dự án.

      Setup cài bộ skill BSA vào cả hai thư mục khám phá. Workflow dùng chung nằm trong docs/framework. Không cần một bản cài skill ở máy cá nhân.

      CODEX / AGENT.agents/skills/bsa-*/10 skill cục bộ
      CLAUDE.claude/skills/bsa-*/Cùng nguồn đóng gói
      WORKFLOWdocs/framework/workflows/Một quy trình chung
      RUNTIMEtools/bsa/Python chuẩn, độc lập
      Không cần global skill. Bộ BSA có skill điều phối sprint và 9 skill phase. BMAD, Spec-Kit, AgentKit là tích hợp tùy chọn, không được tự động cài; nếu bổ sung, toàn bộ tài nguyên cần nằm trong project.
      09 / GOOD TO KNOW

      Những điều cần biết.

      Chỉ nhắn “start sprint 1” đã đủ chưa?

      Đủ để agent xác định hoặc mở sprint. Nếu mục tiêu chưa có trong hội thoại hoặc kế hoạch, agent sẽ hỏi một câu về mục tiêu. Agent không tự chọn một yêu cầu kinh doanh ngẫu nhiên.

      Tôi có cần cấu hình runner cho Claude/Codex không?

      Không khi làm việc trực tiếp trong hội thoại. Agent hiện tại thực hiện các bước. Runner CLI là lựa chọn nâng cao khi bạn muốn chạy ngoài hội thoại, cần CLI nhà cung cấp đã được cài và đăng nhập.

      Chuyển sang phiên chat mới có mất tiến độ không?

      Trạng thái nằm trong .bsa/state.json và .bsa/sprints; tài liệu và evidence nằm trong docs/sprints. Nhắn “continue sprint 2”; agent đọc trạng thái và tiếp tục từ bước còn thiếu hoặc hết hiệu lực.

      Gate có bảo đảm mọi quyết định của AI đều đúng không?

      Không. CLI kiểm tra cấu trúc, tính mới của bằng chứng và kết quả lệnh. Chất lượng nội dung, độ bao phủ test và review vẫn cần agent đánh giá thực chất. CLI không khóa quyền sửa file trực tiếp và không phải ranh giới bảo mật chống việc cố tình sửa validator.

      Đây có phải lệnh shell dùng ngôn ngữ tự nhiên?

      Không. Lệnh chat được agent diễn giải theo AGENTS.md và workflow commands.md. Agent tự gọi CLI có cấu trúc bên dưới. Trang mô phỏng này chỉ giải thích hành vi, không điều khiển một sprint thật.

      Tài liệu sprint cũ có bị xóa khi mở sprint mới?

      Không. Mỗi sprint có thư mục riêng; snapshot truth cũ được giữ nguyên. Audit phát hiện thay đổi lịch sử. Lưu state, tài liệu, evidence và truth versions cùng source trong Git.