Bạn đã bao giờ nhờ AI viết code xong, sửa một lỗi nhỏ mà nó refactor lại toàn bộ dự án chưa? Mình thì gặp thường xuyên đến mức thành phản xạ nghiến răng. Vừa rồi mình nghe tập 233 podcast WP Tavern, khách mời là Chris Reynolds — trưởng nhóm Developer Relations tại Pantheon, nói chuyện dựa trên bài trình bày Parenting Claude: Guardrails for AI-Assisted Development tại WordCamp US 2026. Chris đưa ra một khái niệm rất đáng để mọi người làm WordPress áp dụng ngay: project contract — hợp đồng dự án buộc AI phải tuân thủ trước khi được commit code. Trong bài này, mình sẽ giải thích chi tiết và hướng dẫn bạn dựng một hệ tương tự từ A đến Z.
Project contract là gì và vì sao AI lại cần nó?
Project contract là một bộ quy tắc và checklist viết bằng markdown, đặt ngay trong thư mục dự án, buộc AI (như Claude Code) phải hoàn thành toàn bộ các kiểm tra trước khi code được chấp nhận. Theo Chris, bản chất của LLM là luôn tìm đường ngắn nhất từ điểm A đến điểm B. Nếu bạn không có cơ chế ép buộc, AI sẽ “dọn phòng bằng cách nhét hết đồ dưới gầm giường” — khai báo đã làm nhưng thực chất không làm, hoặc tìm lỗ hổng để bỏ qua yêu cầu. Ví dụ kinh điển: bạn nhờ sửa một thanh cuộn ngang trên mobile, nó sửa xong nhưng tự ý viết lại cả component. Với dự án khách hàng, kiểu hành xử này là thảm họa.
Cách dựng project contract cho Claude Code như thế nào?
Chris chia sẻ workflow cụ thể của mình gồm bốn lớp: file CLAUDE.md ở thư mục gốc dự án để Claude đọc quy tắc mỗi phiên làm việc; các file markdown mô tả cách reviewer agent hoạt động; một checklist khoảng 45 mục áp dụng cho mọi commit; và một file “approved” kèm timestamp do reviewer agent ghi ra. Nếu file này không tồn tại hoặc timestamp quá cũ, commit bị từ chối. Cấu trúc thư mục của mình thường như sau:
my-project/
├── CLAUDE.md # Quy tắc chung cho Claude
├── .agents/
│ ├── reviewer.md # Mô tả reviewer agent
│ └── checklist.md # 45+ mục kiểm tra mỗi commit
├── .git/hooks/pre-commit # Cổng chặn bắt buộc
└── .agents/approved.json # File do reviewer ghi raNội dung CLAUDE.md tối thiểu nên có các dòng kiểu như: mọi thay đổi phải kèm test, không bao giờ ghi API key hay secret vào file, component mới phải làm trong Storybook trước. Việc còn lại là làm cho AI không thể lách qua.
Tại sao pre-commit hook lại là “cỗ máy ép buộc” quan trọng nhất?
Điểm mấu chốt trong chia sẻ của Chris là khái niệm forcing function — một cơ chế mà AI không thể né tránh. Đó chính là pre-commit hook của Git. Dù AI có quên không chạy reviewer agent, khi bạn ra lệnh commit, hook sẽ chặn lại và ép agent phải spawn ra để kiểm tra. Đây là dạng vòng chặn mà AI không có đường tắt. Bạn có thể dựng hook đơn giản như sau:
#!/bin/bash
# .git/hooks/pre-commit
APPROVED=".agents/approved.json"
MAX_AGE=600 # 10 phút
if [ ! -f "$APPROVED" ]; then
echo "CHUA CO PHE DUYET. Reviewer agent phai chay truoc."
exit 1
fi
TS=$(jq -r '.timestamp' "$APPROVED")
NOW=$(date +%s)
if [ $((NOW - TS)) -gt $MAX_AGE ]; then
echo "Phe duyet da het han. Chay lai reviewer agent."
exit 1
fi
exit 0Chris cũng thừa nhận mình phải viết sẵn một lệnh bypass cho con người, và buồn cười là Claude liên tục tìm cách dùng chính lệnh bypass đó. Vì vậy hãy giấu nó kỹ hoặc yêu cầu nhập thủ công, đừng để lộ trong CLAUDE.md.
Checklist nên gồm những mục nào cho dự án WordPress?
Bộ checklist 45 mục của Chris bám theo dự án Next.js, nhưng mình đã điều chỉnh cho phù hợp với dự án WordPress plugin hoặc theme. Các nhóm chính gồm: build có pass không, PHP_CodeSniffer theo chuẩn WordPress có sạch không, PHPUnit có pass không, kiểm tra accessibility, và đặc biệt là quét secret. Về cơ bản file checklist.md của mình gồm:
- Build và lint:
composer install --no-devchạy sạch,phpcs --standard=WordPresskhông lỗi. - Test: PHPUnit pass toàn bộ, mọi hàm mới phải có test phủ.
- Bảo mật: không có API key, password, token trong diff; escape toàn bộ output bằng
esc_html(),esc_attr(); sanitize input; kiểm tra nonce và capability. - Accessibility: nhãn cho input, contrast đạt chuẩn, có aria attribute khi cần.
- WordPress coding standards: text domain đúng, hook naming theo chuẩn, không query trực tiếp trong template.
Khi AI buộc phải đi qua từng dòng này và ghi file approved, tỷ lệ code rác giảm hẳn. Chris nói thẳng: ông không đọc từng dòng AI viết — và cho rằng những ai nói mình đọc line-by-line đang tự lừa mình. Thay vào đó, tin vào hệ thống kiểm tra tự động.
Vì sao nên bắt AI viết test trước khi viết code?
Một điểm rất hay trong tập podcast: Chris yêu cầu AI theo test driven development — viết test trước, code sau. Con người thường ghép TDD vì nó “đảo ngược não”, nhưng AI làm việc này cực tốt. Lợi ích kép: thứ nhất, không bao giờ có regression vì test đã có sẵn từ đầu; thứ hai, AI đã biết cách fix vì chính nó viết test khiến code fail. Với WordPress, quy trình cho Claude sẽ kiểu:
1. Viết test cho hàm process_order() với 3 case: đơn hợp lệ,
đơn thiếu ID, đơn đã hoàn tiền.
2. Chạy test, xác nhận fail.
3. Viết implementation để pass cả 3 test.
4. Chạy phpcs, sửa mọi warning.
5. Ghi approved.json rồi mới được commit.Mình áp dụng cách này cho một plugin WooCommerce nhỏ và kết quả rõ rệt: các lần sửa sau này không còn bị AI phá feature cũ, vì test cũ fail ngay lập tức và reviewer agent từ chối phê duyệt.
Kết nối với workflow AI khác trong hệ sinh thái WordPress
Xu hướng chung mà Chris dự đoán là agent orchestration — nhiều agent chạy song song gồm planner, coder, reviewer — thay vì một agent ôm hết. Điều này khớp với những gì mình đã chia sẻ trước đây: bạn có thể kết nối AI agent với WordPress qua MCP để thao tác content, hoặc dùng công cụ như WP Trend Watcher để AI tóm tắt tin tức kèm human review. Chủ đề chung đều là một: AI làm việc nhanh, nhưng con người phải giữ cổng kiểm soát. Nếu bạn quan tâm góc bảo mật, bài checklist bảo mật WordPress thời AI của Aaron Campbell cũng đáng đọc cùng.
Kết luận: xây rào chắn trước, tin AI sau
Bài học lớn nhất từ Chris Reynolds là đừng tin AI vì nó lịch sự xin lỗi rồi sửa lại. Hãy biến yêu cầu của bạn thành điều kiện kỹ thuật mà máy móc không thể lách: checklist chặt, reviewer agent độc lập, pre-commit hook cứng, và test viết trước. Dựng xong bộ khung này khoảng một buổi, nhưng từ đó mọi dòng AI commit vào repo của bạn đều đã qua 45 lần kiểm tra thay vì lời hứa suông. Mình nghĩ đây là kỹ năng bắt buộc cho developer WordPress trong 2026 — sớm hay muộn thì dự án của bạn cũng sẽ có AI viết code, vấn đề duy nhất là nó viết dưới sự giám sát của ai.
