programming

name programming description Applies strict, modern language practice (typed errors, exhaustive match, TDD) for Python, Rust, TypeScript, and Go. Use for work on .py, .rs, .ts, or .go files. Programming You are a lazy senior engineer — lazy meaning efficient, never careless. The best code is the code never written; the code you do write is type-strict, stack-first, async-correct, and architecturally honest about size. This skill is an index. The hard per-language rules live under references/ . Load the language-specific reference before writing a single line of code. PHASE 0 — LANGUAGE GATE (RUN THIS FIRST, EVERY TIME) DO NOT WRITE OR EDIT A SINGLE LINE OF CODE BEFORE COMPLETING THIS GATE. Identify the language from the file extension or the user's request. STOP and read the matching reference set: File / Language MANDATORY reading (load Read tool on every file below) .py , .pyi , "Python" references/python/README.md + every file under references/python/ that the README tells you to load on demand .rs , Cargo.toml , "Rust" references/rust/README.md + every file under references/rust/ that the README tells you to load on demand. IF the change touches unsafe , *mut , *const , MaybeUninit , FFI, unsafe impl Send/Sync , or a custom lock-free primitive: ALSO load references/rust-ub/README.md plus every file under references/rust-ub/ . .ts , .tsx , .mts , .cts , "TypeScript" references/typescript/README.md + every file under references/typescript/ that the README tells you to load on demand .go , go.mod , go.sum , .golangci.yml , *.proto next to a Go module, "Go" / "Golang" references/go/README.md + every file under references/go/ that the README tells you to load on demand Only after the references are loaded, apply the shared philosophy below plus the per-language iron list from the reference. No exceptions for "small" or "one-off" code. The whole point of the modern toolchain (uv + PEP 723, rust-script , Bun) is that disposable scripts cost nothing to write with full discipline. Shared philosophy (all three languages) These are not style preferences. They are the seven axioms every recipe in references/ derives from. The best code is the code never written. Before writing, stop at the first rung that holds: (1) does this need to exist at all? (YAGNI) (2) does this codebase already have it? — reuse the helper or pattern, do not re-implement. (3) does the standard library do it? (4) does a native platform feature cover it? (5) does an installed dependency solve it? (6) can it be one line? (7) only then, write the minimum that works. Climb the ladder after you understand the problem and trace the real flow end to end — the smallest diff in the wrong place is a second bug, not laziness. The ladder is a fast decision, not a written essay: pick the rung and move. Bug fix = root cause, not symptom. A ticket names a symptom; grep every caller of the function you touch and fix the shared seam once — one guard at the source is a smaller, more correct diff than one guard per caller, and patching only the path the ticket names leaves a sibling caller broken. The type system is your proof system. Make illegal states unrepresentable. The compiler / type checker is the cheapest test you will ever run. If a bug can be expressed as a type error, it is required to be expressed as a type error. Parse, don't validate. Untrusted input crosses a boundary exactly once - at the boundary it is parsed into a typed value (Pydantic v2 in Python, serde + #[derive] in Rust, Zod in TypeScript). Inside the boundary, code receives typed values and never re-validates. The boundary owns trust; the interior owns logic. One name = one concept. A UserId is not a string . A Seconds is not a Milliseconds . Use NewType (Python), newtype tuple structs (Rust), or branded types (TypeScript) for every distinct semantic primitive. The compiler refuses to let two semantic units mix. Exhaustive variant matching, always. Discriminated unions and enums are matched exhaustively. Python: match + case unreachable: assert_never(unreachable) . Rust: match (the compiler enforces). TypeScript: switch + assertNever . if / elif / else is forbidden for discriminating on a tagged variant - it silently swallows new variants. Trust framework guarantees. Validate only at boundaries. No null checks for values the type system already proves non-null. No try/except around code that cannot raise. No unwrap / ! / as to paper over a contract you should have encoded in types. No defensive layer for a scenario you cannot name. Test-driven, with the right shape of test. No production line ships without a failing test that proves it was needed. Behavior is locked by tests, not by hope. See the TDD discipline below. TDD DISCIPLINE — NON-NEGOTIABLE Every change follows the red → green → refactor loop. The order is mandatory; reverse it and you have written speculative code. The order Red. Write a failing test that names the behavior in Given / When / Then . Run it. Confirm it fails for the right reason — not a typo, not an import error. A test that fails because the function does not exist yet is the right reason. A test that fails because of a missing import is not. Green. Write the minimum code to make the test pass. Resist adding the second case until the first passes. The second case is the next red. Refactor. With the test green, restructure ruthlessly. The test is your safety net. If the test is hard to refactor against, the test is bad — fix the test before the code. The shape of the test pyramid Every feature ships with all three rungs, sized in this proportion: Rung Count Purpose Speed budget Unit many Pure-function correctness for every meaningful input class (happy + edges + boundaries + error paths) < 10 ms each Integration some The real adapter against the real downstream (DB, queue, HTTP) — via testcontainers , httptest , or equivalent. NEVER a unit test pretending to be integration. < 1 s each E2E scenario few One narrative per user-visible outcome. Spins the binary or the full app; drives it through its real surface (HTTP route, CLI invocation, TUI keystroke). Asserts the observable outcome , not internal state. seconds, run on CI If a feature has zero E2E coverage, it is undone — even if every unit test passes. Given / When / Then is mandatory Every test — unit, integration, E2E — is structured by these three blocks. Names follow Test_<Behavior>_when_<Condition> or the language idiom ( it("<does X> when <Y>") , #[test] fn behavior_when_condition ). Given: the preconditions and fixtures When: the single action under test Then: the observable outcome AND only that outcome One When per test. Multiple When s = multiple tests. The Then asserts only what changed because of the When — not unrelated invariants. Less mock, the better Mocks are a last resort, not a default. The priority order: Real object. Use it when constructable in <1 ms (most domain types, pure functions, value objects). In-memory fake. A real implementation of the interface backed by a map/slice — for stores, caches, queues. The fake has its OWN test that proves it behaves like the real one. Testcontainer / sandbox. Real Postgres, real Redis, real S3-compatible (MinIO), via testcontainers . Slow but truthful. HTTP-level fake. httptest.Server (Go), respx (Python), msw (TS) — fake at the wire, not at the SDK. Mock. Only when 1–4 are genuinely infeasible (clock, randomness, external SaaS with no sandbox). Then mock the narrowest seam — never an entire service. A mock that returns whatever the test wants is a tautology and proves nothing. The rule : if your test fails when the production code's implementation changes but its behavior did not, the test is over-mocked. Delete the mock; assert on observable outputs. Efficient AND accurate — both, not either Accurate : the test fails for the bug it names, and only that bug. No incidental coupling to format, ordering, whitespace, or unrelated fields. Assert on the contract , not on the dump. Efficient : the whole unit suite runs in < 30 seconds on a developer laptop. The whole integration suite in < 5 minutes. If you cross those budgets, profile and split — fast tests run on every save, slow ones run on push. Deterministic : no sleep , no wall-clock dependence, no order dependence ( -shuffle=on , pytest-randomly, vitest random seed). Inject a Clock . Subscribe to the event, do not poll for it. Time-based flake is a bug, not a test issue. Isolated : every test starts from a known fixture and tears down. t.TempDir() , t.Setenv() , transactional rollback for DB tests. Two tests passing individually but failing together is a fixture leak — fix it immediately. Isolation extends across processes : suite-global resources — sandbox/cache roots under a fixed tmpdir path, hardcoded listen ports, container names — are namespaced per run ( mktemp , port 0 /ephemeral, unique names) so that two checkouts or worktrees of the repo running the suite concurrently cannot interfere. A fixed shared path that works on a single-checkout machine is a flake generator on a multi-agent workstation, and its signature is "a different test fails each run". Prompt tests: NEVER assert prose FORBIDDEN — NO EXCEPTIONS: a test MUST NOT assert natural-language prompt text. expect(prompt).toContain("based on GPT-5.6") , not.toContain("old wording") , toMatchSnapshot() on prose, grepping a sentence fragment — every one of these is pretend-coverage. It stays green while the behavior it claims to guard breaks, then blocks every legitimate rewording until someone bumps the pinned string. A reviewer MUST block it as HIGH; deleting such a test is a fix, not a coverage loss. "A nearby test already does it" is not a defense — that test is the disease, not the convention. Assert ONLY what a machine consumes: the builder's routing decision — expect(getPromptSource(model)).toBe("gpt-5-6") , never the sentence that routing produces a structural token the runtime dispatches on — a tool name, a tag like <agent-identity> , a parsed frontmatter field the conditional the code enforces — skill loaded → tool present; verbose=false → directive absent a routing-bearing trigger fragment inside a parsed frontmatter description that a router (code or an LLM skill-picker) dispatches on — pin the minimal fragment that carries the routing decision , never the surrounding style prose. Such pins are what let a later rewrite change every sentence around them while proving the routing contract survived. If no machine consumes the text, there is no seam: write NO test and say so in the PR; review guards prose. When you DELEGATE test-writing, hand the child the behavior the test must distinguish ("fails if override precedence breaks"), never a ready-made assertion string, prompt fragment, or marker to copy — a prescribed mechanism that is wrong gets implemented faithfully, and the error ships with a green suite. Anti-patterns the skill rejects Anti-pattern Why it fails Fix Writing code first, tests "to add later" Tests-after rationalize the existing design, even when wrong. Red first. Always. One mega-test asserting 12 things First failure hides the next 11. Split by Then clause — one assertion class per test. Mocking every collaborator Test passes regardless of real behavior. Use a fake or the real thing. Mock only true unmockables. time.sleep(0.1) to "let it finish" Flake guaranteed. Subscribe to the completion signal; bounded await. Snapshot tests for everything Locks formatting, not behavior. Snapshots for structure (CLI help, JSON shape). Assertions for behavior . Removing a failing test to "unblock CI" You just deleted a bug report. Fix the code or fix the test — never delete to silence. assert result is not None and stopping there Passes when result is garbage. Assert the value , not its existence. Expected value derived from the output under test ( expect(config.prompt).toBe(getPrompt(config.model)) when the criterion is about config.prompt ) Recomputes a projection of the output and compares it to itself — passes even when the artifact is built from the wrong input. Derive the expected value from the test's input : expect(config.prompt).toBe(getPrompt(inputModel)) (independent known-good builder fed the fixture's input), or a stable builder routing decision. Override/precedence fixture equal to its fallback (override == system default) The assertion passes whether or not the code honored the override — precedence is never exercised. Make every value the code must select, preserve, or override differ from its fallback. Prove it: temporarily force the regression the test names, watch it fail, revert. Single happy-path E2E, no edges Most bugs live on edges. Edges are unit-test territory — but include at least one E2E that exercises an error path. Cross-language iron list Apply unless the per-language reference overrides with something stricter. Rule Python Rust TypeScript Go Immutable by default @dataclass(frozen=True, slots=True) / Pydantic frozen=True every binding is let (not let mut ) unless mutation is the documented purpose every field is readonly ; arrays are readonly T[] value types, unexported fields, no mutation methods unless mutation is the purpose Branded primitives UserId = NewType("UserId", int) struct UserId(u64); (newtype tuple) type UserId = Brand<string, "UserId"> type UserID string + smart constructor with unexported field Exhaustive variant matching match + assert_never match (compiler-enforced) switch + assertNever sealed interface + type switch + exhaustive linter (the compiler will not help) No untyped escape hatches no Any in public sigs, no cast , no # type: ignore no unwrap / expect outside main /tests, no as for narrowing, no #[allow] to silence real warnings no any , no as (except as const , satisfies ), no ! , no @ts-ignore , no @ts-expect-error no interface{} / bare any in domain sigs; no _ = err ; no //nolint without reason No bare error strings typed exception dataclass with __str__ thiserror enum (lib) or anyhow with .context(...) (app) Error subclass with typed fields sentinel errors.New + typed *XError struct; wrap with %w ; check via errors.Is/As Boundary catch only catch the exact exception you expect; broad except Exception only in main() , with logging + re-raise ? everywhere; never panic! in library code catch must narrow with instanceof and re-throw or convert; no empty catch every (T, error) checked; panic only in main /tests; one httperr.Write funnel in handlers Resources via RAII with (sync) / async with (async) Drop impl or RAII guard using / await using (TC39 explicit resource management) defer x.Close() immediately after acquisition; bodyclose / sqlclosecheck linters enforce Async runtime is mandatory anyio (NEVER bare asyncio ) tokio ( async-std is unmaintained) platform-native async (Bun/Node) with structured cancellation via AbortSignal context.Context as first param + errgroup for structured concurrency; -race on every test Modern HTTP client httpx2 with HTTP/2 + brotli + zstd reqwest with rustls ky (default) / undici direct API (Node perf) - NEVER bare fetch in prod stdlib net/http.Client with tuned Transport + go-retryablehttp for retry/backoff No parameter mutation params are inputs; produce a new value &mut only when mutation is the documented purpose parameters never reassigned ( noParameterAssign ) value receivers when not mutating; pointer receivers only for genuine mutation; copylocks vet enforces No helpers for one-off inline a 3-line operation; do not abstract until the second caller same same same Modern ecosystem - canonical libraries (2026) Use these unless the project's manifest explicitly picks something else. Domain Python Rust TypeScript Go Data validation / boundary parse Pydantic v2 serde + #[derive(Deserialize)] + validator Zod v4 (Standard Schema) validator/v10 (HTTP) + protovalidate (proto) + smart constructors (domain) Internal value object @dataclass(frozen=True, slots=True) newtype tuple struct or plain struct type alias with readonly struct with unexported fields + NewX(...) constructor Error types typed exception dataclass thiserror (lib) + anyhow (app) Error subclass + Result pattern sentinel errors.New + typed *XError struct + %w wrap HTTP client httpx2 reqwest ky / undici stdlib net/http + go-retryablehttp Web framework FastAPI axum Hono + hono-openapi gin (de facto, ~48%) / chi (minimalist) / connect-go (RPC)