Bảng tra cứu harness của agent: thành phần, tệp, vấn đề và checklist khởi chạy

Năm hệ thống con của harness

Thứ tự triển khai từ đầu: phản hồi → hướng dẫn → trạng thái → môi trường → công cụ.

Các tệp của harness

Khung AGENTS.md

# Dự án: backend thanh toán (FastAPI, PostgreSQL)

## Khởi chạy
docker compose up -d && ./scripts/init.sh

## Kiểm chứng
make check   # lint, kiểu, unit, arch-check
make e2e     # kịch bản đầu cuối

## Definition of Done
- make check và make e2e — mã 0
- tính năng được chuyển sang passing bởi scripts/verify.sh
- PROGRESS.md đã cập nhật

## MUST
- truy vấn DB chỉ qua repository
- bí mật chỉ lấy từ biến môi trường

## Tài liệu
- docs/payments.md — khi tác vụ liên quan đến thanh toán và hoàn tiền
- docs/migrations.md — khi thay đổi schema DB

Trạng thái của tính năng

Các cấp kiểm chứng

Quyền nói «xong» chỉ có sau cấp cao nhất. Unit test xanh không có nghĩa là hoàn thành.

Cơ chế hoá quy tắc

#!/usr/bin/env bash
fail=0
if grep -rn "from app.db" app/services/; then
  echo "WHY: các service không truy cập DB trực tiếp"
  echo "FIX: dùng repository trong app/repositories/"
  fail=1
fi
exit $fail

Vấn đề thường gặp và cách xử lý

Vai trò cho các tác vụ dài

Ngân sách cho làm việc tự động

• Mục tiêu — một câu (ví dụ đưa mọi tính năng về passing).
• WIP=1, giới hạn thời gian và số lần thử cho mỗi tính năng.
• Chỉ số tăng đơn điệu, hồi quy thì hoàn tác ngay.
• Migration, hạ tầng, tiền bạc — leo thang lên con người.
• Sau nhiều lần review thất bại — bắt đầu lại tính năng với ngữ cảnh sạch.

Checklist khởi chạy agent

1. Có AGENTS.md: stack, cách chạy, lệnh kiểm chứng, DoD.
2. make check chạy được trên một bản clone sạch.
3. Môi trường tái lập được: file khoá, Docker hoặc devcontainer.
4. Agent có các lệnh cần thiết, lệnh nguy hiểm bị cấm hoặc đặt trong sandbox.
5. Có E2E ít nhất cho kịch bản chính.
6. Có PROGRESS.md và quy tắc đọc nó khi bắt đầu phiên.
7. Tính năng trong danh sách có trạng thái, chỉ một cái active.
8. Trạng thái passing do script đặt.
9. Thông báo kiểm chứng có WHY và FIX.
10. Tác vụ có tiêu chí chấp nhận và ranh giới phạm vi.
11. Đã xác định rõ việc nào cần quyết định của con người.
12. Đã đo verification gap trước khi thay đổi, để có gì so sánh.

Chỉ số của harness

Tóm tắt

Harness là một vòng khép kín chứ không phải một tệp: hướng dẫn, công cụ, môi trường, trạng thái và phản hồi. Hãy bắt đầu từ kiểm chứng, giữ AGENTS.md ngắn, giao trạng thái «xong» cho script và xem xét lại harness định kỳ. Toàn bộ điều này được ghép lại trên một dự án thực tế trong khoá học harness engineering.