Cách viết điều kiện /goal có thể kiểm chứng

Hãy hình dung thế này: bạn nhờ agent chơi một ván trong trò chơi chạy sẵn trên trình duyệt. Agent đi vài nước, mô tả thế cờ rồi im lặng. Ván cờ vẫn đang diễn ra. Bạn nhắn "tiếp tục đi". Agent lại đi quân rồi chờ tin nhắn tiếp theo. Đến một lúc, bạn nhận ra việc lặp đi lặp lại nhiều nhất lại là phần mình đang làm.

Goal là mục tiêu có điều kiện hoàn tất, được giao cho agent bằng lệnh /goal. Ví dụ: "hãy lần lượt chơi cả hai bên cho đến khi trang báo ván cờ đã kết thúc". Sau mỗi lượt làm việc, một model riêng sẽ đọc cuộc hội thoại để kiểm tra mục tiêu đã đạt chưa. Nếu chưa, công việc tiếp tục mà bạn không cần nhắn "làm tiếp đi". Bạn có thể chờ kết quả, dù trở ngại hoặc lỗi vẫn có thể khiến công việc dừng sớm hơn.

Trước tiên ta dùng điều kiện có sẵn cho trò chơi, sau đó viết goal cho chức năng tìm kiếm, biểu mẫu và trang trên điện thoại. Mỗi mục tiêu đều có kết quả rõ ràng cùng cách kiểm tra. Ta cũng sẽ xem cách nhờ agent viết điều kiện và phân biệt việc hoàn tất thật sự với việc dừng mà chưa có kết quả.

/goal giúp công việc tiếp tục thế nào

Trong ví dụ trò chơi có hai cơ chế khác nhau, rất dễ nhầm lẫn. Một cơ chế thao tác trên trình duyệt: nhấp chuột, đi quân, đọc nội dung trang. Cơ chế kia không nhấp gì cả - nó đọc toàn bộ cuộc hội thoại rồi quyết định có tiếp tục công việc hay không.

Cơ chế thứ nhất là Playwright, công cụ trình duyệt đã được kết nối trước qua MCP. Cơ chế thứ hai được khởi chạy bằng lệnh /goal. Playwright đi quân, còn /goal quyết định đã đến lúc dừng chưa - hai việc khác nhau, dù nhìn từ bên ngoài có vẻ như chỉ một việc đang diễn ra.

Điểm cần lưu ý: đánh giá không diễn ra sau mỗi lần nhấp chuột, mà sau khi agent hoàn tất lượt làm việc - nói đơn giản là sau cả câu trả lời. Trong một lượt, agent có thể thực hiện liên tiếp nhiều thao tác: đi quân, đọc kết quả rồi phản hồi. /goal chỉ tham gia sau đó, khi đã có nội dung để đánh giá.

Chuẩn bị trò chơi để chạy

Trước khi đặt điều kiện, ví dụ cần hoạt động bình thường: trang mở được ở địa chỉ đã biết, công cụ chơi trên trang (ở đây là Playwright) đã kết nối, và trang có một dấu hiệu cho biết ván cờ đã kết thúc hay chưa.

Trong ví dụ này, đó là thuộc tính dữ liệu: data-game-over="false" khi ván cờ vẫn đang diễn ra và data-game-over="true" khi ván đã kết thúc. Người viết trang trò chơi quy định điều này - agent không tự nghĩ ra mà chỉ đọc giá trị đó.

Kiểm tra rất đơn giản: nhờ agent mở trang và đọc giá trị thuộc tính. Với ván cờ vừa bắt đầu, agent sẽ nhận được false. Như vậy là bình thường, đúng với trạng thái ban đầu.

Nếu trang không có thuộc tính này, chưa nên đặt goal. Điều kiện chỉ có thể dựa trên thông tin thực sự đọc được, vì vậy trước hết cần khôi phục dấu hiệu đó, chứ không nên tùy tiện nghĩ ra thứ thay thế ngay giữa chừng. Khi ví dụ đã sẵn sàng, cũng đừng đổi tiêu chí giữa ván hoặc gắn thêm bộ hẹn giờ riêng chỉ để kết thúc phần minh họa nhanh hơn. Điều kiện phải giữ nguyên từ đầu đến cuối.

