Config Files cho Coding Agent — Từ CLAUDE.md đến .mdc, MCP và Commands

## Stack
- React 18 + TypeScript 5 (strict mode)
- UI: Ant Design 5.x
- State: Zustand v5 (UI state only)
- Server state: React Query v5
- Build: Vite · Testing: Vitest + RTL
- Package manager: pnpm

## Naming
- Components: PascalCase → UserTable.tsx
- Stores: camelCase + suffix → userStore.ts
- Hooks: prefix use → useUserData.ts
- Types: PascalCase + suffix → UserDto, ApiResponse
- Files: kebab-case → user-service.ts

## Architecture rules
- KHÔNG lưu server data vào Zustand — dùng React Query
- Pages chỉ compose components, không fetch trực tiếp
- Components không biết về store structure
- API calls CHỈ trong src/services/
- Business logic CHỈ trong custom hooks

## Agent behavior
- Đọc docs/ARCHITECTURE.md trước khi tạo file mới
- Viết test song song với code
- Hỏi trước khi thêm dependency mới
- Khi xong: liệt kê files đã tạo/sửa + lý do
- Khi thấy bug ngoài scope: comment TODO, không tự fix

## KHÔNG được
- Dùng `any` hoặc `@ts-ignore`
- Import toàn bộ antd: import * as antd
- Lưu API response vào Zustand
- Tạo inline styles
- Commit .env files

"permissions": {
  "allow": [
    "Bash(pnpm run *)",
    "Bash(npx tsc --noEmit)",
    "Bash(npx vitest run *)",
    "Bash(git status)",
    "Bash(git diff *)",
    "Read(./src/**)",
    "Read(./docs/**)"
  ]
}

"permissions": {
  "deny": [
    "Bash(git push *)",
    "Bash(git commit *)",
    "Bash(rm -rf *)",
    "Bash(curl *)",
    "Read(./.env)",
    "Read(./.env.*)",
    "Write(./prisma/migrations/**)"
  ]
}

"hooks": {
  "PostToolUse": [
    {
      "matcher": "Write(./src/**/*.tsx)",
      "hooks": [{
        "type": "command",
        "command": "npx tsc --noEmit 2>&1 | head -30"
      }]
    }
  ]
}

"hooks": {
  "PreToolUse": [
    {
      "matcher": "Write(./src/stores/**)",
      "hooks": [{
        "type": "command",
        "command": "echo 'Reminder: Zustand stores chỉ cho UI state'"
      }]
    }
  ]
}

---
description: "Mô tả để AI biết khi nào dùng rule này"
globs: "src/components/**/*.tsx"
alwaysApply: false
---

# Nội dung rule (markdown bình thường)
- Rule 1...
- Rule 2...

---
alwaysApply: true
description: "Core project conventions"
---
Tech: React 18, TypeScript strict, pnpm, Vitest.
Never: `any` type, class components, default exports.

---
description: "Zustand store patterns"
globs: "src/stores/**/*.ts"
alwaysApply: false
---
- Tách State và Actions interface rõ ràng
- Dùng devtools middleware
- KHÔNG lưu server data
- Luôn có reset() action

---
description: "Dùng khi tạo form với Ant Design validation"
alwaysApply: false
---
- Dùng Form.useForm() không dùng ref
- Rules array cho mỗi Form.Item
- onFinish thay vì onSubmit

.cursor/rules/
├── base.mdc              # alwaysApply: true  (~150 từ)
├── react-components.mdc  # globs: src/components/**/*.tsx
├── zustand-stores.mdc    # globs: src/stores/**/*.ts
├── antd-usage.mdc        # globs: src/**/*.tsx
├── testing.mdc           # globs: **/*.test.tsx,**/*.test.ts
└── personal.mdc          # alwaysApply: true (gitignore)

{
  "mcpServers": {
    "tên-server": {
      "command": "npx",
      "args": ["-y", "@package/server-name"],
      "env": {
        "API_KEY": "${ENV_VAR_NAME}"
      }
    }
  }
}

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

"memory": {
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-memory"]
}

"context7": {
  "command": "npx",
  "args": ["-y", "@upstash/context7-mcp@latest"]
}

Tạo React component: $ARGUMENTS

Steps:
1. Tạo folder src/components/$ARGUMENTS/
2. $ARGUMENTS.types.ts — props interface
3. $ARGUMENTS.tsx — implementation với AntD
4. index.tsx — barrel export
5. $ARGUMENTS.test.tsx — tests RTL

Rules:
- Named export, không default export
- Props interface: ${ARGUMENTS}Props
- Không dùng any

Tạo Zustand store cho domain: $ARGUMENTS

Steps:
1. Tạo src/stores/$ARGUMENTS.store.ts
2. Định nghĩa State + Actions interfaces
3. Implement với devtools middleware
4. Tạo test file

Rules:
- KHÔNG lưu API data
- Tách State và Actions interface
- Luôn có reset() action

Review code: $ARGUMENTS

Checklist:
1. TypeScript: no any, proper generics?
2. React: hooks rules, deps array đúng?
3. Zustand: server state không?
4. Performance: unnecessary re-renders?
5. Tests: behavior tested không?

Output: 🔴 Critical · 🟡 Warning · 🟢 Suggestion

---
name: component-builder
description: Tạo React components với AntD và TypeScript strict.
tools: Read, Write, Bash
---
Trước khi tạo component:
1. Đọc rules liên quan
2. Xem component tương tự để follow pattern
3. Types file trước, component sau, test cùng lúc

---
name: test-writer
description: Viết tests cho React components và hooks.
tools: Read, Write, Bash
---
- Test behavior, KHÔNG test implementation
- Query priority: getByRole > getByLabelText > getByText
- userEvent thay vì fireEvent
- AAA pattern: Arrange → Act → Assert

---
name: code-reviewer
description: Review code theo project standards.
tools: Read, Bash
---
Checklist: TypeScript · React · Zustand · AntD · Security · Performance
Output: 🔴 Critical / 🟡 Warning / 🟢 Suggestion
Mỗi item: vấn đề + file:line + cách fix

## 1. Overview (3-5 câu)
Project là gì, phục vụ ai, scale thế nào.

## 2. Tech decisions + lý do
Zustand thay vì Redux: state đơn giản.
React Query thay vì axios thuần: cần cache, refetch.

## 3. Folder structure
src/
├── components/   # shared components
├── pages/        # route-level
├── stores/       # Zustand (UI state only)
├── services/     # API calls
└── hooks/        # shared custom hooks

## 4. Data flow
API → React Query (cache) → Component
UI events → Hook → Zustand → Component

## 5. Boundary rules
- Pages không gọi API trực tiếp
- Components không biết store internals
- Services không import từ components