CLAUDE.md vs. Auto Memory#

Nguyên tắc: Viết CLAUDE.md cho những điều bạn biết chắc. Để auto memory xử lý những điều agent khám phá ra.

Đặt File Ở Đâu#

Anatomy của Một CLAUDE.md Tốt#

1
# Tổng quan dự án
2

3
Flutter mobile app cho [chức năng].
4
Tech stack: Flutter 3.24+, Dart 3.5+, Firebase, Riverpod.
5

6
## Build & Run
7

8
- Build: `flutter build apk --release`
9
- Run (dev): `flutter run`
10
- Test: `flutter test`
11
- Lint: `dart fix --apply`
12

13
## Architecture
14

15
- State: Riverpod (không BLoC, không Provider)
16
- Navigation: GoRouter với shell routes
17
- DI: Riverpod providers (không GetIt)
18
- API: Dio với interceptor-based auth
19

20
## Code Style
21

22
- `sealed class` cho state classes
23
- `AsyncValue` thay vì `FutureBuilder`
24
- Error handling: `Either<Failure, T>` từ repositories
25
- Không `print()` — dùng `Logger` từ `logging` package
26

27
## Không bao giờ
28

29
- Không dùng `BuildContext` ngoài widget tree
30
- Không import `material.dart` trong domain layer
31
- Không commit `print()` statements
32
- Không generate code với `build_runner` bằng tay

Templates Theo Stack#

1
# Build
2
- Dev: `flutter run -t lib/main_dev.dart`
3
- Test: `flutter test --coverage`
4
- Build: `flutter build apk --split-per-abi`
5
- Format: `dart format .`
6

7
# Conventions
8
- State: Riverpod (không BLoC, không Provider)
9
- Navigation: GoRouter
10
- API: Dio với interceptor-based token refresh
11
- Models: toJson/fromJson tự viết (không json_serializable)
12
- Errors: sealed class Result<T>
13

14
# Không bao giờ
15
- Không dùng BuildContext sau async gap
16
- Không đặt BuildContext trong providers
17
- Không dùng dynamic

1
- Dev: `npm run dev`
2
- Test: `npm test`
3
- Build: `npm run build`
4
- Path aliases: `@/app`, `@/components`, `@/lib`
5
- Styling: Tailwind (không styled-components)
6
- Data: React Query (không SWR)
7
- Components: Server components mặc định
8
- Không default exports — chỉ named exports

Hooks: Vũ Khí Cao Cấp Hơn#

CLAUDE.md bảo agent bạn muốn gì. Hooks bảo agent nó phải làm gì. Scripts chạy ở các điểm cụ thể trong workflow:

1
#!/bin/bash
2
if echo "$@" | grep -E '(api_key|secret|token|password)=' > /dev/null 2>&1; then
3
  echo "❌ Blocked: committing secrets is không được phép"
4
  exit 1
5
fi
6
exit 0

Skills: Lệnh Tái Sử Dụng#

Skills là các CLAUDE.md-concise cho tác vụ cụ thể. Gọi qua slash command:

1
/changelog       — Generate CHANGELOG.md
2
/pr-describe     — Viết PR description từ git diff
3
/test-triage     — Tìm functions chưa có test
4
/docs-from-code  — Parse comments → markdown docs

Auto Memory: Để Agent Học Hỏi#

Khi bạn sửa lỗi cho agent, nó ghi correction đó vào memory file. Session sau, nó bắt đầu với kiến thức đó.

Ví dụ auto-memory entries:

• “Chạy flutter test --coverage, không phải flutter test”
• “Dùng Logger từ logging package, không phải print()”

Auto memory giới hạn 200 dòng / 25KB. Dùng cho preferences khám phá được — không phải rules nên viết vào CLAUDE.md.

Hiệu Quả Thực Tế#

Benchmark trên Next.js codebase:

Kết luận: 20 phút viết CLAUDE.md tiết kiệm hàng giờ mỗi ngày và giảm một nửa chi phí.

Những Sai Lầm Thường Gặp#

Bắt Đầu Trong 10 Phút#

1
# 1. Tạo CLAUDE.md
2
cat > CLAUDE.md << 'EOF'
3
# [Dự án của bạn]
4
Tech stack: Flutter 3.24 / Dart 3.5, Riverpod, GoRouter
5

6
## Build & Run
7
- Dev: flutter run -t lib/main_dev.dart
8
- Test: flutter test --coverage
9
- Build: flutter build apk --release
10
- Format: dart format .
11

12
## Conventions
13
- State: Riverpod (không BLoC, không GetIt)
14
- API: Dio với interceptors
15
- Errors: sealed class Result<T>
16
- Tests: mocktail (không mockito)
17

18
## Không bao giờ
19
- Không dùng BuildContext sau async gap
20
- Không commit print()
21
- Không generate code với build_runner bằng tay
22
EOF
23

24
# 2. Add vao git
25
git add CLAUDE.md && git commit -m "Add CLAUDE.md"
26

27
# 3. Test
28
claude "Bạn thấy gì về dự án này?"

Kết Luận#

CLAUDE.md là file có đòn bẩy cao nhất trong phát triển phần mềm với AI. Tốn 20 phút để viết, tiết kiệm hàng giờ mỗi ngày. Loại bỏ vấn đề “giải thích lại từ đầu mỗi session.” Làm cho việc dùng agent của cả đội nhất quán. Và giảm chi phí bằng cách ngăn chặn sai framework, sai tool, sai pattern.

Nếu bạn đang dùng AI coding agent mà không có CLAUDE.md, bạn đang trả gấp đôi — một lần bằng token cost, một lần bằng sự bực mình. Viết nó ngay hôm nay.

Các template CLAUDE.md trong bài được điều chỉnh từ claude-code-best-practices repository và tài liệu CLAUDE.md của Anthropic.