CLAUDE.md: File Cấu Hình Quan Trọng Nhất Mà Dev Thường Bỏ Qua

TL;DR

CLAUDE.md không phải documentation — nó là system configuration. Điều này quan trọng vì Claude treat instructions trong CLAUDE.md nghiêm ngặt hơn prompt thường. Viết quá 150-200 instructions thì quality degrade đều, nên “less is more” là nguyên tắc vàng. Điểm hay nhất: dùng # shortcut để add instructions ngay khi đang làm việc, không cần chờ edit file riêng.

Hiểu nôm na là CLAUDE.md giúp Claude “nhớ” project setup của mình mỗi lần start session mới, thay vì phải giải thích lại từ đầu.

Bài này dành cho ai?

1. 🤖 AI Office Orchestrator (Người muốn AI làm việc thay mình)

Pain point: Hỏi AI từng task một, mỗi lần phải explain project setup lại từ đầu, tốn 5-10 phút mỗi session Dùng khi: Bất kỳ project nào cần AI hỗ trợ code — từ simple script đến complex app Được gì: Setup một lần, AI nhớ mãi — tiết kiệm 5-10 phút mỗi lần bắt đầu, project càng lớn càng thấy hiệu quả

2. 🛠 Vibe Coder / Builder (Người muốn build products)

Pain point: Mỗi lần Claude vào project mới là “trắng tinh”, phải dò tìm folder structure, không biết dùng lệnh nào Dùng khi: Build bất kỳ project nào — prototype, MVP, hay production app Được gì: Claude hiểu project ngay từ đầu, tập trung vào code thay vì setup, có quy trình chuẩn cho workflow phức tạp

3. 🎯 Team Lead / Dev Manager (Người quản lý team dev)

Pain point: Muốn team dùng AI đúng cách nhưng không có standard, mỗi người setup một kiểu Dùng khi: Onboard member mới, review code, enforce conventions Được gì: CLAUDE.md commit vào git, cả team dùng chung — enforce coding standards tự động, onboarding nhanh hơn

Các điểm chính

1. CLAUDE.md không phải documentation — nó là system configuration. Joe nhấn mạnh: khi đặt trong CLAUDE.md, Claude tuân theo nghiêm ngặt hơn prompt thường vì nó trở thành phần của system prompt. Thực tế: đây là điểm leverage lớn nhất mà developer có trong Claude Code. Mình nên tận dụng bằng cách viết instructions ngắn gọn, rõ ràng, áp dụng cho hầu hết các sessions.

2. Less is more — giới hạn 150-200 instructions. Nghiên cứu frontier LLMs cho thể follow reliably khoảng 150-200 instructions. Claude Code’s system prompt đã có ~50 instructions sẵn, nghĩa là mình chỉ còn ~100-150 trước khi quality degrade. Joe’s golden rule: nếu instruction không apply cho 80%+ sessions thì move sang file riêng. Đây là cách tránh bloat mà nhiều dev mắc phải.

3. Hierarchy system — global, project, nested. CLAUDE.md có thể đặt ở nhiều nơi: ~/.claude/CLAUDE.md (global), ./CLAUDE.md (project root), và ./subdir/CLAUDE.md (nested). Thứ tự load: global → project → nested. Monorepo setup rất hữu ích — app/ có CLAUDE.md riêng, api/ có CLAUDE.md riêng, Claude chỉ load khi cần. Nhớ thêm .local.md cho personal preferences mà không push lên git.

4. Progressive disclosure — dùng separate files cho task-specific instructions. Thay vì nhét tất cả vào CLAUDE.md, tách ra: agent_docs/building.md, agent_docs/database_schema.md… Trong CLAUDE.md chỉ cần reference: “Read agent_docs/building.md when building.” Kỹ thuật này giúp Claude tập trung vào task hiện tại mà không bị overwhelm bởi context không cần thiết.

5. Đừng dùng CLAUDE.md làm linter. Dev thường add 50+ code style rules vào CLAUDE.md — sai rồi. Joe khuyên dùng ESLint/Prettier cho JS, Black/Ruff cho Python, rustfmt cho Rust. Thay vì viết “use 2 spaces indentation”, cài pre-commit hook hoặc Claude Code hooks để run linter tự động. CLAUDE.md chỉ nói “Code must pass linting before commit” — ngắn gọn.

6. Ba cách tạo CLAUDE.md: /init, manual, và # shortcut. /init phân tích codebase và generate starter file — dùng làm baseline, không phải finished product. Manual creation cho full control. # shortcut là hay nhất: đang làm việc, phát hiện Claude miss điều gì, gõ ngay ”# Always run tests before committing” — nó tự add vào. Mình recommend: bắt đầu với /init, sau đó refine manually, dùng # để iterate liên tục.

7. Advanced patterns: workflow definitions, conditional instructions, MCP documentation. Workflow definitions ngăn Claude nhảy vào code liền — ví dụ: “Adding new API endpoint: 1. Check existing… 2. Create schema… 3. Implement…” Conditional instructions: “When working in src/api/: use dependency injection; When working in tests/: use fixtures from conftest.py.” MCP documentation: “Slack MCP: post to #dev-notifications only, rate limited 10 msg/hour.” Những pattern này biến CLAUDE.md thành complete automation system.

8. Hooks + Subagents = complete system. CLAUDE.md định nghĩa rules, hooks enforce tự động (pre-commit lint chạy không cần hỏi), subagents handle isolated tasks với clean context. Joe hướng dẫn cách phối hợp: CLAUDE.md nói rule tồn tại, hook enforce, Claude focus vào coding. Đây là foundation trước khi học Hooks Masterclass.

9. Maintenance: update với PRs, review quarterly, commit to git. CLAUDE.md không phải “set and forget” — project thay đổi, team học patterns mới, tools mới vào workflow. Best practice: add vào PR checklist “CLAUDE.md updated if workflows changed.” Review mỗi quý: commands còn chính xác? Workflows có thay đổi? Có gì obsolete? Commit vào git để team benefit và track changes.

Quick Start

1. Tạo CLAUDE.md đầu tiên: Vào project, gõ claude /init — nó sẽ scan codebase và generate starter file. Xem lại, edit lại cho phù hợp workflow của mình, save.

2. Áp dụng Golden Rule: Trước khi thêm bất kỳ instruction nào, hỏi “Cái này apply cho 80%+ sessions không?” — nếu không thì move sang file riêng hoặc slash command.