codex-harness-engineering 0.1.5 → 0.1.6

package/docs/harness-engineering/research-note.md

@@ -1,318 +1,338 @@
-# Harness Engineering cho AI Agent làm việc dài hạn
+# Harness Engineering White Paper
 
-## Tóm tắt
+## Abstract
 
-Harness engineering là kỷ luật thiết kế môi trường quanh AI agent để agent có
-thể tạo tiến triển dài hạn, kiểm chứng được, và duy trì được. Các nghiên cứu của
-OpenAI, Anthropic và Google cho thấy cùng một luận điểm: năng lực mô hình chỉ trở
-thành năng lực sản xuất khi môi trường cung cấp state bền vững, tool dễ dùng,
-quan sát runtime, tiêu chí nghiệm thu, feedback loop, guardrail cơ học, dọn dẹp
-hệ thống, và các cơ chế tự động hóa hay đánh giá vết chạy [S1], [S2], [S3], [S4], [S5].
+Harness engineering là thiết kế lớp môi trường quanh AI agent để biến năng
+lực mô hình thành tiến triển phần mềm có thể tiếp tục, kiểm chứng, và duy trì
+qua nhiều session [S1], [S2], [S3], [S4], [S5]. Năm nguồn trong phạm vi này
+cho cùng một kết luận thực dụng: agent không trở thành công cụ production chỉ
+nhờ prompt tốt hơn; nó cần repository-local state, tool dễ đọc, quan sát
+runtime, tiêu chí done, guardrail cơ học, cleanup định kỳ, và khi cần thì lớp
+bọc thực thi sinh tự động [S1], [S2], [S4], [S5].
 
-Tài liệu này tổng hợp năm nguồn đó. Mọi nguồn mở rộng khác ngoài phạm vi đã bị
-loại bỏ để giữ trọng tâm.
+## Executive Summary
 
-## 1. Vấn đề
+Để triển khai thực tế, harness nên được xây theo thứ tự sau:
 
-Một agent có thể viết code tốt trong một lượt nhưng vẫn thất bại ở công việc dài
-hạn. Các failure mode lặp lại là:
+1. Bắt đầu bằng harness tối thiểu: `AGENTS.md`, `init.sh`, `feature_list.json`,
+   `progress.md`, test/smoke command, và git checkpoint [S1], [S2].
+2. Đưa state dài hạn ra ngoài chat history để session mới khôi phục được bối
+   cảnh mà không đoán mò [S2].
+3. Mã hóa invariant lặp lại thành check chạy được thay vì chỉ ghi trong prose
+   [S1].
+4. Thêm browser, API, log, metric, trace, hoặc evaluator riêng chỉ khi failure
+   mode thực sự cần [S1], [S2], [S4].
+5. Khi rule quá phức tạp để giữ tay, xem xét wrapper code sinh tự động theo
+   hướng AutoHarness [S5].
 
