Claude Code 101: Hướng Dẫn Toàn Diện Từ Con Số 0

# Kiểm tra Node.js
node --version # phải >= 18
# Nếu chưa cài Node.js, cài từ nodejs.org hoặc dùng nvm:
# curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# nvm install 20
# Cài Claude Code toàn cục (khuyến nghị)
npm install -g @anthropic-ai/claude-code
# Hoặc chạy mà không cần cài (không cần cài đặt, nhưng chậm hơn)
npx @anthropic-ai/claude-code
# Kiểm tra cài đặt đã thành công
claude --version

claude
# Lần đầu chạy, Claude Code sẽ mở trình duyệt để bạn đăng nhập vào claude.ai
# Yêu cầu gói Pro hoặc Max (xem giá tại claude.ai/pricing)

export ANTHROPIC_API_KEY="sk-ant-..."
claude

# Di chuyển vào thư mục dự án
cd my-project
# Khởi động Claude Code
claude
# Hoặc chạy trực tiếp kèm prompt
claude "explain this codebase to me"

"sửa bug"

"Hàm calculateDiscount trong src/pricing.ts trả về giá âm khi
discount > 100%. Hãy sửa để nó throw ra lỗi khi discount không
hợp lệ (< 0 hoặc > 100), và thêm một unit test."

Trong cuộc trò chuyện chat, gõ:
"Xem qua @src/auth/login.ts và tìm các vấn đề bảo mật"
^ Khi bạn gõ @, VSCode sẽ gợi ý file/thư mục
"Giải thích @src/components/ hoạt động như thế nào"
"So sánh cách xử lý lỗi giữa @src/api/users.ts và @src/api/products.ts"

# Giải thích nhanh một file (dùng đường dẫn thật, không cần @)
claude "giải thích src/utils/parser.ts"
# Tìm bug
claude "tìm tất cả những chỗ có thể gây rò rỉ bộ nhớ trong src/"
# Review một PR
claude "review các thay đổi trong git diff này"

.claude/
├── CLAUDE.md ← bộ não của dự án
├── CLAUDE.local.md ← phiên bản riêng tư, không push lên GitHub
├── settings.json ← quyền hạn + hooks
├── settings.local.json ← cài đặt riêng tư
├── memory/ ← bộ nhớ cá nhân của Claude
├── rules/ ← các quy tắc chi tiết
│ ├── workflow.md
│ ├── design.md
│ └── tech-defaults.md
├── agents/ ← các sub-agent chuyên biệt
│ ├── researcher.md
│ └── reviewer.md
├── skills/
│ ├── shop-amazon.md
│ └── run-security-scan.sh
└── hooks/
├── pre-commit.sh
└── pre-push.sh

# API Thương Mại Điện Tử Của Tôi (Spring Boot)
## Tech Stack
- Java 21 + Spring Boot 3.x
- Spring Data JPA + Hibernate
- PostgreSQL (production), H2 (test)
- Maven
- JUnit 5 + Mockito + MockMvc để test
- Spring Security 6 (JWT)
- Spring Mail để gửi email
## Quy tắc code
- Tuân theo kiến trúc phân lớp: Controller → Service → Repository
- Dùng constructor injection, KHÔNG dùng field injection (`@Autowired`)
- Mỗi phương thức public của Service phải có unit test
- Xử lý exception tập trung qua `@RestControllerAdvice`
- Log bằng SLF4J (`private static final Logger log = ...`), KHÔNG dùng
`System.out.println`
## Cấu trúc thư mục
- `src/main/java/com/myapp/` — Mã nguồn chính
- `controller/` — REST controllers
- `service/` — Business logic
- `repository/` — JPA repositories
- `entity/` — JPA entities
- `dto/` — Request/Response DTOs
- `exception/` — Custom exceptions
- `src/main/resources/` — application.yml, migrations
- `src/test/java/` — Unit và integration test
## Workflow
1. Trước khi code: chạy `mvn compile`
2. Trước khi commit: chạy `mvn test`
3. Dùng conventional commits: feat/fix/chore/docs
## Không được làm
- Không commit trực tiếp vào main
- Không xóa các file migration Flyway
- Không đặt business logic trong Controller
- Không dùng `@Transactional` ở tầng Controller
## Database
- Development: `jdbc:postgresql://localhost:5432/myapp_dev`
- Chạy migration: Flyway tự động chạy khi app khởi động
- Tạo migration: thêm file `src/main/resources/db/migration/V{n}__description.sql`

echo ".claude/CLAUDE.local.md" >> .gitignore
echo ".claude/settings.local.json" >> .gitignore

