Giải Mã Thư Mục .claude/ — Cấu Trúc Project Claude Code Mà Mọi Frontend Dev Cần Biết

Nếu bạn đang dùng Claude Code, chắc hẳn bạn đã thấy thư mục .claude/ xuất hiện ở root project. Hầu hết dev coi nó như black box — biết nó tồn tại nhưng chưa bao giờ mở ra xem.

Đó là một sai lầm. .claude/ chính là "bộ não" quyết định Claude hoạt động thế nào trong project của bạn. Hiểu nó = kiểm soát được AI teammate.

Tổng quan: 2 cấp độ .claude/

Claude Code có 2 thư mục .claude/ hoạt động đồng thời:

~/.claude/                    # 🏠 Global — cá nhân, áp dụng tất cả projects
├── CLAUDE.md                 # Preferences cá nhân
├── commands/                 # /user:xxx commands
├── skills/                   # Skills cá nhân
├── agents/                   # Agent definitions
└── rules/                    # Rules cá nhân

my-project/.claude/           # 📦 Project — team shared, commit vào git
├── settings.json             # Permissions config
├── rules/                    # Modular instructions
├── commands/                 # /project:xxx commands
├── skills/                   # Auto-triggered workflows
├── agents/                   # Subagent definitions
├── hooks/                    # Event automation
└── conversations/            # Thread history (gitignored)

Nguyên tắc: Project-level settings luôn ưu tiên hơn global. Team commit .claude/settings.json, rules/, commands/ vào git. Còn conversations/, context/, cache/ thì gitignore.

CLAUDE.md — File quan trọng nhất

Mỗi session, Claude đọc CLAUDE.md đầu tiên và giữ trong context suốt cuộc hội thoại. Bạn viết gì ở đây, Claude sẽ tuân theo.

# CLAUDE.md

## Tech Stack
- Next.js 15 App Router + TypeScript strict
- Tailwind CSS v4 + shadcn/ui
- Prisma ORM + PostgreSQL

## Commands
- npm run dev — start dev server
- npm run test — run Vitest
- npm run lint — ESLint + Prettier

## Conventions
- Prefer Server Components, chỉ dùng "use client" khi thật sự cần
- Naming: kebab-case cho files, PascalCase cho components
- Luôn dùng Result pattern, không throw errors
- Import order: react → next → libs → local → types

## Architecture
- src/components/ui/ — reusable UI (shadcn)
- src/components/features/ — feature-specific
- src/actions/ — server actions
- src/lib/ — utilities, configs

Tips:

• Giữ dưới 200 dòng — file dài quá sẽ giảm instruction adherence
• Chạy /init để Claude tự generate CLAUDE.md ban đầu
• Dùng CLAUDE.local.md cho preferences cá nhân (auto gitignored)

rules/ — Chia nhỏ instructions theo concern

Khi CLAUDE.md bắt đầu quá dài, dùng .claude/rules/ để tách ra:

.claude/rules/
├── api-conventions.md      # API rules — luôn load
├── testing.md              # Testing standards — luôn load
└── backend-only.md         # Chỉ load khi sửa backend/

Killer feature: Path-scoped rules. Thêm YAML frontmatter để rule chỉ active với file cụ thể:

# .claude/rules/react-components.md
---
paths:
  - src/components/**
  - src/app/**
---
- Mỗi component phải có PropTypes hoặc TypeScript interface
- Dùng forwardRef cho components nhận ref
- Test file đặt cạnh component: Button.test.tsx

Rule này chỉ load khi Claude đang sửa file trong src/components/ hoặc src/app/. Sửa file utils? Không load. Tiết kiệm context, tăng accuracy.

commands/ — Custom slash commands cho team

Mỗi file .md trong .claude/commands/ trở thành slash command:

<!-- .claude/commands/review.md -->
Review các thay đổi trong PR hiện tại:

`git diff main...HEAD`

Kiểm tra:
1. TypeScript errors
2. Missing error handling
3. Performance issues (unnecessary re-renders)
4. Accessibility (aria labels, keyboard nav)

Output format: danh sách issues theo severity (critical/warning/info)

Giờ gõ /project:review — Claude tự chạy git diff và review theo checklist. Cú pháp `command` (backtick) sẽ chạy shell command và inject output vào prompt.

Dùng $ARGUMENTS cho dynamic input:

<!-- .claude/commands/fix-issue.md -->
Fix issue #$ARGUMENTS:
`gh issue view $ARGUMENTS --json title,body`
Đọc issue, tìm file liên quan, implement fix, viết test.

Chạy: /project:fix-issue 234 → Claude tự fetch issue #234 và fix.

skills/ — Claude tự trigger khi nhận diện context

Khác với commands (bạn phải gõ), skills tự kích hoạt khi Claude nhận ra task phù hợp:

# .claude/skills/component-gen/SKILL.md
---
name: component-gen
description: Generate React component với TypeScript, tests, và Storybook
triggers:
  - "tạo component"
  - "generate component"
  - "new component"
---
Khi tạo React component mới:
1. Tạo component file với TypeScript interface
2. Tạo test file dùng Testing Library
3. Tạo Storybook story
4. Export từ index.ts

Template: xem ./template.tsx

Skill là thư mục (không phải file đơn lẻ) — có thể chứa templates, scripts, reference docs bên cạnh SKILL.md.

agents/ — Subagent chuyên biệt

Định nghĩa "chuyên gia" mà Claude có thể spawn khi cần:

# .claude/agents/perf-auditor.md
---
name: Performance Auditor
model: claude-sonnet-4-6
tools: [Read, Grep, Glob, WebSearch]
---
Bạn là performance engineer chuyên frontend.
Khi được gọi:
1. Scan bundle size (check package.json, imports)
2. Tìm unnecessary re-renders (memo, useMemo, useCallback usage)
3. Check image optimization (next/image, lazy loading)
4. Audit Core Web Vitals patterns
Output: report với severity levels và fix suggestions.

Key: field tools giới hạn agent chỉ được đọc, không được ghi. Field model cho phép dùng model rẻ hơn (Haiku) cho task đơn giản.

hooks/ — Automation không cần prompt

Hooks chạy shell scripts tự động khi Claude thực hiện action cụ thể:

• Pre-edit hook: Backup file trước khi Claude sửa
• Post-edit hook: Auto-format sau mỗi file edit
• Pre-commit hook: Chạy lint trước khi commit

Hooks là deterministic (scripts cố định), không phải AI-generated — đảm bảo consistency.

Auto Memory — Claude tự ghi nhớ

Ngoài CLAUDE.md (bạn viết), Claude còn có auto memory — tự ghi lại learnings từ các session:

• Build commands đã chạy thành công
• Debug patterns phát hiện được
• Preferences bạn correct trong conversation

Auto memory load tự động mỗi session (200 dòng đầu hoặc 25KB). Bạn không cần làm gì — Claude tự học.

Checklist: Commit gì, Gitignore gì?

# ✅ Commit vào git (team shared)
CLAUDE.md
.claude/settings.json
.claude/rules/
.claude/commands/
.claude/skills/
.claude/agents/

# ❌ Thêm vào .gitignore
CLAUDE.local.md
.claude/settings.local.json
.claude/conversations/
.claude/context/
.claude/cache/
.claude/state.db

Tổng kết

Thư mục .claude/ không phải black box — nó là control center để bạn customize Claude Code cho team:

1. 📝 CLAUDE.md — Instructions chính, dưới 200 dòng
2. 📏 rules/ — Tách instructions theo concern, path-scoped
3. ⚡ commands/ — Slash commands cho team workflows
4. 🎯 skills/ — Auto-triggered workflows với supporting files
5. 🤖 agents/ — Subagent chuyên biệt với tool restrictions
6. 🪝 hooks/ — Deterministic automation
7. 🧠 Auto memory — Claude tự học qua sessions

Master được cấu trúc này = master được AI teammate. Đừng để Claude chạy "mặc định" — hãy configure nó đúng cách.

Nguồn tham khảo: Claude Code Docs, Daily Dose of DS