AI Coding Harness (Bộ Khung Giám Sát Cho AI Viết Code)

Nó là gì

Một AI coding harness là bộ khung thực thi và kiểm chứng mà bạn xây dựng xung quanh một viết code, để nó có thể chạy tự động mà không làm hỏng mọi thứ. Nếu một guardrail (rào chắn an toàn) giống như một thói quen bạn phải tự nhớ để làm (chạy test, đọc diff), thì một harness (bộ khung giám sát) là một cỗ máy nhớ giúp bạn: nó nằm giữa ý định của agent và thế giới thực, và ở mỗi bước nguy hiểm, nó ghi lại, cảnh báo, hoặc chặn lại. dancinlab/harness là một engine tham chiếu không phụ thuộc vào dự án cụ thể — một lõi TypeScript dùng chung, nơi mỗi repo (kho mã nguồn) chỉ khác nhau ở một file harness.config.json cùng vài file dữ liệu .harness/*.json.

Điểm mạnh

Biến các guardrail của bạn từ những thói quen tùy chọn thành các quy tắc được thực thi bằng code — agent không thể bỏ qua chúng.
Kiểm soát toàn bộ vòng đời của công cụ: trước khi một lệnh chạy, trước khi một file được ghi, ở (câu lệnh nhập vào), khi , và khi push.
Một ledger (sổ cái) ở đây giống như một cuốn sổ tay mà bạn chỉ luôn thêm dòng mới chứ không bao giờ xóa dòng cũ. Các ledger này được viết dưới dạng JSONL ( Lines — mỗi dòng một đối tượng JSON) và cho ra một bản ghi chống giả mạo (tamper-evident) về mọi việc agent đã làm. Chúng rẻ để ghi và dễ để kiểm toán.
Có thể đưa vào bất kỳ repo nào: hành vi nằm ở config và dữ liệu, không phải ở code bị fork (phân nhánh).
Được thiết kế để im lặng khi mọi thứ ổn, nhờ đó các cảnh báo vẫn còn ý nghĩa.

Đánh đổi

Đây là hệ thống ống dẫn (plumbing), không phải phép màu: một harness làm cho việc bắt lỗi trở nên rẻ, chứ không làm cho AI đúng.
Cần thiết lập ban đầu và một config được tinh chỉnh theo các vùng nguy hiểm của dự án bạn.
Các quy tắc quá nghiêm ngặt tạo ra ma sát (friction); kỷ luật "bitter-gate" (loại bỏ một quy tắc không còn hoạt động trước khi thêm quy tắc mới) tồn tại chính là để chống lại điều này.
Có giá trị nhất trên các dự án thực với người dùng thực — thừa thãi đối với một bản mẫu (prototype) dùng rồi bỏ.

Phù hợp nhất cho

Vibe coding nghiêm túc, nơi bạn để một agent thực hiện các thay đổi trên nhiều file và chạy lệnh phần lớn không có người giám sát, và bạn cần cái giá phải trả cho một hành động sai gần như bằng không.

Năm nguyên tắc (H1–H5)

H1 Thành công thì im lặng, thất bại thì ồn ào — không có tiếng ồn nào khiến bạn học cách phớt lờ nó.
H2 Không bao giờ tự động sửa — chỉ đề xuất, chặn, hoặc cảnh báo; một con người hoặc agent đã được thông báo sẽ quyết định.
H3 Bitter-gate — loại bỏ một quy tắc không còn hoạt động trước khi thêm quy tắc mới.
H4 Hướng theo config — một engine duy nhất, mỗi dự án có harness.config.json riêng.
H5 Bản chất AI (AI-native) — các ledger JSONL chỉ được thêm vào, không thể bị viết lại âm thầm.

Nó trông như thế nào

Một bản phác thảo config tối giản:

// harness.config.json
{
  "lockedPaths": ["src/auth/**", "infra/**", ".github/**"],
  "blockCommands": ["rm -rf", "git push --force", "curl * | sh"],
  "verify": ["npm run lint", "npm run typecheck", "npm test"],
  "ledger": ".harness/ledger.jsonl"
}

Và luồng hook pre/post (trước/sau) xung quanh một hành động đơn lẻ của agent:

agent intends an action
        │
   ┌────▼─────────────┐
   │ pre  (PreToolUse) │  block dangerous? warn? → else allow
   └────┬─────────────┘
        │  command runs / file is written
   ┌────▼──────────────┐
   │ post (PostToolUse) │  record to JSONL · warn if a locked file was touched
   └────┬──────────────┘
        │  at commit / push
   ┌────▼─────┐
   │  verify  │  lint · typecheck · tests (parallel) → green or stop
   └──────────┘

Agent không bao giờ được phép vượt qua cổng kiểm soát này — đó chính là toàn bộ mục đích.