Đã đăng vào khoảng 5 giờ trước 3 phút đọc

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

🧠 Giải Mã Thư Mục `.claude/` — Điều Khiển Claude Code Như Một Pro

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 Ưu Tiên

Project-level settings luôn ưu tiên hơn global
Team commit: .claude/settings.json, rules/, commands/ vào git
Ignore: conversations/, context/, cache/ (thêm vào .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.

✍️ Template CLAUDE.md

# 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

💡 Best Practices

✅ Làm	❌ Không Làm
Giữ dưới 200 dòng	File dài quá → giảm instruction adherence
Chạy `/init` để auto-generate	Viết từ đầu tay
Dùng `CLAUDE.local.md` cho preferences cá nhân	Commit preferences vào git

📏 `rules/` — Chia Nhỏ Instructions Theo Concern

Khi CLAUDE.md bắt đầu quá dài, dùng .claude/rules/ để tách ra thành các file riêng biệt:

.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/**
---

## React Component Guidelines

- 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`

💡 Lợi ích:

Rule 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:

📌 Ví Dụ: Review PR

<!-- .claude/commands/review.md -->

# Review PR Hiện Tại

Kiểm tra các thay đổi trong PR hiện tại:

`git diff main...HEAD`

## Checklist
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)

Dùng:

/project:review

Claude sẽ tự chạy git diff và review theo checklist.

🔧 Dynamic Input Với `$ARGUMENTS`

<!-- .claude/commands/fix-issue.md -->

# Fix Issue by Number

Fix issue #$ARGUMENTS:

`gh issue view $ARGUMENTS --json title,body`

Đọc issue, tìm file liên quan, implement fix, viết test.

Dùng:

/project:fix-issue 234

Claude tự fetch issue #234 và fix! 🚀

🎯 `skills/` — Auto-Triggered Workflows

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:

📁 Cấu Trúc Skill

.claude/skills/component-gen/
├── SKILL.md           # Skill definition
├── template.tsx       # Template files
└── examples/          # Reference examples

✍️ Ví Dụ: Component Generator Skill

# .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. **Component File** — TypeScript interface + JSX
2. **Test File** — Testing Library tests
3. **Storybook Story** — Interactive documentation
4. **Export** — từ index.ts

Xem template: `./template.tsx`

Khi nào trigger? Bất kỳ lúc nào Claude nghe thấy từ khóa "tạo component" → skill tự bật, không cần gõ command! ✨

🤖 `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]
---

## Vai Trò
Bạn là performance engineer chuyên frontend.

## Khi Được Gọi
1. **Bundle Size** — check package.json, imports
2. **Render Performance** — memo, useMemo, useCallback usage
3. **Image Optimization** — next/image, lazy loading
4. **Core Web Vitals** — patterns & metrics

## Output
Report với severity levels & fix suggestions.

🎮 Key Features

Field	Ý Nghĩa
`model`	Chọn model rẻ hơn (Haiku) cho task đơn giản
`tools`	Giới hạn agent chỉ được đọc, không được ghi

🪝 `hooks/` — Automation Không Cần Prompt

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

# .claude/hooks/
pre-edit:      # Backup file trước khi Claude sửa
post-edit:     # Auto-format sau mỗi file edit
pre-commit:    # Chạy lint trước khi commit

💡 Đặc Điểm

✅ Deterministic — scripts cố định, không phải AI-generated
✅ Consistency — đảm bảo output luôn giống nhau
✅ Fast — không cần gọi Claude, shell command trực tiếp

🧠 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

Cách hoạt động:

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 — Mastering `.claude/`

Component	Mục Đích
📝 CLAUDE.md	Instructions chính, dưới 200 dòng
📏 rules/	Tách instructions theo concern, path-scoped
⚡ commands/	Slash commands cho team workflows
🎯 skills/	Auto-triggered workflows với supporting files
🤖 agents/	Subagent chuyên biệt với tool restrictions
🪝 hooks/	Deterministic automation (shell scripts)
🧠 Auto Memory	Claude tự học qua sessions

🚀 Action Items

✅ Tạo CLAUDE.md cho project (hoặc chạy /init)
✅ Tách long instructions thành rules/
✅ Tạo frequently-used commands/
✅ Commit team-shared files vào git
✅ Gitignore personal + session files
✅ Monitor auto memory qua các 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. Thư mục .claude/ không phải black box, đó là control center để bạn customize Claude Code cho team!

📚 Tham Khảo

🧠 Giải Mã Thư Mục .claude/ — Điều Khiển Claude Code Như Một Pro

📋 Tổng Quan: 2 Cấp Độ .claude/