Dành cho: Software Engineers, Developers và những ai đang quan tâm việc sử dụng Claude Code trong dự án.

Tóm tắt nhanh: Đừng biến CLAUDE.md thành nơi lưu mọi instruction của project. CLAUDE.md phù hợp với context và rule Claude cần biết xuyên suốt project, trong khi Skills phù hợp với checklist hoặc procedure chỉ cần khi thực hiện một task cụ thể. Đọc xong bài này, bạn sẽ biết cách phân biệt và lựa chọn CLAUDE.md và Skills đúng mục đích, từ đó tổ chức instruction rõ ràng, dễ bảo trì, tránh làm context trở nên cồng kềnh, hạn chế token không cần thiết và giúp Claude tập trung vào những instruction liên quan đến task.

Có thể bắt đầu bằng nguyên tắc:

Rule toàn project → CLAUDE.md
Procedure → Skill

Khi mới sử dụng Claude Code, cách đơn giản nhất để Claude hiểu project thường là tạo một file:

CLAUDE.md

Ví dụ:

# Project Rules
Use TypeScript
Use pnpm instead of npm
Follow existing naming conventions
Database access must go through the repository layer
Run tests after changing business logic

Cách này hoạt động tốt.

Vấn đề xuất hiện khi team tiếp tục thêm:

Coding convention
PR Review Process
API checklist
Bug Analysis Process
Security Review
Unit Test Procedure
Release Note Process
Migration checklist

Từ vài chục dòng, CLAUDE.md có thể nhanh chóng trở thành một file dài hàng trăm dòng.

Lúc này câu hỏi không còn là:

“Claude đã có đủ instruction chưa?”

Mà nên là:

“Claude có thực sự cần instruction này trong mọi task không?”

Đây chính là điểm cần phân biệt giữa CLAUDE.md và Skills.

1. CLAUDE.MD DÙNG CHO CONTEXT VÀ RULE XUYÊN SUỐT PROJECT

CLAUDE.md là nơi lưu các project instruction mà Claude cần sử dụng trong quá trình làm việc. CLAUDE.md được Claude đọc khi bắt đầu session và phù hợp với những thông tin Claude cần giữ trong quá trình làm việc.

Ví dụ:

# Project

Backend service for Order Management System

## Stack

Node.js
TypeScript
PostgreSQL
pnpm

## Architecture

Controller
→ Service
→ Repository
→ Database
Controllers must not access repositories directly

## Development Rules

Use pnpm
Follow existing naming conventions
Do not change public API contracts without confirmation
Update tests when changing business logic

Dù Claude đang:

Fix bug
Refactor
Viết API
Viết test

những thông tin trên vẫn có khả năng liên quan.

Đó là loại instruction phù hợp với CLAUDE.md.

2. SKILLS DÙNG CHO PROCEDURE CỦA MỘT TASK

Giả sử team có quy trình Review Pull Request:

1 Đọc requirement
2 Kiểm tra changed files
3 Kiểm tra business logic
4 Kiểm tra error handling
5 Kiểm tra security
6 Kiểm tra test coverage
7 So sánh với acceptance criteria
8 Phân loại finding theo severity
9 Sinh review report

Quy trình này cần thiết khi:

Review Pull Request

Nhưng không cần khi:

Fix typo in README

hoặc:

Explain this function

Thay vì đặt toàn bộ procedure vào CLAUDE.md, có thể tạo:

.claude/
 └── skills/
      └── review-pr/
           └── SKILL.md

Ví dụ:

---
name: review-pr
description: Review a Pull Request for correctness, risks and test coverage
---

When reviewing a Pull Request:

1 Read the requirement
2 Inspect changed files
3 Check business logic
4 Check error handling
5 Check security risks
6 Evaluate test coverage
7 Compare with acceptance criteria

Output:

## Critical
## Major
## Minor
## Suggestions
## Final Recommendation

Claude Code có thể sử dụng Skill khi nó phù hợp với task hoặc người dùng có thể gọi trực tiếp bằng /skill-name. Quan trọng hơn, body của Skill chỉ được nạp khi Skill được sử dụng, thay vì luôn chiếm context như instruction nền.

Đây là khác biệt cốt lõi:

CLAUDE.md
↓
Claude cần biết điều này xuyên suốt project

Skill
↓
Claude cần biết cách làm việc này khi task xuất hiện