-- session mới không biết session trước đã làm gì;
-- agent cố hoàn thành toàn bộ app trong một lần và để lại trạng thái khó tiếp
-  tục;
-- agent nhìn thấy vài feature đã xong rồi tuyên bố cả dự án hoàn thành;
-- agent sửa code nhưng không kiểm thử đầu-cuối;
-- agent không thấy UI, log, metric, trace, hoặc trạng thái runtime;
-- throughput cao làm pattern xấu lan rộng nhanh hơn tốc độ con người review.
-
-Anthropic mô tả vấn đề multi-session như một bài toán khôi phục trạng thái:
-context window không đủ để bảo toàn toàn bộ tiến triển, nên harness phải đặt
-state vào artifact bền vững như feature list, progress file, `init.sh`, và git
-history [S2]. OpenAI mô tả cùng vấn đề ở quy mô repository: khi agent tạo code
-nhanh hơn con người có thể QA thủ công, công việc kỹ sư chuyển sang thiết kế
-môi trường, feedback loop, và control system quanh agent [S1].
-
-Một ràng buộc quan trọng đến từ Anthropic: không phải mọi task đều cần agent hay
-harness phức tạp. Nên bắt đầu bằng giải pháp đơn giản nhất, dùng workflow khi
-đường đi đã rõ, và chỉ dùng agent tự chủ hoặc orchestration nhiều bước khi
-tradeoff về cost, latency, và lỗi tích lũy được biện minh bằng outcome [S3].
-
-## 2. Định nghĩa
-
-Trong phạm vi năm nguồn này, **harness** là lớp scaffold ngoài mô hình giúp
-agent làm việc đáng tin hơn. Nó có thể bao gồm:
-
-- prompt và acceptance criteria;
-- file state như feature list và progress log;
-- script setup như `init.sh`;
-- git history và commit discipline;
-- tool để chạy app, browser automation, API check, log, metric, trace;
-- planner, generator, evaluator khi task cần tách vai trò;
-- linter, structural test, CI rule, và cleanup cadence;
-- tự động tổng hợp lớp bọc thực thi (code harness/wrapper) để chặn hành động lỗi [S5];
-- hệ thống đánh giá vết chạy (trajectory evaluation) và LLM-as-a-judge [S5].
-
-Harness engineering là việc thiết kế, đo, và điều chỉnh lớp scaffold đó. Nó
-khác với prompt engineering ở chỗ trọng tâm không chỉ là câu lệnh cho một lượt
-model, mà là toàn bộ môi trường giúp nhiều lượt agent tiếp tục, quan sát, sửa,
-và để lại bằng chứng.
-
-## 3. Vai trò mới của kỹ sư
-
-OpenAI tóm tắt mô hình vận hành bằng ý tưởng: con người định hướng, agent thực
-thi. Trong case study của họ, Codex viết application logic, test, CI,
-documentation, observability, và internal tooling; con người ưu tiên công việc,
-dịch phản hồi thành acceptance criteria, xác minh outcome, và biến failure thành
-cải tiến môi trường [S1].
-
-Điểm quan trọng không phải là thay con người bằng agent, mà là chuyển tầng làm
-việc của con người. Khi agent thất bại, câu hỏi tốt không phải "nhắc mạnh hơn
-được không?", mà là "agent thiếu capability, context, tool, guardrail, hoặc
-feedback loop nào?" [S1].
-
-## 4. Nguyên lý vận hành
-
-### 4.1 Bắt đầu đơn giản
-
-Anthropic phân biệt workflow và agent. Workflow dùng đường đi định sẵn; agent
-tự điều khiển process và tool usage. Vì agentic system đổi latency và cost lấy
-performance, harness nên bắt đầu từ cấu trúc nhỏ nhất: một LLM call có retrieval,
-tool, memory, hoặc một workflow đơn giản nếu task phân rã rõ [S3].
-
-Chỉ thêm planner, evaluator, nhiều agent, hoặc vòng lặp dài khi failure mode cụ
-thể xuất hiện: mất context, tự đánh giá yếu, runtime vô hình, scope drift, hoặc
-QA không đủ [S2], [S4].
-
-### 4.2 Ngoại hóa trạng thái
-
-Harness cho agent dài hạn cần đưa bộ nhớ ra khỏi hội thoại. Anthropic dùng
-initializer agent để tạo `init.sh`, progress file, feature list, và commit ban
-đầu. Coding agent sau đó đọc các artifact này, chọn một feature chưa pass, làm
-từng bước, cập nhật progress, và commit trạng thái sạch [S2].
-
-Feature list có vai trò như contract bền vững. Mỗi feature nên có mô tả, bước
-kiểm tra, và trạng thái pass/fail. Agent chỉ được đổi trạng thái sau khi xác
-minh. Cách này giảm hai lỗi phổ biến: làm quá rộng và đánh dấu xong quá sớm
-[S2].
-
-Việc Anthropic dùng `feature_list.json` thay vì prose thuần cũng cho thấy một
-điểm thiết kế quan trọng: trạng thái công việc nên đủ có cấu trúc để session
-mới đọc, lọc, và cập nhật pass/fail nhất quán mà không phải suy diễn lại từ
-văn bản tự do [S2].
-
-Git history trong mẫu harness này cũng không chỉ là nhật ký. Anthropic nêu rõ
-việc để agent kết thúc session bằng commit message mô tả rõ và progress update
-giúp nó có recovery point để revert thay đổi xấu và quay về working state sạch
-hơn trong vòng sau [S2].
-
-OpenAI áp dụng cùng logic ở mức repository knowledge: `AGENTS.md` nên là bản đồ
-ngắn trỏ tới tài liệu sâu hơn, còn source of truth nằm trong `docs/`, plan,
-schema, test, lint, và artifact version hóa. Nếu quyết định chỉ nằm trong chat,
-Google Docs riêng, hoặc trí nhớ con người, agent khó dùng nó trong lúc chạy
-[S1].
+Paper này không cổ vũ nhiều agent hơn. Nó chỉ ra cách xây một hệ điều khiển
+đủ nhỏ để dùng được ngay, nhưng đủ chặt để không phụ thuộc vào trí nhớ hội
+thoại.
 
