Form trông như đã xong. Bạn gõ tiêu đề, bấm lưu, spinner quay một vòng rồi trang hiện lại. Không có gì được lưu cả, với bạn hay với bất kỳ ai. Agent viết thay đổi đó đã báo "xong, test pass", và cả hai vế của câu ấy đều đúng.
File nó sửa bắt đầu bằng "use server", directive biến các export của một module Next.js thành server action. Agent chỉ thêm đúng một hằng số được export, nằm cạnh các action. Module có "use server" chỉ được export async function (tài liệu của React ghi rõ luật này), nên lúc runtime framework từ chối cả module và mọi action bên trong đều hỏng. Còn unit test thì import thẳng file đó. Với test runner, "use server" chỉ là một chuỗi ký tự nằm đầu file, không hơn. Xanh.
Coding agent là một người kể chuyện nhanh, trôi chảy và lạc quan. "Xong" là đoạn kết câu chuyện của nó, không phải một sự thật về hệ thống của bạn. Cách chữa không phải là nghi ngờ chung chung, mà là hỏi đúng một câu cho mọi khẳng định: thật sự đã kiểm tra cái gì, và cái gì chưa?
Ba lần báo "xong" mà chưa xong
Vụ export trong "use server" là lần thứ nhất. Thêm hai lần nữa, cùng một họ:
Template chưa bao giờ được điền. Một script sinh config production từ template chứa các token kiểu {API_BASE_URL}. Bước thay thế không hề chạy. Chuỗi có dấu ngoặc nhọn vẫn là chuỗi hợp lệ, nên chẳng parser nào kêu ca, và config được ship đi với nguyên văn {API_BASE_URL} ở chỗ lẽ ra phải là một URL.
Lệnh sửa không khớp chỗ nào. Một lượt find-and-replace chạy qua vài file. Các file đã đổi kể từ lần cuối agent đọc chúng, nên pattern không khớp được gì. Script vẫn in ra thành công, vì nó thành công thật: một lệnh thay thế không thay chỗ nào vẫn là một lần chạy thành công.
Lần thứ ba thì bạn tự tái hiện được trong năm giây:
printf 'timeout = 30\n' > app.conf
sed -i.bak 's/timeout = 60/timeout = 90/' app.conf
echo "exit code: $?" # exit code: 0
cat app.conf # timeout = 30, không đổi gìTài liệu của GNU sed nói rõ exit status 0 nghĩa là chạy xong thành công. "Nó chạy xong chưa?" và "nó có đổi đúng thứ tôi muốn không?" là hai câu hỏi khác nhau, và chỉ câu đầu có exit code.
Trong cả ba chuyện, công cụ nào cũng trả lời đúng câu nó được hỏi. Chỉ là không ai hỏi câu quan trọng: bây giờ hệ thống đã làm được việc đó chưa?
Vì sao AI agent báo "xong" khi code vẫn lỗi?
Không phải vì nó nói dối. Dù là Claude Code, Codex hay OpenCode, cả thế giới của agent chỉ là đống text mà tool trả về: output của compiler, output của test, kết quả ghi file, dòng cuối cùng script in ra. "Xong" là bản tóm tắt của lần thành công gần nhất nó nhìn thấy, và lần thành công nào cũng có thật.
Có ba lý do khiến khoảng hở này mang tính hệ thống chứ không phải do xui:
- Exit code trả lời "có chạy không?", không trả lời "có đúng không?". Số 0 chỉ nói tiến trình đã kết thúc mà không gặp lỗi nào nó biết cách phát hiện.
- Agent kiểm tra ở chỗ agent sống. Nó chạy unit test trong terminal. Hiếm khi nó dựng cả app, đi qua gateway rồi submit một form thật, nên lỗi ở những ranh giới đó nằm ngoài tầm mắt của nó.
- Việc được giao dưới dạng "làm cho pass". Đưa agent một test đỏ, nó sẽ làm cho xanh. Đó cũng chính là cách bạn có một test xanh nhưng không còn test đúng thứ cần test.
Hình ảnh tôi dùng xuyên suốt bài này là biên bản nghiệm thu. Người nghiệm thu công trình không ký vào tờ giấy ghi "công trình đạt". Một biên bản có giá trị sẽ ghi: đã kiểm tra hệ thống điện căn 1 đến 4 và lối thoát hiểm tầng 1 đến 3; chưa kiểm tra mái (không có lối lên) và căn 5 (khóa cửa); ngày; người ký. Chính nửa sau làm cho nửa đầu đáng tin. Biên bản nào không ghi phần chưa kiểm tra thì cứ coi như chưa kiểm tra gì.
Chữ "xong" của agent là lời nhà thầu báo công trình đã hoàn thiện. Thứ bạn cần là biên bản nghiệm thu.
Sao dặn "nhớ kiểm tra lại kỹ" vẫn không ăn thua?
Cách chữa hiển nhiên là đòi cẩn thận hơn. Thêm câu "chạy test trước khi báo xong" vào prompt. Bảo agent kiểm tra lại. Cho một agent thứ hai review báo cáo của agent thứ nhất.
Cách nào cũng hỏng vì cùng một lý do: bạn đang bảo một người kể chuyện cùng kiểu nhìn kỹ hơn vào cùng một bằng chứng. "Chạy test" thì chạy lại đúng những test vốn đã xanh. "Kiểm tra lại" thì đọc lại diff với cùng những giả định, nên một agent tin rằng "use server" chỉ là directive sẽ thấy cái export thừa hoàn toàn bình thường. Người review đọc bản tóm tắt thì kiểm tra câu chuyện, chứ không kiểm tra hệ thống.
Làm vậy chẳng khác gì bắt nhà thầu hứa chắc hơn. Thứ thật sự thay đổi được kết quả là đổi bằng chứng: một loại kiểm tra khác, một artifact bạn tự đọc, và một danh sách viết ra những gì chưa được xem. Có ba công cụ làm được việc đó: nhãn, thang và biên bản.
Bảy nhãn cho những gì bạn thật sự biết
Công cụ đầu tiên là từ vựng. Nền tảng tôi đang làm, gồm mười ba service NestJS trong một Nx monorepo cộng một frontend, giữ luật dự án ở một chỗ duy nhất. Một trong các luật đó là mọi khẳng định về implementation phải mang đúng một nhãn bằng chứng. Có bảy nhãn:
| Nhãn | Nghĩa là |
|---|---|
| Released | Contract, runtime OpenAPI, check và release được track đều khớp nhau |
| Verified implementation | Source hiện tại cộng một check có phạm vi đã pass |
| Prototype observation | Thấy trong một snapshot source đã nêu rõ; chưa chạy gì |
| Architecture decision | Luật đích đã được duyệt, dù đã build hay chưa |
| Planned | Có ý định, chưa có bằng chứng implementation |
| Alignment gap | Thiết kế đích và code lệch nhau; cần xử lý tiếp |
| Unknown | Không có bằng chứng đáng tin; đừng suy diễn gì |
Phần lớn giá trị nằm ở ba phân biệt.
Đọc không phải là chạy. Câu "controller trả 404 khi không tìm thấy order", nói ra sau khi đọc source, là Prototype observation. Nó chỉ thành Verified implementation sau khi có một check thật sự chạy qua nhánh đó. Agent đọc code giỏi tới mức những gì nó quan sát nghe y như đã kiểm chứng; cái nhãn buộc sự khác biệt ấy phải lộ ra.
Verified không phải là released. Trong repository, một service vừa có thêm ba endpoint đọc không cần đăng nhập. Typecheck pass, 31 test suite với 141 test pass, các check của client phía frontend pass, docs và Postman collection đã cập nhật. Hồ sơ vẫn ghi Verified implementation, không phải Released, vì chẳng thứ nào trong số đó chứng minh được routing qua gateway, migration đã được apply, runtime OpenAPI đã được sinh ra, hành vi trên trình duyệt ở môi trường đã deploy, hay một bản release được track.
Unknown là câu trả lời hợp lệ. Đây là nhãn agent ít dùng nhất mà lại cần nhất. "Tôi không tìm thấy bằng chứng theo hướng nào cả" tốt hơn một phỏng đoán tự tin, vì người khác sẽ xây tiếp lên phỏng đoán đó.
Thêm một luật nữa: chỉ nâng nhãn khi đã có đủ bằng chứng cần thiết, và không bao giờ sửa bằng chứng cho khớp với thiết kế mình thích. Khi thiết kế đích và code lệch nhau, đó là một Alignment gap được ghi lại để xử lý, chứ không phải một lần sửa docs cho đẹp.
Kiểm chứng code do AI agent viết thế nào? Leo từng bậc thang
Nhãn cho biết bạn biết gì. Thang cho biết làm sao để biết. Mỗi bậc tốn kém hơn và nhìn thấy nhiều hơn bậc dưới.
| Bậc | Chứng minh được | Không nhìn thấy |
|---|---|---|
| Type | Shape khớp giữa các module | Mọi thứ lúc runtime |
| Test | Những gì môi trường test thấy | Phần wiring test bỏ qua |
| Runtime OpenAPI | Route mà app đã boot đăng ký | Route có chạy đúng không |
| Check có phạm vi | Ranh giới thật, output giữ lại | Nhánh chưa được chạy qua |
| Thứ đang chạy | Thứ người dùng thật sự nhận | Rất ít, nhưng tốn kém |
Câu ở cuối sơ đồ là toàn bộ phương pháp: leo cho tới khi bậc thang khớp với khẳng định. "Type khớp nhau" cần bậc một. "Endpoint tồn tại" cần bậc ba. "Người dùng lưu được bản nháp" cần bậc năm. Agent nói "người dùng lưu được bản nháp" với bằng chứng ở bậc hai là đang đưa ra một khẳng định cao hơn bằng chứng của nó tới ba bậc.
Bậc 1: type
tsc --noEmit hay nx typecheck rẻ và bắt được một nhóm lỗi có thật: field bị đổi tên, thiếu argument, import tới thứ không còn tồn tại. Nhưng nó không bắt được chuyện nào trong ba chuyện ở trên. Một chuỗi chứa {API_BASE_URL} vẫn là chuỗi đúng type.
Bậc 2: test
Test chứng minh những gì môi trường test nhìn thấy, mà môi trường test là một mô hình của hệ thống thật đã bị lược đi vài mảnh. Bug "use server" sống đúng trong một mảnh bị lược như thế. Khi test pass, hãy hỏi nó đã bỏ qua cái gì: import trực tiếp thì bỏ qua framework, mock repository thì bỏ qua database, unit test cho controller thì bỏ qua gateway.
Có một cách phòng rẻ tiền cho những test xanh vì chẳng test gì: xem test fail trước khi tin nó pass. Nếu agent sửa một bug, test mới của nó phải fail trên code cũ. Hãy đòi xem lần chạy đó.
Bậc 3: runtime OpenAPI được sinh ra
Bậc này hay bị xem nhẹ. Trong repository, mỗi service dựng tài liệu OpenAPI từ chính instance ứng dụng đã boot, thông qua một helper dùng chung, rồi serve nó dưới dạng openapi.json. Tài liệu đó liệt kê những route mà Nest thật sự đã đăng ký, chứ không phải những route có ai đó từng viết controller.
Một controller có module không bao giờ được import là route được tuyên bố nhưng chưa từng được nối vào. Đọc source thì thấy nó nằm đó; tài liệu runtime thì bảo không có. Vì thế luật dự án đòi runtime OpenAPI được sinh ra, chứ không phải một spec viết tay, trước khi một endpoint được gọi là Released.
Bậc 4: check có phạm vi qua ranh giới thật
Một check có phạm vi chạy thứ thật, qua một ranh giới thật, trong một phạm vi hẹp, và giữ lại output. Test end-to-end đi qua gateway với database thật là ví dụ dễ thấy nhất.
Script kiểm tra deployment trong repository thể hiện tinh thần này ở dạng thu nhỏ. Với mỗi service, nó gọi /health/live, /health/ready và /openapi.json, rồi kiểm tra nội dung chứ không chỉ nhìn status code:
verify_openapi() {
local url="$1"
local response
if ! response="$(request_json "${url}")" \
|| ! jq -e '.openapi | type == "string"' >/dev/null 2>&1 <<<"${response}"; then
echo "OpenAPI verification failed for ${url}" >&2
return 1
fi
}Bản thân script này cũng có test, và hai test nhắm đúng vào các kiểu thất bại trong bài. Một test đưa vào response OpenAPI bị cắt cụt và khẳng định script fail với thông báo kiểm chứng, chứ không phải lỗi parser. Test còn lại đọc source của script và khẳng định trong đó không có lời gọi POST, login, refresh, logout hay user nào, để việc kiểm tra một môi trường không bao giờ làm thay đổi chính môi trường đó.
Bậc 5: nhìn tận mắt thứ đang chạy
Mở trang. Submit form. Đọc config được sinh ra. Gọi endpoint bằng curl. Bậc này bắt được cả ba chuyện, với chi phí cao nhất, vì nó nhìn vào chính output chứ không nhìn vào thứ đại diện cho output.
Có hai kiểu nhìn đủ rẻ để tự động hóa thành bước đọc lại (read-back). Kiểu thứ nhất kiểm tra file đã render xem còn sót placeholder nào không:
import re
import sys
PLACEHOLDER = re.compile(r"\{[A-Z_]+\}")
def assert_rendered(path: str) -> None:
with open(path, encoding="utf-8") as rendered:
leftovers = sorted(set(PLACEHOLDER.findall(rendered.read())))
if leftovers:
sys.exit(f"{path}: unfilled placeholders {leftovers}")
assert_rendered(sys.argv[1])Kiểu thứ hai từ chối một lần sửa không đổi được gì:
cp app.conf app.conf.before
sed -i.bak 's/timeout = 60/timeout = 90/' app.conf
if cmp -s app.conf app.conf.before; then
echo "edit matched nothing" >&2
exit 1
fiHai đoạn có chung một khuôn: kiểm tra artifact, đừng kiểm tra báo cáo của tool về artifact. Chạy git diff --stat sau một lượt sửa hàng loạt của agent là làm đúng việc này mà không tốn gì. Diff trống sau câu "đã cập nhật 12 file" là một phát hiện, không phải thành công.
Biên bản kiểm chứng cần ghi những gì?
Biên bản kiểm chứng chính là biên bản nghiệm thu của bạn. Biên bản của tôi có năm phần, và phần cuối là thứ làm nó trung thực. Đây là trường hợp ba endpoint đọc ở trên, viết theo khuôn đó:
**Khẳng định:** ba endpoint đọc không cần đăng nhập chỉ trả về item đang active
**Nhãn:** Verified implementation
**Trên:** backend @ <short sha>, worktree có thay đổi chưa commit
**Đã chạy (2026-07-27, UTC):**
- `pnpm exec nx typecheck <service>`: pass
- test suite của service: 31 suite, 141 test, pass
**Không chứng minh:** routing qua gateway, migration đã apply, runtime OpenAPI,
hành vi trên trình duyệt ở môi trường đã deploy, release được trackDòng "Không chứng minh" là dòng người ta hay bỏ, và chính nó bảo vệ người đọc sau. Thiếu dòng đó, một biên bản ở bậc hai sẽ lặng lẽ bị đọc thành bậc năm.
Hai mục khác trong repository cho thấy hai thái cực. Mục thứ nhất là một báo cáo mô tả workflow chạy thành công ở local (migration, seed, build, gọi HTTP qua gateway), nhưng không lưu lại câu lệnh hay output nào. Nó bị hạ xuống Prototype observation cho tới khi có một lần chạy kiểm toán được. Ký nghiệm thu mà không có biên bản thì không phải là nghiệm thu.
Mục thứ hai đồng bộ config, các lệnh CI, tham chiếu Terraform, tài liệu route và Postman, rồi liệt kê mọi check không chạy, vì việc kiểm chứng được cố ý hoãn lại. Biên bản đó gần như chẳng chứng minh được gì nhưng lại hoàn toàn đáng tin, vì nó nói thẳng điều đó. Nó còn ghi chú rằng vài giá trị config đã được nối vào như input lúc deploy, trong khi các module vẫn dựng adapter giả. Đã nối vào không có nghĩa là đã được dùng.
Biên bản chạy lại được thì hơn biên bản phải tin. Wrapper dưới đây khiến các check của agent để lại dấu vết thay vì một câu kể:
#!/usr/bin/env bash
# record.sh: chạy một check và giữ nguyên những gì nó in ra
set -uo pipefail
mkdir -p evidence
log="evidence/$(date -u +%Y%m%dT%H%M%SZ).log"
{
echo "when: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo "revision: $(git rev-parse --short HEAD)"
echo "dirty: $(git status --porcelain | wc -l | tr -d ' ') files"
echo "command: $*"
echo "---"
} > "$log"
"$@" >> "$log" 2>&1
status=$?
echo "exit: $status" >> "$log"
echo "$log"
exit "$status"./record.sh pnpm exec nx test order-service để lại một file log mà agent không tự viết và cũng không thể tóm tắt cho qua.
Vì sao biên bản kiểm chứng bị cũ?
Một lần nghiệm thu chỉ có giá trị với công trình ở đúng hiện trạng ngày hôm đó. Trong repository có một biên bản cho workflow auth, kiểm chứng vào một ngày cụ thể. Một ngày sau, worktree đã có thêm code đổi mật khẩu, reset mật khẩu và quản lý role, và file bằng chứng ghi thẳng rằng biên bản trước không bao gồm những thay đổi này. Chỉ một câu đó đã đủ ngăn người ta đọc "auth đã verify" thành bao luôn cả phần code lúc ấy còn chưa tồn tại.
Vì vậy biên bản nào cũng ghi revision và worktree có dirty hay không. Code đã đổi thì biên bản chỉ còn là lịch sử.
Thế nào là "xong" với một thay đổi do agent viết?
Đây là điều tôi đòi ở mọi agent, và ở chính mình. Nó nằm trong file luật dùng chung mà tool nào cũng đọc, nên không bao giờ bị chép ra năm chỗ (một bộ luật cho mọi agent).
- Phát biểu khẳng định trong một câu, kèm một nhãn. "Người dùng lưu được bản nháp" là một khẳng định. "Đã sửa form" thì không.
- Đưa bằng chứng từ đúng bậc thang khớp với khẳng định, dưới dạng câu lệnh cộng output được giữ lại, không phải lời diễn giải.
- Đọc lại những gì đã thay đổi. Diff, file được sinh ra, config đã render. Diff trống hoặc diff gây bất ngờ đều là phát hiện.
- Liệt kê những gì chưa kiểm chứng. Lần nào cũng vậy. "Không có gì" gần như chẳng bao giờ đúng.
- Chứng minh không có gì khác bị xê dịch. Chụp
git statusở root và ở từng submodule, trước và sau. Một thay đổi không liên quan là tín hiệu phải dừng lại. - Validate các artifact đi kèm. Parse mọi file JSON đã đụng tới và kiểm tra link trong mọi tài liệu đã sửa.
Khi giao việc, brief ghi rõ "xong" đòi bậc thang nào, dưới dạng một câu lệnh agent bắt buộc phải chạy (brief mà "xong" là một câu lệnh). "Xong nghĩa là pnpm exec nx e2e order-service-e2e pass và có đính kèm log" chừa ít chỗ cho kể chuyện hơn nhiều so với "nhớ kiểm tra xem chạy được chưa nhé".
Cách làm này tốn những gì?
- Thời gian. Bậc bốn và bậc năm chậm. Chạy cả bộ end-to-end cho mọi thay đổi nhỏ là không thực tế, và đó chính là lý do chỉ nên khẳng định tới đúng bậc mà bạn đủ sức chi trả.
- Thủ tục rườm rà. Bảy nhãn và một biên bản cho mỗi khẳng định có thể biến thành giấy tờ. Khi viết biên bản lâu hơn làm thay đổi, người ta sẽ thôi viết, hoặc viết cho có.
- Biên bản mau cũ. Với worktree dirty, biên bản cũ đi chỉ sau vài giờ. Chính snapshot của repository cũng thừa nhận nó không khóa được một trạng thái ứng dụng ổn định bằng hash vì lý do đó.
- Bịa kết quả. Agent hoàn toàn có thể gõ ra một bản tóm tắt test nghe rất hợp lý. Chỉ output của tool, được lưu thành file và bạn tự chạy lại được, mới tính.
- Bậc thang cũng có thể đánh lừa. Một stage pipeline được định nghĩa chưa chắc đã từng chạy, và Terraform đã viết chưa phải là hạ tầng đã dựng; bài so sánh Compose với Kubernetes gặp đúng chuyện này.
Nếu làm lại, tôi sẽ làm khác điều gì?
- Biên bản do máy ghi ngay từ đầu. Những biên bản đầu tiên là văn xuôi do agent tự viết. Lẽ ra chúng phải là log do wrapper ghi, văn xuôi chỉ nằm bên trên.
- Cưỡng chế thay vì khuyên nhủ. Một luật trong file markdown chỉ là lời khuyên. Một hook của Claude Code hay một job CI từ chối trạng thái "complete" khi chưa có log bằng chứng mới hơn lần sửa cuối mới là cưỡng chế. Tôi sẽ đưa định nghĩa "xong" vào tooling sớm hơn nhiều.
- Test fail trước. Với mỗi bug fix, đòi bản tái hiện, tức một test fail trên code cũ, trước khi sửa.
- Kiểm chứng trên revision sạch. Khá nhiều biên bản trong repository mô tả worktree dirty. Chúng trung thực về chuyện đó, nhưng một biên bản gắn với commit mà ai cũng checkout được thì giá trị hơn nhiều.
Tóm tắt
- Chữ "xong" của agent là bản tóm tắt lần thành công gần nhất nó thấy. Hãy coi nó là khẳng định, đừng bao giờ coi là sự thật.
- Exit code trả lời "có chạy không?". Bạn vẫn phải tự hỏi "có đổi đúng thứ tôi muốn không?".
- Đòi cẩn thận hơn không giúp được gì. Đổi bằng chứng thì có.
- Mỗi khẳng định mang đúng một nhãn. Đọc không phải là chạy, verified không phải là released, và Unknown là câu trả lời hợp lệ.
- Leo dần từng bậc (type, test, runtime OpenAPI, check có phạm vi, thứ đang chạy) cho tới khi bậc khớp với khẳng định.
- Biên bản kiểm chứng ghi revision, câu lệnh, output được giữ lại và những gì nó không chứng minh.
Vậy là đủ bốn thói quen: Git nằm trong tay người, mọi agent đọc chung một bộ luật, giao việc bằng brief tự đứng được, và không gì là xong khi chưa có bằng chứng. Nếu bạn bắt đầu từ con số không, hãy bắt đầu từ thói quen đầu tiên: giữ Git trong tay người.
Hay