Chạy goal đã chuẩn bị

Tiếp theo là lệnh cần dùng. Điều kiện cho ví dụ này có thể viết như sau:

/goal hãy lần lượt chơi cả hai bên thông qua giao diện trang.
Sau mỗi nước đi, đọc data-game-over và cho biết nội dung trang đang hiển thị.
Ván cờ được xem là kết thúc khi data-game-over chuyển thành true.
Nếu điều đó chưa xảy ra sau 40 nước, hãy dừng lại và mô tả bạn mắc kẹt ở đâu.
Không thay đổi mã trò chơi.

Hãy cùng phân tích từng phần. Bạn cũng có thể dùng các phần này cho nhiệm vụ của mình:

• "chơi... thông qua giao diện trang" - hành động có thể đo lường mà agent thực sự có thể thể hiện trong cuộc hội thoại;
• "ván cờ được xem là kết thúc khi data-game-over chuyển thành true" - điều duy nhất được tính là kết quả thực sự. Đây chính là điều bộ đánh giá sẽ tìm trong cuộc hội thoại;
• "sau mỗi nước đi, đọc... và cho biết" - dữ kiện giúp bộ đánh giá có thể kiểm tra. Không có dòng này thì nó chẳng có gì để xem;
• "nếu điều đó chưa xảy ra sau 40 nước, hãy dừng lại và mô tả" - chỉ dẫn riêng cho trường hợp true không xuất hiện. Đây không phải một phần của thành công mà là cách dừng công việc khi chưa đạt: nó giới hạn phạm vi goal nhưng không thay thế kết quả. Đây vẫn là chỉ dẫn trong văn bản, không phải bộ hẹn giờ lập trình cứng - bộ đánh giá cũng kiểm tra nó qua cuộc hội thoại;
• "không thay đổi mã trò chơi" - điều không được phép xảy ra trong lúc agent tìm cách đạt kết quả.

Chưa thể biết trước kết quả cuối cùng - không thể hứa ai sẽ thắng, ván cờ kéo dài bao lâu, hay liệu nó có kết thúc hay không. Nhưng điều agent cần cho thấy thì rõ: trạng thái trò chơi mà nó đã đọc và lý do tiếp tục hoặc dừng công việc.

Viết điều kiện của riêng bạn

Hãy bắt đầu bằng câu "nhiệm vụ hoàn tất khi...". Nếu phần tiếp theo là "mọi thứ tốt hơn", agent sẽ phải tự đoán ý bạn. Thay đánh giá chung chung bằng hành vi có thể quan sát: "sau khi xóa nội dung tìm kiếm, tất cả thẻ lại hiển thị". Có thể dùng nhiều bước kiểm tra nếu chúng cùng mô tả một kết quả, chẳng hạn chức năng tìm kiếm đã sửa.

• Nêu rõ kết quả. "Sửa chức năng tìm kiếm" chỉ ra hướng cần làm, còn "tìm được thẻ theo tên và khôi phục toàn bộ danh sách sau khi xóa nội dung tìm kiếm" xác định điểm hoàn tất.
• Nêu cách kiểm tra. Ghi rõ cần mở gì, nhập gì và kết quả nào được mong đợi. Yêu cầu hiển thị kết quả thực tế trong cuộc hội thoại để bộ đánh giá có thể đọc.
• Giới hạn thay đổi. Nếu chỉ cần sửa kiểu hiển thị, hãy nói rõ. Nếu agent đang kiểm tra trò chơi đã hoàn thiện, hãy cấm sửa mã của nó để tạo ra kết quả mong muốn.
• Dự liệu trường hợp dừng mà chưa thành công. Chẳng hạn, sau ba lần sửa và kiểm tra lại, agent phải mô tả vấn đề còn tồn tại. Đây là giới hạn công việc, không phải cách khác để tuyên bố nhiệm vụ đã hoàn tất.

Trước khi chạy, hãy kiểm tra agent có thể truy cập đúng trang, tệp và công cụ hay không. Địa chỉ và tên thành phần trong điều kiện phải thuộc dự án của bạn. Giới hạn số lần thử bằng văn bản giúp kiểm soát công việc, nhưng không phải giới hạn kỹ thuật cứng về thời gian hay chi phí.

