BA-kit
Foundations

Artifacts và đầu ra

plans/ {slug}-{date}/ PROJECT-HOME.md COLLAB-HOME.md 01_intake/ 02_backbone/ project-memory.md project-memory/ 03_modules/{module_slug}/ MODULE-HOME.md review-packet.md 04_compiled

Artifacts và đầu ra

Cấu trúc chính

plans/
  {slug}-{date}/
    PROJECT-HOME.md
    COLLAB-HOME.md
    01_intake/
    02_backbone/
      project-memory.md
      project-memory/
    03_modules/{module_slug}/
      MODULE-HOME.md
      review-packet.md
    04_compiled/

designs/
  {slug}/DESIGN.md

Artifact theo lifecycle

ArtifactMục đích
PROJECT-HOME.mdDashboard BA-facing cho trạng thái dự án, next step, câu hỏi cần chốt và prompt nhanh
COLLAB-HOME.mdDashboard cộng tác cho module ownership, review status, blocker và next action
intake.mdChuẩn hóa input và bộc lộ gap
plan.mdKế hoạch thực hiện và các gate
backbone.mdSource of truth sau scope lock
project-memory.mdBộ nhớ compact để tái nạp vocabulary, decisions, assumptions và corrections đã chấp nhận
project-memory/index.mdNavigator cho memory shard tree, không chứa chi tiết nghiệp vụ dài
project-memory/hot/*.mdShard global cho canonical vocabulary, approved decisions và push-back triggers
project-memory/warm/modules/{module_slug}.mdShard theo module cho context module-local
project-memory/log.mdLog audit tùy chọn, không đọc mặc định
project-memory/cold/Archive cho facts đã supersede, không đọc mặc định
MODULE-HOME.mdDashboard riêng cho Module BA, gồm scope được sửa, checklist trước review và dependency
review-packet.mdGói gửi Lead BA review, gồm summary, touched artifacts, trace IDs và cross-module risk
frd.mdMô tả functional requirements theo cấu trúc formal
user-stories.mdEpic / feature / story với acceptance criteria
srs.mdĐặc tả hành vi hệ thống, use case, screen, NFR
DESIGN.mdDesign governance ở mức project
wireframe-input.mdConstraint pack ở mức screen
wireframe-map.mdChecklist handoff để user attach mockup
wireframe-state.mdTrạng thái explicit của wireframe flow
compiled-frd.htmlBản HTML để review/chia sẻ
compiled-srs.htmlBản HTML để review/chia sẻ

Quy ước diagram

  • Swimlane: dùng PlantUML.
  • Sequence diagram: dùng Mermaid.
  • Data Flow Diagram (DFD): dùng Mermaid.
  • Entity Relationship Diagram (ERD): dùng Mermaid.
  • Flow đơn giản không cần swimlane: có thể dùng Mermaid.

Trong packaged HTML, Mermaid được render trực tiếp trong browser; PlantUML được xuất thành SVG-backed image để stakeholder copy vẫn xem được ổn định.

DESIGN.md dùng để làm gì

DESIGN.md không phải mockup cuối. Nó khóa:

  • visual tone
  • màu sắc và typography
  • layout principles
  • navigation schema
  • shared components
  • responsive behavior
  • anti-patterns

Wireframe handoff pack

BA-kit tách rõ:

  • BA-kit chuẩn bị constraint và mapping
  • user/designer tự tạo mockup
  • mockup được attach lại vào SRS

Cách làm này giữ mockup không trở thành source of truth.

Collaboration artifacts

Commit dcb4b9f bổ sung lớp artifact cộng tác để BA team không phải bắt đầu bằng branch/PR:

  • PROJECT-HOME.md giúp user non-tech biết dự án đang ở đâu, bước tiếp theo là gì, agent sẽ chạy workflow nào.
  • COLLAB-HOME.md giúp Lead BA thấy module owner, trạng thái BA, trạng thái review, blocker và next action.
  • MODULE-HOME.md giúp Module BA biết phạm vi được sửa, phần không được tự sửa và checklist trước review.
  • review-packet.md hoặc module review packet giúp gửi thay đổi cho Lead BA review trước khi cần GitHub PR thật.

Các artifact này là dashboard và coordination layer. Khi có mâu thuẫn, source of truth vẫn là backbone.md, intake.md, project memory canonical và module artifacts tương ứng.

Project memory modes

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

  • compact: chỉ có project-memory.md, phù hợp dự án đơn giản hoặc single-module.
  • shard: có thêm project-memory/ với index.md, hot/warm/cold shards và optional log.md, phù hợp dự án nhiều module, nhiều owner hoặc cần delegation.

Nguyên tắc quan trọng:

  • backbone.md vẫn là source of truth chính.
  • project-memory/index.md chỉ điều hướng đến shard liên quan, không được trở thành tài liệu monolith thứ hai.
  • log.md và cold/ không được đọc mặc định; chỉ đọc khi có lý do audit/escalation rõ ràng.
  • Memory được dùng để giảm drift, không dùng để ghi đè artifact canonical.

Trạng thái wireframe

Giá trị hợp lệ:

  • completed
  • skipped
  • not-applicable
  • missing

Trạng thái collaboration

Trạng thái module hợp lệ:

  • unassigned
  • assigned
  • in-progress
  • ready-for-review
  • changes-requested
  • approved
  • integrated
  • blocked

Trạng thái review hợp lệ:

  • none
  • local-packet
  • draft-pr
  • review-requested
  • changes-requested
  • approved
  • merged
  • conflict

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

Raw input -> Intake + Gap Analysis -> PROJECT-HOME.md -> Requirements Backbone -> Project Memory -> COLLAB-HOME.md / MODULE-HOME.md khi có teamwork -> FRD / User Stories -> SRS ->

Project memory và runtime parity

BA-kit dùng project memory để giữ context nghiệp vụ ổn định trên disk, không phụ thuộc vào memory tạm thời của từng runtime. Mục tiêu là giảm drift khi rerun artifact, đổi từ Claud

On this page

Artifacts và đầu raCấu trúc chínhArtifact theo lifecycleQuy ước diagramDESIGN.md dùng để làm gìWireframe handoff packCollaboration artifactsProject memory modesTrạng thái wireframeTrạng thái collaboration