# Cấu hình Local (không push lên GitHub)
## Credentials (chỉ dùng cho local dev)
- Stripe test key: sk_test_...
- Local database: postgresql://localhost:5432/myapp_local
## Ghi chú cá nhân
- Branch hiện tại: feature/payment-flow
- Todo: sửa bug #234 trước buổi demo thứ Sáu

# Workflow
## Trước khi bắt đầu một task mới
1. Đọc kỹ mô tả task
2. Hỏi lại nếu yêu cầu chưa rõ ràng
3. Tạo một plan ngắn gọn và xác nhận với tôi
## Khi viết code
- Viết test trước khi implement (TDD nếu có thể)
- Commit nhỏ và thường xuyên
- Mỗi commit chỉ nên làm một việc
## Khi gặp lỗi
- Đọc kỹ thông báo lỗi trước khi sửa
- Đừng đoán mò — hãy truy về tận gốc rễ vấn đề
- Nếu việc sửa lỗi mất > 30 phút, hãy báo lại cho tôi

# Tech Defaults
## Thiết kế REST API
- Định dạng response chuẩn: `{ "data": ..., "message": ..., "status": ... }`
- HTTP status code: 200 OK, 201 Created, 400 Bad Request, 401 Unauthorized, 404 Not
Found
- Phân trang: dùng `Pageable` của Spring Data, trả về `Page<T>`
- Validate input bằng `@Valid` + annotation Bean Validation
## Xử lý lỗi
- Toàn bộ exception được xử lý trong `GlobalExceptionHandler` (`@RestControllerAdvice`)
- Business exception: kế thừa `BaseBusinessException` với mã lỗi riêng
- Lỗi validation: trả về danh sách lỗi field rõ ràng
- KHÔNG để stack trace lộ ra trong response
## Tiêu chuẩn Testing
- Unit test: mock dependency bằng Mockito, không cần Spring context
- Integration test: dùng `@SpringBootTest` + `MockMvc`, dùng DB in-memory H2
- Coverage tối thiểu: 80% cho tầng Service
- Đặt tên test method: `methodName_whenCondition_thenExpectedResult`
## Hiệu năng
- Dùng `@Transactional(readOnly = true)` cho các method chỉ query
- Tránh N+1 query: dùng `JOIN FETCH` hoặc `@EntityGraph`
- Cache bằng Spring Cache (`@Cacheable`) cho dữ liệu ít thay đổi

Claude wants to run: npm test
Allow? [y/n/always]

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(npx prisma *)",
      "Read(**)",
      "Edit(**)",
      "Write(**)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Bash(DROP TABLE *)"
    ]
  }
}

{
  "permissions": {
    "allow": [
      "Bash(npm *)",
      "Bash(npx *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Bash(git checkout *)",
      "Bash(git branch *)",
      "Read(**)",
      "Edit(**)",
      "Write(**)"
    ],
    "deny": [
      "Bash(git push --force *)",
      "Bash(git reset --hard *)",
      "Bash(rm -rf *)"
    ]
  }
}

/compact
# Claude sẽ tóm tắt toàn bộ cuộc trò chuyện và tiếp tục
# Context nhỏ lại, nhưng ngữ cảnh của task vẫn được giữ nguyên

/clear
# Sau đó cung cấp context cụ thể cho task mới
"Context: Tôi đang xây dựng tính năng thanh toán cho một app
thương mại điện tử.
Tech stack: Next.js + Stripe + Prisma.
File liên quan: @src/app/checkout/ @src/lib/stripe.ts
Task: ..."

.claude/memory/
├── user_preferences.md ← các sở thích làm việc của bạn
├── project_decisions.md ← các quyết định đã đưa ra
└── ongoing_tasks.md ← công việc đang thực hiện

@import .claude/memory/project_decisions.md

# Các quyết định của dự án
## Authentication
- Dùng Spring Security 6 + JWT (stateless)
- Thời hạn token: access token 15 phút, refresh token 7 ngày
- Không dùng Spring Session (quyết định vào tháng 3/2025)
## Database Schema
- Một User có thể có nhiều địa chỉ (1-n, FetchType.LAZY)
- Trạng thái Order: PENDING → CONFIRMED → SHIPPED → DELIVERED → CANCELLED
- Soft delete cho mọi entity: thêm cột `deleted_at`, dùng `@SQLRestriction`
## Thiết kế API
- API RESTful thuần túy, versioning qua URL `/api/v1/...`
- Không dùng GraphQL (đã quyết định — không cần overhead này ở quy mô hiện
tại)
- Các lời gọi service nội bộ dùng Feign Client (đã thiết lập sẵn trong
`infrastructure/client/`)

