Thêm context với CLAUDE.md

CLAUDE.md là gì?

Định nghĩa ngắn: CLAUDE.md là file markdown chứa hướng dẫn dành riêng cho Claude, được tự động chèn vào mọi request bạn gửi trong project.

Nói cách khác, nó hoạt động như "system prompt" nhưng cho project cụ thể, và được chia sẻ dưới dạng text thuần — bạn commit vào Git, team cùng sửa, review như code.

Luồng hoạt động

Hai vai trò chính

CLAUDE.md phục vụ hai mục đích đồng thời:

• Định hướng Claude qua codebase — chỉ rõ architecture, command quan trọng, file nào đáng đọc trước
• Đưa hướng dẫn riêng của bạn — style code, convention đặt tên, cấm làm gì, thích làm gì

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  Bạn gõ: "Thêm endpoint GET /users/:id/invoices"        │
│                     │                                   │
│                     ▼                                   │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Claude Code nội bộ ghép:                        │  │
│  │   1. Nội dung CLAUDE.md (luôn có)                │  │
│  │   2. Tool definitions (Read/Write/Bash...)       │  │
│  │   3. Prompt của bạn                              │  │
│  └──────────────────────┬───────────────────────────┘  │
│                         ▼                               │
│                  ┌─────────────┐                        │
│                  │  Claude API │                        │
│                  └──────┬──────┘                        │
│                         ▼                               │
│           Response tuân theo convention                 │
│                                                         │
└─────────────────────────────────────────────────────────┘

Lệnh /init — Sinh CLAUDE.md tự động

Khi bạn mở Claude Code trong một project lần đầu, luôn chạy /init trước.

Lệnh này ra lệnh cho Claude:

Khi Claude xin permission

Trong quá trình /init, Claude sẽ gọi Write tool và hỏi bạn approve. Có hai cách:

Với /init, thường chỉ có 1 file được tạo (CLAUDE.md) nên Enter là đủ. Với task phức tạp (refactor nhiều file), Shift + Tab tiết kiệm thời gian — nhưng phải trả bằng rủi ro: Claude có thể đi sai hướng mà bạn không kịp chặn.

Ví dụ output điển hình sau /init

30 dòng, mất 20 giây generate. Đây chính là "bản tóm tắt" mà Claude cần để hành xử như senior đã làm trong project 6 tháng — thay vì intern mới toanh.

• Quét toàn bộ codebase (dùng Glob + Grep + Read)
• Hiểu:
• Mục đích & kiến trúc project
• Command quan trọng (build, test, lint, dev server)
• File trung tâm (schema, config, entry point)
• Coding pattern phổ biến (class vs function, naming, folder layout)
• Viết kết quả thành CLAUDE.md ở root project

# Project: uigen

## Overview
Next.js 14 app that generates React UI components via Claude API.
Uses Prisma + SQLite for local persistence.

## Key Commands
- `npm run setup` — install deps + init DB
- `npm run dev` — start dev server (port 3000)
- `npm run test` — Vitest + React Testing Library
- `npm run db:push` — push schema changes to SQLite

## Architecture
- `src/app/` — App Router pages & API routes
- `src/components/` — shared React components
- `src/lib/prompts/` — prompt templates sent to Claude API
- `prisma/schema.prisma` — DB schema source of truth

## Conventions
- TypeScript strict mode
- Use `@/` path alias for imports
- Test files in `__tests__/` next to source

Ba vị trí của CLAUDE.md

Claude Code nhận diện file CLAUDE.md ở ba nơi khác nhau, mỗi nơi phục vụ một mục đích:

Quy tắc phân loại nội dung

Sai lầm phổ biến

❌ Ghi đường dẫn tuyệt đối /Users/john/Projects/app/... vào project CLAUDE.md rồi commit — Khi teammate pull về, path sai, Claude rối loạn.

✅ Dùng relative path hoặc đưa hardcoded path xuống CLAUDE.local.md.

