Cách Mình Viết Documentation

Project/
├── README.md          ← Đây là gì, cách chạy
├── CHANGELOG.md       ← Thay đổi gì và khi nào
├── docs/
│   ├── PRD.md        ← Đang xây gì và tại sao
│   └── ARCHITECTURE.md ← Hệ thống hoạt động thế nào (tuỳ chọn)
└── src/
    └── [code với comment khi cần]

# Tên Dự Án

Mô tả một câu về cái này làm gì.

## Tính năng
- Tính năng 1
- Tính năng 2

## Tech Stack
- NextJS 14
- Supabase
- DataForSEO API

## Bắt đầu

### Yêu cầu
- Bun 1.0+
- Tài khoản Supabase
- DataForSEO API credentials

### Cài đặt
\`\`\`bash
git clone https://github.com/your-org/project-name
cd project-name
bun install
cp .env.example .env.local
# Chỉnh .env.local
bun run dev
\`\`\`

### Biến môi trường
| Biến | Mô tả | Bắt buộc |
|------|--------|----------|
| SUPABASE_URL | URL dự án Supabase | Có |
| SUPABASE_ANON_KEY | Anon key Supabase | Có |

## Cấu trúc
\`\`\`
src/
├── app/           # Pages
├── components/    # React components
├── lib/           # Utilities
└── types/         # TypeScript types
\`\`\`

## Development
\`\`\`bash
bun run dev      # Dev server
bun run build    # Production build
bun run lint     # Linter
\`\`\`

## Deployment
Deploy qua Railway. Push lên main tự động deploy.

# Changelog

## [Unreleased]

### Added
- Export kết quả ra CSV
- Progress indicator trong lúc clustering

### Changed
- Cải thiện thông báo lỗi cho API failure

### Fixed
- Timeout clustering cho dataset lớn

## [1.0.0] - 2024-01-15

### Added
- Upload keyword qua CSV
- Clustering HDBSCAN
- Hiển thị kết quả với nhãn cluster
- Tích hợp DataForSEO cho embeddings

# Claude Context cho [Tên Dự Án]

## Tổng quan
Tool keyword clustering cho SEO. User upload keywords,
cluster bằng HDBSCAN, hiển thị kết quả.

## Tech Stack
- NextJS 14 with App Router
- Supabase for database
- FastAPI for ML processing
- OpenAI for embeddings

## Patterns

### API Route
Nằm trong src/app/api/. Dùng NextJS route handler.

### Database
Supabase. Schema trong supabase/migrations/.
Luôn parameterized query, không nối chuỗi.

### Components
src/components/. Shadcn UI.
Import từ @/components/ui/ cho base components.

## Task thường gặp

### Thêm API endpoint
1. Tạo src/app/api/[name]/route.ts
2. Export GET, POST, v.v.
3. Thêm auth check nếu cần

## Không được
- Commit .env
- Dùng type any
- Bỏ qua error handling cho API calls
- Hardcode API URLs

## Đang làm
Tính năng export. Xem issue #45.

// Tốt: giải thích lý do
// Giảm chiều trước khi cluster vì HDBSCAN
// hoạt động kém trong không gian chiều cao (curse of dimensionality)
const reducedEmbeddings = await reduceDimensions(embeddings, 50);

// Tệ: giải thích cái đã rõ từ code
// Giảm chiều xuống 50
const reducedEmbeddings = await reduceDimensions(embeddings, 50);

// Tốt: giải thích hành vi bất thường
// DataForSEO trả về field name không nhất quán, chuẩn hoá ở đây
const normalizedResults = results.map(r => ({
  keyword: r.keyword || r.search_query,
  ...
}));

/**
 * Cluster keywords bằng HDBSCAN.
 *
 * @param keywords - Mảng keyword string
 * @param options - Cấu hình clustering
 * @param options.minClusterSize - Tối thiểu mỗi cluster (mặc định: 5)
 * @returns Promise trả về kết quả đã cluster
 */
async function clusterKeywords(
  keywords: string[],
  options: ClusterOptions = {}
): Promise<ClusterResult[]> {
  // ...
}