-Một diễn giải thực dụng từ [S1] và [S2] là nên tách hai loại trạng thái. Loại
-ổn định của repository gồm rule, architecture, setup, và lệnh chuẩn; loại biến
-động của công việc gồm feature đang làm, kết quả verify gần nhất, và bước kế
-tiếp. Trộn cả hai vào một file dài làm session mới khó phục hồi nhanh và làm
-instruction dễ drift theo tiến độ ngắn hạn [S1], [S2].
-
-OpenAI còn đi xa hơn ở chỗ không chỉ lưu tri thức trong repo, mà còn tổ chức nó
-theo progressive disclosure và kiểm tra freshness/cross-link bằng cơ chế cơ
-học. Hệ quả là source of truth không nên chỉ "được viết xuống", mà còn nên có
-cách để phát hiện doc cũ, liên kết hỏng, hoặc map điều hướng không còn phản ánh
-thực tế của codebase [S1].
-
-Anthropic còn cho thấy một điểm mạnh hơn: context reset không nhất thiết là
-mất mát phải chịu đựng, mà có thể trở thành cơ chế chủ đích của harness. Khi
-state handoff đủ tốt qua feature list, progress file, git log, và setup script,
-session mới có thể khởi động lại với ngữ cảnh gọn hơn và ít bị context anxiety
-hơn là cố kéo dài một chuỗi hội thoại suy giảm dần [S2], [S4].
-
-### 4.3 Làm môi trường dễ đọc với agent
-
-Agent chỉ sửa đáng tin những gì nó quan sát được. Anthropic cho thấy browser
-automation giúp Claude kiểm thử feature web như người dùng thật và phát hiện lỗi
-không thấy được từ code hoặc unit test đơn lẻ [S2]. OpenAI mở rộng ý tưởng này:
-app, UI, log, metric, trace, và môi trường dev theo worktree phải trở thành tín
-hiệu agent đọc được [S1].
-
-Trong harness tốt, tool là giác quan của agent. Một web agent không có browser
-automation không thật sự thấy app. Một backend agent không có log, metric, hoặc
-trace khó suy luận về hành vi runtime. Một agent không biết setup app sẽ mất
-thời gian đoán cách chạy trước khi làm việc thật [S1], [S2].
-
-Anthropic cũng nhấn mạnh agent-computer interface. Tool nên có tên, tham số,
-description, ví dụ, edge case, và ranh giới rõ. Tool khó dùng với con người mới
-vào dự án thường cũng khó dùng với model [S3].
-
-OpenAI bổ sung một hệ quả thiết kế ít hiển nhiên hơn: ngay cả lựa chọn
-dependency và abstraction cũng là một phần của legibility. Công nghệ có API ổn
-định, hành vi dễ mô hình hóa, và phần logic nằm trong repo thường dễ cho agent
-reason hơn lớp upstream opaque. Vì vậy harness không chỉ thêm tool; nó còn có
-thể ưu tiên stack và helper mà agent inspect, validate, và sửa trực tiếp được
-[S1].
+## Scope
+
+Phạm vi này chỉ dùng năm nguồn [S1] đến [S5]. Mọi luận điểm quan trọng trong
+paper đều phải truy vết về một trong năm nguồn đó hoặc được đánh dấu rõ là
+diễn giải triển khai.
 
