# ${PROJECT_NAME} — Claude Code Instructions

> **${PROJECT_DESCRIPTION}**

## Conditional Documentation Loading

| When working on... | Load this guide |
|---|---|
| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
| Backend/API development | `~/.mosaic/guides/backend.md` |
| Code review | `~/.mosaic/guides/code-review.md` |
| QA/Testing | `~/.mosaic/guides/qa-testing.md` |

## Technology Stack

| Layer | Technology |
|-------|------------|
| **Backend** | Django / Django REST Framework |
| **Database** | PostgreSQL |
| **Task Queue** | Celery + Redis/Valkey |
| **Testing** | pytest + pytest-django |
| **Linting** | ruff |
| **Type Checking** | mypy |
| **Deployment** | Docker + docker-compose |

## Repository Structure

```
${PROJECT_DIR}/
├── CLAUDE.md              # This file
├── AGENTS.md              # Agent-specific patterns and gotchas
├── ${SOURCE_DIR}/         # Django project root
│   ├── manage.py
│   ├── ${PROJECT_SLUG}/   # Django settings module
│   │   ├── settings.py
│   │   ├── urls.py
│   │   └── wsgi.py
│   └── apps/              # Django applications
├── tests/                 # Test files
├── docs/
│   ├── scratchpads/       # Per-issue working documents
│   └── templates/         # Project templates
├── pyproject.toml         # Python project configuration
├── .env.example
└── README.md
```

## Development Workflow

### Branch Strategy
- `main` — Production-ready code
- `develop` — Integration branch (if used)
- `feat/<name>` — Feature branches
- `fix/<name>` — Bug fix branches

### Starting Work
```bash
git pull --rebase
uv sync                        # or pip install -e ".[dev]"
```

### Building / Running
```bash
python manage.py runserver     # Development server
python manage.py migrate       # Apply migrations
python manage.py shell          # Django shell
```

### Testing
```bash
pytest tests/                  # Run all tests
pytest tests/ -x               # Stop on first failure
pytest tests/ --cov            # With coverage
```

### Linting & Type Checking
```bash
ruff check .                   # Lint
ruff format .                  # Format
mypy .                         # Type check
```

## Quality Gates

**All must pass before committing:**

```bash
ruff check . && mypy . && pytest tests/
```

## Django Conventions

### Models
- All tunable parameters stored in the database with `get_effective_*()` fallback patterns
- Always create migrations for model changes: `python manage.py makemigrations`
- Include migrations in commits
- Use `models.TextChoices` or `models.IntegerChoices` for enum-like fields

### Views / API
- Use Django REST Framework for API endpoints
- Use serializers for validation
- Use ViewSets for standard CRUD
- Use permissions classes for authorization

### Management Commands
- Place in `<app>/management/commands/`
- Use `self.stdout.write()` for output
- Handle interrupts gracefully

## Database

### Migration Workflow
```bash
# Create migration after model changes
python manage.py makemigrations <app_name>

# Apply migrations
python manage.py migrate

# Check for missing migrations
python manage.py makemigrations --check
```

### Rules
- Always create migrations for schema changes
- Include migrations in commits
- Use `RunPython` for data migrations
- Use transactions for multi-table operations

## Code Review

### Independent Review (Automated)
After completing code changes, run independent reviews:

```bash
# Code quality review (Codex)
~/.mosaic/rails/codex/codex-code-review.sh --uncommitted

# Security review (Codex)
~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
```

## Issue Tracking

### Workflow
1. Check for assigned issues before starting work
2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
3. Reference issues in commits: `Fixes #123` or `Refs #123`
4. Close issues after successful testing

### Commits
```
<type>(#issue): Brief description

Fixes #123
```
Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`

## Secrets Management

**NEVER hardcode secrets.**

```bash
# .env.example is committed (with placeholders)
# .env is NOT committed (contains real values)
# Load via python-dotenv or django-environ
```