CLAUDE.md Mastery — Tối ưu workspace cho Claude Code

CLAUDE.md là file quan trọng nhất khi làm việc với Claude Code. Nó hoạt động như một bản "hướng dẫn nội bộ" mà Claude Code đọc mỗi khi khởi động, giúp AI hiểu sâu về dự án của bạn mà không cần bạn lặp lại context mỗi phiên làm việc. Nếu bạn đang dùng Claude Code mà chưa tạo CLAUDE.md, bạn đang bỏ lỡ cơ hội tăng năng suất đáng kể.

CLAUDE.md là gì?

CLAUDE.md là file Markdown mà Claude Code tự động phát hiện và đọc khi bạn mở một phiên làm việc trong terminal. Nội dung file này được đưa vào system context, có nghĩa là mọi câu lệnh bạn gửi cho Claude Code đều được xử lý trong bối cảnh đã được cung cấp bởi CLAUDE.md.

Điểm khác biệt so với việc paste context thủ công: CLAUDE.md được lưu trong codebase, version-controlled cùng code, và chia sẻ giữa các thành viên trong team. Khi thành viên mới join dự án, họ tự động nhận được cùng một bộ hướng dẫn mà không cần ai giải thích.

Claude Code tìm file này theo một hệ thống phân cấp rõ ràng, cho phép bạn cấu hình ở nhiều mức độ khác nhau tùy nhu cầu.

Hệ thống phân cấp: Project vs User vs Subdirectory

Claude Code hỗ trợ ba cấp độ CLAUDE.md, mỗi cấp phục vụ mục đích riêng:

Project-level CLAUDE.md

Đặt tại thư mục gốc của dự án, cùng cấp với thư mục .git. Đây là file được sử dụng phổ biến nhất và chứa thông tin đặc thù của dự án.

Vị trí: /your-project/CLAUDE.md

Nội dung phù hợp: tech stack, kiến trúc, coding conventions, lệnh build và test, quy trình phát triển, danh sách các điều cấm.

User-level CLAUDE.md

Đặt trong thư mục cấu hình Claude của người dùng. Áp dụng cho mọi dự án mà bạn làm việc trên máy.

Vị trí: ~/.claude/CLAUDE.md

Nội dung phù hợp: style cá nhân, ngôn ngữ ưu tiên (ví dụ "luôn trả lời bằng tiếng Việt"), preferences về cách trình bày code, các quy tắc bạn muốn áp dụng xuyên suốt dù đang làm dự án nào.

Subdirectory-level CLAUDE.md

Đặt trong các thư mục con của dự án. Phù hợp cho monorepo hoặc dự án lớn có nhiều module với conventions khác nhau.

Vị trí: /your-project/packages/api/CLAUDE.md

Nội dung phù hợp: quy tắc riêng cho module cụ thể, patterns đặc thù, dependencies nội bộ.

Cách Claude Code kết hợp các cấp

Khi có nhiều file CLAUDE.md, Claude Code đọc tất cả và kết hợp chúng. Không có file nào bị ghi đè hoàn toàn. User-level cung cấp nền tảng chung, project-level bổ sung context dự án, và subdirectory-level thêm chi tiết khi bạn làm việc trong thư mục con cụ thể. Nếu có mâu thuẫn, file gần nhất với vị trí làm việc hiện tại được ưu tiên.

Cấu trúc CLAUDE.md hiệu quả

Một file CLAUDE.md tốt không phải là liệt kê mọi thứ về dự án. Nó cần ngắn gọn, có cấu trúc rõ ràng, và tập trung vào những thông tin mà Claude Code cần để làm việc chính xác.

Phần 1: Mô tả dự án

Hai đến ba câu mô tả dự án là gì, phục vụ ai, và dùng tech stack gì. Phần này giúp Claude Code hiểu bối cảnh tổng thể.

# CLAUDE.md

## Project Overview
Ứng dụng quản lý kho hàng cho các shop bán lẻ tại Việt Nam.
Tech stack: Next.js 14, TypeScript, PostgreSQL, Prisma ORM.
Target: Chủ shop vừa và nhỏ, 100-5000 SKU.
Ngôn ngữ UI: tiếng Việt. Code comments: tiếng Anh.

Phần 2: Coding Standards