3. VÌ SAO KHÔNG NÊN ĐỂ TẤT CẢ TRONG CLAUDE.MD?

Một sai lầm phổ biến là:

Claude làm sai
↓
Thêm instruction
↓
Claude tiếp tục sai
↓
Thêm instruction
↓
CLAUDE.md ngày càng dài

Một CLAUDE.md lớn không đồng nghĩa Claude hiểu project tốt hơn.

Có ba vấn đề chính.

3.1. TỐN CONTEXT KHÔNG CẦN THIẾT

CLAUDE.md là một phần context được load khi bắt đầu session. Skill descriptions cũng xuất hiện trong startup context, nhưng phần nội dung đầy đủ của Skill chỉ được đưa vào khi Skill được sử dụng.

Nếu CLAUDE.md chứa:

PR Review Process
Security Checklist
Release Note Process
Migration Process
Bug Analysis Process

thì những instruction này vẫn chiếm context ngay cả khi task hiện tại chỉ là:

Fix typo in README

Context window lớn hơn không có nghĩa chúng ta nên sử dụng nó cho những thông tin không liên quan.

3.2. QUÁ NHIỀU INSTRUCTION CÓ THỂ LÀM GIẢM KHẢ NĂNG TUÂN THỦ

Anthropic khuyến nghị mỗi CLAUDE.md nên dưới 200 dòng: file dài tốn context và có thể làm giảm khả năng tuân thủ. Đây là khuyến nghị, không phải giới hạn cứng. Xem Write effective instructions.

Ví dụ, task hiện tại chỉ là sửa lỗi nút Submit vẫn bị disable sau khi người dùng nhập đủ thông tin, không thay đổi API hay database.

Các instruction cần cho task này có thể chỉ gồm:

Tuân thủ quy ước của component và cách quản lý state hiện có.
Chỉ sửa logic liên quan đến điều kiện enable/disable của nút.
Bổ sung test cho tình huống gây lỗi và chạy các test liên quan.

Nhưng context đồng thời chứa hàng loạt hướng dẫn:

Release procedure

PR Review procedure

Security checklist

Migration rules

API checklist

Testing workflow

Trong ví dụ này, phần Testing workflow liên quan trực tiếp. Migration rules và API checklist chưa cần vì task không đụng đến database hay API. Release procedure và PR Review procedure cần khi đến bước release hoặc review. Các quy tắc bảo mật chung vẫn áp dụng, nhưng checklist chuyên biệt về xác thực hay phân quyền chưa liên quan đến lỗi trạng thái nút này.

Claude phải phân biệt instruction cần áp dụng ngay, instruction chỉ cần ở bước sau, và instruction nằm ngoài phạm vi thay đổi. Vấn đề không chỉ nằm ở số lượng token, mà là những chỉ dẫn quan trọng cho task hiện tại đang bị trộn lẫn với các hướng dẫn chưa cần dùng đến.

3.3. MẤT LỢI ÍCH CỦA PROGRESSIVE LOADING

Skills được thiết kế để Claude có thể biết Skill tồn tại và chỉ load nội dung khi cần.

Nếu mọi procedure đều được đưa thẳng vào CLAUDE.md, chúng ta đang bỏ qua lợi ích này.

Thay vì:

Load everything
↓
Claude tự tìm phần liên quan

có thể chuyển thành:

Load project rules
↓
Nhận diện task
↓
Load Skill phù hợp

4. CHECKLIST: INSTRUCTION NÊN ĐẶT Ở ĐÂU?

Không phải instruction nào cũng cần được Claude sử dụng trong mọi tác vụ. Tùy vào mục đích và phạm vi sử dụng, chúng ta có thể lựa chọn giữa CLAUDE.md và Skill.

Loại Instruction / Tác vụ	Vị trí phù hợp	Lý do
Package Manager (`pnpm`/`npm`)	`CLAUDE.md`	Thông tin nền cần biết khi làm việc với project.
Architecture Constraint	`CLAUDE.md`	Ràng buộc kiến trúc cần tuân thủ trong quá trình phát triển.
Naming Convention & Code Style	`CLAUDE.md`	Quy ước chung được sử dụng thường xuyên trong project.
PR / Code Review Process	Skill	Quy trình chuyên biệt dành cho tác vụ review.
Root Cause Analysis	Skill	Workflow nhiều bước phục vụ việc phân tích nguyên nhân lỗi.
Security Review Checklist	Skill	Checklist chuyên biệt khi thực hiện security review.
Release Note Process	Skill	Quy trình tạo release note theo các bước xác định.
API Review Checklist	Skill	Checklist được sử dụng khi thực hiện API review.

