CLAUDE.md Masterclass — Project Configuration

User Level        ~/.claude/CLAUDE.md           (Global defaults)
          ↓
Project Level     ./CLAUDE.md                   (This project)
          ↓
Rules Level       ./.claude/rules/*.md          (Rules 01-21)

# Claude Code Global Configuration

## Your Preferred Workflow
- Always prefer editing existing files to creating new ones
- Commit frequently with atomic, descriptive messages
- Use Python 3.10+ style (type hints, walrus operator)
- Always read code before refactoring

## Your Development Environment
- Terminal: zsh (oh-my-zsh with git plugin)
- Editor conventions: spaces, 2-space indent for YAML/JSON, 4-space for Python
- Node: v18+, Python: 3.10+
- Git hooks: pre-commit installed, husky for npm projects

## Global Safety Rules
- Never hardcode credentials
- Always anonymize IPs/hostnames in examples
- Use vault.py for secrets management

# MyProject — AI Engineering Platform

## Architecture Overview
- Backend: Python FastAPI, PostgreSQL
- Frontend: React 18 + TypeScript
- ML: PyTorch + Hugging Face transformers
- Deployment: Docker Compose (dev), Kubernetes (prod)

## Key Directories

## Critical Files (Don't Edit Without Understanding)
- `src/config.py` — Global config, changes affect all services
- `docker-compose.yml` — Development environment
- `migration_*.py` — Database migrations, NEVER reorder

## Testing
- Unit tests: `pytest src/tests/` (70% coverage minimum)
- Integration: `pytest tests/integration/`
- E2E: `npm run test:e2e` in frontend/

## Deployment Commands
```bash
# Development
docker-compose up -d

# Production
kubectl apply -f k8s/

### Rules Level (./.claude/rules/*.md) — Reusable Standards

Rules that apply across multiple projects:

```markdown
# 01-safety-rules.md
Safety principles every agent must follow:
- S1: Never expose secrets in output
- S2: Always verify destructive commands
- ...

## Architecture Philosophy

This project uses a microservices architecture:
- API Gateway (nginx) routes requests
- Each service owns its database (no shared DB)
- Services communicate via gRPC
- Async work via Kafka queue

Why this design?
- Allows teams to work independently
- Scales individual services based on load
- Easier to deploy/rollback individual services

Consequences:
- Distributed debugging is harder
- Must handle eventual consistency
- API versioning is critical

## Development Workflow

1. Create feature branch: `git checkout -b feature/my-feature`
2. Make changes (see "Coding Standards" below)
3. Write tests for new code (see "Testing" section)
4. Run `make test` locally before pushing
5. Push and open PR
6. GitHub Actions run tests automatically
7. Merge when all checks pass

## Coding Standards

**Python**: Follow PEP 8, use type hints
```python
def fetch_user(user_id: int) -> User:
    """Docstring describing function."""
    return db.query(User).filter_by(id=user_id).first()

interface ButtonProps {
  label: string;
  onClick: () => void;
  disabled?: boolean;
}

  <button onClick={onClick} disabled={disabled}>{label}</button>
);

### 3. Document the Sad Path

Show Claude how to recover from failures:

```markdown
## Common Problems & Solutions

**Problem**: Tests fail with "No module named 'myapp'"
- Solution: Run `pip install -e .` to install in dev mode
- Root cause: Virtual environment not activated or stale install

**Problem**: Database migration fails with "constraint violation"
- Solution: Check `migrations/migration_001.py` for order
- This happens when migrations are applied out of order
- Fix: Manually reset dev DB: `python scripts/reset_db.py`

**Problem**: Docker image build fails with "permission denied"
- Solution: Check your user can read all source files
- Run: `chmod -R 755 src/` then retry

**Problem**: Kubernetes deployment hangs
- Check pod logs: `kubectl logs deployment/myapp -f`
- Usually means service can't reach database
- Verify DATABASE_URL secret exists: `kubectl get secrets`

## Project-Specific Conventions

- **Imports**: Absolute imports only. `from src.models import User`, never relative
- **Naming**: Database tables singular (table: `user`, not `users`)
- **Dates**: Always store in UTC, convert to local time in API response only
- **Errors**: Use custom exception classes (HTTPException, ValidationError), never raw Exception
- **Config**: Environment variables override defaults — see src/config.py
- **Database**: SQLAlchemy ORM required, no raw SQL except migrations
- **API versions**: Current version is v2 (v1 deprecated 2025-06-01)

## Available Tools & Services

| Tool | Purpose | Command | Notes |
|------|---------|---------|-------|
| pytest | Unit testing | `pytest src/tests/` | 70% coverage min |
| black | Code formatter | `black src/` | Auto-fix style |
| mypy | Type checking | `mypy src/` | Strict mode |
| docker | Containerization | `docker-compose up` | Includes DB, Redis |
| psql | DB client | `psql postgres://...` | Use for manual queries |
| redis-cli | Cache client | `redis-cli` | Running in port 6379 |

## External Services

- **GitHub**: Repo access, Actions for CI/CD
- **DataDog**: Monitoring, logs stored 30 days
- **Stripe**: Payment processing (API key in vault.py)

## Off-Limits

These files should NEVER be modified without explicit approval:
- `docker-compose.yml` — Changing this breaks dev environment for entire team
- `requirements.txt` — Must pin versions, document breaking changes
- Database schemas — Manual migration required, can't auto-generate
- GitHub Actions workflows — Changes affect all developers' CI/CD

Tell the user if you need to change these files. Ask for confirmation first.

# MyDjango Project — REST API

## Architecture

Django REST Framework backend serving React frontend.
- Backend: Django 4.2 + DRF, PostgreSQL 14, Redis
- Frontend: React 18 (separate repo)
- Deployment: Docker + Railway

## Project Structure

## Setup

```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python manage.py migrate
python manage.py runserver

class User(models.Model):
    email = models.EmailField(unique=True)
    created_at = models.DateTimeField(auto_now_add=True, db_index=True)

    class Meta:
        verbose_name = "User"
        indexes = [models.Index(fields=['email'])]

class UserSerializer(serializers.ModelSerializer):
    class Meta:
        model = User
        fields = ['id', 'email', 'created_at']

    def validate_email(self, value):
        if User.objects.filter(email=value).exists():
            raise ValidationError("Email already exists")
        return value

class UserViewSet(viewsets.ModelViewSet):
    queryset = User.objects.all()
    serializer_class = UserSerializer
    permission_classes = [IsAuthenticated]

pytest api/tests/ --cov=api

### Example 2: Next.js SaaS Frontend

```markdown
# SaaS Dashboard — Next.js 14

## Architecture

Next.js 14 frontend + API routes, TypeScript, Tailwind CSS.
- Framework: Next.js 14 (App Router)
- Language: TypeScript
- Styling: Tailwind CSS
- Data fetching: TanStack Query (React Query)
- State: Zustand
- API: OpenAPI via OpenAPI-Generator

## Directory Structure

## Coding Standards

**Components**: Use functional components with TypeScript
```typescript
interface DashboardProps {
  userId: string;
  initialData?: User;
}

  const [user, setUser] = useState<User | null>(initialData || null);

  return <div>{user?.name}</div>;
}

interface LoginFormData {
  email: string;
  password: string;
}

  const { register, handleSubmit, formState: { errors } } = useForm<LoginFormData>();

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <input {...register('email', { required: true })} />
      {errors.email && <span>Email required</span>}
    </form>
  );
};

function useUser(userId: string) {
  return useQuery({
    queryKey: ['user', userId],
    queryFn: () => apiClient.get(`/api/users/${userId}`),
  });
}

npm run test              # Unit tests
npm run test:e2e          # E2E tests

npm run build             # Build for production
npm start                 # Run production server

const apiClient = axios.create({
  baseURL: process.env.NEXT_PUBLIC_API_URL,
});

apiClient.interceptors.request.use((config) => {
  const token = getAuthToken();
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

### Example 3: Python Data Pipeline

```markdown
# ETL Pipeline — Data Processing

## Architecture

Python data pipeline: Extract from APIs, Transform, Load to data warehouse.
- Language: Python 3.11
- Orchestration: Apache Airflow
- Data warehouse: Snowflake
- Data validation: Great Expectations
- Monitoring: Datadog

## Project Structure

## Running Locally

```bash
pip install -r requirements.txt
airflow db init
airflow webserver --port 8080
airflow scheduler

from airflow import DAG
from datetime import datetime, timedelta

default_args = {
    'owner': 'data-team',
    'retries': 1,
    'retry_delay': timedelta(minutes=5),
}

with DAG(
    'daily_etl',
    default_args=default_args,
    schedule_interval='0 2 * * *',  # 2 AM daily
) as dag:
    extract = ApiExtractor(api_endpoint='...')
    validate = DataValidator(expectations_file='...')
    transform = DataTransformer()
    load = SnowflakeLoader()

    extract >> validate >> transform >> load

pytest tests/ -v
pytest tests/test_transformers.py::test_cleaner_handles_nulls -s

# View DAG logs
airflow logs daily_etl task_name

# Test operator locally
python -c "from operators.api_extractor import ApiExtractor; op = ApiExtractor(); op.execute()"

## Anti-Patterns to Avoid

### Anti-Pattern 1: The Instruction Dump

```markdown
# DON'T: Wall of disconnected commands

## Useful Commands
- `npm start` — start dev server
- `npm test` — run tests
- `npm run build` — production build
- `docker build -t myapp .` — build image
- `git commit -m "message"` — commit changes
- `curl http://localhost:3000` — check if running
- `ps aux | grep node` — find processes

# DON'T: Stealing from official docs

## Django Models (from django.readthedocs.io)

Model fields include:
- AutoField
- BigAutoField
- BigIntegerField
- BinaryField
- BooleanField
...

# Better structure:

# Main CLAUDE.md (200-400 lines)
- Architecture overview
- Quick start
- Critical files
- Common errors

# .claude/rules/
- 01-coding-standards.md (details on style)
- 02-testing-strategy.md (how to test this project)
- 03-database-rules.md (schema, migrations)
- 04-deployment.md (how to ship)

## Last Updated: 2026-03-21
Review this document monthly. Stale docs cause bad decisions.

Recent changes:
- 2026-03-21: Updated deployment command (now uses Railway)
- 2026-03-10: Added Redis caching architecture
- 2026-02-28: Migrated from SQLite to PostgreSQL