Guardrails và vòng quét chất lượng đêm

Trang này mô tả hệ kiểm soát chất lượng mã của repo: cái gì chặn lỗi ở đâu, cái gì đo xu hướng, và vòng tự động chạy lúc 3 giờ sáng để mã sạch dần mà không ai phải nhớ.

Ba lớp

Lớp	Trả lời câu hỏi	Ở đâu
Gác (scripts/check-*.mjs)	Luật X có bị vi phạm không? Đúng/sai.	job changes của ci-checks.yml, npm run check:guards
Chỉ số (scripts/qc-scan.mjs)	Thói quen xấu đang lên hay xuống?	cùng job, npm run qc:scan, mốc chỉ được hạ
Vòng đêm (routine cloud)	Ai hạ các con số đó?	03:00 giờ VN mỗi ngày, skill nightly-qc

Ba skill đi kèm: guardrail-design (biến luật thành gác), nightly-qc (quy trình vòng đêm), code-reviewer (rà soát theo các lớp lỗi đã xảy ra thật).

Tám chỉ số

Chỉ số	Vì sao đếm	Mốc 10.10.2026
any-cast	as any / : any tắt kiểm type đúng ở chỗ cần nhất	2.033 (api 1.256)
catch-to-empty	lỗi thành "chưa có gì", thông điệp của một trang khoẻ	49 (api 35)
lint-disable	luật bị tắt tại chỗ	19
huge-file	file trên 1.000 dòng, agent đọc không hết nên sửa theo đoán	12
ts-suppress	@ts-ignore / @ts-nocheck không lý do	0, khoá
empty-catch	catch {} rỗng	0, khoá
lazy-ddl	CREATE TABLE IF NOT EXISTS trong src/	0, khoá
todo	TODO/FIXME trong chú thích	0, khoá

Bốn chỉ số về 0 trong cùng PR dựng hệ này: hai @ts-ignore thay bằng kiểu thật, ba catch {} rỗng được ghi lý do (hoặc khôi phục trạng thái), và hai chỉ số được thu hẹp để không đếm nhầm công cụ migration và dữ liệu thử của các gác khác.

Vì sao routine cloud, không phải cron GitHub Actions

Agent chạy trên hạ tầng Anthropic nên không tốn phút Actions; repo từng phải tắt Actions vì chi phí (28.09 tới 02.10.2026). Nó vẫn tuân luật "không deploy từ máy": chỉ đẩy nhánh, mở PR, để CI kiểm và deploy như mọi PR khác.

Lịch xoay vòng

Một chủ đề mỗi đêm, một PR dưới ~400 dòng: Hai catch-to-empty, Ba any ở api, Tư any ở frontend, Năm lỗ của hệ gác, Sáu file khổng lồ hoặc eslint-disable, Bảy rà soát commit tuần qua, Chủ nhật chỉ báo cáo. Chi tiết và danh sách việc vòng đêm không được làm ở skill nightly-qc.

Kết quả audit 10.10.2026

Nghiên cứu các repo tham chiếu (anthropics/claude-code plugins/, anthropics/claude-code-action examples/, knip, dependency-cruiser, betterer) và rà hệ gác hiện có cho ra:

• Mạnh: 13 gác đều chạy ở CI, đều xanh, tổng dưới 15 giây; api, www, com, admin, tool-plane, play có typecheck tuyệt đối.
• Đã lấp trong PR này: mam và video có job CI (trước đó deploy là lớp kiểm duy nhất); feature-executor được kiểm cú pháp; chỉ số mùi mã có mốc.
• Còn mở (việc của vòng đêm thứ Năm, danh sách sống ở skill nightly-qc): mentors và docs chưa có job CI; 11/13 gác chưa tự kiểm; lint chưa chạy ở CI; chưa có hook trong phiên agent; chưa đo mã chết (knip) và ranh giới import (dependency-cruiser); audit nội dung chỉ chạy tay.

Bài học chung giữ nguyên từ known-risks: một luật không có gác sẽ bị vi phạm, và một gác chưa chứng minh được nó bắt được gì thì chưa phải gác.

Làn mã chết (từ 12.10.2026)

scripts/dead-code-scan.mjs dựng đồ thị import của mọi file mã trong repo (chỉ đọc text, không cần cài phụ thuộc, dưới một giây) và liệt kê file không file nào import mà cũng không phải điểm vào (route, entry, worker, config, test, shadcn components/ui, legacy/, scripts/, migrations/).

Bước	Lệnh	Ý nghĩa
Đánh dấu	node scripts/dead-code-scan.mjs --mark	ghi ngày đánh dấu đầu tiên vào scripts/dead-code-marks.json; file hết chết rơi khỏi sổ
Đến hạn	node scripts/dead-code-scan.mjs --due	file bị đánh dấu liên tục từ 7 ngày
Xoá	vòng đêm	tối đa 10 file, build từng site xanh, PR riêng nhãn qc-deadcode

Lần quét đầu (12.10.2026): 16 file, 13 ở com.conan.school (component khoá học cũ), 2 ở mam, 1 ở mentors. Sớm nhất được xoá: 19.10.2026. Quy trình chi tiết: skill nightly-qc, mục "Làn mã chết".