Tại Sao CLAUDE.md Là File Quan Trọng Nhất Trong Project Của Bạn

# Project: SocialApp Android — Social Media Platform
**Type:** Native Android app + Kotlin Multiplatform shared modules
**Target:** Consumer app (B2C)
**Maintenance:** Active development, 200k+ users

## Tech Stack
- **Language:** Kotlin 1.9.x (target JVM 17)
- **UI:** Jetpack Compose + Material3
- **Architecture:** MVVM + Clean Architecture (3 layers: presentation, domain, data)
- **Networking:** Retrofit 2 + OkHttp + Moshi
- **Database:** Room + SQLDelight (KMP modules)
- **DI:** Hilt (Android) + Koin (KMP shared)
- **Async:** Kotlin Coroutines + Flow
- **Testing:** JUnit5, MockK, Turbine for Flow testing

## Naming Conventions
- **Files:** PascalCase (`UserViewModel.kt`, `LoginScreen.kt`)
- **Classes/Objects:** PascalCase
- **Functions:** camelCase
- **Variables:** camelCase
- **Constants:** UPPER_SNAKE_CASE
- **Composables:** PascalCase như components (`UserCard`, `BookingForm`)
- **ViewModels:** `[Feature]ViewModel` (e.g., `LoginViewModel`)
- **Use Cases:** `[Action][Entity]UseCase` (e.g., `GetBookingsUseCase`)
- **Repositories:** `[Entity]Repository` interface + `[Entity]RepositoryImpl` (e.g., `UserRepository`, `UserRepositoryImpl`)

## Folder Structure

## Code Style
- **Max line length:** 120 characters
- **Function max lines:** 40 lines (refactor if longer)
- **Class max lines:** 300 lines (split if longer)
- **Parameters:** If >3 params, extract to data class
- **Comments:** Vietnamese OK for business logic, English for technical implementation

## CRITICAL RULES
- ❌ **NEVER** modify `build.gradle.kts` without explicit request
- ❌ **NEVER** access or read `.env`, `local.properties`, `google-services.json`
- ❌ **NEVER** hardcode API keys, secrets, or URLs (use BuildConfig)
- ❌ **NEVER** use deprecated APIs (`LiveData` → use `StateFlow` instead)
- ❌ **NEVER** directly call repositories from ViewModels (use UseCases)
- ✅ **ALWAYS** use sealed classes for UI state
- ✅ **ALWAYS** handle loading/success/error states explicitly
- ✅ **ALWAYS** add KDoc for public APIs

## Patterns

### ViewModel Pattern
```kotlin
// CORRECT ✅
class LoginViewModel @Inject constructor(
    private val loginUseCase: LoginUseCase
) : ViewModel() {
    private val _uiState = MutableStateFlow<LoginUiState>(LoginUiState.Idle)
    val uiState: StateFlow<LoginUiState> = _uiState.asStateFlow()

    fun login(email: String, password: String) {
        viewModelScope.launch {
            _uiState.value = LoginUiState.Loading
            loginUseCase(email, password)
                .onSuccess { _uiState.value = LoginUiState.Success(it) }
                .onFailure { _uiState.value = LoginUiState.Error(it.message) }
        }
    }
}

sealed interface LoginUiState {
    object Idle : LoginUiState
    object Loading : LoginUiState
    data class Success(val user: User) : LoginUiState
    data class Error(val message: String?) : LoginUiState
}

class LoginViewModel : ViewModel() {
    var isLoading = false  // mutable var exposed
    var user: User? = null // nullable state
    // No sealed class, no Flow
}

Đưa code examples thật. Claude Code học patterns nhanh hơn nhiều từ code so với từ ngữ.

---

## Trước Và Sau CLAUDE.md

Để thấy rõ impact, đây là so sánh before/after khi tôi thêm CLAUDE.md vào project:

### Trước khi có CLAUDE.md

**Prompt:**
> "Add pull-to-refresh to BookingListScreen"

**Claude Code output:**
```kotlin
// BookingListScreen.kt
@Composable
fun BookingListScreen(viewModel: BookingViewModel = viewModel()) {
    var isRefreshing by remember { mutableStateOf(false) }
    val bookings by viewModel.bookings.collectAsState()  // LiveData!

    SwipeRefresh(  // deprecated library
        state = rememberSwipeRefreshState(isRefreshing),
        onRefresh = { viewModel.refreshBookings() }
    ) {
        LazyColumn {
            items(bookings) { booking ->
                BookingItem(booking)  // component doesn't exist
            }
        }
    }
}

# [Project Name] — [One-line description]

## 1. OVERVIEW
- **Type:** [Web app / Mobile / Backend API / CLI tool]
- **Stack:** [Primary languages and frameworks]
- **Stage:** [Prototype / Active dev / Production / Maintenance]

