Code

• 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)
• Don't comment readable code. If commenting, only comment non-obvious stuff that'll trip future maintainers: why, why not alternatives, pitfalls, invariants, input/output shape, ...
• When tests exists, or writing new code, add tests first. Keep tests fast
• Replace PII in committed code, tests, docs with similar REALISTIC dummy data
• Show status & progress for long tasks (>5s)
• Make re-runs efficient for long tasks (>1min). Restarting should resume. Log state, cache & flush data and LLM/API/HTTP requests, etc.
• Read latest docs for fast moving packages: GitHub README, npm view package-name readme, https://context7.com/$ORG/$REPO/llms.txt, ...

Python

Prefer uv run, uvx over python or python3

Unless pyproject.toml is present, add dependencies to script:

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

Preferred libs:

• typer / click not argparse
• httpx not requests
• lxml not xml
• pandas not csv
• orjson over json if speed/datetime matters
• tenacity for retries
• pytest
• python-dotenv

Use one of these for exception tracebacks with locals:

from rich.traceback import install; install(show_locals=True)
from loguru import logger; logger.add(sink=lambda m: print(m, end=""), diagnose=True, backtrace=True)

HTML

Prefer modern HTML:

• Loading: loading="lazy", fetchpriority="low",
• Forms: inputmode=, enterkeyhint=, autocomplete=, list=, autocapitalize=, spellcheck=, form=
• UI: popover, popovertarget=, formmethod="dialog", inert, for accordions, , , , ,
• Media: picture srcset=, video preload=, crossorigin=, playsinline=, muted=, autoplay=, loop=, controls=, poster=

Prefer SVG favicons e.g.

<link rel="icon" type="image/svg+xml" href="data:image/svg+xml,%3Csvg%20xmlns ... %3C%2Fsvg%3E"/>

designed with Unicode and rich typography, e.g.:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="128">
  <rect fill="#2563eb" width="64" height="64" rx="10"/>
  <text x="32" y="35" text-anchor="middle" dominant-baseline="middle" font-size="40">🌈</text>
</svg>

JavaScript

Preferred JS style:

• Bootstrap. Minimize custom CSS. Prefer declarative data-* patterns
• 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
• Helpers: const $ = (s, el = document) => el.querySelector(s); $('#id')...
• Prefer lit-html > .insertAdjacentHTML / .innerHTML >> .createElement + setting attributes
• Prefer vitest + jsdom for unit tests, Playwright for end-to-end tests
• Import maps: <script type="importmap">{ "imports": { "package-name": "https://cdn.jsdelivr.net/npm/package-name@version" } }</script>

Preferred libs:

import * as d3 from "d3"; // @7/+esm for visualizations
import hljs from "highlight.js"; // @11/+esm highlight Markdown code; link CDN CSS
import { html, render } from "lit-html"; // @3/+esm for DOM updates
import { unsafeHTML } from "lit-html/directives/unsafe-html.js";
import { marked } from "marked"; // @17/+esm
import { parse } from "partial-json"; // @0.1/+esm parse streamed JSON. `const { x } = parse('{"x":"incomplete')`

import { asyncLLM } from "asyncllm"; // @2 streams LLM responses. `for await (const { content, error } of asyncLLM(baseURL, { method: "POST", body: JSON.stringify({...}), headers: { Authorization: `Bearer ${apiKey}` } }))`
import { bootstrapAlert } from "bootstrap-alert"; // @1 for notifications. `bootstrapAlert({ title: "Success", body: "Toast message", color: "success" })`
import { geminiConfig, openaiConfig } from "bootstrap-llm-provider"; // @1 LLM provider modal. `const { baseUrl, apiKey, models } = await openaiConfig()`
import saveform from "saveform"; // @1 to persist form data. `saveform("#form-to-persist")`

Debug front-end apps with Playwright (prefer CDP on localhost:9222) using .evaluate(); view screenshot images, console logs.

Tmux

Use tmux outside the sandbox for interactive REPLs/TUIs, long running commands: servers, services, sub-agents: codex/claude/...

tmux new-session -d -s $SESSION 'uv run --with pandas,httpx,lxml python -iqu'
tmux pipe-pane -t $SESSION -o "cat >> /tmp/$LOG"
tmux send-keys -t $SESSION 'print(1 + 2)' C-m
cat /tmp/$LOG
tmux capture-pane -p -t $SESSION -S -5