-### 4.4 Tách sinh kết quả khỏi đánh giá
+## Problem Statement
+
+Agent có thể tạo tiến triển ngắn hạn nhanh nhưng vẫn thất bại ở dự án dài hạn.
+Các failure mode lặp lại là:
+
+- session mới không biết session trước đã làm gì;
+- agent làm quá rộng thay vì chốt một feature;
+- agent tự tuyên bố done sớm;
+- runtime fail nhưng code review không thấy;
+- generator tự đánh giá quá lạc quan;
+- throughput cao làm drift kiến trúc và drift quy trình tăng nhanh [S1], [S2],
+  [S4].
+
+Vì vậy harness engineering là bài toán thiết kế hệ điều khiển: state, sensing,
+standards, constraints, và cleanup phải được đặt sao cho agent có thể tiếp tục
+qua nhiều session mà vẫn giữ được bằng chứng [S1], [S2], [S4].
+
+## Core Thesis
+
+1. Kỹ sư chuyển từ “viết code cho agent” sang “thiết kế môi trường để agent
+   làm việc đúng” [S1].
+2. Với task dài hạn, state phải được externalize vào file, commit, và script
+   để session mới phục hồi bối cảnh [S2].
+3. Harness nên bắt đầu đơn giản nhất có thể; workflow đủ thì dùng workflow,
+   agent tự chủ chỉ nên xuất hiện khi failure mode thật đòi hỏi [S3].
+4. Invariant quan trọng phải được cưỡng chế bằng máy, không trông chờ prose
+   hoặc nhắc nhở thủ công [S1], [S5].
+5. Khi chất lượng chủ quan khó chấm hoặc self-review bị thiên lệch, tách
+   generator khỏi evaluator [S4].
+
+## Minimal Working Definition
+
+Trong paper này, **harness** là scaffold ngoài mô hình gồm:
+
+- file state như feature list, progress log, lesson log;
+- setup command hoặc `init.sh`;
+- docs làm source of truth trong repo;
+- browser, API, log, metric, trace, hoặc test runtime;
+- acceptance contract, sprint contract, evaluator rubric;
+- lint, structural test, CI rule, cleanup cadence;
+- wrapper code sinh tự động khi rule quá phức tạp để viết tay [S1], [S2],
+  [S4], [S5].
+
+**Harness engineering** là việc thiết kế và vận hành scaffold đó để agent có
+thể làm việc qua nhiều session mà không phụ thuộc chủ yếu vào chat history.
+
+## Operating Principles
+
+### 1. Start with the smallest useful harness
+
+Nếu task có đường đi rõ, dùng workflow và acceptance criteria trước. Chỉ thêm
+planner, evaluator, nhiều agent, hoặc orchestration nhiều bước khi failure mode
+cụ thể chứng minh nó đáng giá [S3], [S4].
+
+### 2. Externalize state
+
+State dài hạn nên sống trong artifact bền vững: feature list, progress file,
+git history, và `init.sh` [S2]. Feature list nên đủ cấu trúc để session mới
+đọc được pass/fail mà không phải suy diễn lại từ prose tự do. Git commit mô tả
+rõ và progress update không chỉ phục vụ audit; chúng tạo checkpoint để agent
+revert thay đổi xấu và khôi phục working state sạch hơn khi cần [S2]. Khi state
+handoff đủ tốt, context reset có thể là một phần chủ đích của harness: reset
+giúp model bám task thay vì trượt theo context anxiety tích lũy qua một context
+window dài [S4].
+
+### 3. Keep the repo as the source of truth
+
+`AGENTS.md` nên là bản đồ ngắn trỏ tới nguồn sâu hơn, không phải manual khổng
+lồ. Quyết định quan trọng phải nằm trong repo, không chỉ trong chat [S1]. Tri
+thức trong repo nên theo progressive disclosure: lớp ngoài cùng ngắn gọn, trỏ
+tới chi tiết sâu hơn khi cần, kèm kiểm tra cơ học cho freshness và cross-link
+để source of truth không drift theo thời gian [S1]. Khi chọn dependency hoặc
+abstraction, ưu tiên thứ agent có thể inspect, validate, và modify trực tiếp
+trong repo; hành vi opaque ở upstream làm giảm leverage của agent [S1].
+
+### 4. Make runtime legible
+
+Agent chỉ sửa đáng tin những gì nó thấy. Browser automation, API checks, log,
+metric, và trace biến hành vi runtime thành tín hiệu mà agent có thể đọc và
+kiểm chứng [S1], [S2], [S4]. Tool cũng phải được mô tả như interface rõ ràng,
+với tham số, ranh giới, và ví dụ sử dụng rõ ràng [S3].
+
+### 5. Separate generation from evaluation
+
+Generator tự chấm output của chính nó thường quá tích cực. Evaluator riêng cho
+phép feedback hoài nghi hơn, cụ thể hơn, và bám vào rubric thay vì cảm tính
+[S4]. Sprint contract giữa generator và evaluator nên nêu rõ phạm vi công việc,
+tiêu chí done, và phương thức QA để cả hai bên đồng thuận trước khi generator
+bắt đầu [S4].
+
+### 6. Encode repeated rules mechanically
+
+Documentation không đủ để giữ architecture coherent khi throughput cao. Các
+quy tắc lặp lại nên được mã hóa thành lint, structural test, custom rule, hoặc
+CI gate để chặn drift đúng thời điểm nó phát sinh [S1].
+
+### 7. Clean up continuously
+
+Throughput cao làm entropy tích lũy nhanh. Cleanup, targeted refactor, và
+review lại artifact bền vững là một phần của harness, không phải việc phụ
+[S1].
 
-Một agent tự đánh giá output của chính nó thường quá tích cực, đặc biệt ở task
-chủ quan như frontend design. Anthropic giải quyết bằng cách tách generator và
-evaluator. Generator tạo sản phẩm; evaluator dùng tiêu chí chấm, Playwright, và
-quan sát runtime để đưa phản hồi cụ thể; generator lặp lại dựa trên phản hồi đó
-[S4].
+### 8. Synthesize wrappers when rules get too complex
 
