Harness Engineering: Kiểm soát mã nguồn AI bằng công cụ xác định và AI Agent

Harness engineering (kỹ thuật khung kiểm soát) là phương pháp bao quanh quá trình tạo mã có sự hỗ trợ của AI bằng các công cụ tất định, quy trình đánh giá dựa trên tác nhân (agent-based) và các đợt kiểm tra entropy định kỳ, nhằm đảm bảo mã do AI tạo ra luôn chính xác và nhất quán theo thời gian. Tài liệu này giải thích nguồn gốc của ý tưởng, các thành phần cấu tạo và cách plugin này triển khai nó.

Nguồn gốc

Thuật ngữ này bắt nguồn từ bài viết của Birgitta Boeckeler trên martinfowler.com, được viết trong bối cảnh các đội ngũ tại ThoughtWorks đang triển khai phần mềm thực tế với sự hỗ trợ của các trợ lý lập trình AI. Boeckeler đã quan sát thấy một điều mà nhiều đội ngũ khác cũng độc lập nhận ra: các trợ lý AI tạo ra mã trông có vẻ hợp lý, nhưng nếu không bị kiểm soát, chúng sẽ dần chệch hướng. Chúng quên đi các quy ước, lặp lại sai lầm và dần làm xói mòn tính nhất quán nội tại của cơ sở mã (codebase). Mã vẫn tiếp tục biên dịch và vượt qua các bài kiểm tra. Sự suy giảm này diễn ra một cách âm thầm.

Nhận định của Boeckeler là vấn đề này đã có một giải pháp tương tự trong kỹ thuật phần mềm: test harness (khung kiểm thử). Các bài kiểm tra không làm cho mã trở nên chính xác ngay từ khi xây dựng. Chúng phát hiện khi nào mã không còn chính xác nữa. Một test harness không phải là sự ràng buộc đối với mã bạn viết; đó là một cơ chế liên tục kiểm tra xem những gì bạn viết có đáp ứng tiêu chuẩn hay không. Harness không tin tưởng lập trình viên. Nó xác minh.

Logic tương tự áp dụng cho phát triển phần mềm có sự hỗ trợ của AI, với một khác biệt quan trọng. Test harness kiểm tra tính đúng đắn về chức năng: chương trình có thực hiện đúng những gì nó cần làm không? Một harness cho lập trình AI cần kiểm tra điều gì đó rộng hơn: cơ sở mã có còn thể hiện các quyết định kiến trúc, quy ước đặt tên, ràng buộc bảo mật và các quy tắc cấu trúc mà nhóm đã thống nhất hay không? Các bài kiểm tra chức năng là cần thiết nhưng chưa đủ. Bạn cần một loại harness khác.

Đó chính là những gì harness engineering cung cấp.

Ba thành phần chính

Boeckeler mô tả ba nhóm vấn đề mà một harness phải giải quyết.

Kỹ thuật ngữ cảnh (Context Engineering)

Một trợ lý lập trình AI chỉ có thể làm việc trong phạm vi những gì nó biết. Nếu nó không biết dự án của bạn sử dụng một thư viện ghi nhật ký (logging library) cụ thể, nó sẽ tự tạo ra cách tiếp cận riêng. Nếu nó không biết rằng bạn không bao giờ sử dụng trạng thái toàn cục có thể thay đổi (mutable global state), nó sẽ sử dụng khi thấy thuận tiện. Nếu nó không biết rằng mọi thao tác ghi cơ sở dữ liệu phải đi qua một lớp trừu tượng cụ thể, nó sẽ bỏ qua lớp đó.

Kỹ thuật ngữ cảnh là kỷ luật đảm bảo AI biết những gì nó cần biết. Trên thực tế, điều này có nghĩa là duy trì một tài liệu — HARNESS.md theo quy ước của plugin này — ghi lại ngăn xếp công nghệ, các quyết định kiến trúc, quy ước đặt tên, các ràng buộc và lý do đằng sau mỗi quyết định đó. Tài liệu này không phải là README dành cho con người. Nó là một cơ sở tri thức dành cho AI. Nó cần phải chính xác, cụ thể và được cập nhật thường xuyên.