/review # Review code theo tiêu chuẩn của dự án
/security-review # Kiểm tra các vấn đề bảo mật
/init # Khởi tạo CLAUDE.md cho dự án mới

<!-- .claude/skills/deploy-check.md -->
Kiểm tra tất cả các điều kiện trước khi deploy:
1. Chạy `npm run typecheck` — phải pass 100%
2. Chạy `npm test` — phải pass 100%
3. Kiểm tra không có `console.log` trong `src/`
4. Kiểm tra không có credentials hardcode
5. Xem lại `CHANGELOG.md` đã được cập nhật chưa
6. Báo cáo kết quả theo định dạng này:
- ✅ Pass: [tên kiểm tra]
- ✅ Fail: [tên kiểm tra] — [lý do]

/deploy-check

# Thêm một MCP server qua terminal (bên ngoài Claude Code)
claude mcp add github -- npx -y @modelcontextprotocol/server-github
# Kiểm tra MCP đã được cài đặt chưa
claude mcp list

// .claude/settings.json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

"Liệt kê các issue đang mở trong repo này và sắp xếp theo độ ưu tiên"
"Tạo một PR từ branch feature/payment sang main với mô tả
tự động tạo từ git diff"
"Review PR #42 và comment vào những chỗ cần sửa"

"Gửi một tin nhắn vào kênh #dev-team: 'Deploy v2.1.0 lên staging đã
thành công'"
"Đọc thread trong #bugs về lỗi đăng nhập hôm qua và tóm tắt lại cho tôi"

# Sau khi cài đặt MCP database
"Lấy 10 user có nhiều đơn hàng nhất trong tháng 4/2025"
"Có bao nhiêu đơn hàng đang ở trạng thái 'pending' quá 24 giờ?"
"Tạo một migration để thêm cột `referral_code` vào bảng users"

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

// .claude/settings.json
{
  "hooks": {
    "postToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/format-on-save.sh"
          }
        ]
      }
    ]
  }
}

# .claude/hooks/format-on-save.sh
#!/bin/bash
# Claude Code truyền context qua stdin dưới dạng JSON
INPUT=$(cat)
FILE=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin);
print(d.get('tool_input',{}).get('file_path',''))" 2>/dev/null)
if [[ "$FILE" == *.java ]]; then
  # Dùng google-java-format để format Java (phải cài đặt trước)
  # Tải về: https://github.com/google/google-java-format/releases
  java -jar ~/.local/bin/google-java-format.jar --replace "$FILE"
  echo "✅ Đã format: $FILE"
fi

# .claude/hooks/pre-commit.sh
#!/bin/bash
set -e
echo "✅ Đang chạy kiểm tra pre-commit..."
# Kiểm tra compile
echo "Đang compile..."
mvn compile -q
if [ $? -ne 0 ]; then
  echo "✅ Compile thất bại. Hủy commit."
  exit 1
fi
# Test
echo "Đang chạy test..."
mvn test -q
if [ $? -ne 0 ]; then
  echo "✅ Test thất bại. Hủy commit."
  exit 1
fi
# Kiểm tra System.out.println
if grep -r "System\.out\.println" src/main/ --include="*.java"; then
  echo "⚠ Phát hiện System.out.println trong code production. Hãy dùng logger
SLF4J thay thế."
  exit 1
fi
echo "✅ Tất cả kiểm tra đã pass!"

# .claude/hooks/pre-push.sh
#!/bin/bash
BRANCH=$(git branch --show-current)
# Không cho phép push thẳng vào main
if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
  echo "✅ Không được phép push trực tiếp vào $BRANCH!"
  echo "Hãy tạo một PR thay vì push trực tiếp."
  exit 1
fi
echo "✅ Branch $BRANCH OK để push"

// .claude/settings.json
{
  "hooks": {
    "preToolUse": [
      {
        "matcher": "Bash(git push*)",
        "hooks": [
          {
            "type": "command",
            "command": "bash .claude/hooks/pre-push.sh"
          }
        ]
      }
    ]
  }
}

