mnemosyne/CLAUDE.md

🐾 Red Panda Approval™

The standard every change is judged against. Don't satisfy a checklist — satisfy the red pandas. Ask of each change: does this earn approval?

1. Fresh Migration Test — migrations apply cleanly from an empty database.
2. Elegant Simplicity — no unnecessary complexity; the obvious solution, done well.
3. Observable & Debuggable — proper logging; failures say what broke and why.
4. Consistent Patterns — follows Django conventions and the patterns already in this repo.
5. Actually Works — passes all checks and serves a real user need.

Criteria 1 and 5 are externally verifiable — migrations apply or they don't; checks pass or they don't. Verify them, don't assert them. Criteria 2–4 are judgement calls: when in doubt, match what the repo already does rather than grading your own elegance.

If a paw print isn't leading the response, the rest of this file probably isn't being honoured either. Lead with one. 🐾

---

Conventions (always-on)

These are the rubric made concrete for the common case — writing models, views, forms, templates, and queries.

Models

• Names: singular PascalCase (User, BlogPost, OrderItem).
• Every model defines __str__ and get_absolute_url.
• Every model has created_at = DateTimeField(auto_now_add=True) and updated_at = DateTimeField(auto_now=True).
• TextChoices for status fields.
• related_name on every ForeignKey; plural snake_case with correct English pluralisation.
• Public-facing models: consider UUIDField primary key and is_active for soft deletes.

Field naming

• Foreign keys: singular, no _id suffix (author, category, parent).
• Booleans: prefixed (is_active, has_permission, can_edit).
• Dates: suffixed (created_at, updated_at, published_on).
• No abbreviations (description, not desc).

Views

• Function-based views exclusively. Explicit logic over implicit inheritance. Extract shared logic into utility functions.
• Business logic lives in service functions, not views and not save().

Forms

• ModelForm with an explicit fields list — never __all__, never exclude.
• Validate at the boundary; never trust client-side validation alone.

Queries

• select_related() for FKs; prefetch_related() for reverse and M2M.
• No queries inside loops (N+1). No .all() when you need a subset.
• .only() / .defer() for large models. Comment non-obvious querysets.

URLs & identifiers

• Public URLs use 12-char short UUIDs via shortuuid. Never expose sequential IDs (enumeration risk). Internal refs may use PKs.
• Resource-based, namespaced URL names per app, trailing slashes, flat structure preferred.

Docstrings

• Google style. Document public classes, functions, methods, modules.
• Imperative one-line summary. Args:/Returns:/Raises: only when the signature doesn't already convey it. Don't restate type hints in prose.
• Skip obvious one-liners and standard Django overrides.

Code organisation

• PEP 8 import ordering (stdlib, third-party, local). Type hints on params.
• CSS and JS in external files only — no inline styles, <style>, inline handlers, or <script> blocks.
• File length: split by domain concept past ~500 lines; hard ceiling 1000.

Testing

• Django TestCase (not pytest). Separate files per module: test_models.py, test_views.py, test_forms.py.

An app isn't done until it's reachable django-admin startapp builds an island. A complete-from-its-own-boundary app — models, views, urls, templates, tests all present and passing — is

Add to always-on Django CLAUDE.md — Conventions section

Insert this block under "Conventions (always-on)", as its own subsection. It is the universal Django definition-of-done. It fires for every app, not just registered tools.

An app isn't done until it's reachable

django-admin startapp builds an island. A complete-from-its-own-boundary app — models, views, urls, templates, tests all present and passing — is still unfinished if nothing in the running site links to it. "It works in isolation" is not done; "a user can reach it from the running site" is done.

Before reporting a new app complete, wire it into the site:

1. INSTALLED_APPS — add the app's config.
2. Root URLconf — include() the app's urls.py in config/urls.py. An app whose URLconf isn't included has unreachable views, full stop.
3. Navigation / discovery — register the app so it surfaces wherever this project expects apps to appear. This project uses an app registry (see Project Setup): the app registers itself in its own apps.py.ready() and the navigation template tag picks it up. Do not hand-edit nav templates or central list views — they read from the registry.
4. Verify reachability — confirm the app's main page actually loads from the running site (not just that its tests pass). Per Red Panda criterion 5, this is externally verifiable: load the page, don't assert it works. Why this rule exists: an LLM reasons locally and closes the visible task at the app's own boundary. The wiring that makes an app reachable lives in other files (config/urls.py, INSTALLED_APPS, the registry) with no signal inside the new app pointing to them. Without this rule, the near-certain result is a fully-built, completely inaccessible app. The registry exists precisely so that "surface it" happens inside the app's own boundary (a register() call in ready()) — collapsing the wiring into the one place local reasoning will actually look.

The same principle generalises beyond Django: a new route that isn't mounted, a CLI subcommand not added to the dispatcher, a handler not registered — all the same failure. Done means connected, not written.

---

Always-on anti-patterns

The cross-cutting tripwires worth carrying everywhere. File-specific landmines (nginx, compose, broker) are in path-scoped rules.

• Models: no .get() without handling DoesNotExist; no null=True on CharField/TextField (use blank=True, default=""); always specify on_delete; don't override save() for business logic; no Meta.ordering on large tables.
• Security: secrets via env vars, never in settings.py; never commit .env; never DEBUG=True in production; never mark_safe() on user-supplied content; never disable CSRF.
• Templates: {% url %} not {{ variable }} for URLs; no logic in templates; {% csrf_token %} in every form.
• Imports/style: no import *; no mutable default args; no bare except:; don't silence linter warnings without a documented reason.

---

Environment

• Virtual environment: ~/env/PROJECT/bin/activate (replace PROJECT).
• pyproject.toml for config — no setup.py, no requirements.txt.
• Dependencies floor-pinned with ceiling (Django>=5.2,<6.0). Exact == pins only in application lock files, never in reusable packages.
• Dev DB: SQLite. Production DB: PostgreSQL.

---

Path-scoped rules to create (.claude/rules/)

These hold the landmines extracted from the standards doc. Each loads only when its paths match, keeping this file lean. Frontmatter shown.

• nginx.md — paths: ["nginx/**", "**/*.conf"] — reverse-proxy reference config: Docker DNS resolver + variable proxy_pass, $proxy_x_forwarded_proto map, access-log filtering, RFC1918 allowlists (all four ranges), always security headers.
• docker-compose.md — paths: ["docker-compose*.y*ml", ".env*"] — per-service environment: scoping (no shared env_file:), ${VAR} interpolation, .env.example annotation convention, the repr() parse diagnostic.
• celery-tasks.md — paths: ["**/tasks.py"] — idempotency, retry logic, pass IDs not instances, synchronous-by-default, broker URL percent-encoding, progress pattern {app}:task:{task_id}:progress.
• migrations.md — paths: ["**/migrations/**"] — never edit deployed migrations; RunPython needs a reverse; no non-nullable field without a default; meaningful --name; test forward and backward.
• memcached.md — paths: ["**/settings.py", ".env*"] — bind 0.0.0.0 not localhost; container can't reach 127.0.0.1; LAN hostname in KVDB_LOCATION; key pattern {app}:{model}:{identifier}:{field}.
• frontend.md — paths: ["**/templates/**", "**/static/**"] — DaisyUI+ Tailwind for new projects / Bootstrap 5 for existing; extend themis/base.html; no inline styles or scripts.

Reference docs (consult on demand, don't inline)

• docs/ gotcha writeups: broker-URL/Kombu parsing, env-file parsing differences, nginx IP-caching. State the rule in the rule file; link the why here.
• Preferred-packages list and per-app architecture: keep in docs/, not in this always-on file.