Hãy chú ý mũi tên quay lại. Nếu kết quả chưa đạt, agent nhận lượt làm việc tiếp theo, có thể sửa vấn đề rồi kiểm tra lại. Nhưng thoát khỏi vòng lặp này không phải lúc nào cũng đồng nghĩa với thành công: cần nêu riêng trở ngại hoặc giới hạn đã đặt ra. Sơ đồ mô tả logic hoạt động của điều kiện; agent và bộ đánh giá theo dõi số lần thử qua cuộc hội thoại.

Ba ví dụ cho nhiệm vụ của bạn

Dưới đây là các điều kiện mẫu cho những trang đã có sẵn. Trước khi chạy, hãy thay địa chỉ, dữ liệu và hành vi mong đợi bằng thông tin của bạn. Đây là ví dụ về điều kiện, không phải báo cáo công việc đã hoàn thành.

Sửa chức năng tìm kiếm trong danh mục

Giả sử danh mục cục bộ có các thẻ "Atlas" và "Orion", nhưng danh sách vẫn trống sau khi xóa nội dung tìm kiếm. Yêu cầu "làm cho tìm kiếm hoạt động bình thường" không nói rõ hành vi nào bạn cần. Ba trường hợp cụ thể sau sẽ hữu ích hơn:

/goal hãy sửa chức năng tìm kiếm trong danh mục tại http://localhost:3000/catalog.
Hoàn tất khi truy vấn "atlas" tìm thấy thẻ "Atlas",
truy vấn "zzzz-no-match" hiển thị "Không tìm thấy kết quả",
và xóa nội dung tìm kiếm sẽ khôi phục tất cả thẻ ban đầu.
Hãy kiểm tra cả ba trường hợp bằng Playwright và cho thấy trong hội thoại
truy vấn, kết quả mong đợi cùng các thẻ hoặc thông báo thực tế hiển thị.
Sau lần sửa cuối, hãy kiểm tra lại cả ba trường hợp.
Chỉ thay đổi logic tìm kiếm; không sửa dữ liệu danh mục hay giao diện.
Nếu vấn đề vẫn còn sau ba lần sửa và kiểm tra,
hãy dừng lại và liệt kê những trường hợp chưa hoạt động.

Từ "cả" rất quan trọng: tìm thấy một thẻ chưa đủ để xác nhận chức năng tìm kiếm đã được sửa. Dữ liệu danh mục được giữ nguyên, nên không thể đổi tên các thẻ để tạo ra kết quả mong muốn. Cũng cần kiểm tra lại sau lần sửa cuối vì sửa thao tác xóa nội dung tìm kiếm có thể làm hỏng chính chức năng tìm kiếm.

Kiểm tra biểu mẫu mà không sửa

Kết quả của một goal có thể là danh sách các quan sát. Giả sử bạn cần kiểm tra biểu mẫu đăng ký đã hoàn thiện và muốn thảo luận riêng về việc sửa lỗi. Khi đó goal kết thúc sau khi kiểm tra tất cả trường hợp, kể cả khi phát hiện lỗi.

/goal hãy kiểm tra biểu mẫu tại http://localhost:3000/signup
bằng Playwright, không thay đổi tệp dự án.
Kiểm tra hai trường hợp, mỗi lần bắt đầu với biểu mẫu trống:
1. Nhấp "Đăng ký" khi chưa điền trường nào.
Mong đợi có thông báo trường bắt buộc; không đăng ký.
2. Nhập "alex" vào trường email và điền các giá trị mẫu hợp lệ
vào những trường bắt buộc còn lại, sau đó nhấp nút.
Mong đợi lỗi định dạng email; không đăng ký.
Hoàn tất khi cuộc hội thoại có báo cáo về cả hai trường hợp:
đã nhập gì, mong đợi gì, trang hiển thị gì và có khớp hay không.
Không gửi biểu mẫu với email hợp lệ và không tạo tài khoản.
Nếu không mở được trang hoặc thành phần, hãy dừng kiểm tra
và nêu trường hợp nào chưa được kiểm tra cùng lý do.