# Researcher Agent
Chuyên gia nghiên cứu và phân tích. Dùng khi bạn cần tìm hiểu về
một thư viện, so sánh các lựa chọn, hoặc phân tích một codebase.
---
Bạn là một senior engineer chuyên về nghiên cứu và phân tích kỹ thuật.
## Trách nhiệm
- Phân tích và so sánh các giải pháp kỹ thuật
- Nghiên cứu thư viện, framework và best practice
- Đọc và tóm tắt tài liệu
- Phân tích codebase hiện tại
## Cách làm việc
1. Luôn đọc source code trước khi đưa ra ý kiến
2. Đưa ra ưu/nhược điểm cụ thể, kèm số liệu nếu có thể
3. Đưa ra khuyến nghị rõ ràng, giải thích lý do
4. Nếu không chắc, hãy nói rõ "Tôi không chắc về điều này"
## Định dạng đầu ra
- Bắt đầu bằng TL;DR (1-2 câu)
- Theo sau là phân tích chi tiết
- Kết thúc bằng một khuyến nghị rõ ràng

# Reviewer Agent
Một reviewer code khắt khe. Dùng trước khi merge code để tìm bug,
vấn đề bảo mật, và vi phạm quy ước.
---
Bạn là một senior engineer review code cực kỳ kỹ lưỡng.
## Tiêu chí review
1. **Bảo mật**: SQL injection, XSS, auth bypass, rò rỉ dữ liệu
2. **Hiệu năng**: N+1 query, re-render không cần thiết, memory leak
3. **Tính đúng đắn**: Lỗi logic, edge case chưa xử lý
4. **Quy ước**: Tuân thủ CLAUDE.md và coding standard
5. **Test**: Coverage đã đủ chưa, test có ý nghĩa không
## Định dạng đầu ra
Với mỗi vấn đề tìm thấy:
- ✅ Critical: phải sửa trước khi merge
- ✅ Warning: nên sửa, có thể merge nhưng cần theo dõi
- ✅ Suggestion: cải thiện tùy chọn
Kết thúc bằng: APPROVED / NEEDS CHANGES / REJECTED

# Claude chính sẽ tự quyết định khi nào dùng sub-agent
"Nghiên cứu và so sánh React Query với SWR cho dự án này"
# → Claude sẽ gọi researcher agent
"Review tất cả thay đổi trong PR này"
# → Claude sẽ gọi reviewer agent

"Dùng researcher agent để phân tích @src/auth/ và tìm các vấn đề tiềm ẩn"

# Task: Migrate từ REST sang GraphQL
# Bước 1: Giai đoạn nghiên cứu
"Dùng researcher agent: phân tích codebase hiện tại và ước tính
công sức để migrate sang GraphQL"
# Bước 2: Claude chính lên kế hoạch dựa trên nghiên cứu
"Dựa trên nghiên cứu, tạo một kế hoạch migrate theo từng giai đoạn"
# Bước 3: Implement
"Implement Giai đoạn 1: thiết lập GraphQL server"
# Bước 4: Review
"Dùng reviewer agent: review toàn bộ code vừa implement trong
@src/graphql/"

# Trong cuộc trò chuyện
/model
# Hoặc đặt mặc định trong config
/config

/fast
# Bật Fast Mode: dùng Opus với tốc độ đầu ra nhanh hơn
# Không hạ xuống model nhỏ hơn

# Đừng dùng Opus để format code
# Đừng dùng Haiku để thiết kế kiến trúc

# Sau khi hoàn thành một task lớn, /clear và bắt đầu lại
# Đừng kéo dài cuộc trò chuyện không cần thiết

# Tệ: "sửa code của tôi" → Claude phải đọc nhiều, hỏi nhiều
# Tốt: "sửa bug trong hàm X, file Y, dòng Z" → ít token hơn

/cost # Xem đã dùng bao nhiêu trong phiên làm việc

# 1. Di chuyển vào dự án
cd my-ecommerce-api
# 2. Khởi động Claude Code
claude
# 3. Kiểm tra context (Claude sẽ tự động đọc CLAUDE.md)
"Bạn đã đọc CLAUDE.md chưa? Tóm tắt dự án này dùng những gì"

"Phân tích src/main/java/com/myapp/auth/ và cho tôi biết:
1. Authentication hiện đang được implement như thế nào (cấu hình
Spring Security, JWT flow)
2. Cần những gì để thêm API Quên mật khẩu
3. Ước tính công sức (giờ)
Chưa viết code, chỉ phân tích thôi"

"OK, thêm yêu cầu này:
- Reset token chỉ có hiệu lực trong 1 giờ
- Gửi email qua Spring Mail (config đã có sẵn, xem
src/main/java/com/myapp/infrastructure/email/)
- Rate limit: tối đa 3 request/giờ cho mỗi email (dùng Bucket4j
hoặc Redis)
Bây giờ hãy tạo một kế hoạch chia thành các bước nhỏ theo kiến
trúc phân lớp"