Sự khác biệt này rất quan trọng: README giải thích dự án làm gì. Tài liệu ngữ cảnh cho một tác nhân AI biết nó phải làm gì, không được làm gì và tại sao. Đây là những tài liệu khác nhau với đối tượng độc giả khác nhau và nhịp độ cập nhật khác nhau.

Ràng buộc kiến trúc

Biết các quy tắc và thực thi các quy tắc là hai vấn đề riêng biệt. Bạn có thể viết mọi ràng buộc vào HARNESS.md nhưng AI vẫn sẽ vi phạm chúng, bởi vì AI là một hệ thống xác suất tối ưu hóa cho sự hợp lý, không phải là một cỗ máy tuân thủ quy tắc. Kỹ thuật ngữ cảnh giúp giảm thiểu các vi phạm, nhưng không loại bỏ hoàn toàn chúng.

Các ràng buộc kiến trúc là cơ chế để phát hiện vi phạm. Boeckeler gọi các điểm thực thi này là "verification slots" (khe xác minh) — những thời điểm xác định trong quy trình phát triển nơi một bài kiểm tra được chạy và kết quả sẽ là thông qua hoặc chặn tiến trình. Quyết định thiết kế quan trọng cho mỗi khe xác minh là liệu nó sử dụng công cụ tất định hay đánh giá dựa trên tác nhân.

Công cụ tất định là linter, tập lệnh (script), kiểm tra regex, xác nhận cấu trúc tệp — bất cứ thứ gì tạo ra kết quả đạt/không đạt mà không cần phán đoán. Những công cụ này được ưu tiên khi ràng buộc có thể được diễn đạt chính xác. Chúng nhanh, rẻ và hoàn toàn đáng tin cậy trong phạm vi đặc tả của chúng.

Đánh giá dựa trên tác nhân là việc sử dụng mô hình ngôn ngữ để xem xét mã dựa trên mô tả ràng buộc và đưa ra phán đoán. Điều này cần thiết khi ràng buộc liên quan đến ý định, ngữ nghĩa hoặc các mẫu khó diễn đạt thành quy tắc máy móc. Các tác nhân đắt đỏ hơn và ít tính tất định hơn, nhưng chúng có thể phát hiện những thứ mà không tập lệnh nào làm được.

Cả hai loại khe xác minh đều thuộc về một harness. Mục tiêu theo thời gian là chuyển đổi các ràng buộc từ dựa trên tác nhân sang tất định khi sự hiểu biết của bạn về ràng buộc đó đủ sắc bén để chỉ định nó một cách chính xác. Đây là nguyên tắc làm cứng dần dần (progressive hardening), được mô tả dưới đây.

Thu gom rác (Garbage Collection)

Cơ sở mã là một hệ thống sống. Ngay cả với kỹ thuật ngữ cảnh tốt và các ràng buộc kiến trúc nghiêm ngặt, entropy vẫn tích tụ. Mã chết (dead code) ngày càng nhiều. Các bình luận TODO tồn tại hàng tháng trời. Các phụ thuộc trở nên lỗi thời. Các lớp trừu tượng từng hợp lý ở giai đoạn này lại trở thành rào cản ở giai đoạn sau. Các quy ước được thiết lập sớm bị âm thầm từ bỏ khi chúng trở nên bất tiện.

Thu gom rác là quá trình định kỳ chống lại sự entropy này. Không giống như hai thành phần kia hoạt động tại thời điểm tạo hoặc đánh giá mã, GC hoạt động theo lịch trình. Nó không được kích hoạt bởi một sự kiện lập trình cụ thể. Nó chạy vì thời gian đã trôi qua.