-Điểm cốt lõi là evaluator không cần hoàn hảo. Nó cần đủ hoài nghi và đủ cụ thể:
-tiêu chí nào fail, bằng chứng quan sát là gì, user path nào lỗi, API hoặc state
-nào chưa đúng, và sửa tiếp nên nhắm vào đâu [S4].
+AutoHarness cho thấy lớp bọc thực thi có thể được sinh tự động bằng iterative
+code refinement dựa trên feedback môi trường để chặn hành vi không hợp lệ trước
+khi nó tác động tới hệ thống. Với cách này, một model nhỏ hơn như
+Gemini-2.5-Flash có thể vượt model lớn hơn trên các môi trường TextArena nhờ
+harness sinh tự động bù lại năng lực mô hình [S5]. Khi phù hợp, code-as-policy
+còn loại bỏ LLM call ở thời điểm ra quyết định để giảm latency và cost runtime
+[S5].
 
-Google Cloud bổ sung khía cạnh **đánh giá vết thực thi (Trajectory Evaluation)**
-và **LLM-as-a-judge** tự động. Việc đánh giá một agent dài hạn không chỉ đo lường
-kết quả đầu ra tĩnh (static final evaluation) mà phải giám sát và chấm điểm toàn bộ
-chuỗi hành động (gọi tool, suy luận) để phát hiện sai lệch hiệu năng sớm. Hơn nữa,
-cơ chế **Meta-Evaluation (VeRO)** có thể được sử dụng để liên tục tối ưu hóa chính
-cấu trúc của harness (prompt, tool) dựa trên vết chạy của session trước [S5].
+## Reference Architecture
 
-### 4.5 Dùng sprint contract cho task dài
+Một harness trưởng thành có thể đọc như hệ điều khiển bốn lớp:
 
-Với phát triển ứng dụng dài hạn, Anthropic dùng planner để mở rộng prompt ngắn
-thành spec, generator để build, evaluator để QA, và sprint contract để hai bên
-đồng thuận trước về scope và "done" [S4].
+| Lớp | Câu hỏi | Artifact điển hình | Nguồn |
+| --- | --- | --- | --- |
+| State | Agent có biết việc đã xảy ra chưa? | feature list, progress log, git history | [S2] |
+| Senses | Agent có thấy hành vi thật chưa? | browser, API check, log, metric, trace | [S1], [S2], [S4] |
+| Standards | Done nghĩa là gì? | acceptance criteria, sprint contract, evaluator rubric | [S3], [S4] |
+| Constraints | Điều gì không được drift? | lint, structural test, CI, cleanup, synthesized wrapper | [S1], [S5] |
 
-Sprint contract không phải thủ tục quản lý dự án. Nó là artifact điều khiển:
-giới hạn phạm vi generator, làm rõ acceptance criteria, và cho evaluator tiêu
-chuẩn chấm độc lập. Nếu task nhỏ, một acceptance contract hoặc test case là đủ.
-Nếu task dài, contract nên nêu user path, API/data path, negative case, và cách
-quan sát runtime [S3], [S4].
+Thứ tự triển khai nên đi từ rẻ đến đắt: state trước, verification trước, tool
+quan sát khi cần, evaluator khi self-review yếu, planner khi scope mơ hồ, và
+guardrail khi invariant đã rõ [S2], [S3], [S4], [S5].
 
-### 4.6 Cưỡng chế invariant bằng cơ chế kỹ thuật
+## Practical Rollout Plan
 
-OpenAI nhấn mạnh rằng documentation đơn thuần không giữ được coherence khi code
-do agent sinh ra tăng nhanh. Họ mã hóa architecture rule, dependency direction,
-data boundary parsing, structured logging, file size limit, naming convention,
-và reliability rule bằng custom linter hoặc structural test [S1].
+### Phase 1: Minimum viable harness
 
-Nguyên tắc là: prompt nói điều nên làm; guardrail cơ học chặn điều không được
-làm. Khi review comment hoặc bug lặp lại, harness tốt biến judgment đó thành
-doc, lint, test, hoặc tool để agent tương lai không phải học lại từ đầu [S1].
+Mục tiêu: làm cho session mới khởi động được và biết phải làm gì.
 
-Google DeepMind đóng góp giải pháp **AutoHarness** (tự động tổng hợp lớp bọc thực thi
-bằng code). Thay vì con người phải tự viết thủ công tất cả luật linter hay guardrail,
-mô hình có thể tự động phân tích và sinh ra lớp bọc (code harness/wrapper) để lọc/chặn
-các hành động không hợp lệ trước khi chúng tác động tới môi trường [S5]. Cơ chế này
-thậm chí có thể biên dịch toàn bộ chính sách quyết định thành code tĩnh
-(**Harness-as-Policy**), giúp chạy trực tiếp mà không tốn chi phí và độ trễ gọi mô hình
-ở runtime [S5].
+Artifacts tối thiểu:
 
-### 4.7 Cleanup là một phần của harness
+- `AGENTS.md`
+- `README.md`
+- `init.sh`
+- `feature_list.json`
+- `progress.md`
+- `lessons.md`
+- test/smoke command
 
