CLAUDE.md và DESIGN.md: hai tờ hướng dẫn giúp Claude Code làm đúng ý ngay lần đầu

Bạn nhờ Claude Code dựng một trang web, nó làm nhanh nhưng màu mè lạ hoắc, chạy sai lệnh build, lại sửa lung tung những file không liên quan. Nguyên nhân thường không nằm ở AI mà ở chỗ nó không có "tờ hướng dẫn" nào về dự án của bạn. Bài này chỉ bạn cách viết hai file nhỏ đặt ở gốc dự án, CLAUDE.md và DESIGN.md, mất khoảng 30 phút, và từ đó Claude làm đúng ý ngay từ lần đầu thay vì phải sửa tới sửa lui.

Hai file này là văn bản markdown bình thường (file chữ có dấu # làm tiêu đề). Claude Code tự đọc chúng khi làm việc, giống một nhân viên mới đọc sổ tay công ty trước khi bắt tay vào việc. Nếu bạn chưa quen Claude Code, hãy đọc trước bài Claude Code là gì và cách cài đặt từ A đến Z.

Chuẩn bị

• Claude Code đã cài trên máy, và một thư mục dự án (mới tạo hoặc đang làm dở).
• Một trình soạn thảo bất kỳ để tạo file chữ (VS Code, Notepad, TextEdit đều được).
• 30 phút để trả lời vài câu hỏi về dự án: nó là gì, chạy bằng lệnh nào, bạn muốn nó trông ra sao.

Ý tưởng cốt lõi là chia đôi vai trò:

Tách ra như vậy giúp mỗi file ngắn gọn, đúng việc, và không nhồi mọi thứ vào một chỗ.

Làm từng bước

Bước 1: Viết CLAUDE.md với 6 mục

Tạo file CLAUDE.md ở thư mục gốc dự án, rồi điền sáu mục sau:

1. Tổng quan dự án: một câu nói Claude đang làm gì. Ví dụ: "Bảng thống kê quảng cáo Facebook, dùng Next.js, TypeScript, Tailwind".
2. Lệnh: cách chạy thử, kiểm tra, đóng gói. Ghi rõ để Claude không phải đoán hay chạy nhầm lệnh.
3. Kiến trúc và file quan trọng: thư mục nào chứa trang, chứa thành phần giao diện, chứa phần gọi dữ liệu, để Claude sửa đúng chỗ.
4. Quy tắc viết code: 5 đến 10 nguyên tắc nền, ví dụ "file mới đều viết bằng TypeScript", "ưu tiên dùng lại thành phần có sẵn thay vì tạo mới".
5. Quy trình và kiểm chứng: các bước khi thay đổi (đọc code đang có, làm theo cách cũ, chạy kiểm tra), để Claude tự soát lỗi trước khi báo xong.
6. Chỉ dẫn thiết kế: một dòng bảo Claude đọc DESIGN.md khi đụng tới giao diện.

Muốn hiểu sâu vì sao file này mạnh, xem bài CLAUDE.md, file duy nhất biến Claude Code thành trợ lý hiểu dự án của bạn.

Bước 2: Mượn hai kiểu CLAUDE.md có sẵn

Bạn không cần viết từ con số không. Có hai kiểu mẫu rất phổ biến, bổ sung cho nhau.

Kiểu 1: nắn cách Claude cư xử. Bản nổi tiếng nhất là "Karpathy CLAUDE.md" trong repo multica-ai/andrej-karpathy-skills trên GitHub, được cộng đồng chia sẻ rất rộng. Phần cốt lõi ngắn gọn thế này:

# CLAUDE.md
Behavioral guidelines to reduce common LLM coding mistakes.

## 1. Think Before Coding
- State your assumptions explicitly. If uncertain, ask.
- If multiple interpretations exist, present them, don't pick silently.

## 2. Simplicity First
- No features beyond what was asked.
- If you write 200 lines and it could be 50, rewrite it.

## 3. Surgical Changes
- Don't "improve" adjacent code or refactor things that aren't broken.
- Match existing style. Every changed line should trace to the request.

## 4. Goal-Driven Execution
- "Fix the bug" becomes "Write a test that reproduces it, then make it pass".

Dịch nôm na: nghĩ trước khi viết, làm đơn giản nhất có thể, chỉ sửa đúng chỗ cần sửa, và đặt tiêu chí thành công rồi kiểm tra tới khi đạt. Bài file CLAUDE.md của Karpathy và 4 luật giúp AI code ít sai giải thích từng luật.

Kiểu 2: nắn cách Claude làm việc. Kiểu này ghi lại quy trình bạn muốn: chia việc cho trợ lý phụ (subagent) để đầu óc chính đỡ rối, tự ghi lại bài học sau mỗi lần bị sửa, luôn kiểm chứng trước khi báo xong, tự sửa lỗi không cần cầm tay chỉ việc:

# Workflow Orchestration

## Don't repeat past mistakes
Read all the lessons learned from tasks/ and avoid those mistakes.

## Self-Improvement Loop
- After ANY correction from the user: update tasks/lessons.md with the pattern
- Review lessons at session start

## Verification Before Done
- Never mark a task complete without proving it works
- Ask yourself: "Would a staff engineer approve this?"

## Core Principles
- Simplicity First: make every change as simple as possible.
- Minimal Impact: only touch what's necessary.

Bạn có thể ghép cả hai vào cùng một file: phần hành vi ở trên, phần quy trình ở dưới. Muốn xem một CLAUDE.md gắn với dự án thật do kỹ sư Anthropic viết, mở repo mẫu anthropics/anthropic-quickstarts trên GitHub.

Bước 3: Viết DESIGN.md với 9 mục

Tạo file DESIGN.md cũng ở thư mục gốc. Chín mục nên có:

1. Hướng thiết kế: tả bằng đặc điểm nhìn thấy được ("gọn, dễ lướt mắt") thay vì lời chung chung ("làm cho đẹp").
2. Nguyên tắc thị giác: ví dụ "dùng nền phẳng, không gradient trang trí", "dùng viền và khoảng trắng thay vì đổ bóng đậm".
3. Bộ thông số thiết kế (design tokens): vai trò của từng màu, kiểu chữ, độ bo góc, cỡ icon. Nếu đã có file thông số dài, chỉ cần ghi nó nằm ở đâu.
4. Bố cục: kiểu menu, bề rộng tối đa của trang, cách xếp lại trên điện thoại.
5. Thành phần mẫu: nút bấm, thẻ, bảng trông thế nào và dùng khi nào.
6. Chuyển động: hiệu ứng nhanh khoảng 150 đến 250 mili giây, tôn trọng người dùng đã tắt hiệu ứng động trong máy.
7. Hiển thị trên nhiều màn hình: bố cục thay đổi ra sao từ máy tính xuống điện thoại.
8. Dễ tiếp cận: chữ đủ tương phản để dễ đọc, dùng được bằng bàn phím, ô nhập có nhãn.
9. Điều cấm: ghi thẳng những thứ không muốn thấy, ví dụ "không gradient thừa", "không hiệu ứng kính mờ trừ khi được yêu cầu", "không dùng emoji làm icon sản phẩm". Mục này giúp tránh vẻ "nhạt nhòa kiểu AI" rất hay gặp.

Bước 4: Lười viết DESIGN.md? Tải bản dựng sẵn

Nếu bạn chưa có phong cách riêng, có hai kho DESIGN.md miễn phí để bắt đầu:

• getdesign.md: bộ DESIGN.md chắt lọc từ hơn 70 thương hiệu lớn như Stripe, Linear, Notion, Apple. Cài vào dự án bằng một lệnh:

npx getdesign@latest add stripe

• styles.refero.design: thư viện hơn 2.000 phong cách rút từ các trang sản phẩm thật, duyệt được theo "chất" thiết kế (Cyber Neon, Cinematic Dark, Monospace UI, Industrial) chứ không chỉ theo tên thương hiệu. Hợp khi bạn chỉ có cảm giác mơ hồ kiểu "tối, đậm chất điện ảnh". Lúc bài này được viết, trang đang ở bản thử nghiệm và cho tải miễn phí.

Tải về, đặt file vào gốc dự án, rồi nói với Claude Code: "Dựng trang theo phong cách trong DESIGN.md". Bạn có thể dùng nguyên bản hoặc chỉnh lại màu và chữ cho hợp thương hiệu của mình.

Bước 5: Chỉ nạp DESIGN.md khi cần

Đừng nhúng thẳng DESIGN.md vào CLAUDE.md (kiểu viết @DESIGN.md). Làm vậy thì phần thiết kế bị nạp mọi lúc, kể cả khi Claude đang sửa phần xử lý dữ liệu chẳng liên quan gì tới giao diện, tốn "bộ nhớ làm việc" của AI vô ích (xem thêm context window là gì). Thay vào đó, ghi trong CLAUDE.md một câu có điều kiện:

Với bất kỳ việc nào chạm tới giao diện, màu sắc, tương tác,
khả năng tiếp cận hay hiển thị trên điện thoại,
hãy đọc DESIGN.md trước khi làm.

Chỉ nhúng thẳng khi dự án gần như toàn là giao diện và tài liệu thiết kế ngắn.

Kết quả mẫu

Thư mục dự án sau khi làm xong trông thế này:

project/
├── CLAUDE.md
├── DESIGN.md
├── README.md
├── package.json
├── src/
│   ├── app/
│   ├── components/
│   └── styles/
└── docs/

Bạn gõ "Thêm trang báo cáo tuần", Claude Code tự đọc CLAUDE.md để biết đặt file ở đâu, chạy lệnh kiểm tra nào, rồi thấy việc này chạm tới giao diện nên mở DESIGN.md để dùng đúng màu, đúng kiểu thẻ, đúng khoảng cách. Kết quả ra đồng bộ với phần còn lại của sản phẩm ngay lần đầu.

Mẹo để kết quả tốt hơn

• Tả điều quan sát được. "Làm cho đẹp" không hành động được. "Chữ tối trên nền sáng, mỗi thẻ cách nhau 16 điểm ảnh" thì làm được ngay.
• Viết điều cấm. Ghi rõ điều KHÔNG nên làm quan trọng không kém điều nên làm.
• Cập nhật sau mỗi lần sửa. Mỗi khi phải nhắc Claude cùng một lỗi lần thứ hai, thêm một dòng vào CLAUDE.md.
• Giữ ngắn. Một CLAUDE.md dưới 100 dòng thường hiệu quả hơn một bản dài lê thê.

Giới hạn cần biết

• Đừng nhồi thông số. Chép cả file màu sắc dài vào DESIGN.md chỉ làm phình ngữ cảnh, hãy trỏ tới chỗ chứa nó.
• Tài liệu dài làm AI phân tâm. Thứ gì nằm trong ngữ cảnh thường trực cũng chiếm sức xử lý, kể cả khi không liên quan.
• File không thay được việc kiểm tra. Claude vẫn có thể hiểu sai. Bạn vẫn cần xem lại kết quả, nhất là với giao diện người dùng thật.
• Phong cách tải sẵn là điểm khởi đầu. Dùng nguyên bản của một thương hiệu lớn cho sản phẩm thương mại thì nên chỉnh lại để có dấu ấn riêng.

Câu hỏi thường gặp

Không biết code có viết được CLAUDE.md không? Được. Đó chỉ là văn bản thường. Bạn còn có thể nhờ chính Claude Code soạn bản đầu bằng lệnh /init, rồi sửa lại cho đúng ý.

Có bắt buộc phải có DESIGN.md không? Không. Dự án không có giao diện (chỉ là script chạy nền) thì CLAUDE.md là đủ. Có giao diện thì nên có, để tránh vẻ nhạt nhòa mặc định của AI.

Đặt hai file ở đâu? Ở thư mục gốc của dự án, cùng chỗ với README.md. Claude Code tự tìm thấy CLAUDE.md ở đó.

Nên chọn mẫu Karpathy hay mẫu quy trình? Dùng cả hai. Mẫu Karpathy dạy Claude cư xử cẩn thận khi sửa code, mẫu quy trình dạy Claude làm việc có kỷ luật. Chúng không giẫm chân nhau.

DESIGN.md tải từ getdesign.md có dùng cho Cursor hay công cụ khác được không? Được. Đó là file chữ thường, công cụ AI nào đọc được file trong dự án đều dùng được.

#claudecode #claudemd #designmd #vibecoding #aicoding