codex-harness-engineering 0.1.4

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

@@ -0,0 +1,318 @@
+# Harness Engineering cho AI Agent làm việc dài hạn
+
+## Tóm tắt
+
+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].
+
+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.
+
+## 1. Vấn đề
+
+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à:
+
+- 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].
+
+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].
+
+### 4.4 Tách sinh kết quả khỏi đánh giá
+
+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].
+
+Đ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].
+
+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].
+
+### 4.5 Dùng sprint contract cho task dài
+
+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].
+
+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].
+
+### 4.6 Cưỡng chế invariant bằng cơ chế kỹ thuật
+
+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].
+
+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].
+
+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].
+
+### 4.7 Cleanup là một phần của harness
+
+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].
+
+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.
+
+## 5. Lợi ích
+
+### 5.1 Tiến triển dài hạn tốt hơn
+
+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].
+
+### 5.2 QA tốt hơn
+
+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].
+
+Đá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].
+
+### 5.3 Judgment của con người tích lũy
+
+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].
+
+### 5.4 Tốc độ cao hơn nếu môi trường đủ chín
+
+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.
+
+## 6. Chi phí và giới hạn
+
+### 6.1 Complexity có giá
+
+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].
+
+### 6.2 Model capability thay đổi thiết kế harness
+
+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].
+
+### 6.3 Evaluator vẫn có giới hạn
+
+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].
+
+### 6.4 Kết quả không tự động tổng quát hóa
+
+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].
+
+## 7. Mô hình tổng hợp
+
+Một harness trưởng thành có thể được đọc như hệ điều khiển gồm bốn lớp:
+
+| Lớp | Câu hỏi | Artifact điển hình | 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á.

package/docs/harness-engineering/sources.md

