AI agent báo 'xong' nhưng không chạy: framework 6 tầng vá lỗi

Bạn hỏi AI agent làm một việc, nó báo "xong", nhưng code không chạy. Bạn đổi model khác, vẫn vậy. Một kỹ sư làm việc với Claude Code, Codex và Cursor hơn một năm vừa công bố ia-engineer-framework, framework mã nguồn mở MIT giải quyết đúng vấn đề này bằng 6 tầng tăng dần.

Vấn đề không nằm ở model

Theo tác giả, khoảng cách giữa "demo chạy được" và "hệ thống cho kết quả nhất quán" đến từ bốn lỗ hổng: đặc tả mơ hồ khiến agent phải đoán, không có bước verify nên agent báo "xong" mà không chạy test, không lưu state nên mỗi phiên làm lại từ đầu, và thiếu observability nên không biết chi phí hay chất lượng có tụt hay không.

6 tầng, từ 10 phút đến CI/CD

Framework chia thành các tầng độc lập, mỗi tầng giải quyết một lớp vấn đề:

• Tier 1 — Harness (10 phút): copy template vào project, gồm CLAUDE.md chứa hướng dẫn, feature_list.json mô tả tính năng dạng máy đọc được, và init.sh để verify môi trường.
• Tier 2 — Eval (30 phút): bộ dataset JSONL với kịch bản và đáp án mong đợi, một runner chạy test trên bất kỳ LLM nào, một scorer đo độ chính xác, và một gate chặn CI nếu điểm rớt dưới ngưỡng — ví dụ output thực tế ghi nhận độ chính xác 87.5%.
• Tier 3 — Observe (1 giờ): logger ghi 10 trường dữ liệu mỗi lần tương tác (token, chi phí, độ trễ, tool, lỗi), cùng dashboard Grafana import sẵn.
• Tier 4 — Hooks (15 phút): tự động hoá cho Claude Code như lint trước commit, chạy test sau task, cảnh báo chi phí phiên, và quét bảo mật.
• Tier 5 — Patterns: 8 tài liệu tham khảo về diagnostic loop, multi-session, model routing, prompt versioning.
• Tier 6 — CI/CD (1 giờ): GitHub Action tự chạy eval trên mỗi PR, chặn merge nếu fail.

Diagnostic loop: pattern hữu ích nhất

Khi agent fail, tác giả khuyên đừng vội đổi model — hãy chẩn đoán theo thứ tự: đặc tả có rõ không, context có đủ thông tin không, environment có đúng dependency không, có bước verify không, agent có nhớ được việc đã làm trước đó không. Sửa đúng tầng bị lỗi, lặp lại; sau 3-5 vòng, environment sẽ ổn định hơn mà không cần tốn thêm chi phí model.

So với framework tương tự

Tác giả so sánh trực tiếp với dự án Learn Harness Engineering (11.3K sao trên GitHub): dự án đó chỉ dừng ở harness, dạng khóa học; ia-engineer-framework thêm cả eval pipeline, observability và CI/CD, đóng gói dạng copy-paste vào production thay vì chỉ để học.

Áp dụng thế nào

Framework hoạt động với Claude Code, Codex, Cursor hoặc bất kỳ agent nào — không khoá vào một nền tảng cụ thể. Repo công khai tại GitHub (pedri77/ia-engineer-framework), giấy phép MIT, tự do dùng và chỉnh sửa. Nếu team đang gặp tình trạng agent báo "xong" ảo, điểm bắt đầu hợp lý nhất là Tier 1 và Tier 2 — harness và eval — vì chi phí thấp (10-30 phút) nhưng giải quyết ngay nguyên nhân gốc: thiếu đặc tả rõ và thiếu verify.