## 2. TECH STACK
- **Language:** [Versions]
- **Framework:** [Versions]
- **Database:** [Type + ORM]
- **Key Libraries:** [Top 5-10 dependencies]

## 3. CONVENTIONS
### Naming
- Files: [Convention]
- Classes: [Convention]
- Functions: [Convention]
- Tests: [Convention]

### Structure
[Folder structure với ví dụ paths]

### Code Style
- Max line length: [X]
- Max function lines: [X]
- Preferences: [Tabs/spaces, comment language, etc]

## 4. CRITICAL RULES
- ❌ NEVER [Hard constraints]
- ✅ ALWAYS [Must-follow patterns]

## 5. PATTERNS
[Code examples cho common tasks với annotations ✅ CORRECT / ❌ WRONG]

# Project: E-commerce Dashboard

## TECH STACK
- Next.js 14 + TypeScript + App Router
- React Server Components + Server Actions
- Prisma ORM + PostgreSQL
- TailwindCSS + shadcn/ui components
- Zod for validation

## CONVENTIONS
### File Structure

### Component Patterns
```typescript
// CORRECT ✅ — Server Component by default
export default async function UserDashboard({ params }: Props) {
  const user = await db.user.findUnique({ where: { id: params.id } });
  return <UserProfile user={user} />;
}

// CORRECT ✅ — Client Component when needed
'use client';
export function UserProfile({ user }: Props) {
  const [editing, setEditing] = useState(false);
  // ... interactive logic
}

// WRONG ❌ — Unnecessary 'use client'
'use client';  // Don't need client for static render
export default function About() {
  return <div>About page</div>;
}

// CORRECT ✅
'use server';
export async function updateUser(formData: FormData) {
  const validated = userSchema.parse({
    name: formData.get('name'),
    email: formData.get('email'),
  });
  await db.user.update({ where: { id: userId }, data: validated });
  revalidatePath('/dashboard');
}

### Python / FastAPI Backend

```markdown
# Project: Analytics API

## TECH STACK
- Python 3.11 + FastAPI
- SQLAlchemy 2.0 + Alembic
- PostgreSQL + Redis
- Pydantic V2 for validation
- Celery for background tasks

## CONVENTIONS
### Structure

### Layering Pattern
```python
# CORRECT ✅ — Router → Service → Repository
@router.post("/users")
async def create_user(
    user_in: UserCreate,
    service: UserService = Depends(get_user_service)
):
    return await service.create_user(user_in)

class UserService:
    def __init__(self, repo: UserRepository):
        self.repo = repo

    async def create_user(self, user_in: UserCreate) -> User:
        # Business logic here
        return await self.repo.create(user_in)

# WRONG ❌ — Direct database access in router
@router.post("/users")
async def create_user(user_in: UserCreate, db: Session = Depends(get_db)):
    user = User(**user_in.dict())  # No validation, no business logic
    db.add(user)
    db.commit()
    return user

# CORRECT ✅
async def get_user(user_id: int) -> User:
    return await user_repo.get(user_id)

# WRONG ❌
def get_user(user_id: int) -> User:  # Missing async
    return user_repo.get(user_id)

### Mobile (Kotlin Multiplatform)

```markdown
# Project: Banking App (KMP)

## TECH STACK
- Kotlin Multiplatform (Android + iOS)
- Compose Multiplatform for UI
- Ktor client for networking
- SQLDelight for database
- Koin for dependency injection
- Kotlin Coroutines + Flow

## CONVENTIONS
### Structure

### expect/actual Pattern
```kotlin
// CORRECT ✅ — commonMain
expect class PlatformSecureStorage {
    suspend fun save(key: String, value: String)
    suspend fun get(key: String): String?
}

// androidMain
actual class PlatformSecureStorage {
    actual suspend fun save(key: String, value: String) {
        // Android Keystore implementation
    }
}

// iosMain
actual class PlatformSecureStorage {
    actual suspend fun save(key: String, value: String) {
        // iOS Keychain implementation
    }
}

// CORRECT ✅ — Sealed class for all states
sealed interface TransactionUiState {
    object Loading : TransactionUiState
    data class Success(val transactions: List<Transaction>) : TransactionUiState
    data class Error(val message: String) : TransactionUiState
}

class TransactionViewModel(
    private val repo: TransactionRepository
) : ViewModel() {
    private val _state = MutableStateFlow<TransactionUiState>(TransactionUiState.Loading)
    val state: StateFlow<TransactionUiState> = _state.asStateFlow()
}

// WRONG ❌ — Mutable state exposed
class TransactionViewModel : ViewModel() {
    var transactions: List<Transaction>? = null  // nullable, mutable
    var isLoading = false
}

### Go Backend Service

```markdown
# Project: Payment Gateway

## TECH STACK
- Go 1.21
- Gin framework
- GORM + PostgreSQL
- Redis for caching
- gRPC for internal services

