169 lines
4.3 KiB
Plaintext
169 lines
4.3 KiB
Plaintext
# ${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
|
|
```
|