diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..a591c0c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,72 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Notify is a reminder/todo management application with multi-user reminders, recurring schedules, and push notifications via Bark. It has a Rust backend (primary) and Next.js frontend.
+
+## Development Commands
+
+```bash
+# Start development (Rust backend + frontend)
+make dev
+
+# Start development (Node.js backend - legacy)
+make dev-node
+
+# Stop all services
+make stop
+
+# Database migrations (Rust/SeaORM)
+make migrate              # Run pending migrations
+make migrate-down         # Rollback last migration
+make migrate-fresh        # Reset database and re-run all migrations
+make generate-entities    # Generate Rust entities from database
+
+# Build release
+make build
+```
+
+## Architecture
+
+**Stack:**
+- Frontend: Next.js 14, React 18, Tailwind CSS 4, Radix UI (shadcn/ui)
+- Backend: Actix-web 4, SeaORM 2.0.0-rc (Rust) - primary
+- Database: PostgreSQL 16
+
+**Key directories:**
+- `backend_rust/src/api/` - REST API endpoints
+- `backend_rust/src/timer/` - Background job scheduler (notifications, Bark delivery)
+- `backend_rust/src/entity/` - Auto-generated SeaORM models (DO NOT EDIT manually)
+- `backend_rust/migration/src/` - Database migrations
+- `frontend/src/app/` - Next.js pages (App Router)
+- `frontend/src/lib/api.ts` - Centralized API client
+
+**API endpoints (port 4000):**
+- `/api/auth` - Login, register
+- `/api/todos` - Personal todo CRUD with recurrence
+- `/api/reminder-tasks` - Multi-user reminder CRUD
+- `/api/notifications` - Notification center
+- `/api/me` - User profile/settings
+- `/api/invites` - Invite code management
+
+## Database Migration Workflow
+
+Follow `.cursor/skills/database-migration/SKILL.md`:
+1. Create migration file: `m{YYYYMMDD}_{sequence}_{description}.rs` in `backend_rust/migration/src/`
+2. Register in `migration/src/lib.rs`
+3. Run `make migrate`
+4. Run `make generate-entities`
+5. Never manually edit `backend_rust/src/entity/` files
+
+## Key Patterns
+
+- **Notification generation**: Worker creates notification records for tasks due within N hours
+- **Bark delivery**: Retry with exponential backoff (1m/5m/15m/1h/4h) on failure
+- **Timezone handling**: All recurrence uses user's timezone; date alignment handles edge cases
+- **Multi-recipient**: Each reminder task creates separate notification per recipient
+
+## Documentation
+
+- `docs/spec.md` - Product/technical spec (Chinese) with business rules, API definitions, UI requirements