From a0cca1f171732a6d2b14c1f57d8d5b110c2776aa Mon Sep 17 00:00:00 2001
From: Caihaohan <caihaohan0712@foxmail.com>
Date: Sat, 27 Dec 2025 10:37:06 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AE=8C=E5=96=84=20CLAUDE.md=20?=
 =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E6=96=87=E6=A1=A3=E7=BB=93=E6=9E=84?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- 添加开发命令参考（构建、测试、数据库）
- 新增架构概述章节（i18n、App Router、数据库等）
- 完善 MCP Servers 使用说明
- 统一提交信息格式规范

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
---
 CLAUDE.md | 97 ++++++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 92 insertions(+), 5 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index b16835e..0942c2f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,5 +1,92 @@
-1\.开发过程中如果遇到api不确定的情况 要用context7 mcp 
-2.如果需要查看页面效果或者修复BUG 要用chrome dev mcp
-3\.如果要查看数据库要使用dbhub mcp
-4\.如果要确认shadcn ui组件 要用 shadcn mcp
-5\.git commit信息主要语言为中文
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Build & Run
+```bash
+pnpm dev          # Start development server (Next.js 15)
+pnpm build        # Build for production
+pnpm start        # Start production server
+pnpm lint         # Run ESLint
+```
+
+### Testing
+```bash
+pnpm test         # Run Vitest unit tests
+pnpm test:e2e     # Run Playwright E2E tests
+```
+
+### Database
+```bash
+pnpm prisma migrate dev   # Run database migrations
+pnpm prisma migrate dev --name init    # Create initial migration
+pnpm prisma db seed       # Seed database (uses ts-node)
+pnpm prisma studio        # Open Prisma Studio for database inspection
+```
+
+## Architecture Overview
+
+This is a **Next.js 15 multilingual AI project navigation website** using the App Router architecture with the following key components:
+
+### i18n Architecture (next-intl)
+- **Locales**: `zh` (default) and `en`
+- **Route pattern**: `/{locale}/path` (always prefixed with locale)
+- **Middleware**: `src/middleware.ts` handles locale detection and routing
+- **i18n config**: `src/i18n/request.ts` loads locale messages from `src/messages/{locale}.json`
+- **Messages**: Translation files at `src/messages/zh.json` and `src/messages/en.json`
+
+### App Router Structure
+```
+src/app/
+├── [locale]/           # Locale-scoped routes
+│   ├── page.tsx        # Home page
+│   ├── projects/       # Projects listing
+│   └── layout.tsx      # Locale layout (header, footer)
+├── api/                # API routes (no locale prefix)
+│   └── webhook/projects/route.ts  # Webhook for project ingestion
+└── layout.tsx          # Root layout
+```
+
+### Database (Prisma + PostgreSQL)
+- **Schema**: `prisma/schema.prisma` defines models: `Project`, `Tag`, `ExternalLink`
+- **Enums**: `ProjectStatus` (ACTIVE/ARCHIVED), `LinkType` (WEBSITE/GITHUB/HUGGINGFACE/PAPER)
+- **Client singleton**: `src/lib/prisma.ts` exports Prisma client instance
+- **Multilingual fields**: Most models have `name`/`nameEn`, `description`/`descriptionEn` pairs
+
+### Webhook Deduplication Strategy
+The webhook at `src/app/api/webhook/projects/route.ts` implements a **multi-level deduplication** strategy to prevent duplicate projects:
+1. **GitHub URL exact match** (highest priority)
+2. **Website URL exact match**
+3. **slug match** (fallback)
+
+### Validation (Zod)
+- **Schemas**: `src/lib/validations.ts` defines all Zod schemas
+- `ProjectInputSchema`: Validates incoming project data
+- `WebhookPayloadSchema`: Validates webhook requests with API key
+- `ProjectQuerySchema`: Validates query parameters
+
+### Styling (Tailwind CSS)
+- **Neo-brutalism design**: Sharp corners, bold borders, hard shadows
+- **Theme colors**: Primary gold (#FFD700), secondary orange, custom shadows (shadow-neo, shadow-brutal)
+- **Dark mode**: Class-based with `dark:` prefix
+- **Config**: `tailwind.config.ts` extends theme with custom colors, shadows, and animations
+
+### UI Components
+- **Radix UI primitives**: `@radix-ui/react-slot`, `@radix-ui/react-navigation-menu`, `@radix-ui/react-dropdown-menu`
+- **Lucide React icons**: Used throughout the app
+- **Custom components**: `src/components/` organized by domain (project/, locale/, search/)
+
+## MCP Servers Usage (按需使用)
+
+1. **context7**: 不确定 API 用法时查阅最新文档
+2. **chrome-devtools-mcp**: 查看页面效果、调试 UI 修复 BUG
+3. **dbhub mcp**: 查询数据库数据（PostgreSQL）
+4. **shadcn mcp**: 确认 shadcn/ui 组件用法
+5. **web-search-prime**: 默认联网搜索工具
+6. **vision-mcp-server**: 图片/视频理解
+
+## Git Commits
+
+提交信息主要使用中文，使用描述性的提交格式。