┌──────────────────────────────────────────────────────────┐
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  1.  <project>/CLAUDE.md                         │   │
│  │      → Commit vào Git, chia sẻ cho team          │   │
│  │      → Quy ước chung: style, architecture        │   │
│  └──────────────────────────────────────────────────┘   │
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  2.  <project>/CLAUDE.local.md                   │   │
│  │      → .gitignore — KHÔNG commit                 │   │
│  │      → Preference cá nhân, secret path, note     │   │
│  └──────────────────────────────────────────────────┘   │
│                                                          │
│  ┌──────────────────────────────────────────────────┐   │
│  │  3.  ~/.claude/CLAUDE.md                         │   │
│  │      → Global, áp dụng mọi project trên máy      │   │
│  │      → Dùng cho habit cá nhân xuyên project      │   │
│  └──────────────────────────────────────────────────┘   │
│                                                          │
└──────────────────────────────────────────────────────────┘

CLAUDE.md không phải silver bullet — vẫn có giới hạn

Đây là chỗ cần thành thật.

• Context cost: CLAUDE.md "plop vào prompt" mỗi request. Nội dung càng dài, càng tốn token, càng dễ đẩy prompt đến giới hạn 200K token. Thực tế: giữ file dưới 500 dòng là an toàn. Trên 1000 dòng, Claude bắt đầu bỏ qua những gì nằm sâu.
• Model tuân thủ tùy version: Model cũ (Claude 3.5 Sonnet) thường "quên" instruction dù ghi rõ (ví dụ: vẫn thêm comment in-line dù đã cấm). Từ Claude 4 trở đi, khả năng follow instruction tốt lên rõ rệt. Nếu bạn đang dùng model mới, có thể rà lại CLAUDE.md và trim bớt những hướng dẫn "workaround cho model cũ".
• Không phải noise collector: Đừng biến CLAUDE.md thành nơi chứa mọi note hay ý tưởng. Mỗi dòng phải có lý do tồn tại — nếu xóa đi không ảnh hưởng hành vi Claude, nên xóa.