Hãy tự hỏi: “Claude có cần biết instruction này trong hầu hết các task của project không?”

Có → CLAUDE.md: Những thông tin nền, quy ước và ràng buộc chung mà Claude cần ghi nhớ khi làm việc với project.
Không → Xem xét Skill: Nếu đây là một workflow, procedure hoặc checklist dành cho một tác vụ chuyên biệt, Skill thường là lựa chọn phù hợp.

Ghi nhớ:

CLAUDE.md giúp Claude hiểu cách làm việc trong project.Skill hướng dẫn Claude thực hiện một công việc cụ thể.

Lưu ý: Đây là cách phân biệt cơ bản. Những instruction chỉ áp dụng cho một phần nhất định của project sẽ được giải thích chi tiết hơn ở mục 6.

5. REFACTOR CLAUDE.MD THÀNH CẤU TRÚC DỄ MAINTAIN HƠN

Giả sử ban đầu:

CLAUDE.md
├── Project architecture
├── Coding convention
├── API checklist
├── Testing procedure
├── Bug analysis procedure
├── PR review procedure
├── Security checklist
└── Release note procedure

Có thể refactor thành:

project/
│
├── CLAUDE.md
│
└── .claude/
    └── skills/
        ├── analyze-bug/
        │   └── SKILL.md
        │
        ├── review-pr/
        │   └── SKILL.md
        │
        ├── security-review/
        │   └── SKILL.md
        │
        └── release-note/
            └── SKILL.md

CLAUDE.md đóng vai trò Hub chứa global context và project rules.

Skills trở thành các Spoke chứa workflow dành cho từng loại task.

                 review-pr
                    │
                    │
analyze-bug ─── CLAUDE.md ─── security-review
                    │
                    │
               release-note

Infographic mô hình Hub & Spoke:

Trung tâm: CLAUDE.md – Global Context / Rules
Xung quanh: .claude/skills/ – Task-specific Workflows

Kết quả là chuyển từ: Một file cố gắng dạy Claude mọi thứ

Sang: Một lớp context nền + các workflow được nạp khi cần.

6. KHÔNG PHẢI MỌI THỨ ĐỀU LÀ CLAUDE.MD HOẶC SKILL

Trong thực tế Claude Code còn có hai cơ chế đáng chú ý.

Rule

Nếu instruction là một Rule nhưng chỉ áp dụng cho một nhóm file cụ thể, thì nên đặt trong .claude/rules/ và sử dụng paths để giới hạn phạm vi áp dụng.

Cách này giúp Claude chỉ áp dụng Rule cho những file liên quan, thay vì áp dụng cho toàn bộ project.

.claude/
└── rules/
    ├── frontend.md
    ├── backend.md
    └── testing.md

Claude Code hỗ trợ path-scoped rules và load rule khi làm việc với file phù hợp.

Ví dụ nội dung .claude/rules/frontend.md (Markdown với YAML frontmatter):

---
paths:
  - "frontend/**/*.tsx"
---

# React conventions

- Use function components and TypeScript.
- Follow the existing component naming conventions.

Hooks

Hooks là cơ chế tự động hóa trong Claude Code, giúp kích hoạt các hành động đã được cấu hình sẵn khi một sự kiện cụ thể xảy ra, thay vì phụ thuộc vào quyết định của AI.

Nếu requirement là: “Sau khi sửa source code, bắt buộc chạy formatter.” thì chỉ viết:

Always run formatter after editing files

trong CLAUDE.md không phải cách enforcement đáng tin cậy nhất.

Hooks được kích hoạt tại những thời điểm cụ thể trong vòng đời thực thi và phù hợp với các hành động cần được thực hiện một cách nhất quán, theo quy tắc xác định trước.

Ví dụ JSON trong .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "file=$(jq -r '.tool_input.file_path // empty'); if [ -n \"$file\" ]; then pnpm exec prettier --write --ignore-unknown \"$file\"; fi"
          }
        ]
      }
    ]
  }
}

Có thể phân loại:

Claude cần BIẾT
→ CLAUDE.md

