Using opencode with Django: A Practical Guide

opencode is a terminal coding agent you start by running opencode in your Django project root. It reads AGENTS.md for project instructions and can modify Django apps, models, migrations, views, templates, and DRF code. The opencode agent works with any model provider you configure, so the workflow stays the same across providers. Think of it as a fast junior Django developer: the more precise your conventions and acceptance criteria, the more reliable its changes.

A reliable pair for Django projects

Django projects reward convention-over-configuration. Apps, models, views, templates, and migrations have predictable locations, which makes an agent effective. AGENTS.md can capture your app layout, queryset style, and test commands once, and opencode will follow them across many tasks. You can ask it to run the project’s commands as part of the change, so it can execute python manage.py makemigrations, run a pytest-django test module, and check lint output before you review. Because a single Django change often spans a model, migration, serializer, view, and test, an agent that can read and edit across the repo keeps those changes coherent. For a broader walkthrough of the workflow, see How to use opencode: a step-by-step guide.

Give opencode the project context it needs

Create AGENTS.md in the repository root before starting opencode. It should list the exact commands for installing dependencies, running migrations, running tests, and linting. Also record the app folder convention and hard rules about Django-specific behavior. This prevents the agent from guessing whether tests use pytest or python manage.py test, whether apps live under apps/, or whether you expect migrations to be generated by makemigrations instead of handwritten.

# AGENTS.md

## Commands
- Install: `python -m pip install -r requirements.txt`
- Migrate: `python manage.py migrate`
- Tests: `pytest` (uses pytest-django) or `python manage.py test`
- Lint: `ruff check .`
- Format check: `ruff format --check .`

## Project layout
- `config/` contains settings, root URLconf, wsgi/asgi.
- Apps live under `apps/<app_name>/` with models.py, admin.py, views.py, urls.py.
- Keep reusable querysets and managers in `apps/<app_name>/managers.py`.

## Django-specific rules
- Never edit migrations by hand; always use `python manage.py makemigrations <app>`.
- Keep model logic on models, querysets, or managers; keep views thin.
- Use `select_related` and `prefetch_related` for any ORM query used in a loop or template.
- Any new endpoint or model change must include tests before the task is done.

Keep this file short enough to be read every session. Update it when you change the test runner, add a new app, or adopt a stricter lint rule; the agent will follow the latest version.

Plan, change, test, review: a practical loop

Use a plan-first loop. Ask opencode to inspect the relevant files and propose a plan before editing. For each task, name the app and file, list acceptance criteria, and tell it to run the relevant test command. After it edits, run the full test module or the linter yourself, then review git diff for unintended changes, especially in migrations and settings.

Example prompts:

• “In the blog app, add a nullable published_at DateTimeField to Post, with a database index. Generate the migration, update the admin list display, and run the blog tests.”
• “Create a DRF read-only endpoint GET /api/posts/ that returns published posts ordered by -published_at. Use the existing PostSerializer, add pagination, and include a test.”
• “Refactor the PostQuerySet to add published() and by_author(username) methods. Update PostListView to use them and confirm no N+1 queries in the template.”
• “Two tests in apps/blog/tests/test_views.py are failing after the last change. Inspect the failures, make the smallest fix, and run only that test module.”
• “Audit PostDetailView for unnecessary queries. Rewrite the queryset to avoid N+1, then add a test using django_assert_num_queries that fails on the old code and passes on the new code.”

Before accepting a larger task, ask for a plan: “Show me your plan and the files you will change before editing.” This forces the agent to map the change instead of touching unrelated files.

Where opencode shines and where it can break your Django app

opencode is strong at adding models, fields, migrations, admin entries, DRF serializers and viewsets, template updates, and tests. It is also useful for query refactors when you give it the relevant model and view. The risk areas are Django-specific: migration graph conflicts, app registry issues in settings or signals, N+1 queries hidden by templates, permission or authentication oversights in DRF, and accidental changes to generated migration files. Watch it closely when it edits settings.py, apps.py, urls.py, or any file that touches the app registry at import time. If the task touches multiple apps, require a migration plan first and run python manage.py makemigrations --check --dry-run before accepting.

Verify every change like a responsible Django engineer

Make verification non-negotiable. Before the task is complete, opencode should run the relevant test subset and either ruff check or python manage.py check. For migrations, run python manage.py makemigrations --check --dry-run to catch missing migrations. For pytest-django, let the agent run pytest apps/blog/tests/test_views.py -x or the full suite when the change is broader. Review the generated migration after every model change: check field defaults, related names, and unique constraints.

| Verification | Command | What it catches | | Missing migrations | python manage.py makemigrations --check --dry-run | Model changes without a migration file | | Test failures | pytest apps/blog/tests -x | Broken views, ORM queries, serializers, forms | | Lint and format | ruff check . && ruff format --check . | Unused imports, style drift, missing trailing commas | | Django system check | python manage.py check | Settings, URL confs, app loading, model errors |

Scaling with parallel opencode agents in AgentVera

When one Django task is too large or you want independent work on separate apps, AgentVera lets you run several opencode agents side by side. Each agent can work in its own git worktree, so one agent changing models and migrations in blog does not overwrite another editing DRF views in api. Automatic code review at the end of each turn links findings directly to file and line, which is useful for catching migration or permission mistakes. Checkpoints let you undo a bad turn and replay the session, so a broken settings change or migration conflict is not a dead end. For more on parallel agent workflows, see Best tools to run AI coding agents in parallel (2026).

Make opencode part of your Django workflow

opencode becomes a reliable Django pair when you invest a little upfront in AGENTS.md and a tight test loop. Keep tasks small, always review migrations and settings changes, and use the verification commands above before committing. With that discipline, opencode can handle a large share of model, view, serializer, and test work without producing surprises.