# Gemini CLI Django: Practical Setup, Prompts, and Testing

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

Use the Gemini CLI coding agent on a Django project: practical setup, effective prompts, pytest-django testing, and common pitfalls to watch.

**In short:**

- Start Gemini CLI inside your Django repo with a GEMINI.md that pins commands and app conventions.
- Use small, test-first prompts for models, migrations, views, and DRF serializers; review diffs before committing.
- Watch for migration conflicts, ORM query counts, settings changes, and template or async issues when the agent edits code.

Gemini CLI is a terminal coding agent you start by running `gemini` inside a Django project folder. With a project-specific GEMINI.md and a test-first workflow, it can draft models, migrations, views, serializers and targeted fixes while you review every diff. This guide covers what to put in GEMINI.md, the prompt loop that works, common Django pitfalls, and verification steps.

## How Gemini CLI fits Django development

Django projects are predictable: apps, models, migrations, views, templates, URLs and settings follow clear conventions. That makes them a good fit for a coding agent. When the project rules are written down, Gemini CLI can handle repetitive work such as adding a new endpoint, updating form fields across templates, converting a function-based view to a class-based view, or expanding test coverage. The real value is not autonomous coding; it is cutting boilerplate and giving you a concrete diff to review. If the app layout and commands are explicit, the agent spends less time guessing and more time producing usable Django code.

For example, a well-structured Django repo with separate apps for accounts, billing and API lets the agent scope changes cleanly. You can ask for a new serializer in the API app without it touching unrelated templates. The agent also benefits from clear naming: services and selectors keep business logic out of views, which reduces the chance of breaking existing endpoints.

## Preparing the repo for Gemini CLI

Gemini CLI reads project instructions from GEMINI.md in the project root. Treat it like an onboarding note for a new Django developer: include the commands for dependencies, tests, linting, formatting, migrations and server startup. Also record folder conventions and rules that are not obvious from one file. A short, specific file is better than a long generic one.

```markdown
# GEMINI.md

## Commands
- Install dependencies: `pip install -r requirements.txt`
- Run tests: `pytest`
- Run one test: `pytest path/to/app/tests/test_views.py::test_home -x`
- Lint: `ruff check .`
- Format: `ruff format .`
- Make migrations: `python manage.py makemigrations`
- Apply migrations: `python manage.py migrate`
- Check for missing migrations: `python manage.py makemigrations --check --dry-run`
- Run server: `python manage.py runserver`

## Project layout
- Apps: `accounts`, `payments`, `api`
- Business logic in `services.py` or `selectors.py`
- Templates in `templates/<app>/`
- DRF serializers and viewsets in the app they belong to

## Django rules
- Keep business logic out of views; use services and selectors.
- Prefer class-based views unless a function-based view is simpler.
- Use `select_related` and `prefetch_related` explicitly when crossing relations.
- Never edit `settings.py` without checking the environment-specific blocks.
- Generate migrations only for the app you changed: `python manage.py makemigrations <app>`.
- After model or migration changes, run the full test suite before committing.
```

Keep the file short and current. If the test command changes, update GEMINI.md. Also add any fixtures or factories the project relies on, such as `pytest-django` fixtures in `conftest.py`, so the agent does not invent its own data setup. For the base CLI loop, see [How to use Gemini CLI: a step-by-step guide](/en/blog/how-to-use-gemini-cli/).

## A practical Django prompting loop

Work in small, reviewable steps. Start by asking the agent to read the relevant models, views, serializer and tests. Then make one change at a time: a field, a migration, a serializer or a view. After each turn, run the narrowest relevant test command or ask the agent to run it, and inspect `git diff` before moving on. Avoid letting the agent create multiple migrations across apps in a single turn unless you explicitly ask for it. Example prompts that work well:

- Add a `published_at` DateTimeField to the `Post` model in `blog`, generate a migration for `blog` only, expose the field in `PostSerializer`, and add a filter to `PostViewSet`.
- Convert the `home` view to a `TemplateView`, move the queryset into a selector function, and add a pytest-django test for the context.
- Write a test that reproduces the duplicate slug error in `Article.save()`, then make the minimal model or form change so the test passes.
- Update the `Order` DRF endpoint to accept nested `line_items` as a writable serializer, but keep `total_price` read-only.
- Reduce queries in `user_dashboard`; use `select_related` and `prefetch_related`, then run `pytest -k dashboard` to confirm the query count drops.

For each prompt, ask the agent to show the diff and the test command it ran. If it suggests a migration, have it run `python manage.py makemigrations --check --dry-run` to confirm no missing migrations. This loop is close to [AI pair programming: how to work with a coding agent](/en/blog/ai-pair-programming/).

