Lần đầu tiên một designer mới tiếp cận AI dùng Claude Code để dựng trang web, nó tạo ra một giao diện với bo góc 12px, button primary màu xanh dương và font Inter. Trong khi đó, hệ thống thiết kế (design system) yêu cầu chuẩn quy định bo góc 4px, button primary màu xanh lá đậm và phông Manrope.
Giao diện Claude làm ra chẳng có lỗi gì cả. Chỉ là nó không hề biết sản phẩm cần trông như thế nào — vì đơn giản là chưa ai nói cho nó biết. Đó chính là lý do file thiết kế CLAUDE.md ra đời.
Mỗi khi bắt đầu một phiên làm việc mới, Claude Code sẽ “xóa sạch bộ nhớ”. Chỉ có hai thứ giúp nó giữ lại kiến thức qua các phiên: Các file CLAUDE.md do bạn tự viết và các ghi chú tự động do Claude tự lưu. File thiết kế chính là phương án đầu tiên. Bạn tự tay viết nó để giải thích cho Claude hiểu sản phẩm của mình trông ra sao và hoạt động thế nào — trước khi nó sinh ra dù chỉ một dòng code giao diện.
Bài viết này sẽ hướng dẫn bạn thiết lập file này từ con số 0. Tất cả những gì bạn cần là đã cài sẵn Claude Code và mở thư mục dự án của mình.
Bản chất của file CLAUDE.md là gì?
CLAUDE.md thực chất là một file Markdown văn bản. Claude Code sẽ tự động đọc file này ngay khi bắt đầu phiên làm việc. File có thể nằm ngay ở thư mục gốc (root) của dự án hoặc bên trong thư mục .claude/. Ngoài ra còn có:
– Phiên bản toàn cục (user-level): Đặt tại ~/.claude/CLAUDE.md — áp dụng cho mọi dự án trên máy tính của bạn.
– Thư mục quy tắc phụ: .claude/rules/ — nơi bạn có thể chia nhỏ hướng dẫn thành các file chủ đề riêng biệt.
Lưu ý quan trọng: Claude coi các file này là bối cảnh tham khảo chứ không phải quy tắc bắt buộc tuyệt đối. Nếu bạn viết “không bao giờ dùng inline style”, Claude sẽ tuân thủ hầu hết thời gian, nhưng đó vẫn chỉ là định hướng. Những gì bắt buộc phải chặn 100% thì nên đưa vào linter, test hoặc hook. File thiết kế dùng cho các yếu tố “mềm” hơn — và thực tế thì hầu hết thiết kế đều nằm ở phần “mềm” này.
Tài liệu hướng dẫn của Anthropic nhấn mạnh rằng: Hướng dẫn càng ngắn gọn, cụ thể thì AI càng thực thi chính xác. Đừng dại bê nguyên cả thư viện tài liệu Figma vào đây. Hãy lọc ra những gì thực sự cần thiết.
Bước 1: Tạo file
Mở terminal tại thư mục gốc của dự án và gõ lệnh claude. Khi phiên làm việc bắt đầu, gõ tiếp /init. Claude sẽ quét qua toàn bộ codebase và tự sinh ra một file CLAUDE.md khung dựa trên những gì nó đọc được (framework, bộ quản lý gói, cấu trúc thư mục…). File tự động này thường nghiêng về kỹ thuật lập trình chứ chưa có thiết kế. Bạn có thể bổ sung phần thiết kế vào ngay file đó, hoặc tạo riêng một file .claude/rules/design.md.
Mẹo: Với team 4–5 người, việc tách riêng file thiết kế sẽ giúp designer dễ dàng quản lý mà không đụng chạm đến phần ghi chú của developer.
Bước 2: Khai báo Design Tokens (Thông số thiết kế)
Hãy bắt đầu bằng các giá trị cốt lõi: màu sắc, typography, khoảng cách (spacing), bo góc (radius), đổ bóng (shadow). Đây là những thứ Claude hay làm sai nhất vì nếu không chỉ rõ, nó sẽ tự dùng các giá trị mặc định của Tailwind (màu xanh dương nhạt và khoảng cách 8px cho mọi thứ).
Một đoạn Design Tokens tối giản sẽ trông như thế này:
## Design Tokens
### Colors
- Primary: #1B4D3E (dùng cho button, link, trạng thái active)
- Surface: #FAFAF8 (màu nền trang)
- Text primary: #1A1A1A
- Text secondary: #6B6B6B
- Error: #C0392B
### Typography
- Font: Manrope cho tiêu đề (heading), Inter cho văn bản (body)
- Scale: 32 / 24 / 20 / 16 / 14 (px)
- Line height: 1.5 cho body, 1.2 cho heading
### Spacing
- Base unit: 4px
- Multiples: 4, 8, 12, 16, 24, 32, 48
### Radius
- Default: 4px
- Cards & Modals: 8px
- Pills & Avatars: full
Mẹo nâng cao: Nếu dự án đã có sẵn file chứa token (như tokens.css hoặc config của Tailwind), đừng chép lại. Hãy dùng cú pháp import để trỏ trực tiếp đến file đó: @src/styles/tokens.css. Claude sẽ tự đọc khi nạp CLAUDE.md. Cách này giữ cho dữ liệu luôn đồng nhất — khi Lead Designer đổi màu chủ đạo, không ai phải nhớ đi cập nhật lại file markdown nữa.
Bước 3: Đặt tên và định nghĩa Component
Lỗi phổ biến thứ hai của Claude là “chế” lại các component đã có sẵn. Nó sẵn sàng tự viết một cái dropdown mới tinh trong khi bạn đã có sẵn component Select xịn xò trong dự án. Hãy liệt kê chúng ra — không cần tất cả, chỉ cần những component dùng liên tục hoặc hay bị dùng sai:
## Components
Luôn ưu tiên dùng component có sẵn trong `src/components/ui/` trước khi viết mới.
- Button: các variant chuẩn gồm primary, secondary, ghost, destructive. Không tự thêm variant mới nếu chưa hỏi.
- Input, Select, Checkbox, Radio: nằm tại `src/components/ui/form/`
- Modal: chỉ dùng cho xác nhận ngắn (confirmation). Form từ 2 trường trở lên bắt buộc dùng Drawer.
- Toast: dùng cho thông báo thành công (success) hoặc thông tin (info). Lỗi chặn thao tác người dùng phải dùng Alert nằm inline, không dùng Toast.
Bước 4: Thêm các quy tắc tương tác (Interaction Rules)
Đây là phần quan trọng nhất tạo nên chất lượng sản phẩm nhưng lại hay bị bỏ qua nhất. Token và Component chỉ nói lên giao diện trông như thế nào, còn phần này định nghĩa giao diện vận hành ra sao.
Ví dụ thực tế từ một file chuẩn:
## Interaction Rules
- Mọi form đều phải có label rõ ràng. Placeholder không được tính là label.
- Hành động nguy hiểm (xóa, hủy đăng ký) bắt buộc phải có bước xác nhận.
- Trạng thái tải (loading): Dùng Skeleton screen cho nội dung, chỉ dùng Spinner cho nút bấm.
- Trạng thái rỗng (empty state): Phải kèm theo 1 nút hành động chính, không chỉ để mỗi hình minh họa.
- Không dùng hiệu ứng chỉ xuất hiện khi hover. Mọi thứ phải hoạt động mượt mà trên màn hình cảm ứng (touch).
- Thiết kế Mobile-first: Dựng layout chuẩn từ kích thước 375px trước, sau đó mới mở rộng ra desktop.
Tiêu chí đánh giá quy tắc: Nếu một lựa chọn thiết kế có thể đi theo 2 hướng trái ngược nhau, và team bạn đã chốt chọn 1 hướng — hãy ghi nó vào. Ngược lại, những nguyên lý quá chung chung mà AI hiển nhiên sẽ làm đúng thì nên bỏ qua để tiết kiệm “dung lượng bộ nhớ” (context window) của Claude.
Bước 5: Bắt buộc quy chuẩn Accessibility (Khả năng truy cập)
Claude mặc định xử lý accessibility ở mức “tạm ổn”, nhưng “tạm ổn” thì chưa đủ chuẩn để đưa lên sản phẩm thật. Hãy thiết lập một “mức sàn” bắt buộc:
## Accessibility
- Đạt chuẩn tối thiểu WCAG 2.2 AA.
- Độ tương phản màu (contrast): Tối thiểu 4.5:1 cho văn bản thường, 3:1 cho văn bản lớn và phần tử UI.
- Mọi phần tử tương tác phải thao tác được bằng bàn phím và có viền viền viền viền nhận diện (focus ring) rõ ràng. Dùng token `focus-ring`, cấm xóa outline.
- Nút chỉ chứa icon (Icon-only button) bắt buộc phải có `aria-label`.
- Không biểu thị trạng thái chỉ bằng màu sắc. Phải kết hợp thêm icon hoặc văn bản.
Bước 6: Danh sách “Những việc CẤM làm” (Do Not)
Các quy tắc mang tính phủ định cực kỳ hiệu quả trong CLAUDE.md vì chúng rõ ràng và không gây mơ hồ.
## Do Not
- Không tự ý cài thêm thư viện UI mới. Chỉ dùng component nội bộ + Radix primitives.
- Không dùng inline styles hoặc các giá trị Tailwind tùy biến kiểu `w-[347px]`.
- Không dùng emoji trong văn bản giao diện (UI copy).
- Không thêm hiệu ứng chuyển động (animation) dài hơn 200ms khi chưa duyệt với team design.
- Không tự tạo màu mới. Nếu màu không có trong tokens, hãy hỏi lại designer.
Bước 7: Kiểm tra các file đã được nạp
Chạy lệnh /memory trong phiên Claude Code. Hệ thống sẽ hiển thị toàn bộ file quy tắc và ghi chú đang hoạt động. Đây là cách để bạn đảm bảo file CLAUDE.md của mình thực sự được Claude đọc chứ không nằm sai vị trí.
Bước 8: Thử nghiệm với một task thực tế
Hãy thử giao cho Claude dựng một màn hình nhỏ: một form đăng nhập, một card cài đặt, hoặc một màn hình empty state. Sau đó đánh giá kết quả như cách bạn review bài của một bạn Junior Designer:
– Nó có dùng đúng màu chủ đạo không?
– Nó có gọi component Button có sẵn ra dùng không?
– Màn hình rỗng có nút bấm hành động không?
– Viền focus khi bấm Tab có hiển thị không?
Mỗi điểm Claude làm sai chính là gợi ý để bạn bổ sung hoặc viết lại quy tắc trong file CLAUDE.md cho sắc bén hơn.
Mẹo giữ cho file luôn “Sống”
Một file thiết kế viết xong rồi bỏ xó sẽ trở nên lỗi thời chỉ sau một tháng. Cách tốt nhất để duy trì là biến nó thành một phần trong quy trình làm việc: Mỗi khi team design chốt một quyết định mới trong buổi review, bước cuối cùng là ghi quyết định đó vào CLAUDE.md.
Quy tắc vàng: Khi Claude làm sai cùng một lỗi đến lần thứ 2 — đó chính là tín hiệu bắt buộc bạn phải viết thêm quy tắc vào file. Lần 1 có thể là ngẫu nhiên, nhưng lần 2 đã là một “lỗ hổng” cần vá.
Lời kết
File CLAUDE.md không nhằm mục đích biến Claude thành một designer chuyên nghiệp. Mạch sống của file này là biến các quyết định thiết kế mà team bạn đã thống nhất từ nhiều tháng trước thành tri thức cho AI, giúp nó không phải tự “đoán mò” nữa.
