codex-harness-engineering 0.1.4 → 0.1.6

package/docs/harness-engineering/implementation-playbook.md

@@ -1,370 +1,316 @@
-# Playbook triển khai harness
+# Harness Implementation Playbook
 
-Playbook này chuyển năm bài OpenAI/Anthropic/Google thành quy trình thiết kế harness
-cho repository phần mềm.
+Playbook này chuyển white paper thành quy trình triển khai thực tế trong một
+repository phần mềm.
 
-## Giả định
+## Mục tiêu
 
-- Repository là nguồn sự thật vận hành.
-- Bắt đầu bằng harness nhỏ nhất làm thay đổi hành vi agent.
-- "Done" nghĩa là có bằng chứng kiểm chứng được.
-- Con người đặt mục tiêu, ràng buộc, và tiêu chí; agent thực thi trong môi
-  trường có state, tool, feedback, và guardrail.
+Mục tiêu không phải là dựng một hệ thống agent phức tạp ngay từ đầu. Mục tiêu
+là tạo được baseline đủ nhỏ để:
 
-## Cây quyết định
+- session mới khởi động được;
+- agent biết việc nào đang mở;
+- trạng thái không bị mất giữa các session;
+- verify command chặn done sớm;
+- runtime có thể quan sát khi cần [S1], [S2], [S3], [S4], [S5].
 
-Áp dụng từ ít phức tạp đến nhiều phức tạp.
+## Nguyên tắc khởi đầu
 
-| Tín hiệu | Can thiệp tối thiểu | Nguồn |
-| --- | --- | --- |
-| Task nhỏ, test rõ | Agent đơn lẻ + acceptance criteria + lệnh verify | [S3] |
-| Task vượt một context | Feature list, progress log, git history, `init.sh` | [S2] |
-| Agent không biết chạy app | Setup script idempotent + smoke test đầu session | [S2] |
-| Code pass nhưng hành vi runtime fail | Browser/API/log/metric/trace check | [S1], [S2] |
-| Agent tự đánh giá quá lạc quan | Evaluator riêng + feedback cụ thể | [S4] |
-| Prompt mơ hồ hoặc app nhiều luồng | Planner + sprint contract + generator/evaluator | [S4] |
-| Throughput tạo drift kiến trúc | Lint, structural test, CI rule, cleanup định kỳ | [S1] |
-| Ràng buộc quá phức tạp để code thủ công | AutoHarness (yêu cầu LLM sinh wrapper bọc thực thi tự động) | [S5] |
-| Hành vi agent drift/cần tối ưu hóa vết chạy | Trajectory evaluation + LLM-as-a-judge + Meta-Evaluation (VeRO) | [S5] |
+1. Bắt đầu bằng harness nhỏ nhất có thể.
+2. Đưa state ra khỏi chat history.
+3. Chỉ thêm tool khi có failure mode thật.
+4. Biến rule lặp lại thành check chạy được.
+5. Ưu tiên dependency và abstraction mà agent có thể inspect, validate, và
+   modify trực tiếp; tránh phụ thuộc opaque ở upstream [S1].
+6. Giữ artifact ngắn, rõ vai, và dễ quét trong session mới [S1], [S2], [S3].
 
-Nếu không có failure mode cụ thể, chưa thêm lớp harness đó.
+## Rollout theo pha
 
-## Harness tối thiểu
+### Pha 0: Audit hiện trạng
 
-Một repository chưa có harness nên bắt đầu bằng:
+Kiểm kê:
 
