Codex is a command-line agent that works well inside an existing Django repository. Start it with codex in the project root, give it a precise task, and let it read the project through AGENTS.md before editing. This guide shows a practical loop for Django models, migrations, ORM work, DRF endpoints, and tests.
Why Codex is a natural fit for Django repositories
Django is convention-heavy and those conventions are easy to write down. Once AGENTS.md explains the app layout, settings split, test command, and migration rule, Codex can follow those rules across many files. It reads models.py, views.py, urls.py, serializers.py, and tests.py as a coherent unit, so changes stay consistent. It can run python manage.py check and pytest after edits, which catches Django-specific mistakes such as missing app_label, wrong URL names, or model field errors. It is not a replacement for your own Django review; it is a fast way to turn a feature request into a tested diff.
Configuring AGENTS.md for Django work
Put project-specific rules in AGENTS.md at the repository root. Codex reads this file at the start of a session, so keep it short and actionable. Include the exact commands for installing dependencies, running tests, linting, and making migrations. A Django project usually has multiple settings modules; say which one Codex should use for tests and checks.
# AGENTS.md
## Project layout
- Django settings live in config/settings/
- Apps live in apps/<app_name>/
- Templates per app under templates/<app_name>/
- Static assets are collected by django.contrib.staticfiles
## Commands
- Install dependencies: pip install -r requirements/dev.txt
- Run tests: pytest
- Run one test: pytest apps/billing/tests/test_orders.py::test_order_total
- Lint: ruff check .
- Format: ruff format --check .
- Type check: mypy .
- Apply migrations: python manage.py migrate
- Make migrations: python manage.py makemigrations
- Run dev server: python manage.py runserver
## Django-specific rules
- Never edit generated migrations by hand. Run makemigrations, then review the generated file.
- Use gettext_lazy for user-facing strings in models and forms.
- Use .select_related() and .prefetch_related() when crossing relationships in a loop.
- Use transaction.atomic() when updating multiple related objects.
- Keep business logic in services or model methods, not in views.
- For DRF, use ModelSerializer unless custom validation is required.
- All tests must pass under pytest-django with the test settings.If you are new to the base CLI workflow, see How to use Codex CLI: a step-by-step guide. Also tell Codex to prefer pytest with pytest-django over the Django test runner; many Django teams use pytest fixtures and django_assert_num_queries. Keep AGENTS.md updated as your conventions change.
A plan–test–diff loop for Django changes
Use a plan-first loop. Before Codex writes code, ask for a short plan: which files change, which migration is created, and which tests cover the behavior. Then ask for one small change at a time. After each change, run the relevant test command and review git diff. Finally, ask Codex to run the full test suite and python manage.py check.
Example prompts:
- Add a
Customermodel inapps/crm/models.pywithname,email, and a uniquestripe_customer_id. Usemakemigrationsand show me the generated migration before running tests. - Create a DRF
CustomerViewSetwith list, create, and detail endpoints. Use aModelSerializer, add authentication and permission classes, and write pytest tests withAPIClient. - In
apps/orders/services.py, refactorfinalize_orderso all writes happen insidetransaction.atomic()and the confirmation email is sent after the transaction commits. Add a test that verifies rollback on failure. - Fix the N+1 query in
apps/reports/views.py. Useselect_relatedandprefetch_relatedwhere needed, and add a test withdjango_assert_num_queries. - Change the
OrderAdminlist display to include a computedtotalcolumn, add a date hierarchy filter, and update the admin tests. Runpython manage.py checkbefore running pytest.
Where Codex shines and where to double-check
Codex handles repetitive Django work well: new apps, models and migrations, serializers and ViewSets, admin registration, form validation, template tags and filters, and pytest-django fixtures. It is also reliable for mechanical refactors such as adding select_related, updating settings, or renaming URL names when the change is small enough to test.
Watch it closely in these areas:
| Area | Why it matters in Django |
|---|---|
| Migrations | Codex may hand-edit a migration or create a conflicting number. Always inspect makemigrations output and run makemigrations --check --dry-run. |
| Settings split | A change might land in base.py when it belongs in dev.py or prod.py; secrets and env-specific config can leak. |
| ORM and transactions | It can introduce N+1 queries or call writes outside transaction.atomic(). Use django_assert_num_queries and rollback tests. |
| Templates and static files | It may forget {% load static %}, app template namespacing, or {% url %} names. |
| Signals and AppConfig | Signals may be registered at import time or not loaded when expected. Put signal imports in AppConfig.ready(). |
| DRF | Serializers may expose fields unintentionally, or permissions may be missing. Always review serializer fields and permission classes. |
These are not reasons to avoid Codex; they are exactly the spots where a quick human review pays off.
Verifying Django changes with pytest and manage.py
Make verification part of every prompt. Tell Codex to run pytest after each change and to show the command output. For Django-specific checks, ask for python manage.py check and makemigrations --check --dry-run. Use pytest -k for targeted tests while iterating, then a full run before review. When writing API tests, prefer rest_framework.test.APIClient and explicit status code assertions. Ask Codex to add django_assert_num_queries for query-sensitive paths and to run the test that proves the N+1 is gone. Review the test diff as carefully as the code diff: a model change with no test update is a red flag.
Running multiple agents safely with AgentVera
Running several agents in parallel on the same Django repository can create conflicts, especially around migrations and settings. AgentVera runs each agent in its own git worktree, so one agent can work on billing models while another works on the API without overwriting files. The automatic code review step matters most for Django because a second model can catch bad migrations, N+1 queries, or insecure DRF permissions with links to file:line. Checkpoints are valuable when a change breaks the migration graph; you can undo a full turn instead of manually reverting files. See AI code review: check what your agents write for how that review step works.
Final notes
Codex fits Django work best when the repository speaks for itself through AGENTS.md and when you keep changes small, tested, and reviewed. Treat generated migrations and settings changes as review points, not as fully trusted output. With that loop, Codex becomes a fast pair engineer for models, views, DRF endpoints, and pytest-django test coverage. For more on splitting work across agents, see AI agent workflow: teams, parallel parts and flows.