Kiến trúc Hybrid 3-File (v1.5.3)

Hybrid 3-File Model giải quyết bài toán “Lãng phí Token vs. Mất trí nhớ” cho AI Agent khi quản lý tác vụ. Thay vì ép agent đọc toàn bộ backlog mỗi phiên, công việc được phân phối qua 3 tệp chuyên biệt.

🌉 Chiếc cầu nối giữa hai thế giới tư duy

Mô hình này đóng vai trò là “chiếc cầu nối” giữa:

• Tư duy ngắn hạn (AI Agent): Cần sự tập trung cao độ, dữ liệu đầu vào cực gọn để tránh nhiễu và lãng phí token.
• Tư duy dài hạn (Con người): Cần lưu trữ đầy đủ lịch sử, kế hoạch vĩ mô và bằng chứng hoàn thành để quản trị dự án.

📦 Ba thành phần cốt lõi

Hệ thống vận hành xoay quanh 3 tệp tin tại thư mục artifacts/tasks/:

artifacts/tasks/
├── backlog.md          # 📌 Nguồn Sự Thật — single source of truth
├── sprint-current.md   # 🔥 Hot Lane — bộ đệm ghi trực tiếp bởi agent
└── done.md             # ✅ Kho Lưu Trữ — nhóm theo plan, chỉ ghi thêm

1. backlog.md (Nguồn Sự Thật)

• Vai trò: Cơ sở dữ liệu chính lưu trữ toàn bộ vòng đời nhiệm vụ (Bugs, Features, ICE Scores).
• Giải quyết: Giữ nguyên bức tranh toàn cảnh (Macro View) cho con người mà không ép AI phải đọc lại hàng nghìn dòng kế hoạch cũ.
• Quy tắc: Chỉ cập nhật thông qua lệnh /backlog.

2. sprint-current.md (🔥 Hot Lane)

• Vai trò: Bộ đệm để agent ghi trực tiếp các task nhanh phát sinh trong phiên làm việc.
• Giải quyết: Loại bỏ hoàn toàn thủ tục phiền phức — agent ghi task trực tiếp tại đây thay vì phải chạy /backlog update cho mỗi mục nhỏ.
• Quy tắc: Agent ghi trực tiếp trong phiên. Được đồng bộ (flush) sang done.md bởi /end.

[!NOTE] Từ v1.5.3, sprint-current.md không còn là bản sao (mirror) tự động của backlog nữa. Nó chính là Hot Lane — bộ đệm nhẹ để agent ghi nhận task nhanh ngay khi phát sinh, không tốn chi phí vận hành nào.

3. done.md (Kho Lưu Trữ Lịch Sử)

• Vai trò: Tệp lưu trữ mọi task đã hoàn thành, nhóm theo plan kèm thẻ nguồn (#backlog hoặc #session).
• Giải quyết: Chống lại “mất trí nhớ” (Amnesia) của AI khi phiên chat quá dài. Cung cấp bằng chứng định lượng để /retro tính toán vận tốc hoàn thành dự án.

🗜️ Nén Backlog (/backlog clean)

Item đã Done được nén gọn, không xóa bỏ. Hành động clean chuyển các item Done từ bảng active sang phần ✅ Completed (Archived) (1 dòng cho mỗi plan + danh sách IDs).

Chuỗi tra cứu:

backlog.md (✅ Completed: tên plan + IDs)
    ↓ link
done.md (chi tiết từng task, nhóm theo heading plan)
    ↓ link
plans/done/*.md (toàn bộ plan: phases, kiến trúc, DoD)

Điều này giữ cho backlog.md luôn là nguồn sự thật duy nhất cho tất cả task, đồng thời cực kỳ tiết kiệm token.

🔄 Luồng Vận Hành

Hai luồng song song

• Luồng chiến lược: /plan → /backlog sync → làm việc → /end → done.md (nguồn: #backlog)
• Luồng tác vụ nhanh: yêu cầu trong phiên → Hot Lane → /end → done.md (nguồn: #session) hoặc thăng cấp → backlog.md

Tích hợp Workflow

[!IMPORTANT] Lưu ý then chốt: Cơ chế 3-file chỉ thực sự vận hành khi bạn thực hiện lệnh /backlog sync sau khi lập kế hoạch (/plan). Nếu thiếu bước này, các task sẽ chỉ nằm trên “bản vẽ” (plan.md) mà không bao giờ được cấp ID để kích hoạt vào luồng xử lý siêu tốc của Agent.

📊 Ngân sách Token

Một trong những mục tiêu thiết kế chính là giữ ngữ cảnh /open siêu nhẹ:

So sánh với cách truyền thống — đọc một backlog duy nhất có thể tiêu tốn ~3,000+ tokens.

📜 Lịch sử Phiên bản

Kiến trúc đã tiến hóa đáng kể qua các phiên bản gần đây:

📚 Tham khảo

• Rule: Rule hybrid-3-file-integrity — C1 (Hot Lane), C2 (plan-grouped done.md), C3 (compress-not-delete), C5 (/end sync)
• Workflow: /backlog, /end, /plan, /retro
• Learn: Defense-in-Depth — File Guard Headers (Lớp 4)

→ Tìm hiểu Workflow /open với Hybrid 3-File → Tìm hiểu Workflow /backlog → Tìm hiểu Workflow /end — Điểm đồng bộ duy nhất