Review và gate

Trang này gom ba lớp kiểm tra chạy quanh một thay đổi: review code, contract gate khi chạm tài nguyên chung, và gate hiệu năng DB. Cả ba đều chạy trong bước cuối của /znf:ship.

Khi nào dùng

Dùng /znf:review khi muốn review một diff độc lập, dùng /znf:gate ngay sau khi sửa một collection, kênh pub/sub, endpoint hoặc queue dùng chung, và để /znf:ship tự gọi cả /znf:explain-plan khi diff chạm một query DB. Phần lớn thời gian bạn không gọi các skill này bằng tay, chúng chạy như một phần của /znf:ship.

Các bước

Các bước của một lượt review

Lệnh

/znf:review

Engine review hợp nhất của kit, đi qua bốn gate: PRE, BUNDLE, REVIEW, VERIFY. Gate PRE chạy build/lint và một lượt quét lỗi mẫu cơ bản, không tốn ngân sách nếu bước này đã fail. Gate REVIEW đo diff để chọn mức độ soi:

Kích thước diff	Mức soi
Nhỏ	T1: một reviewer độc lập
Trên 200 dòng	T2: năm reviewer chạy song song, mỗi người phụ trách một trục: lỗi, bảo mật, hiệu năng, hợp đồng, ý định (intent)
Chạm vùng nhạy cảm, bất kể kích thước: một file đổi nằm trong thư mục, hoặc có tên, đúng bằng auth, iam, oauth, security, permission(s), tenant(s), migration(s)	T3: năm trục như T2, cả năm reviewer chạy opus; không còn Workflow hay vòng skeptic

Diff chạm hợp đồng chung (một collection, endpoint, queue, hoặc kênh pub/sub) được nâng mức soi tối thiểu lên mức vừa, kể cả khi diff nhỏ.

Trục intent so diff với phần ## Intent trong gói ship; chạy độc lập mà không có gói thì so với mục tiêu bạn đã nêu. Mọi reviewer đọc CLAUDE.md/AGENTS.md của repo và các file .claude/rules/ khớp với diff trước khi chấm; khi một quy ước bị vi phạm, finding trích file:dòng của quy ước đó.

Reviewer đọc spec như một bản định hướng: chi tiết spec không nhắc tới chưa chắc là lỗi, trừ bảo mật, phân quyền/tenant, an toàn dữ liệu và vỡ hợp đồng — những thứ này thấy trong diff là lỗi. Điều reviewer không đủ căn cứ để phán (không có dữ liệu, chưa đọc caller) được ghi riêng ở khối Declined:, ngoài danh sách phát hiện.

Gate VERIFY kiểm cơ học: mọi phát hiện có kèm vị trí file phải trích đúng dòng code thật, skill loại bỏ phát hiện nào trích sai trước khi kết luận có ship được hay không. Với diff rất lớn, gate BUNDLE tách diff thành nhiều cụm file nhỏ hơn, mỗi cụm review riêng rồi gộp kết quả; nếu vẫn quá lớn để tách, skill dừng và đề nghị chia nhỏ pull request.

/znf:review

Không có diff nào để review, skill báo "nothing to review" và dừng, không dispatch reviewer nào.

/znf:gate

Cổng kiểm hợp đồng chung giữa các repo, chạy ngay sau khi sửa một collection/bảng dùng chung, một kênh pub/sub, một endpoint giữa các dịch vụ, hoặc một queue. Chỉ đọc, an toàn để chạy tự do.

/znf:gate
/znf:gate chat_rooms

Skill lấy danh sách repo thực sự tham gia hợp đồng chung từ cấu hình workspace, tìm nơi khai báo tài nguyên, mọi nơi đọc/ghi qua lớp truy cập của repo đó, và mọi nơi truy cập trực tiếp bỏ qua lớp đó. Với tài nguyên là DB, skill xác minh tên collection/bảng và tên field bằng dữ liệu thật. Kết quả in ra thứ tự triển khai an toàn khi thay đổi phá vỡ hợp đồng.

zenify gate participants

Liệt kê các repo tham gia contract gate cùng cách mỗi repo truy cập DB chung. Danh sách gộp từ file gate-participants.json trong knowledge store và các repo khai gate.sharedStore=true trong .claude/worktree.json.

zenify gate participants --workspace ~/WorkingSpace/zenify

/znf:contract-sweep

Bước leo thang từ /znf:gate, quét sâu hơn khi một lượt quét inline không đủ tin: quá nhiều chỗ dùng để đánh giá chung, thay đổi chạm nhiều tài nguyên cùng lúc, hoặc gate báo sạch mà bạn vẫn nghi. Skill chạy mỗi repo một agent, tìm mọi chỗ dùng qua ba lượt (nơi định nghĩa, nơi dùng qua model symbol hoặc registry, nơi gọi raw driver và pipeline stage), rồi phán BREAKING, RISKY hoặc SAFE cho từng chỗ dùng.

/znf:contract-sweep

Agent không tự chạy skill này, bạn phải tự gõ lệnh khi thấy cần.

/znf:explain-plan và zenify db-perf

Gate hiệu năng DB, hai tầng. /znf:ground gọi skill này sớm ở mức advisory khi diff thêm một query; /znf:ship gọi lại ở bước verify, và một phát hiện BLOCKING chưa waive làm ship không hoàn tất.

/znf:explain-plan

zenify db-perf --from origin/staging --to HEAD

Lệnh zenify db-perf quét tĩnh diff, không cần kết nối DB, và in từng finding kèm file, dòng, collection và gợi ý sửa. Khi DB truy cập được, skill chạy thêm explain plan thật cho từng query. Một COLLSCAN trên collection lớn, hoặc tỉ lệ document xem trên trả về quá cao, là BLOCKING; một SORT dù đã có index, hay $lookup sang collection bị quét toàn bộ, là ADVISORY.

Để waive một finding, thêm chú thích ngay trên dòng query:

// znf:db-perf-ok: bảng chưa đủ lớn để cần index, đã đo thời gian thực tế

Finding chuyển sang WAIVED và lý do được ghi lại. Một collection chưa được phân loại tenant hay global tạo ra finding BLOCKING cho tới khi bạn thêm nó vào file phân loại của knowledge store.

Kết quả

Skill/lệnh	Kết quả
/znf:review	Danh sách finding xếp theo mức độ nghiêm trọng, kèm câu trả lời có ship được hay không
/znf:gate	Bảng usage theo repo, kèm nhận định phá vỡ hay không và thứ tự deploy an toàn
/znf:contract-sweep	Verdict BREAKING/RISKY/SAFE cho từng chỗ dùng, cùng các thay đổi cần có trước khi deploy
zenify db-perf	Finding BLOCKING hoặc ADVISORY kèm gợi ý sửa, hoặc "gate pass" nếu diff không có query; kèm dòng coverage: unsupported stack khi diff chạm stack scanner không đọc được

Lưu ý

• /znf:gate và /znf:contract-sweep dùng cùng danh sách repo và cùng ba lượt tìm, nên hai công cụ không được cho kết quả lệch nhau.
• Khi không đọc được diff, không kết nối được DB, hoặc không có zenify trong PATH, các gate này bỏ qua và không chặn phiên làm việc. Xem Gate fail-open để hiểu nguyên tắc đó.
• Merge PR luôn là quyết định của bạn. Review sạch hay CI xanh không thay thế bước verify hành vi trong board của /znf:ship.

Xem thêm

/reference/skills/review, /reference/skills/gate, /reference/skills/contract-sweep, /reference/skills/explain-plan, zenify db-perf, ship: verify và mở PR, Gate fail-open