-| Artifact | Mục đích | Nguồn |
-| --- | --- | --- |
-| `AGENTS.md` | Entry point ngắn: đọc gì, chạy gì, tránh gì | [S1] |
-| `README.md` | Mục tiêu dự án và lệnh cơ bản | [S1] |
-| `init.sh` hoặc lệnh setup | Khôi phục môi trường ở session mới | [S2] |
-| `feature_list.json` | Danh sách feature và trạng thái pass/fail | [S2] |
-| `progress.md` | Việc đã làm, verify đã chạy, việc tiếp theo | [S2] |
-| Git commit nhỏ, mô tả rõ | Checkpoint để session sau đọc lại hoặc revert khi cần | [S2] |
-| Task runner | Lệnh chuẩn cho setup/test/lint/build/smoke | [S2], [S3] |
-| Test hoặc smoke test | Bằng chứng tối thiểu trước và sau sửa | [S2], [S3] |
+- setup command hiện có;
+- test command;
+- CI;
+- docs;
+- failure mode đang gặp;
+- artifact nào đã giữ state;
+- artifact nào đang phình hoặc drift;
+- dependency nào opaque làm agent khó inspect, validate, hoặc modify [S1], [S2].
 
-Không thêm planner, evaluator, telemetry stack, hoặc cleanup automation nếu
-chưa có failure mode yêu cầu.
+Kết quả của pha này là một danh sách ngắn các điểm cần chặn trước khi thêm
+harness.
 
-Nếu phải chọn giữa prose thuần và state có cấu trúc cho tiến độ feature, ưu
-tiên dạng như `feature_list.json`: session mới dễ chọn một feature, giữ trạng
-thái pass/fail nhất quán, và tránh suy diễn lại từ ghi chú tự do [S2].
+### Pha 1: Minimum viable harness
 
-## Quy chuẩn tạo harness cho project khác
+Tạo các file tối thiểu:
 
-Áp dụng mục này khi đưa harness vào một repository sản phẩm hoặc nghiên cứu
-khác. Mục tiêu là tạo một baseline có thể tiếp tục qua session và phát hiện
-việc agent tuyên bố hoàn tất khi chưa cập nhật bằng chứng, không phải sao chép
-toàn bộ công cụ của repository mẫu [S1], [S2], [S3].
+- `AGENTS.md`
+- `README.md`
+- `init.sh`
+- `feature_list.json`
+- `progress.md`
+- `lessons.md`
+- `memory/README.md`
 
-### Chuẩn bắt buộc
+Contract tối thiểu:
 
