Hướng dẫn thực tế viết CLAUDE.md: lệnh, kiến trúc, thao tác bị cấm và tham chiếu file, minh họa bằng dự án Rails thực tế.
Mỗi lần bạn mở Claude Code, nó bắt đầu từ đầu — không nhớ cuộc trò chuyện trước, không biết dự án của bạn làm gì, không biết lệnh test là rspec hay pytest, và không biết thao tác nào bị cấm.
CLAUDE.md giải quyết vấn đề này. Đây là file hướng dẫn lâu dài bạn viết cho Claude, được tải tự động vào đầu mỗi cuộc hội thoại. Một CLAUDE.md viết tốt giúp Claude vào guồng làm việc ngay lập tức — không hỏi những câu không cần thiết, không mắc lỗi cơ bản.
Claude Code hỗ trợ hệ thống CLAUDE.md nhiều lớp với ba cấp độ:
~/.claude/CLAUDE.md: Cấu hình toàn cục, áp dụng cho tất cả dự án. Dùng cho các tùy chọn chung như "không bao giờ tự động commit git" hay "trả lời bằng tiếng Việt".CLAUDE.md ở thư mục gốc dự án: Cấu hình cấp dự án. Vị trí phổ biến nhất.CLAUDE.md trong thư mục con: Chỉ được tải khi Claude làm việc với file trong thư mục đó. Lý tưởng để đặt hướng dẫn riêng cho frontend/, api/, hay infra/.Nhiều file CLAUDE.md cộng dồn với nhau — file cụ thể hơn có ưu tiên cao hơn.
Một đoạn văn cho Claude biết dự án là gì và dùng công nghệ gì:
## Project Overview
**Pickful AI** is a Ruby on Rails 8 cryptocurrency-focused social media platform.
Users can create posts, follow others, earn points, track coin prices,
and participate in a gamification system with leaderboards and VIP status.
- **Ruby Version:** 3.3.2
- **Rails Version:** 8.0.2
- **Database:** PostgreSQL with 4 separate databases (primary, cache, queue, cable)
Việc ghi rõ số phiên bản rất quan trọng. Biết là Rails 8 thì Claude sẽ không gợi ý các pattern từ thời Rails 6. Biết có 4 database thì sẽ không phạm lỗi khi viết migration.
Đây là phần mang lại giá trị trực tiếp nhất trong bất kỳ CLAUDE.md nào. Không viết rõ lệnh thì Claude phải đoán mò — và đoán sai.
## Development Commands
### Running the Application
bin/dev # Start Rails server (port 3000) + Tailwind watcher
bin/rails server # Start Rails server only
### Testing
bundle exec rspec # Run all tests
bundle exec rspec spec/models # Run model tests
bundle exec rspec spec/path/to/file_spec.rb:42 # Run test at line 42
### Linting & Security
bin/rubocop # Run RuboCop linter (Rails Omakase preset)
bin/rubocop -a # Auto-correct offenses
bin/brakeman # Security vulnerability scan
### Deployment (Kamal)
bin/kamal deploy # Deploy to production
bin/kamal app logs # View application logs
bin/kamal app console # Remote Rails console
Danh sách này cho Claude biết: test chạy bằng bundle exec rspec chứ không phải rails test; deploy dùng Kamal chứ không phải Capistrano hay Fly.io; linter là RuboCop với preset Rails Omakase. Không viết thì Claude phải tự đoán tất cả.
Mục đích của các ghi chú kiến trúc là ghi lại những quyết định không thấy được trong code. Claude có thể đọc cấu trúc thư mục; nó không thể biết tại sao lại được tổ chức như vậy.
## Key Architectural Patterns
**Services Layer:**
Complex business logic extracted to `app/services/`.
Keep controllers thin, delegate to services.
**Authorization:**
Pundit policies in `app/policies/`.
Check UserPolicy, PostPolicy, etc. for permission rules.
**Background Jobs:**
Use `app/jobs/` for async processing.
Solid Queue handles job processing.
Ba điểm này cho Claude biết: đừng tích lũy business logic trong controller; tìm quy tắc phân quyền ở app/policies/; dùng Solid Queue cho mọi thứ cần xử lý bất đồng bộ.
Liệt kê domain model theo nhóm chức năng cũng rất hữu ích:
## Core Domain Models
**Social Features:** User, Follow, Block, Referral
**Content:** Post, Comment, Topic, Tag, Draft
**Engagement:** Like, Favorite, Share, Report
**Cryptocurrency:** Coin, CoinPrice, Payment
**Gamification:** PointTransaction (VIP status at 400+ points)
Điều này hiệu quả hơn là để Claude tự quét app/models/, đồng thời truyền tải ngữ nghĩa kinh doanh — ví dụ 400 điểm là ngưỡng VIP, điều không rõ ràng khi chỉ đọc code.
Đây là phần hay bị bỏ qua nhất, và thường là quan trọng nhất:
## Important Configuration
**Multi-Database:**
Always be aware of the multi-database setup.
Most migrations should target the primary database
unless working with cache/queue/cable features.
**Lexxy Integration:**
The app uses Lexxy gem (beta) for enhanced ActionText editing.
Configured in config/application.rb with:
config.lexxy.override_action_text_defaults = false
**Asset Handling:**
Uses Propshaft (not Sprockets).
Assets in app/assets/ are served without fingerprinting in development,
with fingerprinting in production.
Cả ba đều là thông tin "không viết thì hối hận": multi-database yêu cầu chỉ định rõ target của migration; Lexxy là gem beta có hành vi khác ActionText chuẩn; Propshaft hoạt động khác Sprockets.
Đây là phần bị đánh giá thấp nhất. Nói rõ cho Claude biết không được làm gì hiệu quả hơn nhiều so với việc sửa lỗi sau khi xảy ra.
## Do Not
- Do NOT run `git commit` automatically — always ask me to confirm first
- Do NOT modify files in `db/migrate/` that already exist
- Do NOT touch `.kamal/secrets*` files — production secrets, handle manually
- Do NOT run `bin/kamal deploy` without explicit instruction
Điểm đầu tiên thuộc về hầu hết mọi dự án. Lệnh deploy còn quan trọng hơn — bin/kamal deploy chạy nhầm sẽ ảnh hưởng trực tiếp đến production.
CLAUDE.md hỗ trợ tham chiếu @ để kéo file khác vào:
Cấu hình deploy: @config/deploy.yml
Schema database: @db/schema.rb
Claude đọc các file này khi cần. db/schema.rb đặc biệt hữu ích — trong dự án Rails nó là nguồn sự thật duy nhất về cấu trúc database.
Viết quá nhiều: CLAUDE.md tiêu thụ cửa sổ ngữ cảnh. Dán toàn bộ README vào sẽ khiến Claude có ít không gian hơn để làm việc với code thực. Chỉ viết những gì Claude không thể suy ra từ việc đọc codebase.
Hướng dẫn mơ hồ: "Viết code tốt" không có ích. Hãy cụ thể: "Đừng đặt business logic trực tiếp trong controller — ủy quyền cho app/services/".
Quên cập nhật: Chuyển từ Sprockets sang Propshaft hay từ Sidekiq sang Solid Queue — nếu CLAUDE.md không cập nhật theo, Claude sẽ vận hành dựa trên giả định lỗi thời. Đưa việc cập nhật CLAUDE.md vào checklist của bất kỳ refactoring lớn nào.
Viết ví dụ code: Ví dụ tiêu thụ ngữ cảnh và Claude đọc code thực chính xác hơn các đoạn minh họa. Dùng tham chiếu @ để trỏ đến file thực.
# [Tên dự án]
[Mô tả trong một câu]
- **Ruby:** x.x.x
- **Rails:** x.x.x
- **Database:** PostgreSQL
## Development Commands
bin/dev # Start server
bundle exec rspec # Run tests
bin/rubocop # Lint
bin/kamal deploy # Deploy (ask before running)
## Architecture
[Cách phân chia trách nhiệm giữa Services / Jobs / Policies]
[Domain model nhóm theo khu vực chức năng]
## Important Notes
[Cấu hình không hiển nhiên, hành vi đặc biệt của gem]
## Do Not
- Do NOT run git commit automatically
[Các thao tác rủi ro cao khác]
Bắt đầu từ template này và điền những gì dự án của bạn thực sự cần. Không cần bao quát mọi thứ — một CLAUDE.md với năm điểm chính xác còn hơn một cái nhồi đầy tiếng ồn.