## Where Gemini CLI excels and where to double-check

Gemini CLI is useful for adding simple model fields with migrations, writing DRF serializers and viewsets, adding form validation, registering models in admin, and expanding fixtures or factories. It is less reliable around multiple settings files, custom user models, migration history in a shared branch, and transactions.

| Area | Good prompt | What to check |
|------|-------------|---------------|
| Models and fields | Add a `slug` CharField to `Article` with `unique=True`, create a migration for `news` only, and add a duplicate-slug test. | Migration file in the right app; defaults; unique constraints against existing data. |
| DRF APIs | Create `CommentSerializer` and `CommentViewSet` for the `posts` app, using `Post.objects.prefetch_related('comments')`. | Query count, serializer fields, router registration, pagination. |
| Views and templates | Refactor `post_detail` to use `get_object_or_404` and add a `can_edit` context flag. | Template variable names, object permissions, `request.user` checks. |
| Tests | Write a pytest-django test for `Order.status_transition` using `django_assert_num_queries`. | Test isolation, fixtures, pytest-django database setup. |
| Settings and migrations | Change `AUTH_USER_MODEL` to `accounts.User` and update all references. | Treat as high risk; review every settings change and migration dependency. |

Specific Django pitfalls to watch: the agent may edit `settings.py` without respecting environment-specific blocks, introduce N+1 queries by looping over related objects in views or templates, create a migration in the wrong app when app labels are ambiguous, or change pytest-django options such as `--reuse-db` or `--nomigrations` without understanding the test setup. Also check that it does not use `select_for_update` or transactions in a way that conflicts with Django’s test runner. Review generated migrations and settings diffs manually.

For example, if the agent adds a field to a model and generates a migration, verify that the migration includes the correct `app_label` and dependencies. If it modifies a view, look for any `.all()` calls that could be replaced with `select_related` or that might load thousands of rows.

## Testing Django changes with confidence

The fastest safe workflow is to make the agent write or update a test first. Configure pytest-django in `pytest.ini` or `pyproject.toml` so the settings module is deterministic, then put the exact test command in GEMINI.md. After each change, run the narrowest test command first, then the full suite. Tell the agent to run `pytest path/to/app/tests/test_models.py -x` and paste failures. If it proposes a migration, run `python manage.py makemigrations --check --dry-run` to confirm no missing migrations. Also run `python manage.py check` and `ruff check .` if configured. Do not rely on the agent’s summary; inspect the diff yourself.

For pytest-django, set `DJANGO_SETTINGS_MODULE` in `pytest.ini` or use a `conftest.py` with `pytest_configure`. If the agent writes a test that uses database access, ensure the test is marked with `@pytest.mark.django_db` or that the fixture uses `db`. Check that it does not mix `TestCase` and pytest style inconsistently. For a debugging workflow, see [How to debug code with AI: a practical workflow](/en/blog/debug-code-with-ai/).

## Coordinating several agents on one Django repo with AgentVera

AgentVera is a desktop app that runs coding agents' real command line tools side by side in one window, each in its own real terminal panel. For a Django project, the most useful parts are parallel agents in separate git worktrees, automatic code review after each turn with findings linked to file:line, checkpoints that let you undo a bad migration or settings change in one click, and token budgets that stop runaway work without losing the conversation. This keeps isolated app changes from overwriting each other and gives you a review gate before migrations or API changes reach the main branch.

## Closing notes

Start with a concise GEMINI.md, keep changes small, and make the agent earn every diff with a passing test or a clear verification command. Gemini CLI is not a replacement for Django knowledge, but it can handle the mechanical parts while you focus on data modeling, API design and review. The more deterministic your commands and conventions, the more useful the agent becomes.

## Frequently asked questions

**How do I start Gemini CLI in a Django project?** Open a terminal in the project root and run gemini. Add a GEMINI.md file with your Django commands and conventions, then ask for small changes. The agent reads that file on startup and uses it as project instructions.

**Can Gemini CLI create Django models and migrations?** Yes, it can write Django models and run python manage.py makemigrations. Always review the generated migration file, especially for app labels, dependencies and unique constraints, and run the test suite before committing.

**How do I make Gemini CLI use pytest-django for tests?** Configure pytest-django in pytest.ini or pyproject.toml, then put the exact test command such as pytest in GEMINI.md. Ask the agent to run that command after each change and inspect any failures yourself.

**What should I watch out for when Gemini CLI edits Django settings or views?** It may introduce N+1 queries in views or templates, edit settings without respecting environment-specific blocks, or create migrations in the wrong app. Review every diff for settings, migration files and query access, and run python manage.py check.

---

**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/