code

name: code description: ALWAYS follow this style when writing Python / JavaScript code

• Ask if the success criteria is unclear
• Prefer libraries to writing code. Prefer popular, modern, minimal, fast libraries
• Write readable code. Keep happy path linear and obvious. Write flow first, then fill in code. Name intuitively
• Keep code short
  • Data over code: Structures beat conditionals. Prefer config.{json|yaml|toml|...} if >= 30 lines
  • DRY: Helpers for repeated logic, precompute shared intermediates
  • Early returns fail fast and reduce nesting. Skip defensive fallbacks, existence checks, ... unless essential
  • YAGNI: Skip unused imports, variables, and code
• Change existing code minimally. Retain existing comments. Follow existing style
• Use type hints and docstrings (document contracts and surprises, not mechanics)
• Only comment non-obvious stuff that'll trip future maintainers: why, why not alternatives, pitfalls, invariants, input/output shape, ...
• When tests exist, or writing new code, add new failing tests first (including edge cases). Keep tests fast
• Test web pages with screenshots (for layout, overlaps, contrast) AND DOM (for interactions, navigation) before finalizing
• Log status & progress for long tasks (>5s)
• Make scripts re-startable if interrupted
• Check latest docs for fast moving packages

Python

Prefer uv run --with pkg1 --with pkg2 script.py, uvx --from pkg cmd over python or python3

Avoid requirements.txt. Unless pyproject.toml is present, add dependencies as PEP 723 metadata:

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.14"
# dependencies = ["scipy>=1.10", "httpx"]
# ///

Preferred libs:

• typer / click not argparse
• httpx not requests
• lxml not xml
• pandas not csv
• tenacity for retries

HTML

Prefer modern HTML:

• Loading: loading="lazy", fetchpriority="low", <link rel="preload" as="image">
• Forms: inputmode=, enterkeyhint=, autocomplete=, list=, autocapitalize=, spellcheck=, form=
• UI: popover, popovertarget=, formmethod="dialog", inert, <details name=""> for accordions, <dialog>, <meter>, <progress>, <track>, <data>
• Media: picture srcset=, video preload=, crossorigin=, playsinline=, muted=, autoplay=, loop=, controls=, poster=

JavaScript

Preferred JS style:

• Use CSS libraries. Minimize custom CSS
• Hyphenated HTML class/ID names (id="user-id" not id="userId")
• Use modern browser APIs and ESM2022+: Use ?., ??, destructuring, spread, implicit returns (=> over => { return })
• Avoid TypeScript, but enable // @ts-check. .d.ts is OK for packages
• Loading indicator while awaiting fetch()
• Error handling only at top level. Render errors for user

Preferred libs: d3, hljs, lit-html, marked, partial-json

Debug front-end apps with agent-browser or Playwright via CDP on localhost:9222. For single-page HTML files try file:// before spinning up a server.