-| Thành phần | Contract tối thiểu | Cách kiểm tra |
-| --- | --- | --- |
-| `AGENTS.md` | Nêu thứ tự đọc, lệnh khởi động, lệnh verify, giới hạn local, và rule cập nhật state | Session mới đọc được đường vào repo trong một lượt ngắn |
-| `README.md` | Mô tả mục tiêu, bản đồ artifact, và lệnh vận hành chính | Các artifact trong harness có link hoặc đường dẫn tìm được |
-| `init.sh` hoặc lệnh tương đương | Chạy baseline rẻ, lặp lại được ở đầu session | Chạy thành công trên checkout sạch hoặc báo lỗi hành động được |
-| `feature_list.json` hoặc trạng thái có cấu trúc tương đương | Mỗi capability có acceptance, verify command, status, evidence | Status chỉ chuyển sang verified sau khi lệnh liên quan pass |
-| `progress.md` | Mỗi vòng làm việc ghi task, artifact liên quan, kết quả verify và bước tiếp theo | Session mới xác định được công việc đang mở mà không cần chat history |
-| Test/verify command | Cưỡng chế invariant quan trọng thay vì chỉ ghi bằng prose | Lệnh verify fail khi invariant bị phá |
-
-Đây là diễn giải triển khai từ repository-local knowledge và mechanical
-guardrail của [S1], kết hợp state handoff và quy trình verify-before-status của
-[S2]. Với task nhỏ không thay đổi hành vi hay guardrail, project có thể chỉ
-dùng acceptance criteria và lệnh verify rõ theo nguyên tắc bắt đầu đơn giản
-của [S3].
-
-### Contract cập nhật state
-
-Một project áp dụng harness nên định nghĩa **behavior artifact** là file làm
-thay đổi cách sản phẩm, package, test, guardrail, skill hoặc agent hoạt động.
-Ví dụ thường gặp: source code, `scripts/`, `tests/`, `skills/`, manifest
-package, workflow verify, và `AGENTS.md`.
-
-Khi task chạm behavior artifact:
-
-1. Chạy baseline trước sửa và ghi lại trạng thái ban đầu nếu task có rủi ro
-   hồi quy.
-2. Nêu acceptance criteria và command kiểm chứng trước khi chuyển trạng thái.
-3. Sau khi verify pass, cập nhật feature state với evidence cụ thể.
-4. Thêm entry mới nhất vào progress, 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.
-
-Contract này ngăn hai failure mode: session sau mất dấu thay đổi đã làm và
-agent kết thúc sớm chỉ vì code/test cục bộ đã xanh trong khi state handoff chưa
-được cập nhật [S2]. Khi omission lặp lại, quy tắc này nên được mã hóa thành
-check chạy được thay vì phụ thuộc vào nhắc nhở prose [S1].
-
-### Gate cơ học tối thiểu
-
-Project có thay đổi hành vi qua nhiều session nên đưa các invariant sau vào
-`verify` hoặc CI:
-
-| Invariant | Gate đề xuất |
-| --- | --- |
-| Artifact bắt buộc không bị mất | Fail khi thiếu `AGENTS.md`, state file, bootstrap hoặc docs map cần thiết |
-| Thay đổi hành vi không thiếu handoff | Nếu diff chạm behavior artifact, fail khi không có cập nhật feature state và progress |
-| Progress không dùng bằng chứng cũ | Entry progress mới nhất phải nêu behavior artifact đang đổi và command verify vừa chạy |
-| Feature không được đánh dấu sớm | Chỉ chấp nhận trạng thái verified khi có evidence gắn với verify command |
-| Quy tắc kiến trúc lặp lại | Dùng lint hoặc structural test thay cho review comment lặp lại |
-
-Phạm vi so sánh diff phải khớp workflow của project: nếu agent verify trước
-commit, có thể so với `HEAD`; nếu CI kiểm sau commit, phải so với base branch
-hoặc pull request base. Không chọn baseline diff mơ hồ vì gate sẽ cho qua đúng
-failure mode mà nó cần chặn.
-
-### Checklist bootstrap
+- `AGENTS.md` là bản đồ vào repo theo progressive disclosure: lớp ngoài ngắn,
+  trỏ tới chi tiết sâu hơn, không phải manual dài [S1].
+- `init.sh` khởi động lại môi trường hoặc smoke test rẻ nhất [S2].
+- `feature_list.json` mô tả capability, acceptance, verify command, status,
+  evidence [S2].
+- `progress.md` ghi việc đang làm, artifact liên quan, verify vừa chạy, và bước
+  tiếp theo [S2].
+- `lessons.md` ghi mistake, root cause, rule, status [S1], [S2].
+- `memory/README.md` mô tả lớp lạnh, layout archive, và nhịp rotate [S1], [S2].
 
-Khi tạo harness cho repository mới:
+### Pha 2: Verify-before-status
+
+Thêm gate để chặn done sớm:
+
+- chỉ đánh dấu `verified` sau khi command verify pass;
+- entry progress mới nhất phải nêu behavior artifact đã đổi;
+- state change phải có evidence gắn với command vừa chạy;
+- diff chạm behavior artifact thì không được thiếu progress/feature update
+  [S1], [S2].
+
+### Pha 3: Runtime observability
+
+Chỉ thêm khi code pass nhưng behavior fail hoặc agent không thấy runtime:
+
+- browser automation;
+- API checks;
+- log, metric, trace;
+- database state checks [S1], [S2], [S4].
 