-Throughput cao đổi failure mode từ "agent không viết được" sang "agent viết
-nhiều và lan truyền pattern lệch". OpenAI mô tả recurring cleanup process,
-quality grade, và targeted refactoring pull request như một dạng garbage
-collection cho codebase agent-first [S1].
+Acceptance:
 
-Cleanup không phải refactor tùy hứng. Nó nên là task có trigger, phạm vi, tiêu
-chí nghiệm thu, và verification giống mọi thay đổi khác.
+- session mới đọc được thứ tự đọc;
+- setup chạy được;
+- feature có trạng thái rõ;
+- progress ghi được việc đang làm;
+- commit trở thành checkpoint [S1], [S2].
 
-## 5. Lợi ích
+### Phase 2: Verification harness
 
-### 5.1 Tiến triển dài hạn tốt hơn
+Mục tiêu: chặn done sớm và thiếu handoff.
 
-Externalized state giúp session mới không phải đoán dự án đang ở đâu. Feature
-list, progress file, git history, và `init.sh` giảm thời gian khởi động và giúp
-agent chọn phần việc kế tiếp có phạm vi rõ [S2].
+Thêm:
 
-### 5.2 QA tốt hơn
+- test hoặc smoke test rẻ;
+- gate kiểm state update;
+- evidence trong `feature_list.json`;
+- entry progress mới nhất phải nêu artifact đã đổi và command verify [S1], [S2].
 
-Browser automation, test runtime, API check, log, metric, và trace giúp agent
-kiểm chứng hành vi thay vì chỉ đọc code. Evaluator riêng có thể bắt gap mà
-generator bỏ sót, như feature display-only, interaction thiếu chiều sâu, hoặc
-stub chưa được thay bằng hành vi thật [S1], [S2], [S4].
+### Phase 3: Runtime observability
 
-Đánh giá vết thực thi (trajectory evaluation) và LLM-as-a-judge tự động giúp giám
-sát độ an toàn và hiệu năng của agent liên tục, phát hiện lỗi suy luận hoặc lỗi
-gọi công cụ một cách có hệ thống trước khi tích hợp [S5].
+Mục tiêu: thấy hành vi thật thay vì chỉ thấy code.
 
-### 5.3 Judgment của con người tích lũy
+Thêm khi cần:
 
-Khi preference, review comment, architecture rule, và bug pattern được mã hóa
-vào docs, lint, test, hoặc cleanup, chúng ảnh hưởng tới nhiều lần chạy agent sau
-đó. Harness biến một lần can thiệp của con người thành ràng buộc lặp lại [S1].
+- browser automation;
+- API checks;
+- log, metric, trace;
+- database state checks [S1], [S2], [S4].
 
-### 5.4 Tốc độ cao hơn nếu môi trường đủ chín
+### Phase 4: Evaluation separation
 
-OpenAI báo cáo case study nội bộ với throughput PR cao và codebase lớn do Codex
-sinh ra, nhưng họ cũng cảnh báo mức tự chủ đó phụ thuộc mạnh vào cấu trúc và
-tooling cụ thể của repository [S1]. Vì vậy lợi ích không nên được đọc như lời
-hứa phổ quát; nó là kết quả của đầu tư vào harness.
+Mục tiêu: giảm self-review bias.
 
-## 6. Chi phí và giới hạn
+Thêm khi task có UI, design, hoặc chất lượng chủ quan:
 
-### 6.1 Complexity có giá
+- evaluator riêng;
+- rubric rõ;
+- sprint contract;
+- handoff artifact giữa generator và evaluator [S4].
 
-Harness nhiều agent, nhiều vòng evaluator, và nhiều QA runtime có thể tốn nhiều
-giờ và token. Anthropic nêu các run ứng dụng dài hạn kéo dài hàng giờ với chi
-phí đáng kể. Vì vậy harness phức tạp phải được dùng như tradeoff có chủ đích,
-không phải mặc định [S4].
+### Phase 5: Mechanical guardrails and cleanup
 
-### 6.2 Model capability thay đổi thiết kế harness
+Mục tiêu: giữ kiến trúc ổn định qua throughput cao.
 
-Một lớp orchestration hữu ích với model hiện tại có thể không còn cần thiết khi
-model mới tốt hơn. Anthropic khuyến nghị re-examine harness khi model thay đổi:
-loại bỏ phần không còn load-bearing và thêm phần mới nếu model mở ra khả năng
-khác [S4].
+Thêm:
 
-### 6.3 Evaluator vẫn có giới hạn
+- lint;
+- structural tests;
+- CI rule;
+- cleanup cadence;
+- doc-gardening hoặc freshness check nếu source of truth drift [S1].
 
