Dự án của bạn chạy tốt, nhưng sau tuần thứ ba không ai còn trả lời nổi câu hỏi đơn giản: file này nên nằm ở đâu. Logic nghiệp vụ rò rỉ vào route handler, một file utils.ts phình lên hàng trăm dòng, và một ngày đẹp trời bạn phát hiện database client bị import thẳng vào component. Bài viết này chỉ cách viết một Claude Code Skill riêng để bắt các lỗi cấu trúc đó trước khi chúng vào PR — áp dụng được cho bất kỳ stack nào, không chỉ SvelteKit.

Vấn đề quen thuộc: cấu trúc rã dần sau vài chục route

Một lập trình viên SvelteKit mô tả đúng cảm giác này: dự án nào anh từng làm cũng "chạm tường" ở khoảng route thứ hai mươi — app vẫn chạy, nhưng không ai còn trả lời được file này nên đặt ở đâu. Logic nghiệp vụ trôi dần vào +page.server.ts, utils.ts phình to, và database client len lỏi vào tận component. Vấn đề không nằm ở framework — nó nằm ở chỗ quy ước cấu trúc chỉ tồn tại trong đầu vài người, không có gì enforce nó khi team lớn dần.

Anh cũng chỉ ra một điểm đáng chú ý: phần lớn lời khuyên về folder structure trên mạng chỉ có hai dạng — tutorial cho người mới, hoặc một layout "chân lý duy nhất" áp đặt sẵn. Không có công cụ nào tự động đối chiếu quy ước riêng của team bạn với code thực tế mỗi khi có PR mới.

Claude Code Skill giải quyết đúng chỗ hổng đó

Skill là cách bạn dạy Claude Code quy ước riêng của dự án — thay vì hỏi lại "file này nên đặt ở đâu" mỗi lần review, bạn viết quy ước đó một lần, và Claude áp dụng lại mỗi khi được gọi để kiểm tra một thay đổi. Điểm khác biệt so với một linter thông thường: skill có thể lập luận về ngữ cảnh (đây là logic nghiệp vụ hay chỉ là helper hiển thị?), chứ không chỉ khớp pattern cứng.

Bắt đầu từ đâu: ba câu hỏi cần trả lời trước khi viết skill

Trước khi ngồi viết, hãy trả lời rõ ràng cho chính team mình — đây là phần khó nhất, không phải phần code:

File chứa logic nghiệp vụ (business logic) phải nằm ở layer nào, và layer nào tuyệt đối không được import trực tiếp database client?
Ngưỡng nào thì một file "quá to" và cần tách — theo số dòng, theo số trách nhiệm, hay theo tần suất bị sửa?
Có ngoại lệ hợp lệ nào không (ví dụ: script migration, seed data) mà skill không nên gắn cờ?

Ví dụ minh họa (không phải cú pháp chính thức, chỉ để hình dung ý tưởng) một quy ước bạn có thể viết ra thành tài liệu cho skill đọc:

// Quy ước minh họa cho team Next.js
- src/features/*/server/*.ts: được phép import DB client
- src/features/*/components/*.tsx: KHÔNG được import DB client trực tiếp
- Bất kỳ file .ts nào vượt 300 dòng: gắn cờ "cần tách", trừ file *.generated.ts

Sau khi có quy ước bằng lời rõ ràng, việc còn lại là đưa nó vào skill để Claude Code đối chiếu mỗi khi review một thay đổi, thay vì để một reviewer con người nhớ và nhắc lại thủ công.

Vì sao đáng đầu tư thời gian này thay vì chuyển hẳn sang công cụ khác

Một dev khác từng trả tiền dùng song song cả Claude Code và Cursor suốt hai tuần, chạy cùng sáu tác vụ lặp lại hằng ngày trên cả hai công cụ để so sánh trực tiếp. Kết quả cá nhân của anh: đến ngày thứ mười lăm, anh hủy đăng ký Cursor và không thấy tiếc. Bản thân anh cũng lưu ý framing "công cụ nào tốt hơn" là câu hỏi không có đáp án chung, vì "tốt hơn" phụ thuộc vào chính workflow của từng người — điều anh chia sẻ chỉ là sáu tác vụ cụ thể anh làm mỗi ngày và công cụ nào xử lý chúng theo cách anh cần.

Điểm rút ra không phải "Claude Code luôn thắng Cursor" — mà là: nếu bạn đã chọn gắn bó với một công cụ agentic đủ lâu để nó hiểu ngữ cảnh dự án, khoản đầu tư hợp lý tiếp theo là dạy nó quy ước riêng của team, chứ không phải đổi công cụ liên tục.

Việc cần làm tiếp theo

Nếu team bạn đang dùng Claude Code hàng ngày, thử viết một skill review cấu trúc cho đúng ba câu hỏi ở trên trước khi mở rộng sang các quy ước phức tạp hơn (naming convention, quy tắc test coverage). Theo dõi thêm cách cộng đồng chia sẻ skill cho các stack khác ngoài SvelteKit — đây vẫn là mảng còn thiếu tài liệu chuẩn hóa, nên kinh nghiệm thực chiến từ chính team bạn có giá trị hơn một template có sẵn.

#code review

Claude Code Skill: Tự Động Review Cấu Trúc Dự Án Cho Team

#code review

Claude Code Skill: Tự Động Review Cấu Trúc Dự Án Cho Team