loadout python.instructions.md

Python Engineering Instructions (CLI + API, framework-agnostic) 🐍

These instructions define the default engineering approach for building modern, production-grade Python CLIs and APIs.

They must remain applicable to:

• Minimal CLIs (standard library argparse)
• Command frameworks (for example Typer, Click)
• Rich output and TUIs (for example Rich, Textual, prompt_toolkit)
• Django (including Django REST Framework)
• FastAPI (ASGI)
• AWS Lambda–hosted APIs (for example API Gateway + Lambda, function URLs, or containers)

They are non-negotiable unless an exception is explicitly documented (with rationale and expiry) in an ADR/decision record.

Identifier scheme. Every normative rule carries a unique tag in the form [PY-<prefix>-NNN], where the prefix maps to the containing section (for example OP for Operating Principles, LCL for Local-first developer experience, QG for Quality Gates, continuing through AI for AI-assisted expectations). Use these identifiers when referencing, planning, or validating requirements.

---

0. Quick reference (apply first) 🧠

This section exists so humans and AI assistants can reliably apply the most important rules even when context is tight.

• [PY-QR-001] Specification first: treat the specification as the source of truth for behaviour ([PY-OP-001]).
• [PY-QR-002] Small, safe changes: prefer small, explicit, testable changes ([PY-OP-002], [PY-OP-006]).
• [PY-QR-003] Fast feedback: local development and tests must be quick and confidence-building ([PY-OP-007], [PY-LCL-001]–[PY-LCL-008]).
• [PY-QR-004] Run the quality gates after any code/test change and iterate to clean ([PY-QG-001]–[PY-QG-005]).
• [PY-QR-005] Validate at boundaries and reject ambiguous inputs ([PY-DATA-001]–[PY-DATA-003]).
• [PY-QR-006] Deterministic outputs: stable ordering, stable field naming, no hidden randomness ([PY-OP-003], [PY-CTR-007]).
• [PY-QR-007] Correct CLI streams: stdout for primary output, stderr for diagnostics ([PY-BEH-008]–[PY-BEH-011]).
• [PY-QR-008] No secrets in args or logs: use env vars or secure prompts; never print secrets ([PY-SEC-001]–[PY-SEC-004], [PY-OBS-013]).
• [PY-QR-009] Local by default: no real cloud/network by default; use fakes/emulators; explicit integration mode switches ([PY-EXT-001]–[PY-EXT-007]).
• [PY-QR-010] Operational visibility: correlation IDs and structured logs for APIs; controlled diagnostics only ([PY-OBS-004]–[PY-OBS-010], [PY-OBS-015]–[PY-OBS-026], [PY-ERR-013]).
• [PY-QR-011] Static typing is mandatory: type hints + static analysis (mypy) are the critical safety net for AI-generated code; enforce in CI ([PY-TYP-001]–[PY-TYP-012]).
• [PY-QR-012] Avoid common anti-patterns: bare except, mutable defaults, assert for validation, global mutable state, untyped public APIs (§6, §21).