# CLAUDE.md Template
# Place this file in the ROOT of your project folder

> This file is automatically read by Claude Code when working in this directory.
> It provides persistent context, coding standards, and project-specific instructions.

---

## 🎯 Project Overview

<!-- Replace with your project details -->

**Project Name:** [Your App Name]
**Type:** [Web App / Mobile App / macOS App / API / Full-Stack]
**One-liner:** [What does this app do in one sentence?]

### Problem Being Solved
[Describe the core problem your users face]

### Target User
[Who is this for? Be specific]

### Success Looks Like
[What does a successful v1.0 look like?]

---

## 🛠️ Tech Stack

<!-- Update based on your project -->

| Layer | Technology | Why |
|-------|------------|-----|
| Frontend | Next.js 14 (App Router) | Modern React, SSR, file-based routing |
| Styling | Tailwind CSS | Rapid UI development |
| Backend | Supabase | Auth, Database, Edge Functions |
| Database | PostgreSQL (via Supabase) | Relational, RLS for security |
| Deployment | Vercel | Zero-config, edge network |

---

## 📁 Project Structure

```
/app                    # Next.js app router pages
/components             # Reusable UI components
  /ui                   # Base components (buttons, inputs)
  /features             # Feature-specific components
/lib                    # Utilities and helpers
  /supabase             # Supabase client and queries
  /hooks                # Custom React hooks
/types                  # TypeScript type definitions
/public                 # Static assets
```

---

## ✅ Coding Conventions

### CHANGELOG Updates
- **ALWAYS update `/docs/CHANGELOG.md` before committing**
- Add entry under `[Unreleased]` section
- Document ALL changes (features, fixes, tests added)
- Use categories: Added, Fixed, Changed, Security

### General
- Use TypeScript with strict mode
- Prefer server components unless client interactivity is needed
- Keep functions small and focused (< 50 lines)
- Use descriptive variable names (no abbreviations)

### React/Next.js
- Use functional components with hooks
- Prefer `const` arrow functions for components
- Colocate related files (component + styles + tests)
- Use `use client` only when necessary

### Database
- All queries go through Supabase client
- Always validate input before database operations
- Use RLS (Row Level Security) for access control
- Never trust client-side data

### Error Handling
- Always handle async errors with try/catch
- Provide user-friendly error messages
- Log errors for debugging

### Naming Conventions
- Components: PascalCase (`UserProfile.tsx`)
- Functions: camelCase (`getUserById`)
- Constants: SCREAMING_SNAKE_CASE (`API_BASE_URL`)
- Files: kebab-case or match component name

---

## 🚫 Do NOT

- Do not create new dependencies without asking first
- Do not modify database schema without migration files
- Do not store secrets in code (use environment variables)
- Do not skip error handling
- Do not ignore TypeScript errors

---

## 📋 Current Phase

<!-- Update this as you progress -->

**Current Focus:** [e.g., "MVP Development - User Authentication"]

**What's Done:**
- [x] Project setup
- [x] Database schema
- [ ] Authentication flow
- [ ] Core feature 1

**What's Next:**
- [ ] Implement login/signup
- [ ] Build dashboard
- [ ] Add core feature

---

## 🔗 Key Files to Know

| File | Purpose |
|------|---------|
| `/app/layout.tsx` | Root layout with providers |
| `/lib/supabase/client.ts` | Supabase client initialization |
| `/types/database.ts` | Generated database types |
| `/docs/PRD.md` | Product requirements |
| `/docs/tasks.md` | Current task breakdown |

---

## 💬 How to Work With Me

**My Role:** I am the product owner and reviewer. I plan, you implement.

**Your Role:** You write code, explain tradeoffs, and ask clarifying questions.

**Communication Style:**
- Before coding, briefly explain your approach
- If requirements are unclear, ask before assuming
- Suggest better approaches if you see them
- Keep explanations concise but complete

---

## ⚠️ CRITICAL: Verification Protocol

**DO NOT HALLUCINATE. Verify everything.**

Before implementing:
1. **Check this codebase** for existing patterns
2. **Check package.json** for installed versions
3. **Use Context7** to look up library docs
4. **Confirm APIs exist** before using them

If uncertain, say:
- "Let me verify this with Context7 first"
- "Let me check your existing code for patterns"

Never say:
- ❌ "I believe this should work..."
- ❌ "This typically works like..."
- ❌ "Try this..." (without verification)

Reference: `/skills/verification/SKILL.md`

---

## 📚 Reference Documents

<!-- Link to other docs in your project -->

- [PRD](/docs/PRD.md) - Product Requirements
- [Tasks](/docs/tasks.md) - Current task breakdown
- [Database Schema](/docs/database-schema.md) - ERD and tables
- [API Contracts](/docs/api-contracts.md) - Endpoint definitions

---

*Last Updated: [Date]*