Coding Agent Mastery — Tư duy, prompt và patterns làm việc hiệu quả

npm install -g @anthropic-ai/claude-code
cd your-project
claude

your-project/
├── .claude/
│   ├── CLAUDE.md          # rules cho claude code
│   └── commands/          # custom slash commands
├── .cursor/
│   └── rules/             # .mdc rules cho Cursor
├── docs/
│   ├── ARCHITECTURE.md    # context quan trọng nhất
│   └── specs/             # feature specs
├── src/
└── tests/

# Project: E-commerce API (Node.js + TypeScript)

## Stack
- Runtime: Node.js 20, TypeScript strict mode
- Framework: Fastify (KHÔNG dùng Express)
- DB: PostgreSQL via Prisma ORM
- Auth: JWT + refresh tokens
- Testing: Vitest, coverage > 80%

## Architecture
- Clean Architecture: domain / application / infrastructure
- Không để business logic trong route handlers
- Tất cả DB calls phải qua repository pattern

## Conventions
- Naming: camelCase cho functions/vars, PascalCase cho types/classes
- Files: kebab-case (user-service.ts, không userService.ts)
- Error handling: custom error classes, không throw generic Error
- Async: async/await, tránh .then() chains
- Comments: chỉ comment "tại sao", không comment "cái gì"

## Agent Behavior
- Trước khi implement: tóm tắt approach và hỏi confirm nếu thay đổi lớn
- Luôn viết unit tests cho function mới
- Nếu thấy bug ngoài scope task: comment TODO, không tự sửa
- Không thêm dependencies mới mà chưa hỏi
- Prefer immutability: const > let, readonly khi có thể

## KHÔNG được
- Thay đổi database schema mà không có migration file
- Xóa hoặc rename public API endpoints
- Disable TypeScript strict checks
- Commit credentials, API keys vào code
- Dùng any type — dùng unknown nếu cần

Viết API endpoint tạo user

Context: Đang build user management cho SaaS app.
Đã có: UserRepository (src/repositories/user.repo.ts),
AuthService (src/services/auth.service.ts)

Action: Tạo POST /users endpoint trong src/routes/users.ts

Result cần:
- Validate input: email (unique), password (min 8 chars), name
- Hash password qua AuthService.hashPassword()
- Lưu qua UserRepository.create()
- Return: { id, email, name, createdAt } (không return password)
- Error handling: 400 nếu validation fail, 409 nếu email đã tồn tại

Exclusion: Không tự tạo JWT, không implement login ở đây

Test: Viết test cho happy path + email duplicate + validation error

Trước khi code, hãy:
1. List tất cả files cần đọc để hiểu context
2. Mô tả approach ngắn gọn
3. List potential side effects
4. Sau đó mới bắt đầu implement

Tạo config loader.

KHÔNG làm như này:
- if (env === 'production') { ... } else { ... }
- require('./config.json')
- process.env.MY_VAR || 'default'

Thay vào đó: centralized config object với Zod validation

Sau khi xong, trả lời theo format:

## Changes
- [file] [reason]

## Testing
- Lệnh để chạy test
- Expected output

## Potential issues
- Điều gì cần chú ý khi deploy?

Implement UserService tương tự cách ProductService
đã được implement trong @src/services/product.service.ts.
Giữ nguyên pattern dependency injection và error handling.

Đây là spec feature [tên feature]:
[paste spec]

Hãy phân tích và trả lời:
1. Danh sách acceptance criteria (numbered)
2. Danh sách technical tasks (ordered by dependency)
3. Files cần tạo mới / sửa
4. Potential risks và edge cases
5. Questions cần clarify trước khi code

# Feature: User Authentication

## Tasks (ordered)
1. [ ] Create User model + migration
2. [ ] Implement UserRepository
3. [ ] Implement AuthService (hash, jwt)
4. [ ] Create /register endpoint
5. [ ] Create /login endpoint
6. [ ] Create auth middleware
7. [ ] Protect existing routes
8. [ ] Integration tests

## Acceptance Criteria
- [ ] User có thể register với email/password
- [ ] Login trả về JWT valid 24h
- [ ] Token được verify ở protected routes
- [ ] Sai password trả về 401

Thực hiện task #3 trong TASKS.md:
'Implement AuthService (hash, jwt)'

Đọc:
- @TASKS.md để biết context toàn dự án
- @src/types/user.types.ts để biết User type
- @src/config/index.ts để lấy JWT_SECRET

Khi xong: update TASKS.md, tick [x] vào task #3

# Spec: [Tên feature]

## Overview
[1-2 câu mô tả]

## User story
As [người dùng], I want [action], so that [benefit]

## Functional requirements
- FR1: ...
- FR2: ...

## Non-functional requirements
- Performance: response time dưới 200ms
- Security: ...

## API Design (nếu có)
POST /api/endpoint
Request: { ... }
Response 200: { ... }

## Out of scope
- Những gì KHÔNG implement trong sprint này

## Definition of Done
- [ ] Unit tests viết xong
- [ ] Integration test pass
- [ ] Code review approved

Spawn 3 sub-agents chạy song song:
Agent 1: Viết unit tests cho src/services/user.service.ts
Agent 2: Viết unit tests cho src/services/product.service.ts
Agent 3: Viết unit tests cho src/services/order.service.ts
Mỗi agent không cần đợi agent kia.

Agent 1 (Analyzer):
→ Đọc codebase, tạo ANALYSIS.md
→ Output: danh sách vấn đề + recommended fixes

Agent 2 (Implementer):
→ Đọc ANALYSIS.md
→ Implement fixes
→ Output: code changes + CHANGES.md

Agent 3 (Tester):
→ Đọc CHANGES.md
→ Viết/chạy tests cho code mới
→ Output: test report

Orchestrator agent:
- Nhận high-level task
- Break down thành sub-tasks
- Giao cho worker agents
- Collect results
- Resolve conflicts

Worker agents:
├── Worker-backend: API changes
├── Worker-frontend: UI changes
├── Worker-tests: test updates
└── Worker-docs: documentation

Bước 1 — Explore (read-only)
"Đọc và tóm tắt: codebase structure,
conventions đang dùng, patterns lặp lại.
KHÔNG edit gì. Chỉ report."

Bước 2 — Plan
"Dựa trên exploration, propose implementation plan
cho [feature]. List files sẽ tạo/sửa."

Bước 3 — Implement
"Implement theo plan đã approve ở bước 2."

Bước 1 — Tests first
"Viết failing tests cho UserService.createUser().
Tests nên cover: happy path, duplicate email,
invalid data. Chưa implement logic."

Bước 2 — Make tests pass
"Implement UserService.createUser() để
tất cả tests pass. Không sửa test file."

"Implement [task] theo từng bước nhỏ.
Sau mỗi bước, dừng lại và show diff.
Chờ tôi approve trước khi tiếp tục."

"Tóm tắt session này vào HANDOFF.md:
- Task đã xong
- Task còn lại
- Decisions đã make và tại sao
- Files đã thay đổi
- Next steps cho session mới"

Bug report: [mô tả bug]
Error: [paste full error + stack trace]
Reproduction steps: [steps]
Expected vs actual: [...]

Hãy:
1. Hypothesize nguyên nhân (3-5 candidates)
2. Propose cách verify từng hypothesis
3. Sau khi tôi confirm, mới fix