Progress Tracking: JSON feature list, checklist, progress files

Định nghĩa

Progress tracking trong AI agent là kỹ thuật lưu trữ trạng thái tiến độ công việc (dưới dạng structured data như JSON, checklist, hoặc plain text) để agent có thể tiếp tục từ đúng chỗ dừng trong session tiếp theo, thay vì bắt đầu lại từ đầu.

Giải thích chi tiết

Vấn đề: Context window không nhớ "đã làm gì"

Khi agent xử lý project thực tế kéo dài nhiều giờ hoặc nhiều ngày, context window sẽ bị đầy và bị cắt bớt (truncation). Thông tin về những gì đã hoàn thành — "đã setup xong database", "đã viết 3/5 test cases" — thường là nạn nhân đầu tiên của quá trình nén context. Kết quả: agent quay lại implement feature đã xong, chạy lại test đã pass, hoặc quên mất bug đã fix. Đây không phải lỗi "trí nhớ" của AI mà là thiết kế persistence thiếu sót.

JSON Feature List: Anti-overwrite pattern

Anthropic đề xuất pattern này trong hệ thống Claude Code để giải quyết hiện tượng "hallucinate progress" — khi agent tưởng đã làm xong việc gì đó nhưng thực chất chưa bắt đầu. Thay vì dùng bullet point dễ bị ghi đè khi context bị nén, dùng JSON với boolean flags hoặc status enum:

{
  "features": {
    "auth_oauth2": {"status": "implemented", "tested": false, "file": "src/auth.py"},
    "database_migration": {"status": "not_started", "depends_on": "auth_oauth2"},
    "api_rate_limiting": {"status": "in_progress", "last_step": "Redis config"}
  }
}

Ưu điểm: Machine-readable, có thể parse để validation, và quan trọng nhất — immutable history. Khi agent cập nhật, nó ghi đè object cụ thể thay vì rewrite toàn bộ file, giảm rủi ro mất thông tin.

Checklist Pattern: Human-readable với latch mechanism

File CHECKLIST.md hoặc TODO.md đơn giản:

## Sprint 3: Payment Integration
- [x] Setup Stripe SDK
- [ ] Implement webhook handler (đang làm: cần verify signature)
- [ ] Write integration tests

Tuy nhiên, để tránh agent "tự đánh dấu xong" mà không có evidence, cần latch mechanism: agent chỉ được phép tick [x] khi có proof (file tồn tại, test pass, hoặc explicit human approval). Pattern này kết hợp tốt với feedback loops để tạo quality gate.

Progress Files: The .txt simplicity

Pattern progress.txt hoặc state.json tối giản, chỉ chứa 4 trường:

1. Current phase: Giai đoạn hiện tại (e.g., "Refactoring")
2. Last completed: Bước cuối cùng đã xong
3. Next immediate: Hành động tiếp theo phải làm
4. Blockers: Vấn đề đang blocking (nếu có)

Đặt file này ở root project. Agent đọc đầu mỗi session, cập nhật cuối mỗi session. Đơn giản nhưng hiệu quả cho session handoff.

Ví dụ thực tế

Claude Code: JSON feature registry

Trong repo lớn như claude-engineer hoặc SWE-agent, Claude Code tạo file .claude/features.json. Mỗi feature là object với schema rõ ràng. Khi agent cần quyết định "làm gì tiếp theo", nó parse file này thay vì dựa vào chat history dễ bị truncated. Nếu context bị nén đến mức chỉ còn 10k tokens, JSON này vẫn được ưu tiên giữ lại qua chiến lược nén thông minh.

OpenHands: Progress log với timestamp

Agent viết log tiến độ vào progress.txt sau mỗi action quan trọng:

[2024-01-15 10:30] Phase: Setup → Done: Install dependencies → Next: Run reproduce script
[2024-01-15 10:45] Phase: Debug → Done: Identify root cause (race condition) → Next: Implement fix
[2024-01-15 11:00] Phase: Testing → Blocked: Test env không có GPU

Session mới bắt đầu bằng việc cat progress.txt thay vì "bạn nhớ chúng ta đang làm gì không?".

Integration với Memory 3 tầng

Kết hợp progress tracking với memory 3 lớp:

• Layer 1 (Index): MEMORY.md chứa link đến progress/features.json
• Layer 2 (Topic): progress_payment.md chi tiết tiến độ module thanh toán
• Layer 3 (Session): Transcript có reference "Updated progress.json: marked auth as done"

Khi chuyển sang session mới, agent đọc Index → tìm đến Topic file → xem Progress → mới bắt đầu làm việc.

Ứng dụng

Sinh viên/Developer cá nhân

Dùng TODO.md đơn giản cho project cá nhân kéo dài nhiều ngày. Tránh "hôm qua đang làm gì dở?" syndrome — mở VS Code, thấy file progress là biết ngay trạng thái.

Startup/Team nhỏ

JSON feature list cho product roadmap. Kết hợp CI check: nếu feature marked "status": "done" nhưng test fail → báo lỗi. Đảm bảo "done" thực sự có nghĩa là done, không phải agent tự nghĩ vậy.

Enterprise/Tech Lead

• Dual-write pattern: Progress file là "source of truth" cho agent, Jira/Linear là "source of truth" cho human. Dùng MCP (Model Context Protocol) để sync hai hệ thống.
• Audit trail: Lịch sử git của features.json cho biết agent thay đổi trạng thái task khi nào, tạo accountability.

So sánh

Kết luận: Chọn JSON nếu project phức tạp và cần integration với CI/CD. Chọn Checklist nếu cần sự giám sát của con người (human-in-the-loop). Chọn Progress File nếu ưu tiên tốc độ và ít overhead cho project cá nhân.

Bài viết liên quan

Cùng cụm

Đọc tiếp