# Using opencode with Django: A Practical Guide

URL: https://agentvera.dev/en/blog/opencode-for-django/ · Published: 2026-11-01

Learn how to use opencode in a Django project: configure AGENTS.md, plan migrations and ORM changes, run tests, review diffs, and avoid common pitfalls.

**In short:**

- opencode works well in a Django project when you give it a precise AGENTS.md describing commands, app layout, and Django-specific rules.
- Use a loop of small planned changes with targeted prompts, run tests and migrations checks, then review the diff before accepting.
- Watch it closely around migrations, ORM query counts, and Django settings because those are where subtle breakage happens.

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](/en/agents/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](/en/blog/how-to-use-opencode/).

## 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.

```markdown
# 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)](/en/blog/best-tools-parallel-ai-coding-agents/).

## 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.

## Frequently asked questions

**How do I start opencode in a Django project?** Run opencode in the project root after activating your virtual environment or installing dependencies. It picks up AGENTS.md automatically, so put your Django build, test, and lint commands there before starting.

**Can opencode write Django models and migrations?** Yes, it can create models, fields, and migrations with python manage.py makemigrations. Always review the generated migration files and run python manage.py makemigrations --check --dry-run or the test suite before accepting.

**How do I keep opencode from breaking my Django project?** Use a small-step workflow with clear acceptance criteria and a plan before editing. Run python manage.py test or pytest and linters after each change, and review the diff carefully, especially for migrations and settings.

**Does opencode work with Django REST framework?** Yes, it can add or modify serializers, viewsets, routers, and permissions. Provide the existing serializers and URL patterns as context or ask it to inspect the code first, then verify with pytest-django and an OpenAPI schema check if you use drf-spectacular.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/