django-project-template: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository. Tool-specific entrypoints such as CLAUDE.md point here so every agent shares one source of truth.

Project Overview

A Django backend project bootstrapped from a Django project template, set up for rapid development.

Key characteristics:

• Python 3.13 with Django 5.2 (LTS)
• Custom settings layout in config/ (not within the app directory)
• Custom User model with email-only authentication (no username)
• Full-stack setup including frontend tooling (Tailwind, htmx, Alpine.js)
• Celery + Redis for async tasks
• Docker-first development approach

Essential Commands

Development Setup

# Local development (without Docker)
uv sync
cp .env.example .env
uv run pre-commit install
uv run python manage.py check

# Docker development (recommended)
cp .env.example .env
docker-compose up --detach --build
# Default admin: [email protected] / password123

Running Tests

# Run all tests
uv run pytest

# Run with coverage (CI standard: 85% minimum)
uv run pytest --cov={{ project_name }} --cov-fail-under=85 --cov-report term-missing:skip-covered

# Run specific test file
uv run pytest tests/test_something.py

# Run specific test
uv run pytest tests/test_something.py::test_function_name

Code Quality

# Run all pre-commit hooks manually
uv run pre-commit run --all-files

# Individual tools
uv run ruff check .        # Run linting
uv run ruff check . --fix  # Run linting with auto-fix
uv run ruff format .       # Run formatting
uv run mypy .              # Run type checking

Commit Messages

This project enforces Conventional Commits format:

# Interactive commit (recommended for beginners)
uv run cz commit

# Manual commit (must follow conventional format)
git commit -m "feat: add user profile page"
git commit -m "fix(auth): resolve token expiration"
git commit -m "docs: update README with new features"