Harness Engineering (Phần 2): 5 Chiều Thiết Kế Biến AI Agent Từ Vô Dụng Thành Production-Ready

TL;DR

Một Harness hoàn chỉnh cần 5 chiều: Context Management (bộ nhớ 3 lớp), Execution (ít tool hơn = mạnh hơn), Task Orchestration (Ralph Loop), Feedback Mechanisms (AI tự verify), và Architectural Guardrails (chặn code xấu từ đầu). Bài này đi qua từng chiều với số liệu thực tế.

Chiều 1 - Quản lý ngữ cảnh: Bộ nhớ 3 lớp

LLM quên quy tắc project trong hội thoại dài vì context window hoạt động như một danh sách tin nhắn phẳng - quy tắc project và câu hỏi thông thường được xếp ngang hàng nhau. Hội thoại càng dài, ràng buộc đặt từ đầu càng bị pha loãng.

OpenAI nói thẳng: "Từ góc độ của Agent, kiến thức không có mặt trong runtime thì không tồn tại." Mọi thứ bạn nói miệng, thảo luận trong Slack, hay nghĩ là hiển nhiên - nếu không được ghi vào file trong repo, AI không thể thấy.

Giải pháp: phân lớp context theo tần suất đọc và mức độ quan trọng.

Lớp 1 - Project map (AGENTS.md / CLAUDE.md): Luôn được load vào đầu context. Giữ trong 100 dòng. Ghi tech stack, cấu trúc thư mục, điều cấm, lệnh phải chạy trước commit, UI style rules. Đây là bản đồ - ngắn, súc tích, luôn sẵn.

Lớp 2 - Detail docs (docs/ directory): frontend.md, security.md, api-design.md... AI đọc lớp 1 thấy gợi ý rồi mới kéo file liên quan về. Không load mặc định, tránh tốn context.

Lớp 3 - Raw records (git log, conversation history, full logs): Chỉ truy cập qua grep/tail. Khối lượng lớn nhất nhưng hoàn toàn không chiếm context chủ động.

OpenAI đã mắc sai lầm nhồi mọi thứ vào một file AGENTS.md vài nghìn dòng - AI lại càng dễ bỏ qua thông tin quan trọng. Phải chia thành map + detail mới giải quyết được.

Chiều 2 - Năng lực thực thi: Ít tool hơn = mạnh hơn

Model chỉ sinh text. Nó có thể nói "chạy npm install" nhưng không tự chạy được, không thấy kết quả, không điều chỉnh bước tiếp theo dựa trên lỗi. Harness kết nối model vào môi trường thực.

Nhưng đây là điều phản trực giác nhất trong Harness Engineering:

Tool càng nhiều, agent càng hay chọn nhầm tool, đi sai đường.

Vercel build internal text-to-SQL agent với đầy đủ specialized tools: schema lookup, query validation, error recovery. Kết quả: 80% success rate - tạm ổn nhưng fragile, chậm, cần bảo trì liên tục.

Sau đó họ thử xóa 80% tools, chỉ để lại 1 tool duy nhất: chạy bash command tùy ý. Agent dùng grep, cat, find, ls để tự đọc schema, tự hiểu cấu trúc, tự viết SQL.

Lý do: semantic layer của Vercel đã là tài liệu tốt sẵn. Các file YAML chứa định nghĩa dimension, công thức measure, quan hệ join đầy đủ. Họ build tools để tóm tắt thứ đã legible sẵn rồi - không cần thiết. Claude chỉ cần được đọc trực tiếp.

Nguyên tắc: trước khi thêm tool, tự hỏi - nó giải quyết gap hành vi cụ thể nào? Không trả lời được thì chưa cần thêm.

Chiều 3 - Điều phối tác vụ: Ralph Loop

Failure mode phổ biến nhất của AI trên tác vụ dài: cố one-shot cả feature lớn. Context window hết, làm đến giữa chừng phát hiện hướng cũ sai, quay lại sửa code cũ, càng sửa càng rối. Kết quả là không làm được gì.

Anthropic phát triển pattern Ralph Loop - tiếp sức 2 giai đoạn:

Initializer Agent (chỉ chạy 1 lần duy nhất ở đầu project):