Claude cần BIẾT khi làm một nhóm FILE
→ .claude/rules/

Claude cần BIẾT CÁCH LÀM một TASK
→ Skills

Một ACTION cần được thực thi tại lifecycle event
→ Hooks

Như vậy, mỗi cơ chế trong Claude Code đều có vai trò và phạm vi sử dụng riêng. CLAUDE.md cung cấp thông tin nền cho project, Rules áp dụng các quy tắc theo phạm vi file, Skills hướng dẫn thực hiện những tác vụ chuyên biệt, còn Hooks tự động kích hoạt hành động khi có sự kiện tương ứng.

Tuy nhiên, khi làm việc thực tế, không phải lúc nào cũng dễ xác định một instruction nên được đặt ở đâu.

Vậy làm thế nào để lựa chọn cơ chế phù hợp mà không khiến CLAUDE.md trở nên quá tải?

Phần tiếp theo sẽ tổng hợp những kiến thức trên thành một Decision Tree (sơ đồ quyết định), giúp bạn nhanh chóng xác định vị trí phù hợp cho từng loại instruction hoặc tác vụ.

7. DECISION TREE ĐƠN GIẢN

Trước khi thêm instruction mới, hãy hỏi:

Instruction này áp dụng gần như mọi task?
│
├─ Có → CLAUDE.md
│
└─ Không
    │
    ├─ Chỉ áp dụng cho một nhóm file?
    │      └─ Có → .claude/rules/
    │
    ├─ Là procedure/checklist của một task?
    │      └─ Có → Skill
    │
    └─ Là action cần tự động thực thi?
           └─ Có → Hook

Chỉ cần decision tree này cũng đã giúp tránh việc biến CLAUDE.md thành một Prompt Storage chứa mọi thứ của project.

8. KẾT LUẬN

Khi Claude làm sai, phản xạ thường gặp là: Thêm instruction.

Nhưng tối ưu Claude Code không chỉ nằm ở việc viết instruction tốt hơn.

Một câu hỏi quan trọng không kém là: Instruction đó nên xuất hiện ở đâu và vào thời điểm nào?

Một cấu trúc dễ maintain có thể là:

Minimal CLAUDE.md
        +
Scoped Rules
        +
Task-specific Skills
        +
Deterministic Hooks

Trong đó:

CLAUDE.md giữ project context và global rules.
.claude/rules/ giữ rule; thêm paths để giới hạn theo nhóm file.
Skills giữ procedure và knowledge cho từng loại task.
Hooks xử lý những action cần chạy tại lifecycle event cụ thể.

Nếu chỉ cần nhớ một nguyên tắc:

CLAUDE.md mô tả cách Claude nên làm việc trong project.Skill mô tả cách Claude thực hiện một loại công việc cụ thể.

Mục tiêu cuối cùng không phải làm Claude biết càng nhiều càng tốt.

Mà là: Cho Claude đúng context, đúng instruction, vào đúng thời điểm.

File CLAUDE.md trong project của bạn hiện đang dài bao nhiêu dòng? Bạn đang để toàn bộ workflow trong một file hay đã bắt đầu tách sang Skills?

1. CLAUDE.MD DÙNG CHO CONTEXT VÀ RULE XUYÊN SUỐT PROJECT

2. SKILLS DÙNG CHO PROCEDURE CỦA MỘT TASK

3. VÌ SAO KHÔNG NÊN ĐỂ TẤT CẢ TRONG CLAUDE.MD?

3.1. TỐN CONTEXT KHÔNG CẦN THIẾT

3.2. QUÁ NHIỀU INSTRUCTION CÓ THỂ LÀM GIẢM KHẢ NĂNG TUÂN THỦ

3.3. MẤT LỢI ÍCH CỦA PROGRESSIVE LOADING

4. CHECKLIST: INSTRUCTION NÊN ĐẶT Ở ĐÂU?

5. REFACTOR CLAUDE.MD THÀNH CẤU TRÚC DỄ MAINTAIN HƠN

6. KHÔNG PHẢI MỌI THỨ ĐỀU LÀ CLAUDE.MD HOẶC SKILL

Rule

Hooks

7. DECISION TREE ĐƠN GIẢN

8. KẾT LUẬN

NGUỒN THAM KHẢO

CLAUDE.md hay Skills: Nên đặt instruction cho Claude Code ở đâu?