-1. Kiểm kê setup, test, CI, tài liệu và failure mode đang xảy ra.
-2. Tạo artifact tối thiểu trong bảng chuẩn bắt buộc; không thêm evaluator hoặc
-   automation khi chưa có lỗi tương ứng.
-3. Viết một feature đầu tiên mô tả chính harness và command verify của nó.
-4. Tạo smoke test rẻ nhất cho `init.sh` hoặc lệnh bootstrap tương đương.
-5. Tạo ít nhất một negative test chứng minh gate fail khi bỏ state update hoặc
-   phá invariant quan trọng.
-6. Chạy verify, ghi evidence vào feature state và progress, rồi mới dùng
-   harness cho task sản phẩm.
+Mỗi tool thêm vào nên được mô tả như interface rõ ràng — tham số, ranh giới, và
+ví dụ sử dụng — để agent gọi đúng [S3].
 
-Negative test là bước quan trọng: một verifier chỉ pass trên baseline hợp lệ
-chưa chứng minh nó chặn được lỗi quy trình cần kiểm soát. Đây là cách thực thi
-nguyên tắc biến feedback lặp lại thành guardrail cơ học [S1], đồng thời giữ
-state handoff kiểm chứng được giữa các session [S2].
+### Pha 4: Evaluation separation
 
-## Phân tầng nguồn sự thật
+Chỉ thêm khi self-review hoặc chất lượng chủ quan là failure mode:
 
-Giữ artifact ngắn, đúng vai, và dễ quét trong session mới.
+- generator riêng;
+- evaluator riêng;
+- rubric rõ;
+- sprint contract nêu rõ phạm vi, tiêu chí done, và phương thức QA;
+- evidence rõ cho evaluator [S4].
 