Liệt kê các quy tắc coding cụ thể. Tránh viết chung chung như "viết code sạch" vì Claude Code đã hiểu nguyên tắc cơ bản. Tập trung vào những conventions đặc thù của dự án bạn.

## Coding Standards
- TypeScript strict mode bắt buộc, không dùng `any`
- Function components + hooks, không class components
- Tên file: kebab-case (user-profile.tsx)
- Tên component: PascalCase (UserProfile)
- Mỗi component một file, test co-located cùng thư mục
- Error handling: custom error classes kế thừa AppError
- Import order: external > internal > relative, tách bằng dòng trống
- Named exports mặc định, chỉ default export cho pages

Phần 3: Các lệnh thường dùng

Claude Code sẽ sử dụng đúng lệnh thay vì đoán. Phần này đặc biệt quan trọng vì mỗi dự án có cấu hình khác nhau (npm vs pnpm vs yarn, jest vs vitest, etc.).

## Common Commands
- Dev server: `pnpm dev`
- Build production: `pnpm build`
- Run all tests: `pnpm test`
- Run single test: `pnpm test -- path/to/file.test.ts`
- Lint and fix: `pnpm lint:fix`
- Type check: `pnpm typecheck`
- Database migration: `pnpm prisma migrate dev`
- Seed database: `pnpm prisma db seed`
- Generate Prisma client: `pnpm prisma generate`

Phần 4: Kiến trúc dự án

Mô tả cấu trúc thư mục và vai trò của từng phần. Giúp Claude Code biết đặt code mới ở đâu và không tạo file ở vị trí sai.

## Architecture
src/
  app/          -- Next.js App Router pages và layouts
  components/   -- UI components tái sử dụng (Radix UI based)
  features/     -- Feature modules, mỗi feature chứa components + hooks + utils
  lib/          -- Utilities dùng chung, API clients, constants
  server/       -- Server-side: tRPC routers, services, repositories
  types/        -- TypeScript interfaces và types dùng chung

Key patterns:
- Server Components mặc định, chỉ 'use client' khi cần interactivity
- Data fetching qua tRPC, không gọi Prisma trực tiếp từ components
- Client state: Zustand. Server state: tRPC cache với React Query

Phần 5: Danh sách cấm

Ghi rõ những điều Claude Code tuyệt đối không được làm. Negative instructions thường hiệu quả hơn positive instructions vì chúng ngăn ngừa lỗi cụ thể.

## Do NOT
- NEVER modify files in src/generated/ -- auto-generated bởi Prisma
- NEVER commit .env files hoặc hardcode API keys
- NEVER dùng React.FC type annotation
- NEVER tạo barrel exports (index.ts re-export)
- ALWAYS chạy pnpm typecheck trước khi báo hoàn thành
- ALWAYS thêm rate limiting cho API routes mới

Ví dụ CLAUDE.md cho dự án Node.js Backend

Dự án API backend có yêu cầu khác với frontend. CLAUDE.md cần tập trung vào API conventions, database patterns, và testing strategy.

# CLAUDE.md — Order Management API

## Overview
REST API quản lý đơn hàng, phục vụ 50K+ requests/ngày.
Runtime: Node.js 20. Framework: Fastify. DB: PostgreSQL 16. ORM: Drizzle.

## Coding Standards
- Strict TypeScript, không dùng `any` hoặc `as` type assertions
- Zod schemas cho mọi request/response validation
- Pattern: controllers > services > repositories
- Async functions bắt buộc try-catch với custom error types
- Dependency injection qua fastify-awilix

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Single test: `pnpm test -- --grep "test name"`
- Generate migration: `pnpm drizzle-kit generate`
- Apply migration: `pnpm drizzle-kit migrate`

## API Conventions
- Routes versioned: /api/v1/...
- Response: { success: boolean, data?: T, error?: { code, message } }
- Pagination: cursor-based, default 20, max 100
- Auth: JWT trong Authorization header
- Rate limit: 100 req/min per user, 1000 req/min per IP

## Testing
- Unit: vitest, co-located cùng source files
- Integration: __tests__/integration/, dùng test database
- Coverage tối thiểu: 80% services, 60% controllers

Ví dụ CLAUDE.md cho dự án Python ML