@@ -0,0 +1,126 @@
+# Nguồn
+
+File này chỉ theo dõi bốn nguồn được phép dùng trong bản nghiên cứu hiện tại.
+Không thêm claim vào tài liệu nếu claim đó không ánh xạ tới một trong bốn nguồn
+này hoặc không được đánh dấu rõ là diễn giải.
+
+## Danh mục nguồn
+
+### [S1] OpenAI
+
+- Tiêu đề: "Harness engineering: leveraging Codex in an agent-first world"
+- Tác giả: Ryan Lopopolo
+- Ngày xuất bản: 11 tháng 2, 2026
+- URL: https://openai.com/index/harness-engineering/
+- Dùng cho:
+  - framing "humans steer, agents execute";
+  - harness engineering như thiết kế environment, intent specification, và
+    feedback loop quanh Codex;
+  - repository knowledge base như system of record;
+  - `AGENTS.md` như bản đồ, không phải cẩm nang khổng lồ;
+  - ưu tiên dependency, abstraction, và thông tin mà agent có thể inspect,
+    validate, và modify trực tiếp trong repo;
+  - application, browser, log, metric, và trace như tín hiệu agent đọc được;
+  - progressive disclosure cho tri thức trong repo và kiểm tra cơ học về
+    freshness/cross-link để giảm drift của tài liệu;
+  - cưỡng chế architecture và taste bằng lint, structural test, và custom rule;
+  - throughput, merge philosophy, autonomy, entropy, và cleanup định kỳ;
+  - cảnh báo rằng mức tự chủ phụ thuộc vào cấu trúc và tooling cụ thể của repo.
+
+### [S2] Anthropic
+
+- Tiêu đề: "Effective harnesses for long-running agents"
+- Tác giả: Justin Young
+- Ngày xuất bản: 26 tháng 11, 2025
+- URL: https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
+- Dùng cho:
+  - failure mode của agent qua nhiều context window;
+  - initializer agent và coding agent;
+  - feature list dạng JSON với trạng thái pass/fail;
+  - tiến triển từng feature thay vì làm quá rộng;
+  - progress file, git commit, và `init.sh`;
+  - kiểm thử đầu-cuối bằng browser automation;
+  - vòng bắt đầu session: đọc progress, feature list, git log, setup, smoke test.
+
+### [S3] Anthropic
+
+- Tiêu đề: "Building effective agents"
+- Tác giả: Erik Schluntz và Barry Zhang
+- Ngày xuất bản: 19 tháng 12, 2024
+- URL: https://www.anthropic.com/engineering/building-effective-agents
+- Dùng cho:
+  - phân biệt workflow định tuyến sẵn và agent tự điều khiển process/tool;
+  - nguyên tắc bắt đầu bằng giải pháp đơn giản nhất;
+  - tradeoff giữa performance, latency, cost, và complexity;
+  - building block "augmented LLM" với retrieval, tool, và memory;
+  - workflow pattern như prompt chaining, routing, parallelization,
+    orchestrator-workers, evaluator-optimizer;
+  - thiết kế agent-computer interface và tool definition dễ dùng.
+
+### [S4] Anthropic
+
+- Tiêu đề: "Harness design for long-running application development"
+- Tác giả: Prithvi Rajasekaran
+- Ngày xuất bản: 24 tháng 3, 2026
+- URL: https://www.anthropic.com/engineering/harness-design-long-running-apps
+- Dùng cho:
+  - vấn đề context anxiety và self-evaluation;
+  - tách generator khỏi evaluator;
+  - grading criteria để làm chất lượng chủ quan dễ chấm hơn;
+  - planner-generator-evaluator cho phát triển ứng dụng dài hạn;
+  - sprint contract giữa generator và evaluator;
+  - QA bằng Playwright qua UI, API, database state, và hành vi runtime;
+  - chi phí, độ trễ, và token cost của harness phức tạp;
+  - nguyên tắc xem lại harness khi model mới làm một số lớp orchestration không
+    còn load-bearing.
+
+### [S5] Google
+
+- Tiêu đề: "AutoHarness: Improving LLM Agents by Automatically Synthesizing a Code Harness" (Google DeepMind) và thực tiễn vận hành Agent/Evaluation Harness trên Google Cloud.
+- Tác giả: Google DeepMind & Google Cloud
+- Ngày xuất bản: 2024-2026
+- URL: https://arxiv.org/abs/2406.11252
+- Dùng cho:
+  - AutoHarness: Tự động tổng hợp lớp bọc thực thi (code harness/wrapper) bằng LLM để chặn hành động lỗi và cưỡng chế ràng buộc;
+  - Harness-as-Policy: Biên dịch chính sách quyết định thành code tĩnh để giảm chi phí/độ trễ runtime về 0;
+  - Trajectory Evaluation: Đánh giá vết chạy đầy đủ (gồm tool call, suy luận) thay vì chỉ chấm điểm kết quả tĩnh;
+  - LLM-as-a-Judge tự động & Meta-Evaluation (VeRO) để liên tục tối ưu cấu trúc của agent.
+
+## Bản đồ bằng chứng
+
+| Nhận định | Nguồn |
+| --- | --- |
+| Harness engineering chuyển trọng tâm kỹ sư từ viết code tay sang thiết kế môi trường, intent, và feedback loop. | [S1] |
+| Repository-local knowledge giúp agent truy cập quyết định, quy tắc, và trạng thái mà không phụ thuộc chat history. | [S1] |
+| `AGENTS.md` nên là bản đồ ngắn trỏ tới nguồn sự thật sâu hơn, không phải một manual khổng lồ. | [S1] |
+| Chọn dependency và abstraction nên tính đến việc agent có thể inspect, validate, và modify chúng trực tiếp; hành vi opaque ở upstream làm giảm leverage. | [S1] |
+| Agent cần application legibility: UI, log, metric, trace, và môi trường dev có thể quan sát được. | [S1] |
+| Repository knowledge nên theo progressive disclosure và có kiểm tra cơ học cho freshness/cross-link; doc-gardening định kỳ giúp giảm drift của source of truth. | [S1] |
+| Documentation đơn thuần không đủ; architecture và taste nên được cưỡng chế bằng lint, structural test, và custom rule. | [S1] |
+| Throughput cao làm entropy tích lũy nhanh, nên cleanup định kỳ là một phần của harness. | [S1] |
+| Agent dài hạn dễ mất context giữa các session và cần externalized state. | [S2] |
+| Feature list, progress file, git history, và `init.sh` giúp session mới phục hồi trạng thái. | [S2] |
+| Feature list dạng JSON giúp agent giữ trạng thái feature có cấu trúc và cập nhật pass/fail nhất quán qua nhiều session. | [S2] |
+| Git commit mô tả rõ và progress update không chỉ để audit; chúng còn tạo checkpoint để agent revert thay đổi xấu và khôi phục working state sạch hơn. | [S2] |
+| Làm từng feature và chỉ đánh dấu pass sau kiểm thử giúp giảm tuyên bố hoàn thành sớm. | [S2] |
+| Browser automation giúp agent phát hiện lỗi không thấy được từ code hoặc unit test đơn lẻ. | [S2] |
+| Agentic system nên bắt đầu bằng giải pháp đơn giản nhất và chỉ tăng complexity khi cần. | [S3] |
+| Workflow phù hợp với task có đường đi định sẵn; agent phù hợp khi cần model tự quyết định tool/process. | [S3] |
+| Tool nên được thiết kế như agent-computer interface với mô tả, tham số, ranh giới, và ví dụ rõ. | [S3] |
+| Generator tự đánh giá thường quá tích cực; evaluator riêng dễ được chỉnh thành hoài nghi hơn. | [S4] |
+| Sprint contract giúp generator và evaluator đồng thuận về phạm vi, tiêu chí done, và phương thức QA. | [S4] |
+| Context reset có thể là một phần chủ đích của harness; nếu state handoff đủ tốt, reset giúp giữ model bám task thay vì trượt theo context anxiety. | [S4] |
+| Harness phức tạp có thể tốn nhiều giờ và token, nên phải được xem là tradeoff thay vì mặc định. | [S4] |
+| Khi model mới xuất hiện, nên xem lại và loại bỏ các phần harness không còn tạo giá trị. | [S4] |
+| Thay vì tự viết thủ công mọi ràng buộc, mô hình (như Gemini Flash) có thể tự động tổng hợp lớp bọc thực thi (AutoHarness) bằng code để lọc các hành động lỗi. | [S5] |
+| Biên dịch chính sách quyết định thành code tĩnh (Harness-as-Policy) giúp loại bỏ việc gọi mô hình ở runtime, tối ưu hóa chi phí và độ trễ. | [S5] |
+| Đánh giá agent dài hạn cần dựa trên vết chạy đầy đủ (Trajectory Evaluation) bao gồm cả chuỗi gọi tool và suy luận, thay vì chỉ so sánh kết quả đầu ra tĩnh. | [S5] |
+| LLM-as-a-Judge tự động giúp đo lường độ an toàn và hiệu năng của agent liên tục, và Meta-Evaluation (VeRO) tối ưu hóa cấu trúc của harness dựa trên phản hồi. | [S5] |
+
+## Chính sách citation
+
+- Chỉ dùng mã `[S1]`, `[S2]`, `[S3]`, `[S4]`, `[S5]`.
+- Không thêm citation, paper, DOI, benchmark, hoặc blog ngoài phạm vi nếu chưa
+  được yêu cầu.
+- Nếu mở rộng phạm vi sau này, phải cập nhật file này trước rồi mới cập nhật
+  `research-note.md` hoặc `implementation-playbook.md`.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "codex-harness-engineering",
+  "version": "0.1.4",
+  "description": "Codex harness engineering docs and installable agent skills.",
+  "keywords": [
+    "codex",
+    "harness-engineering",
+    "agent-skills",
+    "ai-agents",
+    "long-running-agents"
+  ],
+  "type": "module",
+  "bin": {
+    "codex-harness-engineering": "scripts/install-skills.mjs",
+    "codex-harness-install-skills": "scripts/install-skills.mjs"
+  },
+  "files": [
+    "AGENTS.md",
+    "README.md",
+    "docs",
+    "scripts",
+    "skills"
+  ],
+  "scripts": {
+    "test": "node --test tests/*.test.mjs",
+    "verify": "node scripts/verify-harness.mjs && npm test",
+    "pack:dry": "npm pack --dry-run",
+    "release": "./scripts/publish.sh",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "UNLICENSED"
+}