Trong khuôn khổ harness engineering, các quy tắc GC là những tuyên bố rõ ràng về thế nào là "sạch", kết hợp với các tác nhân hoặc tập lệnh được lên lịch để kiểm tra xem cơ sở mã có còn đáp ứng các tiêu chuẩn đó hay không. Đầu ra không phải là danh sách lỗi để chặn một PR; đó là một báo cáo thu hút sự chú ý đến các vấn đề đang tích tụ trước khi chúng trở nên nghiêm trọng.

Harness sống (The Living Harness)

Đặc tính quan trọng nhất của một harness được duy trì tốt là nó không tĩnh. Một harness được viết một lần và không bao giờ cập nhật chỉ phản ánh sự hiểu biết của nhóm tại một thời điểm nhất định. Cơ sở mã tiếp tục phát triển. Các mẫu mới xuất hiện. Các ràng buộc cũ trở nên không còn phù hợp. Các loại sai lầm mới do AI tạo ra xuất hiện mà các tác giả ban đầu không lường trước được.

HARNESS.md được thiết kế như một tài liệu tự tham chiếu. Nó không chỉ mô tả các ràng buộc nào đang có hiệu lực; nó theo dõi trạng thái của từng ràng buộc: liệu nó hiện chưa được xác minh, đang được tác nhân đánh giá hay được thực thi một cách tất định. Tài liệu tuyên bố những gì nên là sự thật. Các tác nhân, hook và kiểm tra CI xác minh xem điều đó có đúng hay không. Trình kiểm toán harness (harness auditor) — một tác nhân được lên lịch trong plugin này — đọc kết quả của các bài kiểm tra đó và cập nhật các mục trạng thái trong HARNESS.md để phản ánh thực tế.

Điều này tạo ra một vòng lặp phản hồi. Tài liệu vừa là đặc tả vừa là hồ sơ sức khỏe. Đọc HARNESS.md tại bất kỳ thời điểm nào cũng cho bạn biết không chỉ những gì nhóm đã đồng ý là đúng về cơ sở mã, mà còn là mức độ các thỏa thuận đó đang được duy trì tốt như thế nào.

Đặc tính tự tham chiếu là thứ phân biệt một harness sống với một tài liệu bị lỗi thời và bị bỏ qua. Vì bản thân harness cũng là mục tiêu của việc thực thi — tác nhân kiểm toán harness kiểm tra xem HARNESS.md có phản ánh chính xác trạng thái xác minh hiện tại hay không — việc bỏ bê harness sẽ trở nên hiển nhiên thay vì vô hình. Lối vào hàng ngày cho việc tự kiểm tra này là /harness-sync, lệnh này chạy logic phát hiện của trình kiểm toán và hiển thị bảng trôi dạt (drift table) hợp nhất; người dùng thấy sự sai lệch giữa harness đã khai báo và thực tế mà không cần phải nhớ gọi một chẩn đoán riêng biệt.

Làm cứng dần dần (Progressive Hardening)

Không phải mọi ràng buộc đều như nhau, và không phải mọi ràng buộc đều sẵn sàng để được thực thi một cách tất định ngay từ đầu. Làm cứng dần dần là thang thăng tiến mô tả cách các ràng buộc trưởng thành.

Thang đo là một trục. Phạm vi tiếp cận — liệu một ràng buộc là bắt buộc trên mọi PR hay chỉ hoàn thiện nếu có — là trục thứ hai, và trường Enforcement (Thực thi) không ghi lại điều này.

Unverified (Chưa xác minh) là trạng thái bắt đầu. Bạn đã khai báo một ràng buộc trong HARNESS.md. Bạn tin rằng nó quan trọng. Bạn chưa có cơ chế để kiểm tra nó. Trạng thái này không phải là thất bại; đó là sự hạch toán trung thực. Một ràng buộc chưa xác minh là cam kết xây dựng cơ chế thực thi, không phải là tuyên bố rằng việc thực thi đã tồn tại.