Hãy phân biệt: "kiểm tra biểu mẫu" và "đảm bảo biểu mẫu hoạt động" là hai nhiệm vụ khác nhau. Lỗi trong biểu mẫu không ngăn việc hoàn tất báo cáo, miễn là agent đã kiểm tra cả hai trường hợp và đưa ra kết quả. Nhưng nếu không truy cập được trang thì không thể hoàn thành: phỏng đoán thay cho quan sát không thể khép lại goal.

Hiển thị trang vừa màn hình điện thoại

Yêu cầu "làm cho trang đẹp trên di động" phụ thuộc quá nhiều vào đánh giá chủ quan của agent. Hãy chọn trang cụ thể, kích thước cửa sổ và các thành phần phải luôn truy cập được.

/goal hãy sửa kiểu hiển thị trang http://localhost:3000
cho cửa sổ kích thước 390x844 và 1440x900.
Hoàn tất khi cả hai kích thước không có thanh cuộn ngang,
tiêu đề và nút "Bắt đầu" hiển thị đầy đủ, không chồng lấp,
và nhấp "Bắt đầu" vẫn mở phần trò chơi.
Sau lần sửa cuối, hãy kiểm tra cả hai kích thước bằng Playwright.
Hiển thị ảnh chụp màn hình, kết quả nhấp nút và các giá trị đo được
của scrollWidth và clientWidth trên phần tử gốc của trang:
scrollWidth không được lớn hơn clientWidth.
Chỉ sửa CSS. Không ẩn hay cắt bớt nội dung
để loại bỏ thanh cuộn. Giữ nguyên văn bản và hành vi trò chơi.
Nếu điều kiện chưa đạt sau ba lần sửa và kiểm tra,
hãy dừng lại và cho thấy điểm chưa khớp.

Các kích thước ở đây là chiều rộng và chiều cao cửa sổ trình duyệt tính bằng pixel. scrollWidth cho biết chiều rộng nội dung, kể cả phần nằm ngoài mép hiển thị; clientWidth là chiều rộng khả dụng. So sánh hai giá trị giúp phát hiện nội dung tràn, nhưng tự nó không chứng minh văn bản không bị cắt hay nút có thể sử dụng. Vì vậy điều kiện còn yêu cầu ảnh chụp màn hình và thao tác nhấp. Hai kích thước cũng không đảm bảo trang tiện dùng trên mọi thiết bị - chúng chỉ xác định phạm vi nhiệm vụ này.

Nhờ agent soạn goal

Không nhất thiết phải tự viết điều kiện từ đầu. Bộ sưu tập Claude Code Best Practice nêu hai gợi ý từ cộng đồng: yêu cầu agent đề xuất goal dựa trên ngữ cảnh dự án, hoặc nhờ agent soạn câu chữ sau khi đọc hội thoại và các tệp. Dưới đây là cách điều chỉnh những gợi ý này cho một nhiệm vụ nhỏ.

Nếu chưa rõ nên giao việc gì cho một tác vụ chạy lâu, hãy bắt đầu bằng tin nhắn thông thường, chưa cần dùng /goal:

Hãy đọc cuộc hội thoại hiện tại và các tệp dự án liên quan đến nhiệm vụ.
Đề xuất ba mục tiêu hữu ích có thể đưa đến kết quả kiểm chứng được.
Với mỗi mục tiêu, hãy nêu kết quả, cách kiểm tra,
phạm vi thay đổi và những thông tin còn thiếu để bắt đầu.
Dựa trên những gì chúng ta đã thống nhất. Chưa chạy các mục tiêu,
không sửa tệp. Nếu ý định chưa rõ, hãy đặt câu hỏi.

Hãy chọn một mục tiêu. Công việc kéo dài tự nó không phải lợi thế: sửa xong chức năng tìm kiếm hữu ích hơn vài giờ "cải thiện" không rõ ràng. Khi nhiệm vụ đã cụ thể, bạn có thể bỏ qua yêu cầu đầu tiên và nhờ agent soạn thẳng bản nháp điều kiện:

Hãy viết nội dung /goal cho nhiệm vụ đã chọn dựa trên cuộc hội thoại,
các tệp dự án và tài liệu của dự án. Tạm thời đừng thực hiện gì.
Nêu kết quả có thể quan sát, cách kiểm tra và nội dung cần hiển thị
trong hội thoại. Thêm phạm vi chỉnh sửa và điều kiện dừng nếu chưa thành công.
Không tự nghĩ ra địa chỉ, lệnh hay dấu hiệu hoàn tất:
hãy tìm trong dự án hoặc hỏi tôi.
Trả về một nội dung hoàn chỉnh và liệt kê riêng những điểm chưa rõ.

