TL;DR

Một bộ máy đánh giá (evaluation harness) cấp độ sản xuất chỉ phát huy giá trị khi cấu trúc thiết lập (setup) của nó được trình bày rõ ràng. Đặc tả này định nghĩa frontmatter, các sections, và các hiện vật tài liệu bắt buộc mà bạn BẮT BUỘC PHẢI xuất bản cho mỗi eval suite. Mục tiêu là đảm bảo con người, các trình chạy CI (CI runners), và documentation agents (các LLMs đọc tài liệu) đều có thể nhất quán trả lời những câu hỏi: suite này đo lường điều gì, phương thức chấm điểm ra sao, và khi nào nó sẽ chặn một bản phát hành (release). Hãy áp dụng đặc tả này như một giao thức chuẩn giữa các đội ngũ phát triển agent, quản trị nền tảng (platform owners), và chuyên viên kiểm định chất lượng (quality reviewers).

Tại sao đặc tả này tồn tại

Phần lớn các hướng dẫn hiện tại thường tiếp cận evaluation harnesses dưới góc độ mã nguồn: cách lập trình một người chấm điểm (scorer), cách tích hợp (wire) một dataset, hoặc cách thực thi thử nghiệm đồng thời (concurrently). Cách tiếp cận này tạo ra khoảng trống lớn về mặt tài liệu. Anthropic phân định rất rõ evaluation harness — cơ sở hạ tầng chịu trách nhiệm thực thi evals toàn trình (end-to-end), cung cấp hướng dẫn (instructions) và công cụ (tools), xử lý tác vụ (tasks), ghi nhận các bước (steps), chấm điểm đầu ra (outputs), và tổng hợp kết quả (results) — hoàn toàn độc lập với agent harness mà nó đang kiểm thử.

Harness đó chỉ mang lại giá trị thực tiễn khi những người liên quan có thể diễn giải chính xác dữ liệu đầu ra. Nếu một regression eval sụt giảm từ 98% xuống 91%, kỹ sư trực ban (on-call engineer) cần xác định được scorer nào đã được kích hoạt (fired), trên phân vùng dữ liệu (slice) nào, với mức độ nghiêm trọng (severity) ra sao, và rubric nào đang định nghĩa tiêu chí đạt (pass). Những thông tin này BẮT BUỘC PHẢI được lưu trữ trong tài liệu chính thức, thay vì phân tán trong các luồng tin nhắn nội bộ.

Đặc tả này đóng vai trò chuẩn hóa hệ thống tài liệu nói trên. Nó được thiết kế tối ưu cho khả năng đọc-hiểu của LLMs — nhờ đó, các agents truy xuất tài liệu (RAG agents, doc bots, codegen agents) có thể dễ dàng trả lời câu hỏi "policy-compliance suite đang kiểm thử những gì?" mà không yêu cầu rà soát toàn bộ mã nguồn (crawling source).

Phạm vi

Trong phạm vi:

• Các trang tài liệu tĩnh (Static documentation pages) mô tả một eval suite trên mỗi bài viết.
• Các trường Frontmatter và các sections phần thân bắt buộc.
• Các liên kết chéo (Cross-references) tới các scorers, datasets, và rubrics.
• Quản lý phiên bản (Versioning), chu kỳ đánh giá (review cycles), và metadata về quyền sở hữu.

Ngoài phạm vi:

• Việc triển khai trình chạy (Runner implementation) bằng bất kỳ ngôn ngữ lập trình cụ thể nào.
• Định dạng lưu trữ đối với các trace artifacts.
• Đấu nối CI/CD (được xử lý bởi các tài liệu về kỹ thuật phát hành/release-engineering của bạn).
• Các điểm chuẩn hiệu suất theo từng mô hình (những thông tin đó thuộc về thẻ khả năng/capability cards).

Thuật ngữ