Dự án machine learning cần ghi rõ environment setup, data handling rules, và experiment tracking.

# CLAUDE.md — Vietnamese NLP Pipeline

## Overview
Pipeline xử lý ngôn ngữ tự nhiên tiếng Việt: tokenization,
NER, sentiment analysis. PyTorch + Hugging Face Transformers.

## Environment
- Python 3.11, managed by pyenv
- Install: pip install -e ".[dev]"
- GPU required cho training, CPU ok cho inference

## Code Style
- PEP 8 enforced by ruff
- Type hints bắt buộc cho public functions
- Docstrings: Google style (Args, Returns, Raises)
- Max line: 100 chars
- Dùng pathlib.Path thay os.path

## Commands
- Train: `python -m src.train --config configs/ner.yaml`
- Evaluate: `python -m src.evaluate --checkpoint outputs/latest`
- Test: `pytest tests/ -v`
- Lint: `ruff check src/`
- Format: `ruff format src/`

## Data Rules
- Raw data: data/raw/ -- NEVER modify trực tiếp
- Processed: data/processed/
- Models: outputs/ với timestamp
- NEVER commit data files hoặc model weights
- Dùng DVC cho data versioning
- Vietnamese tokenization: underthesea
- Experiments: log vào Weights and Biases

Ví dụ CLAUDE.md cho dự án React Frontend

Frontend projects cần ghi rõ component guidelines, styling approach, và state management patterns.

# CLAUDE.md — E-commerce Admin Dashboard

## Overview
Dashboard quản trị cho sàn thương mại điện tử.
React 18, TypeScript, Vite, TanStack Query, Tailwind CSS.

## Structure
src/
  pages/        -- Route pages, lazy loaded
  components/   -- Shared UI components
  features/     -- Feature-based modules
  hooks/        -- Custom hooks (prefix: use-)
  api/          -- API client, endpoint definitions
  utils/        -- Pure utility functions
  types/        -- TypeScript interfaces

## Standards
- Functional components, không class components
- Tailwind cho styling, không inline styles, không CSS modules
- Forms: react-hook-form + zod validation
- Tables: TanStack Table, server-side pagination
- Không prop drilling quá 2 levels, dùng context hoặc Zustand

## Commands
- Dev: `pnpm dev`
- Build: `pnpm build`
- Test: `pnpm test`
- Storybook: `pnpm storybook`

## Component Rules
- Props interface: ComponentNameProps
- Destructure props trong function signature
- forwardRef cho components nhận ref
- useMemo cho expensive computations
- useCallback cho callbacks truyền xuống children

Anti-patterns cần tránh

Sau khi biết cách viết CLAUDE.md đúng, cần nhận diện các anti-patterns phổ biến để không mắc phải:

1. File quá dài không có cấu trúc

CLAUDE.md dài hàng trăm dòng không có heading rõ ràng khiến Claude Code khó trích xuất thông tin. Giữ file dưới 200 dòng, dùng Markdown headings phân cấp, sắp xếp thông tin theo mức độ quan trọng giảm dần.

2. Nội dung quá chung chung

Viết "follow best practices" hay "write clean code" không có giá trị vì Claude Code đã biết những nguyên tắc này. Bạn cần viết cụ thể: "dùng Zod cho validation, không manual type checking" thay vì "validate inputs properly".

3. Mâu thuẫn giữa các phần

Phần trên ghi dùng default export, phần dưới lại nói dùng named export. Claude Code sẽ bị nhầm lẫn và output không nhất quán. Review toàn bộ file để đảm bảo tính thống nhất. Nếu có ngoại lệ, ghi rõ trường hợp nào áp dụng quy tắc nào.

4. Thông tin lỗi thời

CLAUDE.md ghi lệnh npm run build nhưng dự án đã chuyển sang pnpm từ 6 tháng trước. File lỗi thời gây ra nhiều vấn đề hơn là không có file. Đưa việc review CLAUDE.md vào quy trình sprint review hoặc khi thay đổi tooling.

5. Copy-paste nguyên file từ dự án khác

Mỗi dự án có đặc thù riêng. Copy CLAUDE.md từ dự án Node.js sang dự án Python sẽ gây nhầm lẫn nghiêm trọng. Bạn có thể tham khảo cấu trúc nhưng phải viết lại nội dung phản ánh đúng dự án hiện tại.