Trước khi gửi bản nháp, hãy kiểm tra ý nghĩa. Kết quả có đúng điều bạn muốn không? Trang được nêu có tồn tại không? Agent có tự cho phép mình sửa dữ liệu hoặc thêm tính năng không? Nếu cuối bản nháp còn điểm chưa rõ, hãy làm rõ trước. Chỉ chạy sau khi đã chốt nội dung: lệnh /goal bắt đầu công việc ngay lập tức.

Xem trạng thái và dừng công việc

Khi goal đang hoạt động, bạn có thể theo dõi tiến trình: lệnh /goal không có tham số sẽ hiển thị trạng thái hiện tại - điều kiện, thời gian và số lượt đã trôi qua, cùng lý do gần nhất do bộ đánh giá trả về.

Bạn cũng có thể dừng goal sớm bằng lệnh /goal clear. Lệnh này xóa điều kiện, ngay cả khi ván cờ chưa kết thúc.

Kết quả đã được xác nhận ở đây chỉ có một: điều kiện được đáp ứng và điều đó thể hiện trong câu trả lời của bộ đánh giá ở cuộc hội thoại. Xóa goal bằng lệnh /goal clear cũng là một kết cục rõ ràng, nhưng đó là quyết định dừng lại của bạn, chứ không phải bằng chứng rằng công việc đã xong. Những cách khác khiến goal tự dừng không xác nhận kết quả.

Model kiểm tra nhận được gì

Bộ đánh giá /goal không nhìn thấy trang mà chỉ đọc cuộc hội thoại: những gì agent viết và nội dung nó sao chép từ các quan sát trên trình duyệt. Bộ đánh giá không có công cụ riêng - nó không mở lại trang hay tự chạy lệnh, mà chỉ đọc phần văn bản đã tích lũy.

Hệ quả rất đơn giản. Câu "ván cờ kết thúc rồi" của agent tự nó chẳng chứng minh điều gì với bộ đánh giá hay với bạn. Bằng chứng là kết quả agent thực sự đọc được từ trang - chính giá trị data-game-over đó. Một bên là lời khẳng định, bên kia là quan sát; dù nghe giống nhau, đó vẫn là hai thứ khác nhau.

Cũng cần hiểu giới hạn của dấu hiệu này. data-game-over cho biết trạng thái của một ứng dụng cụ thể - trạng thái mà tác giả trang đã lập trình. Nó không cho biết toàn bộ ván cờ có tuân theo luật cờ vua và không mắc lỗi nào hay không. Tương tự, không có thanh cuộn cũng không chứng minh nút hoạt động. Hãy chọn dấu hiệu phù hợp với kết quả bạn thực sự muốn và đừng suy diễn quá mức.

Điều này thay đổi công việc ra sao

Với nhiệm vụ của mình, bạn có thể làm theo lộ trình ngắn tương tự:

• kết quả rõ ràng và cách kiểm tra sẵn có;
• điều kiện có phạm vi chỉnh sửa và dừng, được đặt bằng lệnh /goal;
• trạng thái có thể xem bất cứ lúc nào bằng /goal không có tham số;
• kết luận được củng cố bằng quan sát và kết quả kiểm tra;
• goal được xóa thủ công bằng lệnh /goal clear nếu công việc mắc kẹt hoặc điều kiện không phù hợp.

Tự động tiếp tục công việc và quyết định bước tiếp theo là hai việc khác nhau. Bạn có thể giao việc thứ nhất cho /goal trong một phiên làm việc. Việc thứ hai - tìm hiểu kết quả thực tế, xóa goal chưa hoàn tất và đặt nhiệm vụ tiếp theo - vẫn do bạn quyết định.

Hành vi chính xác của bộ đánh giá và định dạng trạng thái có thể hơi khác tùy phiên bản Claude Code. Nguyên tắc chung vẫn là đánh giá dựa trên cuộc hội thoại, không phải truy cập trực tiếp vào trang.