• Evaluation harness (Bộ máy đánh giá) — hệ thống chạy các evals từ đầu đến cuối (end-to-end): cấp phát (provisions) môi trường, thực thi agent, chụp lại quỹ đạo (trajectory), áp dụng các graders, tổng hợp kết quả.
• Agent harness (Bộ máy agent) — bộ giàn giáo (scaffold) bao quanh mô hình biến nó trở thành một agent (system prompt, các công cụ, vòng lặp điều phối, bộ nhớ). LangChain tóm tắt nó là "mọi thứ không phải là bản thân mô hình".
• Eval suite — một bộ sưu tập nhất quán bao gồm các tasks (nhiệm vụ) nhắm vào một năng lực (capability) hoặc hành vi cụ thể, ví dụ: "refunds-and-cancellations".
• Scorer / Grader (Người chấm điểm) — một hàm số (function) hoặc rubric đảm nhiệm việc gán kết quả pass/fail (đạt/trượt) hoặc điểm số dạng số. Bao gồm ba nhóm (families) chính: dựa-trên-code (code-based), dựa-trên-mô-hình (model-based tức LLM-as-judge), và con người (human).
• Trajectory (Quỹ đạo) — bản ghi chú được sắp xếp theo thứ tự hiển thị các quan sát (observations), quyết định (decisions), lệnh gọi công cụ (tool calls), và đầu ra (outputs) mà agent đã phát ra trong quá trình giải quyết một task.
• Capability eval vs regression eval — Cái đầu tiên dùng để hỏi "agent này có thể làm được gì?"; cái thứ hai dùng để hỏi "chúng ta có vô tình làm vỡ những thứ vốn đang hoạt động bình thường không?". Chúng có các đường cơ sở (baselines) và các ngữ nghĩa thiết lập rào chắn (gating semantics) khác nhau.

Các hiện vật tài liệu bắt buộc

Mỗi eval suite BẮT BUỘC PHẢI xuất bản ba hiện vật (artifacts) trên bề mặt tài liệu của bạn:

1. Suite spec page (Trang đặc tả suite) — văn bản tài liệu chịu sự chi phối của chính đặc tả này. Nó mô tả mục đích (intent), các scorers, datasets, rào chắn (gating).
2. Scorer reference page(s) (Trang tham chiếu cho scorer) — một trang cho mỗi scorer; định nghĩa các inputs, outputs, rubric, ghi chú hiệu chuẩn (calibration notes).
3. Dataset card (Thẻ tập dữ liệu) — mô tả nguồn gốc xuất xứ (provenance), cấp phép (licensing), định nghĩa lát cắt (slice definitions), nhịp độ làm mới (refresh cadence).

Trang đặc tả suite (Suite spec page) BẮT BUỘC PHẢI liên kết tới từng thẻ tham chiếu scorer và thẻ dataset thông qua một canonical URL. Người tiêu dùng (con người và agents) nên duyệt qua (traverse) từ suite cho đến các scorers và datasets chỉ bằng một cú nhấp chuột (one click).

Giao kèo Frontmatter cho các đặc tả suite

Mỗi trang đặc tả suite BẮT BUỘC PHẢI bao gồm các chuẩn frontmatter chung dành cho tài liệu (identity, canonical layer, taxonomy, SEO, AI readability, lifecycle, relations, i18n, authorship) CỘNG THÊM các trường dành riêng cho từng suite dưới đây nằm trong khối eval_suite::

[[CODE_FENCE_LANG=yaml]]

eval_suite:

suite_id: "refunds-and-cancellations"

suite_version: "2.3.0"

agent_under_test:

• "customer-support-agent"

eval_type:

• "capability"
• "regression"

trajectory_required: true

environment:

type: "sandboxed-sql"

fixtures: "fixtures/refunds-v2.sql"

scorers:

• id: "refund-recorded"

kind: "code"

doc: "/ai-agents/scorers/refund-recorded"

• id: "tone-empathy"

kind: "llm-judge"

doc: "/ai-agents/scorers/tone-empathy"

datasets:

• id: "refunds-golden-2026-q1"

doc: "/ai-agents/datasets/refunds-golden-2026-q1"

slices: ["happy-path", "edge-card-decline", "policy-violation"]

gating:

blocks_release: true

capability_baseline: 0.55

regression_floor: 0.97

severity_on_fail: "high"

owner: "agent-quality@example.com"

review_cycle_days: 30

[[/CODE_FENCE]]

Ngữ nghĩa của các trường:

• suite_id — định danh cố định (stable identifier) theo định dạng kebab-case; nghiêm cấm tái sử dụng định danh này sau khi suite đã ngừng hoạt động (retirement).
• eval_type — định dạng mảng (array); một suite có thể đảm nhiệm vai trò capability eval (đánh giá năng lực) và/hoặc regression eval (đánh giá hồi quy) tùy thuộc vào phân vùng dữ liệu (slice) được áp dụng.
• trajectory_required — thiết lập giá trị true nếu có bất kỳ scorer nào yêu cầu phân tích quỹ đạo (trajectory), thay vì chỉ đánh giá kết quả cuối cùng (final output).
• environment.type — nhận một trong các giá trị tiêu chuẩn: stateless, sandboxed-sql, containerized, browser, multi-agent-arena, production-shadow.
• gating.blocks_release — thiết lập giá trị true nếu CI gate sẽ hủy bỏ tiến trình build (fails the build) khi hệ thống vi phạm mức sàn hồi quy (regression_floor breach).
• gating.capability_baseline — tỷ lệ đạt (pass rate) tối thiểu cần thiết để xác nhận năng lực (claim the capability).
• gating.regression_floor — tỷ lệ đạt tối thiểu trước khi bản build bị từ chối triển khai (rejected).

Các phần nội dung thân bài bắt buộc

Các trang đặc tả Suite BẮT BUỘC PHẢI bao gồm các sections (phần) chuẩn H2 theo thứ tự dưới đây.

1. Purpose (Mục đích)

Nêu rõ một năng lực (capability) hoặc rủi ro (risk) duy nhất mà suite này giải quyết, trình bày súc tích trong hai đến bốn câu. Khởi đầu bằng năng lực cốt lõi ("Suite này đo lường độ chính xác của customer-support agent khi thực thi lệnh hoàn tiền/refund..."). Kết thúc bằng hậu quả khi hệ thống gặp lỗi ("…bất kỳ sự hồi quy nào tại đây cũng sẽ dẫn đến việc khách hàng nhận sai số tiền hoàn trả.").

2. Agent under test (Agent được kiểm thử)

Liệt kê mọi agent harness và phiên bản (version) mà suite này kiểm thử. Nếu suite được thiết kế để hoạt động độc lập không phụ thuộc vào harness (harness-agnostic), hãy tuyên bố minh bạch và liệt kê rõ các giao thức (contract) mà agent bắt buộc phải thỏa mãn (ví dụ: "bắt buộc triển khai công cụ submit_refund với định dạng schema X").

3. Environment and fixtures (Môi trường và các fixtures)

Mô tả chi tiết môi trường hộp cát (sandbox): database fixtures, mocked APIs, các chính sách mạng (network policies), time fixtures, và các giá trị seed (hạt giống). Hãy tài liệu hóa các cam kết về tính tất định (determinism guarantees) — Anthropic nhấn mạnh rằng một môi trường ổn định (stable environment) là yêu cầu tiên quyết không thể thỏa hiệp đối với bất kỳ eval harness nào. Trong trường hợp môi trường mang tính phi tất định (non-deterministic) (ví dụ: sử dụng live model-as-judge), bạn phải tài liệu hóa các cấu hình seed, temperature (nhiệt độ), và các giao thức ràng buộc về phiên bản mô hình (model-version contract).

4. Datasets (Tập dữ liệu)

Đối với mỗi dataset, hãy cung cấp siêu liên kết (hyperlink) tới dataset card tương ứng và mô tả chi tiết:

• Thành phần phân vùng dữ liệu (Slice composition) (số lượng bản ghi trên mỗi lát cắt).
• Phương pháp gán nhãn (Labeling methodology) (nguồn thiết lập ground-truth).
• Các độ lệch dữ liệu đã được xác định (Known biases) hoặc các lỗ hổng về độ bao phủ (coverage gaps).
• Chu kỳ làm mới (Refresh cadence) và ngày cập nhật gần nhất (last refresh date).

5. Scorers (Thành phần chấm điểm)

Đối với mỗi scorer, hãy cung cấp liên kết tới trang tham chiếu (reference page) và tài liệu hóa các thuộc tính sau:

• Loại thành phần (Kind) — code, llm-judge, hoặc human.
• Dữ liệu đầu vào (Inputs) — final output, full trajectory, trạng thái môi trường (environment state), hoặc kết hợp cả ba.
• Dữ liệu đầu ra (Output) — giá trị boolean, thứ tự (ordinal), hoặc định dạng số trong khoảng [0, 1].
• Rubric — đối với llm-judge, hãy trích dẫn (paste) toàn văn rubric (verbatim) hoặc cung cấp liên kết tới một canonical rubric file.
• Hiệu chuẩn (Calibration) — tỷ lệ nhất trí (agreement rate) so với các nhãn do con người đánh giá (human labels) trên một holdout slice (phân vùng dữ liệu cô lập), kèm theo ngày cập nhật (refresh date).

Mô hình kết-hợp-cả-ba (combine-all-three pattern) của Anthropic (sử dụng code cho các kết quả có thể xác minh toán học/verifiable outcomes, LLM-as-judge cho các đánh giá ngữ nghĩa/nuance, và human cho công tác hiệu chuẩn/calibration) là phương pháp mặc định (default) được khuyến nghị. Hãy tài liệu hóa chiến lược ứng dụng của từng loại để các reviewers có thể xác định rõ scorer nào đóng vai trò là chân lý nền (ground truth) và scorer nào cần được hiệu chuẩn lại (recalibration) định kỳ.

6. Trajectory rubric (Yêu cầu bắt buộc khi trajectory_required: true)

Đánh giá quỹ đạo (Trajectory grading) là một bước quy trình mà các đội ngũ thường bỏ qua, nhưng lại đóng vai trò tối quan trọng (essential) đối với các agents thực thi đa bước (multi-step agents). Hãy tài liệu hóa bằng ngôn ngữ tự nhiên (plain language) các tiêu chí sau:

• Các bước bắt buộc (Required steps) — các lệnh gọi công cụ, dù có hay không có thứ tự, BẮT BUỘC PHẢI được thực thi.
• Các hành động bị cấm (Forbidden actions) — các công cụ hoặc chuỗi thao tác sẽ dẫn đến kết quả đánh giá trượt (fail) của toàn bộ quỹ đạo, bất kể kết quả cuối cùng (final output) có chính xác hay không.
• Phát hiện vòng lặp (Loop detection) — ngưỡng giới hạn lặp lại (ví dụ: kích hoạt cùng một tool với cấu hình args trùng lặp > 3 lần = fail).
• Dải hiệu suất (Efficiency band) — kỳ vọng linh hoạt (soft expectation) đối với tổng số bước thực thi (step count) hoặc chi phí tiêu thụ token (token cost); không đóng vai trò rào chắn (not gating) nhưng luôn được hệ thống theo dõi (tracked).

Tại các điểm phù hợp, hãy cung cấp cả hai biến thể: phương pháp tất định (deterministic / khớp-chính-xác exact-match) và LLM-as-judge, đồng thời giải thích rõ ngữ cảnh áp dụng tương ứng của từng biến thể.

7. Gating logic (Logic rào chắn)

Hãy trình bày rõ ràng hệ thống rào chắn (gating) từ cấu trúc frontmatter dưới dạng văn bản (prose) để một quản lý phát hành (release manager) có thể hiểu ngay hệ quả (consequences) khi đọc trên thiết bị di động. Cần liệt kê:

• CI job cụ thể nào sẽ thực thi suite này.
• capability baseline (đường cơ sở năng lực) có tác động gì đến sản phẩm (ví dụ: "dưới mức 55%, tính năng này sẽ không được phát hành").
• Cấp độ rào chắn mà regression floor (mức sàn hồi quy) sẽ chặn lại (ví dụ: "dưới tỷ lệ đạt 97%, tiến trình deploy sẽ bị chặn và hệ thống sẽ gửi cảnh báo đến kỹ sư trực ban - page on-call").
• Quy trình ghi đè rào chắn (Override path) (chỉ định nhân sự có thẩm quyền phê duyệt ngoại lệ/waiver và các bằng chứng/evidence cần thiết).

8. Reporting and trace artifacts (Báo cáo và các trace artifacts)