Thêm hướng dẫn tùy chỉnh qua memory mode (#)

Giả sử bạn đang chat với Claude, nó lại thêm comment kiểu // increment counter by 1 cho một dòng counter++ (vô nghĩa). Bạn có thể:

Dấu # ở đầu dòng kích hoạt memory mode. Claude sẽ:

Kết quả: file CLAUDE.md vừa được update mà bạn không phải rời khỏi terminal.

Khi nào nên dùng memory mode?

✅ Khi bạn phát hiện một lỗi lặp lại (Claude vừa mắc → rút kinh nghiệm ngay) ✅ Khi bạn vừa giải thích một convention dài trong chat — muốn lưu lại ✅ Khi đang trong flow và không muốn mất context để edit file thủ công

❌ Không dùng cho "vibe note" không rõ ràng (chi phí re-read sau này cao) ❌ Không dùng cho secret/credential — memory mode không biết cái gì là secret

Ví dụ conversation thực tế

• Cách cũ: mở CLAUDE.md, gõ thêm câu "Use comments sparingly...", save, quay lại Claude.
• Cách memory mode: gõ ngay trong prompt:
• Đọc hướng dẫn đó
• Tự phân tích xem nên append vào file CLAUDE.md nào (project / local / global) — hoặc hỏi bạn
• Merge thông minh: nếu đã có section "Comments", thêm dòng vào section đó; nếu chưa, tạo mới
• Save, report lại cho bạn

# Use comments sparingly. Only comment complex code.

Ví dụ conversation thực tế

Lần sau khi Claude định tạo util mới, nó sẽ tự grep lib/utils/ trước khi viết — không phải vì nó nhớ từ conversation (conversation sẽ hết sau khi bạn exit), mà vì dòng đó đã nằm vĩnh viễn trong CLAUDE.md.

You:  Tại sao bạn lại viết lại hàm formatDate? 
      Mình đã có helper @lib/utils/date.ts rồi.

Claude: Bạn nói đúng — tôi đã tạo hàm trùng lặp. Để tôi xóa và 
        dùng lại helper có sẵn.

You:  # Before creating any utility function, search in lib/utils/ 
      first to check if an equivalent exists.

Claude: Đã thêm vào project CLAUDE.md, section "Code Style".

Cú pháp @ — Mention file cụ thể

Khi bạn cần Claude nhìn vào file cụ thể, gõ @ rồi tên file/folder:

Claude sẽ:

Khác biệt với CLAUDE.md

Dùng @ bên trong CLAUDE.md

Đây là kỹ thuật nâng cao rất hữu ích. Bạn có thể viết trong CLAUDE.md:

• Suggest autocomplete (giống Git Tab): hiện list file matching
• Bạn chọn file → nội dung file được tự động include vào request
• Claude trả lời với ngữ cảnh đầy đủ

Giải thích flow auth của project, tập trung vào @src/lib/auth/

Dùng @ bên trong CLAUDE.md

Khi Claude load CLAUDE.md, nó sẽ tự động đọc luôn prisma/schema.prisma và src/app/api/_example/route.ts vào context. Bạn không phải mention lại mỗi lần hỏi về DB.

Trade-off: Hai file đó luôn nằm trong prompt — tốn token. Chỉ làm khi file đó thực sự cần cho hầu hết câu hỏi (ví dụ: schema là trung tâm của project).

## Database

The database schema is defined in @prisma/schema.prisma. 
Reference it anytime you need to understand the structure of 
data stored in the database.

## API Conventions

All API routes must follow the pattern defined in 
@src/app/api/_example/route.ts. Use this as template for 
new endpoints.

Ví dụ thực chiến: Onboard một team 8 engineer

Tình huống

Bạn là tech lead team 8 người ở công ty fintech. Team vừa merge PR gộp ba microservices thành monorepo. Ai cũng đang loay hoay vì Claude Code (mới rollout) hành xử khác nhau trên máy mỗi người — người bảo "Claude cứ dùng callback thay vì async/await", người than "Claude tự thêm console.log khắp nơi".

Bước 1: Mở repo, chạy /init

Claude quét, viết CLAUDE.md đầu tiên:

Bước 2: Thêm team conventions (viết tay)

Bạn edit CLAUDE.md, append:

# Monorepo: acme-finance

Three services in one repo: payments, ledger, reporting.

## Structure
- services/payments/ — Fastify + Drizzle
- services/ledger/ — Fastify + Drizzle
- services/reporting/ — Next.js + tRPC
- packages/common/ — shared types, utils
- packages/sdk-* — client SDKs

## Commands
- `pnpm install` — at root
- `pnpm --filter payments dev`
- `pnpm --filter reporting test`

Bước 2: Thêm team conventions (viết tay)

Bước 3: Commit & broadcast

## Code Style

- Async/await ONLY. Never use raw Promise.then chains or callbacks.
- No console.log in committed code. Use `pino` logger (see 
  @packages/common/logger.ts).
- All money amounts stored as BigInt (minor units). Never Number.
- Error handling: throw typed AppError (see @packages/common/errors.ts).

## Testing

- Unit tests colocated: `foo.ts` + `foo.test.ts`
- Integration tests in `__integration__/` folder
- Use `describe/it` (Vitest), not `test()`

## Git

- Conventional Commits required
- PR titles: <type>(<scope>): <summary>
- Branch names: feat/<ticket-id>-slug

Bước 3: Commit & broadcast

Slack message cho team: "Vừa push CLAUDE.md. Pull về, Claude Code của mọi người sẽ đồng bộ convention."

Bước 4: Mỗi dev tự customize local

Một dev Python-first (mới chuyển sang TS) tạo CLAUDE.local.md:

git add CLAUDE.md
git commit -m "chore: add Claude Code project instructions"
git push

Bước 4: Mỗi dev tự customize local

File này không commit. Chỉ dev đó được hưởng.

Kết quả sau 2 tuần

Tiết kiệm thực tế: ~3 giờ/tuần/dev × 8 dev = 24 giờ team/tuần.

• Review time PR giảm 40% — convention comment giảm từ ~8/PR xuống ~2/PR
• Claude output nhất quán trên 8 máy — không còn "case by case"
• Onboard dev mới: chỉ cần git pull + /init → Claude hiểu codebase ngay

## Personal preferences

- Explain TypeScript concepts in terms of Python equivalents 
  when I ask about types (I'm more familiar with Python typing).
- Verbose error messages preferred over terse ones.

Case studies theo ngành

💰 Finance Engineer — Compliance-aware Claude

Trước: "Claude cứ suggest dùng float cho số tiền. Compliance flag mỗi PR. Mình phải sửa tay."

Với CLAUDE.md:

⚖️ Legal Tech — Dữ liệu nhạy cảm không leak

Trước: "Claude thỉnh thoảng log SSN/PII vào debug output khi generate test data."

Với CLAUDE.md:

• Kết quả: 0 compliance flag liên quan money type trong 90 ngày, tiết kiệm ~5 giờ/tuần review.

## CRITICAL: Money representation
- NEVER use float/double for monetary values
- Use decimal.Decimal (Python) or BigInt (TS) with minor units
- All amounts must include Currency enum reference
- See @src/finance/types.ts for canonical types

⚖️ Legal Tech — Dữ liệu nhạy cảm không leak

🏥 Healthcare SaaS — HIPAA boundary

Trước: "Team dev ở 3 múi giờ. Mỗi người giải thích HIPAA cho Claude khác nhau."

Với CLAUDE.md chia sẻ:

• Kết quả: Security audit pass clean — không có incident generated PII leak trong 6 tháng.

## Data handling
- NEVER generate realistic PII in test fixtures (no real SSN 
  patterns, no real emails, no real addresses)
- Use faker library with `faker.seed(42)` for reproducibility
- Any field marked `@sensitive` in schema must never appear in logs
- See @security/data-policy.md for full rules

🏥 Healthcare SaaS — HIPAA boundary

📣 Marketing Agency — Brand voice consistency

Trước: "Claude viết microcopy cho landing page mỗi lần một kiểu — lúc formal, lúc casual."

Với ~/.claude/CLAUDE.md (global cho designer):

• Kết quả: Zero cross-boundary PHI leak trong Claude-generated code, pass SOC 2 audit.

## HIPAA boundaries
- Patient data only in `services/phi-vault` — never in `services/reporting`
- If Claude detects PHI field name (see @common/phi-schema.ts list) 
  being imported outside phi-vault, refuse and flag
- All audit logs via @common/audit-logger.ts (no console.log)

📣 Marketing Agency — Brand voice consistency

🛠️ Product Engineer — Migration dần dần

Trước: "Team đang migrate từ Prisma sang Drizzle nhưng Claude vẫn mặc định suggest Prisma pattern."

Với CLAUDE.md:

• Kết quả: 3-4 rounds review → 1 round, giao client 2x nhanh.

## Brand voice (Acme Agency)
- Tone: confident but humble, no hype
- Words to avoid: "revolutionary", "game-changing", "cutting-edge"
- Words to prefer: "practical", "direct", "tested"
- CTA style: verb-first, imperative, max 4 words
- See @brand/voice-examples.md for before/after samples

🛠️ Product Engineer — Migration dần dần

• Kết quả: Migration hoàn thành 2 tuần sớm, không có PR "chống migration" từ Claude.

## Database migration in progress

Status: migrating Prisma → Drizzle (tracker @docs/migration.md)

- Files in services/payments/: Drizzle ONLY (migration complete)
- Files in services/ledger/: Prisma allowed (migration pending)
- New code: ALWAYS Drizzle, even in ledger/
- Never write new Prisma schema — edit @drizzle/schema.ts instead

Prompt templates cho CLAUDE.md

Dưới đây là 5 template bạn có thể copy-adapt cho project của mình.

1. Bootstrap một CLAUDE.md mới (ngoài /init)

2. Audit CLAUDE.md đang có

Đọc toàn bộ codebase này, đặc biệt @package.json, @tsconfig.json, 
các file README, và 3-5 file source đại diện nhất. Sau đó viết một 
file CLAUDE.md với các section:

1. Project Overview (1-2 câu)
2. Key Commands (build/dev/test/lint)
3. Architecture (folder structure chính, không quá chi tiết)
4. Conventions đã phát hiện (naming, testing pattern, error handling)
5. Files to always reference (dùng @)

Giữ dưới 200 dòng. Ưu tiên hướng dẫn có actionable behavior hơn 
là description.

Prompt templates cho CLAUDE.md (tiếp)

3. Trích xuất conventions từ existing code

Review @CLAUDE.md hiện tại. Với mỗi instruction, đánh giá:

- Nó có thực sự thay đổi hành vi của Claude không? Hay chỉ là 
  description?
- Có lặp với convention đã có trong eslint/prettier/tsconfig không?
- Có outdated (ví dụ: mention package cũ đã thay thế) không?

Output: danh sách instruction đề xuất (a) giữ, (b) xóa, (c) rewrite 
cho rõ hơn. KHÔNG tự sửa file.

Prompt templates cho CLAUDE.md (tiếp)

4. Migrate convention khi chuyển tech stack

Đọc 10 file random trong @src/. Phát hiện các pattern lặp lại không 
có trong @CLAUDE.md hiện tại (naming, error handling, import order, 
comment style). Liệt kê và đề xuất add vào CLAUDE.md.

Prompt templates cho CLAUDE.md (tiếp)

5. Sync CLAUDE.md với documentation người

Team đang migrate từ [X] sang [Y]. Đọc @CLAUDE.md hiện tại, tìm 
tất cả instruction còn tham chiếu [X]. Suggest update để:
- Nêu rõ trạng thái migration (in progress / complete)
- Rule cho code mới vs code cũ
- Reference doc migration plan nếu có

Prompt templates cho CLAUDE.md (tiếp)

So sánh @CLAUDE.md với @docs/CONTRIBUTING.md và @docs/ARCHITECTURE.md. 
Tìm:
- Convention trong docs nhưng thiếu trong CLAUDE.md → nên add
- Instruction trong CLAUDE.md mâu thuẫn với docs → flag
- Thông tin duplicate cần consolidate

Output: markdown report, không auto-edit.

Anti-patterns — Những sai lầm cần tránh

❌ Viết CLAUDE.md như brochure giới thiệu sản phẩm

Biểu hiện: dòng kiểu "This project is a revolutionary platform that empowers users to..."

Tại sao sai: Claude không cần marketing. Tốn token, không thay đổi hành vi.

Cách đúng: Văn phong "imperative" — câu lệnh ngắn, rõ: "Use pnpm, not npm. Tests live in __tests__/ folder."

❌ Nhồi quá nhiều rule — không ưu tiên

Biểu hiện: CLAUDE.md 1200 dòng, bao gồm cả "lịch sử dự án", "kế hoạch roadmap Q3"...

Tại sao sai:

Cách đúng:

❌ Rule "negative" không có alternative

Biểu hiện: "Don't use callbacks." — dừng ở đó.

Tại sao sai: Claude biết không được dùng callback, nhưng giờ dùng gì? Promise? async/await? Generator?

Cách đúng: "Don't use callbacks. Use async/await. See @common/async-patterns.ts for examples."

❌ Commit secrets hoặc path cá nhân

Biểu hiện: Project CLAUDE.md chứa /Users/john/.secrets/api.key hoặc DB password.

Tại sao sai: Commit vào Git = public với team. Với public repo = public với Internet.

Cách đúng:

❌ Không update khi codebase thay đổi

Biểu hiện: CLAUDE.md vẫn nói "use React Router v5" trong khi team đã chuyển TanStack Router 3 tháng trước.

Tại sao sai: Claude làm theo rule cũ, bạn tốn thời gian sửa từng PR.

Cách đúng:

❌ Giả định model hiểu implicit

Biểu hiện: "Follow the standard pattern." (pattern nào?!)

Tại sao sai: "Standard" với team A khác team B. Claude đoán sai.

Cách đúng: Dẫn chứng cụ thể: "Follow the pattern in @src/api/users/route.ts as canonical example."

• Tốn 10-15% context window mỗi request
• Model có xu hướng bỏ qua instruction ở giữa file dài
• Update khó, ai cũng ngại sửa
• Giữ dưới 500 dòng (ideal 200-300)
• Priority: rule CRITICAL (security, compliance) → convention → preference
• Đẩy context dài xuống file riêng, dùng @ mention
• Secret/path cá nhân → CLAUDE.local.md (đã .gitignore)
• Mention vị trí secret chung → môi trường biến: "API key in env var ANTHROPIC_API_KEY"
• Coi CLAUDE.md như code — đưa vào review checklist của PR lớn
• Khi migration xong, thêm task "update CLAUDE.md" vào định nghĩa "Done"
• Chạy định kỳ /review @CLAUDE.md để audit

Mẹo nâng cao

Mẹo 1: Dùng section heading cho Claude scan nhanh

Thay vì block text dài, dùng heading ## Testing, ## Error Handling. Model tìm section liên quan dễ hơn, output focus hơn.

Mẹo 2: Versioning nhẹ

Thêm dòng đầu file: <!-- Last reviewed: 2026-04 — TL: @jimmy -->. Mỗi quý review lại, update ngày. Team biết file còn "sống".

Mẹo 3: Test CLAUDE.md như test code

Sau khi edit CLAUDE.md, restart Claude Code và chạy 2-3 prompt cụ thể để verify rule có được tuân không. Ví dụ:

Nếu Claude vi phạm → rule viết chưa đủ rõ, cần sửa.

Mẹo 4: Phân tầng rule theo độ nghiêm ngặt

Prompt test: "Thêm một endpoint CRUD cho entity Product."
Kỳ vọng: Claude dùng Drizzle (vì CLAUDE.md), không tự thêm comment 
thừa (vì CLAUDE.md), có test file colocated (vì CLAUDE.md).

Mẹo 4: Phân tầng rule theo độ nghiêm ngặt

Giúp Claude biết rule nào "không được phép sai" vs "có thể uyển chuyển".

## CRITICAL (security/compliance — must not violate)
- ...

## STRONG (team convention — violate only with approval)
- ...

## PREFERENCE (stylistic — suggest but negotiable)
- ...

Áp dụng ngay

Bài tập 1: Bootstrap CLAUDE.md cho project thật của bạn (15 phút)

Bước 1: Mở một project đang làm trong Claude Code.

Bước 2: Chạy /init. Đợi Claude sinh CLAUDE.md.

Bước 3: Review file — trả lời trong note:

Bước 4: Dùng memory mode (#) để bổ sung ít nhất 2 rule bạn nghĩ sẽ thay đổi hành vi Claude:

Bước 5: Thử prompt test — yêu cầu Claude làm việc tương tự trước khi và sau khi thêm rule. So sánh output.

Ghi lại:

Bài tập 2 (optional, 30 phút): Audit CLAUDE.md cũ

Nếu team bạn đã có CLAUDE.md vài tháng rồi, chạy prompt template #2 "Audit CLAUDE.md đang có" phía trên.

Output nên chứa:

Tạo một PR nhỏ để update. Commit message: docs(claude): audit and trim CLAUDE.md.

• Có rule nào thiếu mà bạn thường xuyên phải nhắc Claude không? ________
• Có thông tin nào sai/lỗi thời không? ________
• File dài bao nhiêu dòng? ________
• Rule có tác dụng ngay không: ☐ Có ☐ Không
• Thời gian trung bình cho 1 prompt task: _____ phút (trước) → _____ phút (sau)
• Số comment review cần sửa: _____ (trước) → _____ (sau)
• ☐ Danh sách instruction đề xuất xóa (duplicate, outdated, không actionable)
• ☐ Danh sách rewrite (vague → specific)
• ☐ Danh sách gap (convention team có nhưng CLAUDE.md chưa ghi)

# [Rule 1]
# [Rule 2]

Tóm tắt bài học

🎯 CLAUDE.md là "system prompt ngầm" của project — mỗi request Claude đọc lại, nên đặt convention ở đây thay vì copy-paste mỗi lần.

🎯 /init là bước 0 của mọi project — đừng quên chạy ngay khi clone repo mới, dù chỉ để có bản draft tự sửa.

🎯 Ba vị trí, ba mục đích — project CLAUDE.md (team share), CLAUDE.local.md (cá nhân, không commit), ~/.claude/CLAUDE.md (global mọi project).

🎯 # memory mode > edit file tay — trong flow, gõ # rule... nhanh hơn mở editor; Claude tự merge thông minh.

🎯 @ dùng được cả trong chat lẫn trong CLAUDE.md — mention file để auto-include; đặt trong CLAUDE.md biến file thành "luôn có trong context".

🎯 Ít nhưng sắc bén > nhiều và mờ nhạt — dưới 500 dòng, imperative voice, có alternative sau mỗi "không được".