AI SDLC BA Engine (ai-sdlc-ba-engine)

Hệ Điều Hành Phân Tích & Đặc Tả Phần Mềm Đa Định Dạng dành cho AI Agent (Copilot, Claude Code, Cursor...). Hướng dẫn agent phỏng vấn người dùng, phân tích quy trình nghiệp vụ, mô hình hóa và lập đặc tả đa định dạng (BRD/SRS/TDD/JSON Spec/Playwright E2E Specs).

Cấu trúc thư mục

BA-SKILL/
├── .github/
│   ├── copilot-instructions.md       # Global Instructions tự động nạp cho VS Code Copilot Agent
│   └── agents/
│       ├── ba-interviewer.agent.md   # Custom Agent chuyên trách Phỏng vấn & Modeling
│       ├── spec-architect.agent.md   # Custom Agent chuyên trách Kiến trúc & Đặc tả (SRS/TDD/JSON)
│       ├── qa-automation.agent.md    # Custom Agent chuyên trách Sinh Test Suite Playwright E2E
│       └── dev-executor.agent.md     # Custom Agent chuyên trách Thực thi Code, Sync Spec & Changelog
├── .agent.md                         # Cấu hình Custom Agent Mode cho BA Engine
├── .instructions.md                  # System Rules ngắn gọn cho workspace
├── SKILL.md                          # Quy trình phỏng vấn & điều phối chính của BA Agent
├── document.html                     # Trang web trực quan hóa tài liệu đặc tả & sơ đồ Mermaid (Zoom/Pan modal)
└── references/
    ├── analysis-frameworks.md        # Các khung phân tích (SWOT, PESTLE, quy trình 8 bước, UAT)
    ├── architecture-guide.md          # Hướng dẫn đánh giá & lựa chọn Monolithic vs Modular vs Microservices
    ├── codebase-organization.md      # Quy chuẩn cấu trúc thư mục Domain-Driven Modular Layout
    ├── cost-risk.md                  # Phân tích hạ tầng, chi phí & rủi ro
    ├── doc-coauthoring-integration.md# Quy trình đồng sáng tác & kiểm thử tài liệu với Sub-Agent Reader
    ├── example-walkthrough.md        # Kịch bản mẫu một phiên làm việc đầy đủ
    ├── modeling.md                   # Hướng dẫn vẽ sơ đồ Mermaid (As-Is/To-Be, BPMN, Sequence)
    ├── output-agent-prompt.md        # Template xuất ra Agent Prompt (dành cho AI Dev)
    ├── output-brd-srs.md             # Template xuất ra tài liệu BA chuẩn (BRD / SRS / FRS)
    ├── output-json-spec.md           # Template Machine-Readable JSON Spec (Ràng buộc từng hàm/logic cho AI Agent)
    ├── output-tdd.md                 # Template xuất ra tài liệu thiết kế kỹ thuật & Security (TDD cho Tech Lead/Dev)    ├── skill-stitch.md               # Tích hợp trực tiếp Stitch UI Generator Skill vào đặc tả    ├── stitch-codegraph-mockup.md    # Hướng dẫn tích hợp Code Graph (đọc code) & Stitch (tạo UI mockup)
    ├── testing-playwright.md         # Quy trình tạo kịch bản kiểm thử E2E tự động bằng Playwright từ AC
    └── update-protocol.md            # Quy trình cập nhật & phân tích ảnh hưởng cho tài liệu cũ

Quy trình 3 Bối cảnh Phát triển (Project Contexts)

BA Skill tự động chuyển đổi luồng xử lý tùy theo bối cảnh dự án:

1. 🟢 Dự án rỗng (Mới từ đầu): Phỏng vấn thu thập yêu cầu người dùng $\rightarrow$ Mô hình hóa To-Be $\rightarrow$ Vẽ UI Mockup bằng Stitch $\rightarrow$ Xuất tài liệu đặc tả (BRD/SRS/TDD/Document Root).
   • ⚡ Ultra Fast-Path (Dự án nhỏ / MVP < 4 tuần): Tự động cắt bỏ 70% thủ tục rườm rà. Chỉ cần 1-2 câu hỏi chốt flow chính $\rightarrow$ 1 Sơ đồ To-Be $\rightarrow$ Xuất ngay 1 file đặc tả duy nhất.
2. 🟡 Dự án đã có tài liệu: Đọc lại tài liệu đặc tả cũ $\rightarrow$ Phân tích ảnh hưởng (Impact Analysis) $\rightarrow$ Cập nhật/thêm feature mới $\rightarrow$ Ghi Changelog & bump version tài liệu.
3. 🔵 Dự án có Code nhưng thiếu Tài liệu: Dùng Code Graph quét thông minh toàn bộ codebase (tiết kiệm token) $\rightarrow$ Reverse-engineer tạo tài liệu đặc tả ban đầu $\rightarrow$ Tiếp tục làm feature mới.

🛠️ Kiểm tra Công cụ (Prerequisite Check): Ngay ở Phase 0, Agent sẽ tự động rà soát sự hiện diện của Code Graph, Stitch MCP, và Playwright. Nếu thiếu, Agent sẽ chủ động gợi ý người dùng cài đặt hoặc chuyển hướng sang giải pháp thay thế tương đương.

🤖 Ghi vết AI Model (AI Attribution): Mỗi tài liệu đặc tả, kịch bản test hay bản cập nhật Changelog đều được ghi vết chính xác tên AI Model đã thực thi (vd: Copilot 3.6 low, Claude 3.5 Sonnet, GPT-4o).

⚠️ Nguyên tắc bắt buộc: Sau khi hoàn thành task, sửa đổi feature lớn hoặc thêm tính năng mới, Agent luôn phải tự động tạo/cập nhật lại file đặc tả (Spec), bắt buộc ghi log chi tiết vào mục Changelog (phiên bản, lý do, tác động, tên AI Model) để đảm bảo khả năng truy vết hoàn hảo.

Cách sử dụng

Kích hoạt skill bằng cách đưa câu lệnh hoặc yêu cầu nghiệp vụ cho AI Agent:

• "Bắt đầu phân tích yêu cầu làm ứng dụng bán hàng"
• "Tôi muốn viết tài liệu SRS cho hệ thống CRM"
• "Tạo agent prompt từ ý tưởng làm web đặt lịch"
• "Vẽ quy trình nghiệp vụ As-Is / To-Be cho bài toán này"