Hãy mô tả thứ mà bộ máy (harness) sẽ ghi lại (writes) cho mỗi một lượt chạy (run): mẫu định dạng URL nơi lưu trữ trace (trace-store URL pattern), thời gian lưu giữ (retention period), các chính sách PII, các dashboards. Cung cấp một ví dụ về URL truy cập cho lượt chạy (example run URL) — có thể bấm (linkable), có quyền ẩn bớt thông tin (redacted if needed) — để người đọc có thể xem trước hình thù (shape) của artifact.

9. Change log (Nhật ký thay đổi)

Chỉ có tác dụng đính kèm (Append-only) nhằm liệt kê các phiên bản suite-version bumps đi kèm ngày tháng năm, tên tác giả, và một dòng lý do (rationale). Sử dụng Semver: MAJOR (chính) đối với các scorer không có khả năng tương thích ngược (backward-incompatible) hoặc các thay đổi về schema, MINOR (phụ) đối với các scorers bổ sung, PATCH (bản vá lỗi) dùng cho các mục đính chính (clarifications).

10. FAQ

Gồm 3 đến 5 câu Hỏi Đáp (Q&A) với phong cách "Trả lời trước, Hỏi sau" (answer-first) nhằm dự đoán các câu hỏi của reviewer và agent (hãy xem bộ mẫu nằm ở phía cuối bài viết này).

Cấu trúc thẻ tham chiếu Scorer (Scorer reference card schema)

Trang tham chiếu Scorer (scorer reference) phải là một tài liệu độc lập. Trang này BẮT BUỘC PHẢI bao gồm:

[[CODE_FENCE_LANG=yaml]]

scorer:

id: "tone-empathy"

kind: "llm-judge"

scale: "ordinal-1-5"

inputs: ["final_output"]

judge_model: "claude-sonnet-4.5"

judge_prompt_path: "prompts/tone-empathy.v3.md"

calibration:

holdout: "tone-empathy-human-2026-03"

agreement: 0.86

last_refreshed: "2026-03-12"

failure_modes:

• "over-apologizes on policy violations"
• "scores high on refusals if polite"

[[/CODE_FENCE]]

Phần nội dung (body) BẮT BUỘC PHẢI chứa rubric, hai ví dụ đạt (passing examples), hai ví dụ trượt (failing examples), và các kịch bản lỗi (failure modes) đã được xác định. Yêu cầu thực hiện hiệu chuẩn lại (recalibrate) tối thiểu mỗi quý một lần (quarterly) và tài liệu hóa tỷ lệ nhất trí (agreement rate) dựa trên đối chiếu với tập dữ liệu holdout (dữ liệu kiểm tra độc lập do con người đánh giá).

Cấu trúc thẻ tập dữ liệu (Dataset card schema)

Datasets được định nghĩa là các đối tượng ưu tiên hạng nhất (first-class citizens). Một dataset card BẮT BUỘC PHẢI bao gồm: nguồn gốc dữ liệu/provenance (dữ liệu tổng hợp từ các personas giả lập, hoặc được trích xuất từ logs hệ thống với quy tắc lọc PII chuẩn X), thông tin cấp phép (licensing), định nghĩa chi tiết các phân vùng (slice definitions), chu kỳ làm mới (refresh cadence), và số lượng bản ghi trên mỗi phân vùng (row count per slice). Cần theo dõi (track) đội ngũ gán nhãn ground-truth (ground-truth labelers) và độ tin cậy nhất trí giữa các người đánh giá (inter-rater reliability) khi khả thi.

[[CODE_FENCE_LANG=yaml]]

dataset:

id: "refunds-golden-2026-q1"

version: "1.4.0"

size: 412

slices:

happy-path: 220

edge-card-decline: 84

policy-violation: 108

provenance: "ticket-export-2026-01 with synthetic augmentation"

pii_policy: "scrubbed-v3"

labelers: ["support-quality-team"]

inter_rater_agreement: 0.91

refresh_cadence_days: 90

last_refreshed: "2026-03-30"

[[/CODE_FENCE]]

Nguyên tắc đánh giá: Capability eval vs Regression eval