-Evaluator là LLM nên vẫn có thể bỏ sót bug hoặc đánh giá sai, nhất là ở domain
-mà nó thiếu giác quan trực tiếp. Anthropic nêu ví dụ âm thanh: QA về musical
-taste bị giới hạn nếu model không thực sự nghe được output [S4].
+### Phase 6: Auto-synthesized wrappers
 
-### 6.4 Kết quả không tự động tổng quát hóa
+Mục tiêu: xử lý rule quá phức tạp cho việc viết tay.
 
-OpenAI nói rõ khả năng Codex drive feature end-to-end phụ thuộc mạnh vào cấu
-trúc và tooling của repository. Đội khác không nên kỳ vọng outcome tương tự nếu
-chưa có source of truth cục bộ, setup lặp lại, tool quan sát, test, lint, review
-loop, và cleanup [S1].
+Chỉ chọn khi:
 
-## 7. Mô hình tổng hợp
+- rule dày đặc và lặp lại;
+- hành vi không hợp lệ cần chặn trước runtime;
+- cost runtime của LLM call là vấn đề;
+- wrapper code có thể được tổng hợp và kiểm soát bằng verify [S5].
 
-Một harness trưởng thành có thể được đọc như hệ điều khiển gồm bốn lớp:
+## Artifact Contract
 
-| Lớp | Câu hỏi | Artifact điển hình | Nguồn |
+| Artifact | Nên chứa | Không nên chứa | Nguồn |
 | --- | --- | --- | --- |