package/scripts/install-skills.mjs

@@ -0,0 +1,104 @@
+#!/usr/bin/env node
+
+import { realpathSync } from "node:fs";
+import { access, cp, mkdir, rm } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+
+export const SKILL_NAMES = [
+  "acceptance-contract",
+  "cleanup-harness",
+  "creator-harness",
+];
+
+async function exists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function assertCanWrite(target, force) {
+  if (!force && await exists(target)) {
+    throw new Error(`${target} already exists. Re-run with --force to overwrite it.`);
+  }
+}
+
+export async function installSkills({
+  packageRoot = PACKAGE_ROOT,
+  projectRoot = process.cwd(),
+  force = false,
+} = {}) {
+  const sourceRoot = path.join(packageRoot, "skills");
+  const targetRoot = path.join(projectRoot, ".agents", "skills");
+  const docsSource = path.join(packageRoot, "docs", "harness-engineering");
+  const docsTarget = path.join(projectRoot, "docs", "harness-engineering");
+  const installed = [];
+
+  await mkdir(targetRoot, { recursive: true });
+
+  for (const skillName of SKILL_NAMES) {
+    const source = path.join(sourceRoot, skillName);
+    const target = path.join(targetRoot, skillName);
+
+    if (path.resolve(source) !== path.resolve(target)) {
+      await assertCanWrite(target, force);
+      await rm(target, { recursive: true, force: true });
+      await cp(source, target, { recursive: true, force: true });
+    }
+    installed.push(skillName);
+  }
+
+  if (path.resolve(docsSource) !== path.resolve(docsTarget)) {
+    await assertCanWrite(docsTarget, force);
+    await rm(docsTarget, { recursive: true, force: true });
+    await cp(docsSource, docsTarget, { recursive: true, force: true });
+  }
+
+  return { targetRoot, docsTarget, installed };
+}
+
+export function parseArgs(args) {
+  const [command, ...flags] = args;
+
+  if (command !== "init") {
+    throw new Error("Usage: codex-harness-engineering init [--force]");
+  }
+
+  const unknownFlag = flags.find((flag) => flag !== "--force");
+  if (unknownFlag) {
+    throw new Error(`Unknown option: ${unknownFlag}`);
+  }
+
+  return { command, force: flags.includes("--force") };
+}
+
+function isDirectRun() {
+  if (!process.argv[1]) {
+    return false;
+  }
+
+  return pathToFileURL(realpathSync(process.argv[1])).href ===
+    pathToFileURL(realpathSync(fileURLToPath(import.meta.url))).href;
+}
+
+if (isDirectRun()) {
+  try {
+    const { force } = parseArgs(process.argv.slice(2));
+    const { targetRoot, docsTarget, installed } = await installSkills({ force });
+
+    console.log(`Installed ${installed.length} skills to ${targetRoot}`);
+    for (const skillName of installed) {
+      console.log(`- ${skillName}`);
+    }
+    console.log(`Copied docs to ${docsTarget}`);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+  }
+}