Capability evals (đánh giá năng lực) thường khởi đầu với tỷ lệ đạt ở mức thấp và sau đó tài liệu hóa tiến trình cải thiện năng lực (climb); trong khi đó, regression evals (đánh giá hồi quy) bắt buộc phải duy trì ổn định ở ngưỡng gần 100% và liên tục ghi nhận tính ổn định đó (stability). Hai loại đánh giá này yêu cầu logic rào chắn (gating logic) và chu kỳ kiểm duyệt (review cadence) hoàn toàn khác biệt. Các trang đặc tả suite NÊN tuyên bố rõ ràng chế độ hoạt động trong trường eval_type và chỉ định cụ thể hệ thống rào chắn áp dụng cho từng phân vùng dữ liệu (data slice) nếu sử dụng chung một dataset cho cả hai mục đích.

Ví dụ

Một trang đặc tả suite đáp ứng tiêu chí tối giản nhưng đầy đủ (minimal-but-complete) sẽ có cấu trúc khởi đầu như sau:

[[CODE_FENCE_LANG=mdx]]

---

title: "Refunds and Cancellations Eval Suite"

slug: "refunds-and-cancellations-eval-suite"

section: "ai-agents"

content_type: "specification"

…toàn bộ cấu trúc Geodocs frontmatter…

eval_suite:

suite_id: "refunds-and-cancellations"

suite_version: "2.3.0"

eval_type: ["capability", "regression"]

trajectory_required: true

# …

---

Refunds and Cancellations Eval Suite

Purpose (Mục đích)

Suite này xác minh khả năng của customer-support agent trong việc ghi nhận chính xác số tiền hoàn lại (refund amount) vào cơ sở dữ liệu thanh toán (billing database) và đảm bảo không bao giờ bỏ qua các chặn vi phạm chính sách (policy-violation blocks). Bất kỳ lỗi (fail) nào xảy ra đồng nghĩa với việc khách hàng nhận sai số tiền hoàn trả hoặc các chính sách bị vi phạm một cách âm thầm (silently violated) trên môi trường thực tế.

Agent under test (Agent được kiểm thử)

• Phiên bản v3.x harness của customer-support-agent, tích hợp các công cụ submit_refund, cancel_subscription, và lookup_policy.

…các sections bắt buộc còn lại…

[[/CODE_FENCE]]

Anti-patterns

• Đánh giá theo cơ chế outcome-only (chỉ tập trung vào đầu ra cuối cùng) đối với các agents thực thi đa bước (multi-step). Nếu suite của bạn bỏ qua việc kiểm tra quỹ đạo (trajectory), bạn phải tài liệu hóa lý do TẠI SAO (ví dụ: "vì nhiệm vụ này chỉ gọi công cụ một lần - single-tool"). Việc thiếu kiểm tra quỹ đạo sẽ dẫn đến rủi ro bỏ sót các lỗi "right-answer-wrong-path" (đáp án đúng nhưng quy trình thao tác sai lệch).
• Thiếu tài liệu hóa LLM-judge prompts. Một prompt dùng để đánh giá (judge prompt) nếu chỉ được lưu trữ trong mã nguồn mà không có tài liệu đối chiếu sẽ là một prompt không thể kiểm duyệt (unreviewable). Hãy liên kết trực tiếp đến file canonical prompt với đường dẫn và phiên bản (version) cụ thể.
• Trộn lẫn các phân vùng (slices) cho capability và regression mà không gán nhãn (labels). Reviewers không thể đánh giá chính xác mức tỷ lệ đạt 78% nếu không xác định được phân vùng dữ liệu nào đang áp dụng cho rào chắn (gate) nào.
• Hệ thống hiệu chuẩn bị lỗi thời (Stale calibration). Một hệ thống LLM-judge sẽ không còn độ tin cậy nếu tỷ lệ nhất trí với người đánh giá (human-agreement rate) không được tái hiệu chuẩn trong vòng 6 tháng.
• Ẩn giấu trạng thái môi trường (Hidden environment state). Lời tuyên bố "chúng tôi luôn thực thi reset DB" không phải là một đặc tả kỹ thuật tiêu chuẩn — hãy liên kết trực tiếp đến file fixture và tài liệu hóa chính xác trạng thái hoạt động mà lệnh "reset" thiết lập.

Danh sách kiểm tra khi triển khai

Trước khi xuất bản một suite spec, hãy xác minh các điều kiện sau:

• [ ] Frontmatter bao gồm khối eval_suite (đi kèm đầy đủ các trường dữ liệu bắt buộc / required fields).
• [ ] Mọi scorer đều được liên kết chính xác đến thẻ tham chiếu (reference card) tương ứng.
• [ ] Mọi dataset đều được liên kết chính xác đến dataset card tương ứng.
• [ ] Trajectory rubric đã được định nghĩa chi tiết (nếu trajectory_required: true).
• [ ] Các ngưỡng giới hạn rào chắn (Gating thresholds) hoàn toàn khớp với cấu hình CI trong tài liệu release-engineering.
• [ ] Phần FAQ bao gồm tối thiểu 3 mục Q&A theo phong cách "Answer-first".
• [ ] Nhật ký thay đổi (Change log) đã được cập nhật phiên bản, ngày tháng và nội dung chi tiết.
• [ ] Đã thiết lập thông tin email của Owner và chu kỳ đánh giá (review cadence).

FAQ

Q: Đặc tả này chỉ áp dụng cho các agents trên môi trường sản xuất (production) hay áp dụng cho cả các nguyên mẫu (prototypes)?

A: Đặc tả này áp dụng cho cả hai. Các Prototypes thường xuất bản các suite specs ở chế độ "capability-only" (chỉ đánh giá năng lực) với các thiết lập rào chắn nới lỏng (looser gating) và nhật ký thay đổi ngắn gọn. Tuy nhiên, cấu trúc frontmatter bắt buộc phải nhất quán nhằm duy trì tính chuẩn hóa của hệ thống tài liệu cho đến khi mô hình nền tảng (underlying model) được nâng cấp lên môi trường production.

Q: Tôi nên tài liệu hóa một suite sử dụng kết hợp (mixes) các loại scorers như code-based và LLM-as-judge như thế nào?

A: Liệt kê (List) từng scorer cùng với định dạng type/kind trong mảng scorers (scorers array) và giải thích chi tiết trong phần "Scorers" để xác định rõ scorer nào đóng vai trò là chân lý nền/source of truth cho từng nhiệm vụ cụ thể. Theo tiêu chuẩn Anthropic, cấu trúc ưu tiên là: code-based cho các kết quả có thể xác minh thuật toán, LLM-judge cho các đánh giá mang tính sắc thái (nuance), và con người để hiệu chuẩn (calibration). Hãy thiết kế và trình bày rõ ràng hệ thống phân cấp này bằng văn bản chuyên ngành.

Q: Điểm khác biệt về nội dung hiển thị (What) giữa suite spec và scorer reference là gì?

A: Trang suite spec trình bày tổng quan về mục đích, cấu hình môi trường, hệ thống rào chắn, và cách tổ hợp các scorers. Trái lại, trang scorer reference tập trung mô tả chi tiết rubric, thông số hiệu chuẩn, prompt đánh giá (judge prompt), và các kịch bản lỗi (failure modes) của một scorer duy nhất. Khuyến nghị tuyệt đối tránh sao chép nội dung giữa hai trang — hãy sử dụng các siêu liên kết thay vì thao tác dán (paste) dữ liệu.

Q: Tần suất (How often) thực hiện đánh giá lại các trajectory rubrics là bao lâu?

A: Luôn thực hiện đánh giá lại (Re-review) ngay khi giao diện công cụ (tool surface) của Agent có sự thay đổi, hoặc khi danh sách các thao tác bắt buộc và bị cấm (required and forbidden actions) trong rubric không còn tương thích với hành vi thực tế trên môi trường production. Tần suất mặc định (default cadence) sẽ được cấu hình trong trường review_cycle_days của suite; tần suất này CẦN được rút ngắn đối với các safety-critical suites (các suite liên quan trực tiếp đến an toàn hệ thống).

Q: Có thể tích hợp nhiều suites vào một tài liệu (document) duy nhất không?

A: Không. Quy tắc chuẩn là một trang (one page) dành riêng cho một suite duy nhất. Hãy nhóm (Bundle) các file suites có liên quan bằng trường series và series_order trong frontmatter, đồng thời xây dựng một trang "hub page" để tổng hợp và hiển thị danh sách các suites. Cách tiếp cận này giúp người đọc và các "docs agents" dễ dàng truy xuất và kiểm duyệt danh mục khi cần thiết.