diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 00000000..730d38d9
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,85 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Fork Identity
+
+This is a **customized fork** of [Wei-Shaw/sub2api](https://github.com/Wei-Shaw/sub2api.git), branded as **StarFireAPI**. Upstream remote: `https://github.com/Wei-Shaw/sub2api.git`.
+
+### Customizations to preserve on every upstream sync
+
+| Category | Details |
+|----------|---------|
+| **Brand** | All user-facing `Sub2API` → `StarFireAPI` in `frontend/src/` (stores, i18n, views, components, router) |
+| **Links** | GitHub links → `https://anthropic.edu.pl` in AppHeader, HomeView, i18n |
+| **docker-compose** | Image: `starfireapi:latest`, port `6580:8080`, external Redis at `172.18.0.2:6379`, project name `xinghuoapi`, built-in Redis disabled |
+| **Update module** | Disabled in `system_handler.go` (always returns no update), `app.ts` (forces `hasUpdate=false`), `VersionBadge.vue` (`isReleaseBuild=false`, removed GitHub release links) |
+
+Full details: `skills/sync-upstream/SKILL.md`
+
+## Build & Test Commands
+
+```bash
+# Full build (backend + frontend)
+make build
+
+# Backend only
+cd backend && make build              # Binary → bin/server
+cd backend && make test               # go test ./... + golangci-lint
+cd backend && make test-unit          # Unit tests only
+cd backend && go test ./internal/service/... -run TestXxx  # Single test
+
+# Frontend only
+cd frontend && pnpm install --frozen-lockfile
+cd frontend && pnpm dev               # Dev server
+cd frontend && pnpm build             # Type-check + production build
+cd frontend && pnpm test:run          # Vitest
+cd frontend && pnpm lint:check        # ESLint (no fix)
+
+# Code generation (Ent ORM + Wire DI)
+cd backend && make generate
+```
+
+## Architecture
+
+**AI API Gateway**: receives requests with user API keys → authenticates → selects upstream account (sticky session / load-aware) → forwards to upstream AI service → records usage for billing.
+
+### Backend (`backend/internal/`)
+
+- **Entry**: `cmd/server/main.go` — supports setup mode, auto-setup (Docker), normal server
+- **DI**: Google Wire (`cmd/server/wire.go`)
+- **Layers**: handler → service → repository (enforced by `depguard` — service must not import repository)
+- **Key services**: `GatewayService` (request forwarding, account selection, failover), `OpenAIGatewayService`, `GeminiMessagesCompatService`, `AntigravityGatewayService`
+- **ORM**: Ent (`ent/schema/` for definitions, `ent/` for generated code)
+- **Middleware stack**: Recovery → Logger → CORS → SecurityHeaders → RequestBodyLimit → ClientRequestID → APIKeyAuth
+- **Run modes**: `standard` (full SaaS with billing) / `simple` (skip billing checks)
+
+### Frontend (`frontend/src/`)
+
+- **Framework**: Vue 3 + Pinia + Vue Router + TailwindCSS
+- **State**: `stores/app.ts` (global), `stores/auth.ts` (JWT auth)
+- **i18n**: `i18n/locales/en.ts`, `zh.ts` — all user-facing strings
+- **Embedded**: production build goes to `backend/internal/web/dist/` and is embedded into the Go binary
+
+### Gateway Routes
+
+```
+/v1/messages              — Claude API compatible
+/v1/responses             — OpenAI API compatible
+/v1beta/models/*          — Gemini native API
+/antigravity/v1/*         — Antigravity platform
+```
+
+## Coding Conventions
+
+- **Go**: `gofmt`, `golangci-lint` (see `backend/.golangci.yml`), max 3 levels of `if` nesting
+- **Frontend**: Vue SFC + TypeScript, 2-space indent, ESLint, components `PascalCase.vue`, composables `useXxx.ts`
+- **Commits**: Conventional Commits (`feat(scope):`, `fix(scope):`, `chore(scope):`)
+- **JSON hot-path**: prefer `gjson` over `encoding/json` for read-only/partial extraction
+- **Layering**: handler/service must NOT import repository/gorm/redis directly
+
+## Skills (in `skills/`)
+
+- **sync-upstream** — Pulls and merges upstream sub2api, re-applies all StarFireAPI customizations. Trigger: "拉取上游", "同步上游", "sync upstream"
+- **bug-fix-expert** — Multi-agent bug fix workflow with worktree isolation and cross-validation
+- **code-review-expert** — Parallel 5-dimension code review with worktree isolation