## CONVENTIONS
### Structure

### Handler Pattern
```go
// CORRECT ✅
func (h *PaymentHandler) CreatePayment(c *gin.Context) {
    var req CreatePaymentRequest
    if err := c.ShouldBindJSON(&req); err != nil {
        c.JSON(http.StatusBadRequest, gin.H{"error": err.Error()})
        return
    }

    payment, err := h.service.CreatePayment(c.Request.Context(), req)
    if err != nil {
        c.JSON(http.StatusInternalServerError, gin.H{"error": err.Error()})
        return
    }

    c.JSON(http.StatusCreated, payment)
}

// WRONG ❌ — No error handling
func (h *PaymentHandler) CreatePayment(c *gin.Context) {
    var req CreatePaymentRequest
    c.BindJSON(&req)  // No error check
    payment, _ := h.service.CreatePayment(c.Request.Context(), req)  // Ignoring error
    c.JSON(200, payment)
}

// CORRECT ✅ — Always check errors
payment, err := repo.GetByID(ctx, id)
if err != nil {
    if errors.Is(err, ErrNotFound) {
        return nil, ErrPaymentNotFound
    }
    return nil, fmt.Errorf("failed to get payment: %w", err)
}

// WRONG ❌
payment, _ := repo.GetByID(ctx, id)  // Ignoring errors

---

## Sai Lầm Thường Gặp Khi Viết CLAUDE.md

Sau khi review CLAUDE.md của 50+ developers, đây là những sai lầm tôi thấy nhiều nhất:

### 1. Quá chung chung

❌ **Wrong:**
```markdown
## Tech Stack
- JavaScript
- Database
- Frontend framework

## Tech Stack
- Next.js 14.1.0 + TypeScript 5.3
- PostgreSQL 15 + Prisma ORM 5.x
- React 18 + TailwindCSS 3.4

This project uses React and we prefer functional components and we use TypeScript and we use Prettier with 2 spaces and we don't like semicolons and we use Redux for state management but only for global state and local state should use useState or useReducer and...

## Rules
- Use sealed classes for state
- Follow repository pattern
- Add tests

## State Management Pattern
```kotlin
// ✅ CORRECT
sealed interface UiState {
    object Loading : UiState
    data class Success(val data: Data) : UiState
    data class Error(val message: String) : UiState
}

Một code example thắng vạn lời.

### 4. Không update theo thời gian

Nhiều người viết CLAUDE.md một lần rồi bỏ quên. Project evolve, conventions thay đổi, nhưng CLAUDE.md không.

**Solution:** Mỗi khi Claude Code generate code sai convention, thêm correction vào CLAUDE.md ngay. Treat nó như living document.

### 5. Quên section "Secret Files"

❌ **Missing:**
Không mention files nào Claude Code không được access.

✅ **Correct:**
```markdown
## SECRET FILES (never access)
- .env, .env.local, .env.production
- docker-compose.yml (has database passwords)
- local.properties (Android API keys)
- GoogleService-Info.plist (iOS Firebase)
- credentials.json (GCP service account)

# SocialApp Android
## Stack
- Kotlin, Jetpack Compose, MVVM
## Rules
- Don't edit build.gradle.kts
- Use StateFlow not LiveData

## Naming
- ViewModels: [Feature]ViewModel
- Screens: [Feature]Screen
- UseCases: [Action][Entity]UseCase

## ViewModel Pattern
```kotlin
sealed interface UiState { ... }

Quality improvement: ~70%. Tôi chỉ cần sửa minor details.

**Month 2:** 60 dòng (thêm testing patterns, error handling)
```markdown
## Testing
Test files mirror source: `src/test/java/.../FeatureTest.kt`
Always use `runTest` for coroutines
Use MockK for mocking

## Error Handling
Always wrap repository calls with try-catch
Map domain exceptions to UI error messages

## Edge Cases
- Empty states: Show EmptyStateMessage component
- Loading during pagination: Show footer loader, not full screen
- Network errors: Show retry button with specific error message

# [Project Name] — Team Conventions

## OVERVIEW
- **Team size:** [X developers]
- **Git workflow:** [Feature branches / Trunk-based]
- **Code review:** [Required reviewers, approval policy]

## CONVENTIONS
[Shared conventions như bình thường]

## COMMIT MESSAGES

## CODE REVIEW CHECKLIST
- [ ] Tests pass
- [ ] No hardcoded secrets
- [ ] Follows naming conventions
- [ ] KDoc added for public APIs
- [ ] No TODO comments without tracking ticket

## TEAM PREFERENCES
- **Comment language:** Vietnamese for business logic, English for technical
- **PR size:** Max 400 lines changed (split larger features)
- **Merge strategy:** Squash and merge
- **Branch naming:** `feature/JIRA-123-short-description`