Gemini CLI Django: Practical Setup, Prompts, and Testing

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.

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

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.

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.

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.

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.