• Setup development environment, chạy init.sh
• Expand brief prompt thành danh sách feature chi tiết (feature-list.json)
• Tạo progress.md - log tiến độ và quyết định kiến trúc
• Git commit đầu tiên

Coding Agent (chạy lại ở mỗi context window mới):

1. Chạy pwd để biết đang ở đâu
2. Đọc git log - xem lịch sử commit gần nhất
3. Đọc progress.md - biết đang làm đến đâu, quyết định nào đã chốt, bug nào chưa giải
4. Chọn feature ưu tiên cao nhất chưa xong từ danh sách
5. Làm xong 1 feature, chạy test verify
6. Git commit, cập nhật progress.md - ghi rõ vòng này làm gì, vòng sau làm gì

Dù AI bị ngắt, model version thay đổi, hay context window đầy - vòng tiếp theo chỉ cần đọc git log và progress.md là vào việc ngay. progress.md và git history cùng nhau tạo thành bộ nhớ ngoài xuyên context window.

Chiều 4 - Cơ chế phản hồi: AI không tự review code mình vừa viết

Model không chạy code. Nó đọc code, đánh giá bằng mắt xem có vẻ chạy được không dựa trên pattern quen thuộc. Nếu code trông "đúng" - tên biến hợp lý, cú pháp clean, indent đẹp - nó cho là pass. Điều đó không liên quan đến việc code có thật sự chạy không.

Đây là lý do AI hay tự tin nói "đã sửa xong" nhưng bạn mở lên vẫn thấy lỗi.

Ba loại feedback sensor:

• Computational (deterministic): linter, type checker, unit test, integration test. Chạy được mỗi lần commit. Cheap và reliable. Không pass = chưa xong.
• Visual (inferential): UI task dùng Playwright tự click qua app như user thật, screenshot làm evidence hoàn thành.
• LLM review (inferential): AI riêng biệt đánh giá code AI vừa viết - tìm logic bug, architecture issue, potential crash.

Điểm then chốt: không để generator tự review output của chính nó. Generator LLM thiên về justify cho lựa chọn của mình. Anthropic tách generator và evaluator thành 2 agent riêng biệt với role config và prompt khác nhau. Reviewer agent được cấu hình để skeptical - sau đó tuning evaluator skeptical dễ hơn nhiều so với làm generator tự phê phán.

Anthropic chia sẻ số liệu: cho model một vòng lặp tự verify, chất lượng output tăng 2-3 lần. Đây là single best Harness investment có return cao nhất.

Chiều 5 - Kiến trúc bảo hộ: Chặn code xấu ngay từ đầu

AI mô phỏng pattern đã có trong repo - code tốt lẫn code xấu. Mỗi commit AI riêng lẻ trông hợp lý, nhưng tích lũy lại là project càng ngày càng tệ.

OpenAI ghi nhận: agent sẽ copy pattern unstable, inconsistent, bad style sẵn có trong codebase và khuếch đại chúng.

Giải pháp: chuyển architectural rules từ document sang code executable.

• Pre-commit hooks: Tự động chạy check scripts trước khi git commit. Không hợp lệ = bị chặn ngay.
• Architectural linter: Khác với syntax linter - linter này check layer violations (UI layer không được gọi thẳng database layer), module dependency direction, file size threshold.
• CI gate: Dù hooks bị bypass locally, CI server chạy lại toàn bộ checks. Main branch luôn thỏa mãn architectural constraints.
• Background garbage collection: OpenAI cho Codex định kỳ scan codebase, phát hiện architectural drift, tự mở small PRs trả nợ kỹ thuật. AI viết code nhanh bao nhiêu thì tech debt sinh ra nhanh bấy nhiêu - cleanup cũng phải auto hóa.

Kết

5 chiều này không độc lập - chúng tạo thành một hệ thống. Context Management đảm bảo AI biết nó đang làm gì. Execution cho nó khả năng hành động. Task Orchestration chia nhỏ công việc. Feedback giúp nó tự verify. Guardrails ngăn nó phá codebase theo thời gian.

Phần 3 của series sẽ xem Anthropic, OpenAI và Nous Research implement các chiều này thực tế như thế nào - và 3 nguyên tắc ngược trực giác quan trọng nhất của Harness Engineering.

via Vercel - We removed 80% of our agent's tools · Anthropic - Effective harnesses for long-running agents · Martin Fowler - Harness Engineering