CLAUDE.md for a Django project

When to use this

Use it on a Django app with a Postgres database and pytest. The section that matters most is the migrations rule: agents love to hand-edit a migration file, which breaks the next person's database. Fill in the project name and change the database or dependency tool to match yours.

# [Project] — agent guide

## Stack
Django 5, Python 3.12, PostgreSQL. Dependencies with pip in a virtualenv.

## Commands
- Install: `pip install -r requirements.txt`
- Run: `python manage.py runserver`
- Migrate: `python manage.py migrate`
- Test: `pytest`
- Lint and format: `ruff check .` then `ruff format .`

## Conventions
- One app per domain area. Keep business logic in services, not views.
- Use the ORM. Write raw SQL only when a query needs it, with a comment why.
- Add a migration for every model change and commit it with the change.
- Split settings per environment. Read secrets from the environment.

## How to work here
- Run pytest and ruff before you call a task done.
- Make the smallest change that solves the task.

## Do not
- Do not hand-edit files in `migrations/`; generate them with makemigrations.
- Do not commit the local database or `.env`.
- Do not add a dependency without saying why in the pull request.

Why each section is there

• Stack pins the Django and Python versions so the agent writes current code.
• Commands hand it the real manage.py, test and lint lines.
• Conventions keep logic out of views and migrations committed with their change.
• Do not stops the two classic mistakes: edited migrations and committed secrets.

Prefer a form? The CLAUDE.md generator writes one from a few answers. For how an agent reads a file like this, see working with agents.