centralize guides and rails under mosaic with runtime compatibility links
This commit is contained in:
Jason Woltje
79
templates/agent/projects/django/AGENTS.md.template
Normal file
79
templates/agent/projects/django/AGENTS.md.template
Normal file
@@ -0,0 +1,79 @@
|
||||
# ${PROJECT_NAME} — Agent Context
|
||||
|
||||
> Guidelines for AI agents working on this Django project.
|
||||
> **Update this file** when you discover reusable patterns or non-obvious requirements.
|
||||
|
||||
## Codebase Patterns
|
||||
|
||||
- **Django project:** Standard Django project layout
|
||||
- **Database:** PostgreSQL with Django ORM
|
||||
- **API:** Django REST Framework for REST endpoints
|
||||
- **Tasks:** Celery for background/async tasks
|
||||
- **Config:** Environment variables via `.env` / `python-dotenv`
|
||||
|
||||
## Common Gotchas
|
||||
|
||||
- **Run migrations** after model changes: `python manage.py makemigrations && python manage.py migrate`
|
||||
- **Import order matters:** Django setup must happen before model imports
|
||||
- **Celery tasks** must be importable from `tasks.py` in each app
|
||||
- **Settings module:** Check `DJANGO_SETTINGS_MODULE` environment variable
|
||||
- **Test database:** Tests use a separate database — check `TEST` config in settings
|
||||
- **Static files:** Run `collectstatic` before deployment
|
||||
|
||||
## Context Management
|
||||
|
||||
| Strategy | When |
|
||||
|----------|------|
|
||||
| **Spawn sub-agents** | Isolated coding tasks, research |
|
||||
| **Batch operations** | Group related operations |
|
||||
| **Check existing patterns** | Before writing new code |
|
||||
| **Minimize re-reading** | Don't re-read files you just wrote |
|
||||
|
||||
## Quality Gates
|
||||
|
||||
**All must pass before any commit:**
|
||||
|
||||
```bash
|
||||
ruff check . && mypy . && pytest tests/
|
||||
```
|
||||
|
||||
## Orchestrator Integration
|
||||
|
||||
### Task Prefix
|
||||
Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
|
||||
|
||||
### Worker Checklist
|
||||
1. Read the finding details from the report
|
||||
2. Implement the fix following existing patterns
|
||||
3. Run quality gates (ALL must pass)
|
||||
4. Commit: `git commit -m "fix({finding_id}): brief description"`
|
||||
5. Push: `git push origin {branch}`
|
||||
6. Report result as JSON
|
||||
|
||||
### Post-Coding Review
|
||||
After implementing changes, the orchestrator will run:
|
||||
1. **Codex code review** — `~/.mosaic/rails/codex/codex-code-review.sh --uncommitted`
|
||||
2. **Codex security review** — `~/.mosaic/rails/codex/codex-security-review.sh --uncommitted`
|
||||
3. If blockers/critical findings: remediation task created
|
||||
4. If clean: task marked done
|
||||
|
||||
## Key Files
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `CLAUDE.md` | Project overview and conventions |
|
||||
| `pyproject.toml` | Python dependencies and tool config |
|
||||
| `${SOURCE_DIR}/manage.py` | Django management entry point |
|
||||
| `.env.example` | Required environment variables |
|
||||
|
||||
## Testing Approaches
|
||||
|
||||
- Unit tests: `pytest` with fixtures in `conftest.py`
|
||||
- API tests: DRF's `APITestCase` or pytest with `api_client` fixture
|
||||
- Database tests: Use `@pytest.mark.django_db` decorator
|
||||
- Mocking: `unittest.mock.patch` for external services
|
||||
- Minimum 85% coverage for new code
|
||||
|
||||
---
|
||||
|
||||
_Model-agnostic. Works for Claude, Codex, GPT, Llama, etc._
|
||||
168
templates/agent/projects/django/CLAUDE.md.template
Normal file
168
templates/agent/projects/django/CLAUDE.md.template
Normal file
@@ -0,0 +1,168 @@
|
||||
# ${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
|
||||
```
|
||||
Reference in New Issue
Block a user