6. Thiếu ví dụ cụ thể

Nói "follow naming conventions" mà không minh họa. Luôn kèm ví dụ: "Files: kebab-case (user-profile.tsx), Components: PascalCase (UserProfile), hooks: camelCase có prefix (useUserProfile)".

Kỹ thuật nâng cao từ Boris Cherny

Boris Cherny, tác giả cuốn Programming TypeScript (O'Reilly), đã chia sẻ nhiều kỹ thuật thiết lập CLAUDE.md cho các dự án phức tạp. Dưới đây là những insight đáng học hỏi nhất.

Layered context strategy

Thay vì nhồi mọi thứ vào một file duy nhất, Boris sử dụng hệ thống phân tầng. User-level chứa preferences cá nhân và style chung. Project root chứa architecture overview cùng conventions của toàn bộ dự án. Package-level chứa quy tắc riêng cho từng package trong monorepo.

Mỗi file CLAUDE.md chỉ dài 30-80 dòng, dễ đọc và dễ maintain. Claude Code vẫn nhận đủ context vì nó đọc và kết hợp tất cả các file cùng lúc.

Executable documentation

Boris khuyến nghị CLAUDE.md chứa các lệnh chạy được thay vì mô tả trừu tượng. Thay vì viết "chạy tests trước khi commit", hãy ghi lệnh cụ thể cùng giải thích khi nào và tại sao cần chạy. Claude Code có thể thực thi trực tiếp các lệnh này mà không cần suy luận thêm.

Negative instructions

Ghi rõ những điều Claude Code KHÔNG ĐƯỢC làm thường hiệu quả hơn chỉ nói nên làm gì. Lý do: positive instructions mở ra không gian giải thích rộng, trong khi negative instructions đặt ranh giới cứng.

## Do NOT
- Do not create new files trong src/generated/
- Do not dùng React.FC type annotation
- Do not thêm comments giải thích code hiển nhiên
- Do not tạo barrel exports (index.ts re-exports)
- Do not install dependencies mới khi chưa hỏi ý kiến

Context-aware rules

Thay vì quy tắc cứng nhắc áp dụng mọi nơi, Boris sử dụng quy tắc có điều kiện theo thư mục. Cách này giúp Claude Code linh hoạt hơn mà vẫn tuân thủ conventions đúng nơi đúng chỗ.

## Context-Dependent Rules
- In src/components/: Luôn tạo Storybook story cùng component
- In src/server/: Luôn thêm OpenAPI JSDoc comments
- In tests/: Dùng test.each cho parameterized tests khi hơn 3 cases
- In migrations/: Không bao giờ sửa migration cũ, tạo migration mới

Progressive disclosure

Thông tin quan trọng nhất đặt ở đầu file. Chi tiết bổ sung đặt ở cuối. Claude Code xử lý context theo thứ tự, và thông tin ở đầu có trọng số cao hơn trong thực tế. Boris sắp xếp theo thứ tự: project overview, commands, coding standards, architecture, special rules, edge cases.

Workflow tích hợp CLAUDE.md vào team

CLAUDE.md mang lại giá trị lớn nhất khi cả team cùng sử dụng và duy trì. Dưới đây là quy trình bốn bước.

Bước 1: Khởi tạo

Tech lead hoặc senior developer viết bản CLAUDE.md đầu tiên dựa trên conventions hiện tại. Commit vào repo, tạo PR để review, và thông báo cho team.

Bước 2: Review và bổ sung

Mỗi thành viên review và đề xuất bổ sung dựa trên kinh nghiệm cá nhân. Những pattern mà họ hay gặp phải khi dùng Claude Code chính là nội dung cần bổ sung vào file.

Bước 3: Duy trì liên tục

Đưa mục "Review CLAUDE.md" vào checklist sprint review. Mỗi khi thay đổi tooling, upgrade framework, hoặc thêm convention mới, cập nhật file ngay. Một CLAUDE.md lỗi thời gây hại nhiều hơn không có file.

Bước 4: Onboarding

Thành viên mới đọc CLAUDE.md như tài liệu onboarding kỹ thuật đầu tiên. Nếu họ phát hiện thiếu thông tin khi bắt đầu sử dụng Claude Code, bổ sung ngay. Cách này biến onboarding thành cơ hội cải thiện documentation.

Template khởi đầu

Copy template sau và điều chỉnh cho dự án của bạn. Mỗi phần có ghi chú trong ngoặc vuông để bạn biết điền gì.

# CLAUDE.md

## Project
[Mô tả 1-2 câu về dự án, đối tượng sử dụng]
Tech: [Framework], [Language], [Database]
Deploy: [Platform]

## Commands
- Dev: `[lệnh dev server]`
- Build: `[lệnh build]`
- Test: `[lệnh test]`
- Lint: `[lệnh lint]`
- Deploy: `[lệnh deploy]`

## Code Standards
- [Quy tắc 1 với ví dụ cụ thể]
- [Quy tắc 2 với ví dụ cụ thể]
- [Quy tắc 3 với ví dụ cụ thể]

## Architecture
[Cấu trúc thư mục chính với mô tả vai trò]
[Key patterns và conventions]

## Do NOT
- [Điều cấm 1 với lý do ngắn]
- [Điều cấm 2 với lý do ngắn]
- [Điều cấm 3 với lý do ngắn]

## Context Rules
- In [thư mục A]: [quy tắc riêng]
- In [thư mục B]: [quy tắc riêng]

Tự cập nhật CLAUDE.md bằng Claude Code

Một mẹo hữu ích là dùng chính Claude Code để cải thiện CLAUDE.md theo thời gian. Mỗi khi Claude Code làm sai điều gì đó lặp đi lặp lại, yêu cầu nó bổ sung quy tắc vào file.

Claude vừa tạo component với default export, nhưng dự án này
dùng named export. Hãy thêm quy tắc này vào CLAUDE.md
trong phần Do NOT để lần sau không lặp lại.

Cách tiếp cận này biến mỗi lỗi thành cơ hội cải thiện. Theo thời gian, CLAUDE.md ngày càng phản ánh chính xác cách team thực sự làm việc, và Claude Code ngày càng ít mắc lỗi hơn.

Đo lường hiệu quả

Sau khi thiết lập CLAUDE.md, theo dõi các chỉ số sau để đánh giá tác động:

• Convention violations trong PR: Số lần reviewer phải yêu cầu sửa code do vi phạm conventions. Chỉ số này nên giảm dần.
• Context repetition: Số lần bạn phải giải thích lại thông tin cho Claude Code trong cùng phiên làm việc. Mục tiêu là gần bằng 0.
• Onboarding time: Thời gian thành viên mới cần để bắt đầu dùng Claude Code hiệu quả. Nên rút ngắn đáng kể.
• Code review turnaround: Thời gian từ lúc mở PR đến lúc merge. Khi Claude Code tuân thủ conventions ngay từ đầu, review nhanh hơn.

So sánh trước và sau khi có CLAUDE.md

Dưới đây là so sánh thực tế từ một dự án TypeScript có 6 developers:

• Trước: Trung bình 4-5 comments về convention violations mỗi PR. Sau: Giảm xuống 0-1 comments.
• Trước: Claude Code đoán sai lệnh test 40% trường hợp. Sau: Luôn dùng đúng lệnh.
• Trước: Mỗi phiên phải paste 3-5 dòng context. Sau: Bắt đầu làm việc ngay.
• Trước: Thành viên mới mất 2-3 ngày làm quen với Claude Code. Sau: Hiệu quả từ ngày đầu tiên.

Kết luận

CLAUDE.md không phải là tài liệu viết một lần rồi quên. Nó là living document phát triển cùng dự án, phản ánh cách team thực sự làm việc. Một CLAUDE.md tốt giúp Claude Code trở thành thành viên hiệu quả trong team, hiểu conventions, biết cấu trúc, và sản xuất code phù hợp ngay từ lần đầu.

Đầu tư 30 phút viết CLAUDE.md ban đầu, sau đó 5 phút mỗi sprint để cập nhật, có thể tiết kiệm hàng giờ sửa code mỗi tuần cho cả team. Bắt đầu với template ở trên, điều chỉnh cho dự án của bạn, và liên tục cải thiện qua thực tế sử dụng.

Khám phá thêm các kỹ thuật nâng cao khác tại Thư viện Nâng cao.