-| Artifact | Nên chứa | Không nên chứa | Nguồn |
-| --- | --- | --- | --- |
-| `AGENTS.md` | Bản đồ vào repo: đọc gì trước, lệnh nào chuẩn, điều gì bị cấm | Toàn bộ lịch sử dự án hoặc manual quá dài | [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 theo từng session | [S1] |
-| `feature_list.json` hoặc tương đương | Scope công việc và trạng thái pass/fail theo feature | Rule kiến trúc chung của repo | [S2] |
-| `progress.md` | Verify đã chạy, lỗi đang mở, bước kế tiếp | Chính sách bền vững lặp lại cho mọi task | [S2] |
-| Test, lint, structural check | Invariant cần cưỡng chế bằng máy | Giải thích dài dòng thay cho check chạy được | [S1] |
+### Pha 5: Mechanical guardrails
 
-Nếu một quyết định cần agent dùng lặp lại, nó nên sống trong repo và ở đúng
-artifact của nó; nếu chỉ nằm trong chat, session mới khó khôi phục đáng tin
-cậy [S1], [S2].
+Chỉ thêm khi quy tắc kiến trúc hoặc quy tắc quy trình lặp lại:
 
-## Bảo trì source of truth
+- lint;
+- structural test;
+- CI rule;
+- cleanup cadence;
+- doc freshness hoặc cross-link checks [S1].
 
-Không nên dừng ở việc "có tài liệu". Với tri thức vận hành quan trọng, harness
-nên ưu tiên progressive disclosure và thêm check cơ học cho freshness,
-cross-link, hoặc độ khớp giữa map tài liệu và cấu trúc repo thực tế [S1].
+### Pha 6: Wrapper synthesis
 
-Trigger nên thêm check kiểu này khi:
+Chỉ thêm khi rule quá phức tạp để viết tay hoặc chi phí runtime là vấn đề:
 
-- `AGENTS.md` bắt đầu trỏ tới tài liệu đã đổi tên hoặc không còn đúng;
-- index trong `docs/` không còn phản ánh nơi source of truth thực sự nằm;
-- agent lặp lại việc đọc nhầm tài liệu cũ hoặc bỏ qua tài liệu mới;
-- review thường xuyên phát hiện policy trong prose nhưng không được cập nhật.
+- wrapper code sinh tự động;
+- policy thành code tĩnh;
+- verify chặt trước khi chấp nhận [S5].
 
-Nếu drift này xảy ra nhiều lần, một tác vụ doc-gardening định kỳ hoặc lint nhẹ
-cho docs thường rẻ hơn việc nhắc lại trong prompt mỗi session [S1].
+Bằng chứng từ AutoHarness cho thấy harness sinh tự động có thể giúp một model
+nhỏ hơn vượt model lớn hơn trên các môi trường thử nghiệm, nên đây là cách bù
+năng lực mô hình chứ không chỉ là tối ưu chi phí runtime [S5].
 
-## Vòng lặp session
+## Quyết định can thiệp
 
-Mỗi session agent dài hạn nên làm:
+| Tín hiệu | Can thiệp tối thiểu | Khi nào dừng |
+| --- | --- | --- |
+| Task nhỏ, test rõ | Agent đơn lẻ + acceptance criteria + verify command | Khi pass test và state đã cập nhật [S3] |
+| Vượt một session | Feature list + progress + git history + init.sh | Khi session mới có thể tiếp tục không cần chat history [S2] |
+| Không biết chạy app | Setup script idempotent + smoke test | Khi session mới bootstrap được [S2] |
+| Runtime fail | Browser/API/log/metric/trace | Khi hành vi thật đã quan sát được [S1], [S2], [S4] |
+| Self-review yếu | Evaluator riêng | Khi rubric và evidence rõ [S4] |
+| Scope mơ hồ | Planner + sprint contract | Khi generator và evaluator đồng thuận scope [S4] |
+| Drift kiến trúc | Lint + structural test + cleanup | Khi rule được cưỡng chế bằng máy [S1] |
+| Rule quá phức tạp | AutoHarness / synthesized wrapper | Khi wrapper chặn được hành vi sai trước runtime [S5] |
+
+## Session loop chuẩn
+
+Mỗi session dài hạn nên chạy theo vòng này:
 
 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 đây.
-5. Chạy `init.sh` hoặc setup command.
-6. Chạy smoke test rẻ nhất để biết repo có đang sạch không.
+3. Đọc `feature_list.json`.
+4. Xem git history gần nhất.
+5. Chạy `init.sh`.
+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. Triển khai thay đổi nhỏ nhất.
+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. Ghi progress và commit nếu workflow yêu cầu.
+11. Chỉ đổi trạng thái 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 checkpoint nếu workflow yêu cầu [S1], [S2].
 
-Vòng này trực tiếp xử lý lost context, done sớm, môi trường hỏng, và thiếu kiểm
-thử đầu-cuối [S2].
+Hai lưu ý về checkpoint và reset:
 
-Nếu harness thường chạy dài hoặc qua nhiều lần reset, thiết kế nó như thể
-context reset sẽ xảy ra thường xuyên: artifact khởi động phải đủ ngắn để quét
-nhanh, commit phải đủ rõ để đọc lại, và setup phải đủ lặp lại để session mới
-không phụ thuộc ký ức hội thoại cũ [S2], [S4].
+- Commit mô tả rõ và progress update không chỉ để audit; chúng tạo checkpoint
+  để revert thay đổi xấu và khôi phục working state sạch hơn [S2].
+- Nếu state handoff đủ tốt, context reset giữa session là chủ đích chứ không
+  phải mất mát: reset giúp model bám task thay vì trượt theo context anxiety
+  [S4].
 
-Checkpoint thực dụng trước khi bắt đầu sửa code:
+## Artifact contract chi tiết
 
-- nếu `AGENTS.md` dài đến mức không quét nhanh được, rút nó về vai trò bản đồ;
-- nếu `progress.md` lặp lại policy chung, chuyển policy đó sang artifact bền
-  vững hơn;
-- nếu feature list không nói rõ thế nào là pass, thêm bước verify cụ thể trước
-  khi triển khai.
+### `AGENTS.md`
 
-## Acceptance contract
+Nên chứa:
 
-Dùng cho bug hoặc feature nhỏ.
+- thứ tự đọc;
+- lệnh khởi động;
+- lệnh verify;
+- quy tắc cập nhật state;
+- giới hạn local;
+- đường dẫn tới docs sâu hơn.
 
-```markdown
-# Acceptance Contract
+Không nên chứa:
 
-## Scope
-- Feature/fix:
-- User-visible behavior:
-- Likely files:
+- lịch sử dài;
+- policy trùng lặp;
+- hướng dẫn lan man [S1].
 
-## Acceptance Criteria
-- [ ] ...
-- [ ] ...
+### `feature_list.json`
 
-## Verification
-- Unit:
-- Integration:
-- Browser/API:
-- Log/metric/trace:
+Nên có:
 
-## Out of Scope
-- ...
-```
+- `id`;
+- `title`;
+- `status`;
+- `acceptance`;
+- `verify`;
+- `evidence`.
 
-Contract nên ngắn hơn phần việc. Nếu dài hơn phần việc, chia nhỏ scope.
+Chuyển `status` sang verified chỉ khi evidence gắn với verify command [S2].
 
-## Sprint contract
+### `progress.md`
 
-Dùng khi task trải qua nhiều file, nhiều luồng runtime, hoặc chất lượng chủ quan.
+Nên có:
 
-```markdown
-# Sprint Contract
+- context;
+- relevant files;
+- done;
+- verification;
+- next.
 
-## Scope
-- Feature:
-- User path:
-- API/data path:
-- Likely files/modules:
+Entry mới nhất phải nhắc đúng behavior artifact đang đổi [S2].
 
-## Done Means
-- [ ] User can ...
-- [ ] API/data reflects ...
-- [ ] Error state handles ...
-- [ ] No regression in ...
+### `lessons.md`
 
-## Verification
-- Unit:
-- Integration:
-- Browser/API:
-- Log/metric/trace:
+Nên dùng cho mistake do agent gây ra.
 
-## Evaluator Focus
-- Runtime behavior:
-- Negative cases:
-- UX/quality concerns:
+Format tối thiểu:
 
-## Out of Scope
-- ...
-```
+- Mistake
+- Root cause
+- Rule
+- Status
 
-Sprint contract là chuẩn chung giữa generator và evaluator. Nó giảm scope drift
-và làm feedback của evaluator cụ thể hơn [S4].
+Khi cùng một rule lặp lại, promote nó vào `AGENTS.md` hoặc một gate [S1],
+[S2].
 
-## Planner, generator, evaluator
+### `memory/README.md`
 
-Chỉ dùng ba vai khi task đủ lớn.
+Nên chứa:
 
-| Vai | Trách nhiệm | Không làm |
-| --- | --- | --- |
-| Planner | Chuyển prompt thành spec, scope, sprint contract | Viết toàn bộ code |
-| Generator | Triển khai phần nhỏ nhất theo contract | Mở rộng ngoài scope |
-| Evaluator | Kiểm thử runtime và báo lỗi cụ thể | Chỉ đọc diff rồi khen đạt |
+- contract của lớp lạnh;
+- layout archive;
+- khi nào rotate;
+- file nào là hot và file nào là cold.
 
-Evaluator tốt phải nêu bằng chứng: screenshot, DOM state, API response, database
-state, log, trace, hoặc command output. Feedback nên nói tiêu chí nào fail và
-bước sửa tiếp theo là gì [S4].
+Không nên chứa:
 
-Bên cạnh đó, áp dụng **đánh giá vết thực thi (Trajectory Evaluation)** để đánh giá cả
-chuỗi hành động và suy luận của agent (tool calling sequence, logic steps) thông qua
-**LLM-as-a-judge** tự động để chấm điểm hiệu năng thực tế. Có thể dùng **VeRO (Meta-Evaluation)**
-để chạy một vòng lặp tối ưu hóa tự động cấu trúc prompt/tool dựa trên các vết chạy lỗi [S5].
+- state tác vụ đang mở;
+- ghi chú ngắn hạn theo session.
 
-## Legibility map
+## Bootstrap checklist
 
-Khi agent không thấy hành vi thật, bổ sung tín hiệu theo bảng sau.
+Khi tạo harness cho repository mới:
 
-| Khu vực | Tín hiệu | Cách verify |
-| --- | --- | --- |
-| UI | Browser automation, screenshot, DOM snapshot | Chạy user path chính |
-| API | Request/response, contract test | Gọi endpoint và kiểm dữ liệu |
-| Backend | Structured log, metric, trace | Quan sát lỗi, latency, span |
-| Data | Schema, seed, query kiểm tra | Kiểm state trước/sau action |
-| Build | Build log, CI log | Chạy lệnh chuẩn |
-| Architecture | Import boundary, structural test | Chạy lint/test guardrail |
+1. Kiểm kê setup, test, CI, docs, và failure mode.
+2. Tạo artifact tối thiểu.
+3. Viết feature đầu tiên mô tả chính harness.
+4. Tạo smoke test rẻ nhất cho `init.sh`.
+5. Tạo negative test cho thiếu state update hoặc phá invariant.
+6. Chạy verify, ghi evidence, rồi mới dùng harness cho task sản phẩm [S1],
+   [S2].
+
+## Gate tối thiểu
+
+Nên fail khi:
+
+- thiếu artifact bắt buộc;
+- diff chạm behavior artifact nhưng thiếu update state;
+- progress mới nhất không nêu behavior artifact và verify command;
+- feature bị đánh dấu sớm;
+- rule kiến trúc lặp lại nhưng chưa bị mã hóa thành gate [S1], [S2].
 
-Legibility nghĩa là tín hiệu cần thiết nằm trong tầm đọc của agent, không phải
-thêm log tùy tiện [S1].
+## Khi nào chưa nên thêm lớp mới
 
-Legibility cũng áp vào lựa chọn stack và abstraction. Nếu hai giải pháp tương
-đương về yêu cầu sản phẩm, ưu tiên giải pháp có API ổn định, hành vi dễ kiểm
-chứng, và phần quan trọng nằm trong repo thay vì ẩn sau upstream khó quan sát.
-Khi agent thường xuyên kẹt ở một thư viện opaque, đó là tín hiệu xem lại
-abstraction chứ không chỉ siết prompt [S1].
+Chưa thêm planner, evaluator, telemetry stack, hoặc automation nếu:
 
-## Guardrail cơ học
+- task nhỏ;
+- đường đi rõ;
+- failure mode chưa xuất hiện;
+- state handoff hiện tại đã đủ [S3].
 
-Khi một rule quan trọng lặp lại, đưa nó từ prose sang check.
+## Khi nào phải xem lại harness
 
-Ví dụ:
+Xem lại harness khi:
 
-- cấm dependency đi ngược layer;
-- yêu cầu parse dữ liệu ở boundary;
-- yêu cầu structured logging ở luồng quan trọng;
-- giới hạn file size nếu drift kích thước gây hại;
-- chặn update feature status nếu verify chưa pass;
-- chạy smoke test trước merge;
-- dùng AutoHarness để tự động sinh lớp bọc thực thi (code harness) khi môi trường có quá nhiều luật phức tạp hoặc khó kiểm soát bằng linter tĩnh [S5]. Lớp bọc này lọc và chặn các hành vi vi phạm trước khi thực thi [S5];
-- biên dịch chính sách quyết định thành code tĩnh (Harness-as-Policy) để thực thi nhanh và tiết kiệm token ở runtime [S5].
+- model mới làm orchestration cũ không còn load-bearing;
+- docs và code drift nhau;
+- session mới phải đoán quá nhiều;
+- cleanup không còn theo kịp throughput [S1], [S4].
 
-Guardrail chỉ nên bảo vệ invariant thật. Rule quá rộng tạo nhiễu và làm agent
-tối ưu quanh check thay vì quanh mục tiêu [S1], [S3].
+## Mẫu rollout thực tế
 
-## Cleanup
+### Tuần 1
 
-Khi throughput tăng, cleanup phải có trigger và verify.
+- dựng minimum viable harness;
+- thêm smoke test;
+- thêm feature đầu tiên;
+- thêm state update contract [S1], [S2].
 
-Trigger hợp lý:
+### Tuần 2
 
-- cùng một helper xuất hiện nhiều lần;
-- feature bypass architecture boundary;
-- progress log lặp lại cùng lỗi;
-- evaluator liên tục bắt cùng nhóm defect;
-- code mới tạo workaround thay vì sửa nguyên nhân.
+- thêm verify gate;
+- thêm negative test;
+- chuẩn hóa progress entry;
+- chuẩn hóa evidence [S1], [S2].
 
-Cleanup task nên có scope, acceptance criteria, verification, và rollback path.
-Đây là garbage collection cho codebase agent-first [S1].
+### Tuần 3
 
-## Ablation harness
+- thêm runtime observability nếu cần;
+- thêm evaluator nếu self-review yếu;
+- thêm cleanup rule nếu drift bắt đầu xuất hiện [S1], [S4].
 
-Sau khi model hoặc tooling thay đổi, xem lại harness:
+### Tuần 4+
 
-| Lớp | Câu hỏi ablation |
-| --- | --- |
-| Feature list | Nếu bỏ, agent có đánh dấu xong sớm không? |
-| Progress log | Nếu bỏ, session mới có mất context không? |
-| `init.sh` | Nếu bỏ, agent có mất thời gian đoán setup không? |
-| Browser/API check | Nếu bỏ, runtime defect có tăng không? |
-| Evaluator | Nếu gộp vào generator, chất lượng có giảm không? |
-| Planner | Nếu bỏ planner, scope có drift không? |
-| Guardrail | Nếu tắt rule, vi phạm có xuất hiện lại không? |
-| AutoHarness | Nếu dùng code tĩnh thay vì gọi LLM ở runtime, latency và cost có giảm đáng kể mà vẫn giữ được chất lượng không? [S5] |
-| Trajectory Eval | Nếu không chấm vết chạy mà chỉ chấm kết quả tĩnh, ta có bỏ sót các lỗi tiềm ẩn trong suy luận của agent không? [S5] |
+- promote lessons lặp lại thành guardrail;
+- re-check docs freshness;
+- loại bỏ lớp harness không còn giá trị [S1], [S4].
 
-Giữ phần rẻ và hiệu quả. Loại bỏ orchestration đắt nếu không còn tạo outcome
-tốt hơn [S4].
+## Anti-patterns
 
-## Definition of done
+- Đưa quá nhiều policy vào `AGENTS.md`.
+- Dùng prose thay cho gate.
+- Mark verified trước verify.
+- Để state trong chat thay vì file.
+- Thêm evaluator trước khi có failure mode rõ.
+- Giữ wrapper cũ dù model mới không còn cần nó [S1], [S2], [S4], [S5].
 
-Một thay đổi harness hoàn thành khi:
+## Kết luận triển khai
 
-- scope và acceptance criteria rõ;
-- lệnh hoặc quan sát verify đã chạy;
-- state/progress chỉ cập nhật sau verify;
-- guardrail mới gắn với failure mode thật;
-- tài liệu chỉ cite `[S1]-[S5]`;
-- không còn placeholder hoặc nguồn ngoài phạm vi.
+Nếu áp dụng đúng thứ tự, harness tốt nhất thường là harness nhỏ nhất có thể
+giữ được state, verify, và observability. Mọi lớp thêm vào đều phải trả lời
+được một failure mode thật. Nếu không, nó chỉ làm hệ thống nặng hơn mà không
+làm agent đáng tin hơn [S1], [S2], [S3], [S4], [S5].