django

Django conventions

These are one developer's house rules for their own Django projects. They are not Django community consensus, and they are not binding on anyone else's codebase.

When contributing to a project you do not own, that project wins. Its CLAUDE.md or AGENTS.md, its existing code, its reviewers, and any explicit instruction all take precedence over anything here, and where they are silent the surrounding code is the better guide. Follow these by default on the owner's own projects; treat them as a starting point everywhere else.

Each convention below states a principle that holds for any Django project, then the concrete values for this one. Every concrete value (which formatters, which threshold, which paths) comes from profile.json. Read it first; do not assume the stack named here is the stack this project runs.

Adapting the skill to a different project is profile.json plus ADAPTING.md.

This skill is meant to grow. Each convention is self-contained. Add new ones under ## Conventions, and when a convention has real implementation detail, give it a file under references/ and link it from here.

Conventions

Code style: match the project's formatters, and emit code that already passes

Principle. Whatever formatters and linters a project runs, match them and emit code that passes them on the first try. CI runs them in check mode and fails on any diff, so unformatted code never merges. Hand-formatting around a formatter wastes a review cycle and produces a diff the next make reformat will undo.

The one trap worth knowing regardless of project: if both isort and black run, isort must use profile = black. Otherwise the two rewrite imports each other's way and CI never converges.

This project (profile.json → formatting). The stack is black, isort, djlint, flake8, checked by make lint and autofixed by make reformat, each running inside docker compose run --rm web.

• black formats Python on its defaults. There is no [tool.black] block anywhere in the repo; do not add one. Write black-shaped code: no manual alignment, no fighting its line breaks.
• isort sorts imports with profile = black: stdlib, third-party, first-party, alphabetized, parenthesized multi-line imports with trailing commas.
• djlint formats and lints Django templates with profile = "django". Formatting and linting run as two separate commands, not combined.
• flake8 lints Python with max-line-length = 100 but E501 extended-ignored, so flake8 never fights black over length. Black's 88 governs in practice.
• makemigrations --check also runs in make lint, so a model change without a migration fails the build.