Imported from chrysa/django-query-optimizer-vscode (AGENTS.md). Install upstream with npx skills add chrysa/django-query-optimizer-vscode. Copyright stays with the author.

AGENTS.md — django-query-optimizer-vscode

Guidance for AI coding agents working in this repository. See CLAUDE.md for the full project brief; this file is the agent-facing quick reference.

What this is

A YAML-driven Django app scaffolder. The forgeapps management command reads a spec document and generates Django apps with a custom structure — a generic, declarative replacement for per-project Python scaffolding scripts.

Architecture rules (do not break)

• The core (naming.py, render.py, spec.py, generator.py) MUST stay import-free of Django. Only apps.py and management/commands/forgeapps.py touch Django.
• plan() is pure (no side effects); apply(dry_run=True) reports actions but writes nothing — keep --dry-run exact.
• Existing files are SKIP by default; --force overwrites. Never clobber by default.

Always do

• Run tests, lint, type-check, and build through Docker or pre-commit only — never on the host. Use make docker-test, make lint, make typecheck, make test-cov.
• Keep code, comments, docs, commits, and PRs in English.
• Conventional commits (feat/fix/chore/docs/refactor/test/build/ci) — the changelog and version bump are derived from them (cliff.toml, GitVersion.yml).
• mypy strict (django-stubs), ruff line length 120, coverage fail_under = 85.

Never do

• Never add a Django import to the core modules.
• Never run pytest / ruff / mypy directly on the host.
• Never overwrite generated files without --force semantics in the generator.

Resources

chrysa standards — agent view (generated)

The same rules as CLAUDE.md, for any AGENTS.md-aware tool. Detail loads on demand from standards/rules/<domain>.md; the canon is standards/STANDARDS.chrysa.md.

Governance, language & compliance · standards/rules/governance.md

• Normative annexes
• Language
• Compliance targets
• Governance — strategic pillars & ADR format

Cross-cutting stack · standards/rules/stack.md

• Cross-cutting stack (settled ADRs — do not relitigate)

SCM — branches, commits & pull requests · standards/rules/scm.md

• Commits
• Branches
• Branch model — main is production, develop is the workspace
• Merge
• One PR per issue
• Every PR references a Shortcut story
• Issues and PRs are type-driven

Architecture, decoupling & portability · standards/rules/architecture.md

• Repo provenance — every code repo depends on project-init
• Every repo declares its profile and DDD level
• Projects talk through versioned contracts only
• Everything is machine-agnostic and portable — no rule, repo, or script is bound to one machine
• Every external server the service talks to is addressed through the environment — never hardcoded
• Every tracked file and folder must earn its place — a repo holds only what is useful to it now
• The repository architecture is legible to an agent — optimised for Claude, not only for humans
• Deferred work is a governed job, not a fire-and-forget

Testing · standards/rules/testing.md

• Tests: pytest only
• Frontend tests: Vitest + Testing Library + MSW — from the scaffold, not later

Frontend & web semantics · standards/rules/frontend.md

• TypeScript is strict by contract
• The JS/TS package manager is pnpm — npm and yarn are forbidden
• React is a presentation layer, not the domain
• The frontend says when the backend is unreachable or unstable
• The frontend is reactive and real-time by default
• UI state survives reload & focus
• Everything is semantic — the markup, the data, and the URLs
• URL-addressable frontend navigation — mandatory

APIs, contracts & real-time · standards/rules/api.md

• A real-time backend has channel contracts and never blocks
• APIs, SDKs & public contracts follow the STD-API-001 contract

Accessibility · standards/rules/accessibility.md

• Dark mode
• Every site is usable by the majority of disabilities — not only the screen-reader case

Documentation & session state · standards/rules/docs.md

• Notion logging
• Documentation and Notion are maintained in lockstep with the code — a change that leaves them stale is unfinished
• Every repo ships generated context files
• Session lifecycle (primer + memory + hindsight)

AI agents & features · standards/rules/agents.md

• Agent actions are governed
• An AI feature is evaluated, not just shipped
• An agent writes only where the owner owns

Security, identity & sessions · standards/rules/security.md

• Per-person data implies a user account — no exceptions dressed up as simplicity
• Identity goes through the cluster SSO first
• Rights are resolved against the common directory (LDAP), never re-declared per service
• A session is secured and it expires
• Every form is a hostile input surface — validate on the server, always
• Security scanning is a gate, not an afterthought — it runs in pre-commit and in CI

Code quality & anti-patterns · standards/rules/code-quality.md

• No hardcoded constants
• No literal HTTP status codes — use the constants the framework already ships
• No code duplication — the second occurrence is an extraction order
• Raised errors are typed
• Failures are contained, and observable
• Prefer a lookup table to a state machine
• Decompose into small, independently unit-testable methods
• Code is read far more often than it is written — optimise for the reader, and standardise the form
• Avoid lambdas and anonymous constructs — a named function is the default
• Basic optimisations and known anti-patterns are caught in review and in CI
• A cache is a correctness contract, not a sprinkle of speed
• Quality gates
• Error handling pattern (all automations)

Backend Python · standards/rules/backend-python.md

• Python packaging — pyproject.toml is the single source of truth
• Python is written object-oriented, one class per file
• Import the item, not the module — from x import y; y()
• Functions and methods are called with named arguments — positional call sites are the exception, not the rule

Data, persistence & migrations · standards/rules/data.md

• Data, persistence & migrations follow the STD-DATA-001 contract

Observability & operations · standards/rules/observability.md

• Observability & production readiness follow the STD-OPS-001 contract
• The container is versioned separately from the application it hosts, and an admin can see what is actually deployed
• Observability — error-tracking → GitHub issues (norm)

Containers & compose · standards/rules/containers.md

• Everything runs in a container — the only exception is the slice of a repo genuinely bound to the host OS
• External dependencies are installed in containers, never on the host
• No virtualenv in a repo — ever
• Tool caches & deps never touch the project tree
• Dockerfiles are multi-stage, with a production and a dev stage — mandatory
• App containers ship the app only — the platform layer is the owner's responsibility
• Only a publicly useful port is published — everything else stays on the container network
• A compose file is minimal — declare only what the stack needs, default the rest
• Dev stage must hot-reload
• Local dev runs the code in-container, live, in debug mode — never the production server
• Default to dev mode when starting an app locally — any other mode only when explicitly asked
• .dockerignore mandatory & exhaustive
• Container-runtime policy

Product surfaces · standards/rules/product.md

• Setup wizard & config panel
• A game is DRM-free and fully playable solo offline
• Every product that is operated ships a management backoffice
• If a user can supply a file, the product accepts an upload
• A floating assistant where it earns its place — never as decoration

Design system · standards/rules/design.md

• Design system

Developer loop & tooling · standards/rules/dev-loop.md

• Makefile targets
• Shared skills (load on demand from shared-standards/.claude/skills/)

CI/CD, pre-commit & release · standards/rules/ci-cd.md

• Release & changelog config (canonical)
• GitHub Actions (reuse first · custom actions centralised · thin workflows)
• Pre-commit & git hooks (native, via pre-commit.com — never wrapped in make)