Agent (Tác nhân) là trạng thái thứ hai. Bạn đã viết một câu lệnh (prompt) cho tác nhân để kiểm tra ràng buộc như một phần của đánh giá PR hoặc kiểm tra định kỳ. Ràng buộc đang được thực thi, nhưng bởi một mô hình ngôn ngữ đưa ra phán đoán, không phải bởi một quy tắc tất định. Việc thực thi bằng tác nhân bắt được hầu hết các vi phạm trong hầu hết thời gian. Nó không hoàn toàn đáng tin cậy và đòi hỏi sự xem xét của con người đối với đầu ra của tác nhân.

Deterministic (Tất định) là trạng thái cuối cùng. Bạn đã diễn đạt ràng buộc đủ chính xác để mã hóa nó thành một tập lệnh, quy tắc linter hoặc kiểm tra cấu trúc. Nó chạy trong CI. Nó hoặc thông qua hoặc chặn việc hợp nhất. Không có sự phán đoán nào ở đây, và không có khả năng bài kiểm tra bị nhầm lẫn hoặc hiểu sai.

Hướng di chuyển luôn là hướng tới trạng thái tất định. Khi một tác nhân liên tục bắt được cùng một loại vi phạm, sự lặp lại đó là một tín hiệu: mẫu đó hiện đã được hiểu đủ rõ để tự động hóa. Hãy viết tập lệnh, loại bỏ kiểm tra bằng tác nhân cho ràng buộc cụ thể đó và chuyển mục nhập trong HARNESS.md sang trạng thái tất định.

Làm cứng dần dần rất quan trọng vì nó ngăn chặn hai kiểu thất bại. Kiểu thất bại thứ nhất là cố gắng thực thi mọi thứ một cách tất định ngay từ đầu, điều này là bất khả thi đối với các ràng buộc mới hoặc phức tạp về ngữ nghĩa. Kiểu thất bại thứ hai là chấp nhận việc thực thi dựa trên tác nhân như một trạng thái vĩnh viễn, vốn đắt đỏ và không đáng tin cậy. Thang đo này cung cấp cho bạn một con đường giữa hai thái cực đó.

Cách plugin này triển khai

Plugin này cấu trúc các khe xác minh thành ba vòng lặp thực thi, hoạt động ở các thang thời gian khác nhau và với các mức độ chấp nhận khác nhau đối với các kết quả dương tính giả (false positives).

Vòng lặp trong cùng mang tính tư vấn và chạy tại thời điểm chỉnh sửa. Khi bạn lưu tệp hoặc hoàn thành một phiên lập trình, các bài kiểm tra nhẹ sẽ chạy và đưa ra các vấn đề tiềm ẩn dưới dạng gợi ý thay vì chặn. Vòng lặp trong cùng được tối ưu hóa để giảm ma sát. Nó không nên làm gián đoạn luồng công việc. Công việc của nó là làm cho các vấn đề hiển thị sớm, không phải để dừng công việc.

Vòng lặp ở giữa rất nghiêm ngặt và chạy tại thời điểm PR. Khi bạn mở một pull request, một bộ đầy đủ các bài kiểm tra dựa trên tác nhân và tất định sẽ chạy. Vòng lặp này có thẩm quyền chặn việc hợp nhất. Đây là điểm thực thi chính cho các ràng buộc kiến trúc. Các lỗi ở đây phải được giải quyết trước khi mã được đưa vào.

Vòng lặp ngoài cùng mang tính điều tra và chạy theo lịch trình. Các quy tắc thu gom rác, hàm thích nghi (fitness functions) và kiểm toán harness chạy định kỳ — hàng ngày, hàng tuần hoặc bất kỳ nhịp độ nào phù hợp với quy tắc. Vòng lặp ngoài cùng tạo ra các báo cáo thay vì chặn. Những phát hiện của nó phản hồi ngược lại vào harness như các ràng buộc tiềm năng mới hoặc cập nhật cho các ràng buộc hiện có.