# Bước 1: Entity + Migration
"Implement Bước 1:
- Tạo JPA Entity PasswordResetToken với các field: id, user
(ManyToOne), token, expiresAt, usedAt
- Tạo file migration Flyway tương ứng trong
src/main/resources/db/migration/"

"Compile dự án để kiểm tra không có lỗi"
# → Claude chạy: mvn compile
# Nếu có lỗi, Claude sẽ tự động sửa

# Bước 2: Repository + Service
"Implement Bước 2:
- PasswordResetTokenRepository (Spring Data JPA)
- ForgotPasswordService với các phương thức sau:
+ initiatePasswordReset(email): validate, tạo token, gửi email
+ validateToken(token): kiểm tra tồn tại, chưa dùng, chưa hết hạn
+ resetPassword(token, newPassword): validate token rồi cập nhật
mật khẩu
- Viết unit test cho ForgotPasswordService bằng Mockito"

# Bước 3: Controller
"Implement Bước 3 - REST Controller với 2 endpoint:
- POST /api/v1/auth/forgot-password body: { email }
- POST /api/v1/auth/reset-password body: { token, newPassword,
confirmPassword }
Thêm annotation Bean Validation cho các request DTO
Xử lý exception qua GlobalExceptionHandler đã có sẵn"

# Review thủ công (thường dùng)
"Review toàn bộ code vừa viết trong
src/main/java/com/myapp/auth/password/ tập trung vào các vấn đề
bảo mật: độ ngẫu nhiên của token, timing attack, rò rỉ thông tin"
# Hoặc dùng reviewer agent nếu đã tạo sẵn
"Dùng reviewer agent để kiểm tra code vừa implement"

"Viết integration test với @SpringBootTest + MockMvc cho toàn bộ
luồng quên mật khẩu:
1. POST /forgot-password với email hợp lệ → 200 OK (không tiết lộ
user có tồn tại hay không)
2. POST /forgot-password với email không hợp lệ → 400 Bad Request
3. POST /forgot-password quá 3 lần trong 1 giờ → 429 Too Many
Requests
4. POST /reset-password với token hợp lệ → 200 OK, mật khẩu được
cập nhật
5. POST /reset-password với token đã hết hạn → 400 Bad Request
6. POST /reset-password với token đã dùng rồi → 400 Bad Request
Dùng DB in-memory H2, mock email service để không gửi email thật"

"Chạy toàn bộ test suite và sửa các lỗi nếu có"
# → Claude chạy: mvn test

# Bước 1: Commit theo conventional commits
"Commit tất cả thay đổi. Định dạng message:
feat: Add forgot password API
- PasswordResetToken entity + Flyway migration
- ForgotPasswordService với rate limiting
- REST endpoint POST /forgot-password và /reset-password
- Unit test + integration test"
# Bước 2: Push lên branch
"git push origin feature/forgot-password"
# → Claude sẽ chạy lệnh này

"Tạo một PR từ feature/forgot-password sang main với mô tả sau:
- **What:** Thêm đầy đủ API quên mật khẩu
- **Why:** Cho phép user khôi phục tài khoản khi quên mật khẩu
- **API:**
+ POST /api/v1/auth/forgot-password
+ POST /api/v1/auth/reset-password
- **Testing:**
1. mvn test — tất cả test pass
2. Test thủ công với Postman (collection đã có sẵn trong
/docs/postman/)
- **Checklist:**
- [ ] Test pass (mvn test)
- [ ] Compile sạch (mvn compile)
- [ ] Không có System.out.println
- [ ] Migration Flyway đặt tên đúng quy ước"

{
  "permissions": {
    "allow": [
      "Bash(mvn *)",
      "Bash(git status)",
      "Read(**)",
      "Edit(**)"
    ]
  }
}

# 1. Kiểm tra MCP đã được cài đặt chưa
claude mcp list
# 2. Kiểm tra auth token (nếu cần)
echo $GITHUB_TOKEN # hoặc API key khác
# 3. Khởi động lại Claude Code
# Đóng phiên làm việc, chạy lại: claude

"Sửa bug này, đảm bảo mvn compile pass 100%"
# Claude sẽ chạy compile để kiểm tra

// Đúng
{
  "permissions": {
    "allow": ["Bash(mvn *)", "Read(**)", "Edit(**)"]
  }
}
// Sai (chỉ được ghi nhớ trong phiên làm việc này)
// Trả lời "always" khi được hỏi

# Tốt: hook chạy formatter, không thay đổi logic
#!/bin/bash
npx prettier --write "$FILE"

# Xấu: hook có thể fail âm thầm
npx prettier --write "$FILE" || true # Nguy hiểm!