-| State | Agent biết việc đã xảy ra chưa? | feature list, progress log, git history | [S2] |
-| Senses | Agent thấy hành vi thật chưa? | browser, API check, log, metric, trace, trajectory evaluator | [S1], [S2], [S4], [S5] |
-| Standards | Done nghĩa là gì? | acceptance criteria, sprint contract, evaluator rubric, LLM-as-a-judge | [S3], [S4], [S5] |
-| Constraints | Điều gì không được drift? | lint, structural test, CI, cleanup, synthesized code harness | [S1], [S5] |
-
-Thứ tự triển khai nên đi từ rẻ đến đắt: state trước, verification trước, tool
-quan sát khi cần, evaluator khi self-review yếu, planner khi scope mơ hồ, và
-guardrail khi invariant đã rõ.
-
-## 8. Câu hỏi mở
-
-Năm nguồn để lại một số câu hỏi nghiên cứu:
-
-- Khi nào một agent tổng quát tốt hơn nhiều agent chuyên biệt? [S2], [S4]
-- Khi nào evaluator đáng chi phí so với self-review hoặc test deterministic?
-  [S3], [S4]
-- Làm sao đo được phần cải thiện đến từ model, prompt, tool, state, evaluator,
-  hay guardrail? [S3], [S4]
-- Architecture coherence của codebase agent-generated sẽ tiến hóa thế nào qua
-  nhiều năm? [S1]
-- Những phần harness nào nên bị loại bỏ khi model mới mạnh hơn? [S4]
-- Khi nào nên dùng AutoHarness tự động sinh thay vì viết linter/guardrail thủ công? [S5]
-- Làm thế nào để giảm thiểu sai số của LLM-as-a-judge trong trajectory evaluation? [S5]
-
-## 9. Kết luận
-
-Harness engineering làm autonomy trở thành thuộc tính của hệ thống, không chỉ
-là thuộc tính của model. Một model mạnh trong môi trường thiếu state, thiếu
-tool, thiếu tiêu chí done, và thiếu guardrail sẽ tạo tiến triển giòn. Cùng model
-đó trong harness tốt có thể tiếp tục công việc, quan sát lỗi, nhận feedback,
-sửa có bằng chứng, và giữ kiến trúc ổn định hơn.
-
-Kết luận thực dụng từ các nghiên cứu là: đừng bắt đầu bằng harness phức tạp. Bắt
-đầu bằng task rõ, state bền vững, setup lặp lại, và verify thật. Chỉ thêm evaluator,
-planner, observability, hoặc cleanup automation khi failure mode cụ thể cho
-thấy chúng đang mua thêm chất lượng đáng giá.
+| `AGENTS.md` | Bản đồ vào repo: đọc gì trước, lệnh nào chuẩn, điều gì bị cấm | Manual dài hoặc lịch sử dự án | [S1] |
+| `README.md` | Mục tiêu dự án, cấu trúc chính, cách chạy cơ bản | Task state ngắn hạn | [S1] |
+| `feature_list.json` | Scope công việc, acceptance, verify command, status, evidence | Rule kiến trúc chung | [S2] |
+| `progress.md` | Verify đã chạy, lỗi đang mở, bước kế tiếp | Policy bền vững lặp lại cho mọi task | [S2] |
+| `lessons.md` | Mistake, root cause, rule, status promote | Rule đã promote | [S1], [S2] |
+| Test/lint/check | Invariant cần cưỡng chế bằng máy | Giải thích dài thay cho check chạy được | [S1] |
+
+## State Update Contract
+
+Khi task chạm behavior artifact như source code, `scripts/`, `tests/`,
+`skills/`, manifest package, workflow verify, hoặc `AGENTS.md`, agent nên:
+
+1. Chạy baseline trước sửa nếu task có rủi ro hồi quy.
+2. Nêu acceptance criteria và verify command trước khi đổi trạng thái.
+3. Sau khi verify pass, cập nhật feature state với evidence cụ thể.
+4. Thêm entry progress mới nhất, liệt kê behavior artifact đã đổi, command
+   đã chạy, kết quả, và bước tiếp theo.
+5. Chỉ tuyên bố hoàn tất hoặc commit checkpoint sau khi gate state và lệnh
+   verify đều pass [S2].
+
+## Session Loop
+
+Mỗi session dài hạn nên làm:
+
+1. Đọc `AGENTS.md`.
+2. Đọc `progress.md`.
+3. Đọc `feature_list.json` hoặc artifact trạng thái tương đương.
+4. Xem git history gần nhất.
+5. Chạy `init.sh` hoặc setup command.
+6. Chạy smoke test rẻ nhất.
+7. Chọn một feature/fix chưa verify.
+8. Viết acceptance criteria ngắn.
+9. Thực hiện thay đổi nhỏ nhất.
+10. Verify bằng lệnh hoặc quan sát đã nêu.
+11. Chỉ đổi trạng thái feature sau khi verify pass.
+12. Nếu lỗi do agent gây ra, ghi lesson trước khi sửa tiếp.
+13. Ghi progress và commit nếu workflow yêu cầu [S1], [S2].
+
+## Failure Modes and Responses
+
+| Failure mode | Response tối thiểu |
+| --- | --- |
+| Mất context giữa session | Externalize state vào feature list, progress, commit, setup script [S2] |
+| Done sớm | Gate trạng thái bằng verify command và evidence [S2] |
+| Không thấy runtime | Thêm browser/API/log/metric/trace [S1], [S2], [S4] |
+| Self-review quá lạc quan | Tách generator khỏi evaluator [S4] |
+| Drift kiến trúc | Mã hóa rule thành lint/structural test/CI [S1] |
+| Throughput làm nợ kỹ thuật tích lũy | Cleanup định kỳ và doc-gardening [S1] |
+| Rule quá phức tạp để viết tay | AutoHarness hoặc wrapper code sinh tự động [S5] |
+
+## Tradeoffs
+
+Harness mạnh hơn không có nghĩa là harness càng phức tạp càng tốt.
+
+- Harness nhiều lớp có thể tốn giờ và token; đây là tradeoff có chủ đích, không
+  phải mặc định [S4].
+- Một số lớp orchestration hữu ích ở model hiện tại có thể không còn load-
+  bearing khi model mới tốt hơn [S4].
+- Evaluator vẫn là mô hình nên vẫn có giới hạn, đặc biệt nếu domain cần giác
+  quan trực tiếp mà evaluator không có [S4].
+- Không phải task nào cũng cần agent hoặc harness nặng. Nếu task nhỏ và đường
+  đi rõ, workflow đơn giản vẫn là lựa chọn đúng [S3].
+
+## Implementation Checklist
+
+Khi đưa harness vào repository thật:
+
+- kiểm kê setup, test, CI, docs, và failure mode đang xảy ra;
+- tạo artifact tối thiểu trong contract;
+- viết feature đầu tiên mô tả chính harness và verify command của nó;
+- tạo smoke test rẻ nhất cho setup;
+- tạo ít nhất một negative test cho trạng thái sai;
+- chạy verify, ghi evidence, rồi mới dùng harness cho task sản phẩm [S1], [S2].
+
+## Conclusion
+
+Kết luận thực dụng từ năm nguồn là:
+
+1. Đừng bắt đầu bằng harness phức tạp.
+2. Bắt đầu bằng task rõ, state bền vững, setup lặp lại, và verify thật [S2],
+   [S3].
+3. Thêm tool quan sát khi agent không thấy runtime [S1], [S2], [S4].
+4. Tách generator khỏi evaluator khi self-review yếu [S4].
+5. Mã hóa invariant lặp lại thành rule chạy được [S1].
+6. Khi rule quá phức tạp để giữ tay, xem xét wrapper code sinh tự động như
+   AutoHarness [S5].
+
+Đây là định nghĩa thực dụng của harness engineering trong phạm vi [S1]–[S5]:
+không phải thêm nhiều agent, mà là xây môi trường để agent tạo tiến triển phần
+mềm có thể tiếp tục, kiểm chứng, và duy trì qua nhiều session.