Skip to content

Latest commit

 

History

History
565 lines (425 loc) · 26.3 KB

AGENTS.md

File metadata and controls

565 lines (425 loc) · 26.3 KB

AI Coding Standards

Guidelines for AI agents, mostly derived from Effective Programming Practices for Economists. These capture deltas from a capable agent's defaults — ecosystem-specific tool choices and opinionated rules. Generic best practice a strong model already follows is omitted.


Critical Rules

Type Hints

Type hints are mandatory in every function signature.

  • Do NOT use from __future__ import annotations in Python 3.14+ projects — PEP 649 deferred evaluation makes it unnecessary and changes runtime annotation semantics. For projects supporting < 3.14, use it for forward references.

Immutability

Prefer immutable data structures throughout.

  • @dataclass(frozen=True) for all config/state objects, with PEP 257 inline field docstrings (an attr: int line followed by its own """...""" line).
  • tuple / MappingProxyType / frozenset over list / dict / set.
  • Create modified copies via dataclasses.replace() or with_* methods — never mutate.
  • NewType to distinguish same-typed domain values (Period, Age); Enum for categorical values instead of string-literal or boolean flags.

File Paths & Numerics

  • Paths: always pathlib.Path, never strings; join with the / operator; no hardcoded absolute paths outside the project.
  • Float comparison: never ==; use np.isclose / math.isclose with an explicit tolerance.
  • Random numbers: np.random.default_rng(seed=...); never the legacy np.random.seed / np.random.rand / np.random.randn.

Evidence and Claims

A claim ships with its evidence or with its limit — never bare. Drop it, make the observation, or state it with what was measured and what was inferred marked, so a reader can see the edge of the evidence. A bounded claim is a claim; an unmarked one is a guess. This binds on numbers, counts, mechanisms, negative results, and "that can't happen" alike.

The third branch is not a concession. "Eight call expressions; reachability per-mode not traced", "900 binades short, derived from the grid definition rather than from instrumented geometries", "single-route, unconfirmed" — each is decision-relevant, none is fully measured, and withholding any of them would be the wrong call. What is forbidden is stating one of them unqualified.

The instrument lied to you

These fire many times a day and produce no symptom. Each yields evidence that looks exactly like the real thing, which is why care alone prevents none of them.

Measure something complete by construction

A count, a summary line, an exit code, a checksum. Never a truncated view of a listing: head, tail, and grep -m return output indistinguishable from the full thing.

# Every number is complete by construction; the listing is separate and whole.
# `grep -c` counts matching *lines*, so count occurrences instead whenever
# two calls can share one line.
grep -c "parse_record(" records.py           # matching lines
grep -o "parse_record(" records.py | wc -l   # call sites
grep -n "parse_record(" records.py

You cannot know in advance which output becomes a claim, so make every listing complete at the point you run it. Truncation cannot be repaired afterwards: a truncated result and a complete one are indistinguishable, and by the time the number matters the short view is all you have.

Nobody reads a 2000-test run unabridged, and this does not ask you to. It asks that the number you quote come from something that cannot be short — the summary line, not the tail of the log.

Complete is necessary and not sufficient. A predicate can cover the whole file and still answer the wrong question, because it matched something correlated with the defect rather than the defect: grep -o "s'" over a paper's notation is exactly complete and reports 5 where the symbol s-prime occurs 3 times, having counted the possessives in resources' and Households'. Widening it fixes nothing, since breadth was never what was wrong.

So before running a measurement, say what the predicate would also match and what it cannot match, then name the defect and confirm the predicate is aimed at it rather than at a proxy. A predicate is chosen before you know the answer, which is why there is no later moment at which it looks wrong.

A summary line is itself only available to a run that reached one. A run killed part-way — walltime, OOM, a worker dying — writes no summary and no --junitxml report, since the report is written at the end. What it leaves is whatever it had already streamed, which under -q is bare F markers attributable to no test. So -v and --junitxml are not alternatives: the report is the count that cannot be short on a run that finishes, and -v is the only record of one that does not. Ask which of the two failure modes you are exposed to before dropping either.

That generalises into the standing limit of every check here that reads a claim back against an artefact: the check is blind to any failure that destroys the artefact first. Comparing a sentence against a log presumes a log. Nothing recovers a run whose evidence died with it, so the only defence is arranging in advance that a partial run still leaves something attributable.

Prefer installing a rule to remembering it. Every rule in this section has been violated by an agent that had read it, because a note is read at the wrong moment — the rule matters when a command is composed, and that is the one moment nothing re-reads the file. Where a rule can become an artefact that fires at the point of use, make it one: a task default (pixi run tests carries -v --junitxml=…), a PreToolUse hook, or a one-time sweep for state a per-command check cannot see. Give any gate an explicit, easy override that leaves a reason in the transcript; a gate with no override is a gate that gets disabled, which is strictly worse than no gate, because it also removes the record.

Prove the instrument can fire, and that the specimen survived construction

"No NaNs", "no regressions", "no callers" are claims about a detector, not about the world. A probe that reports a negative must be shown capable of producing a positive in the same run — a deliberately failing case, a known-bad input, a seeded defect. Otherwise a disabled check, a skipped validation, or a probe that silently did nothing reports clean.

The same applies to the specimen. Assert — as a line of code in the run, not as a reading of the output — that your inputs survived construction in the format that will actually be used: assert jnp.isfinite(rival).all(), assert x0 > 0 and x1 != x0. An operand that leaves the representable range on the way in — underflowing to zero, overflowing to infinity, collapsing to equal endpoints, silently cast — answers an easier question truthfully, and the run continues.

Two things that are not this check. A library diagnostic is not: depending on one to notice makes luck the last line of defence, and the quiet case is the one that reaches the record. Agreement with an independent report is not either: two parties can construct the same degenerate witness, and a confirming wrong answer is where checking stops.

Check the population, not the verdict

Zero collected is not zero failures. A filter that selects nothing, a glob that matches nothing, and a query that returns nothing all exit successfully.

Piping a run into tail hands you tail's status, so a run that collected nothing and a run that was killed both read as success. Read the runner's own status instead:

# Exit 5 is "nothing collected"; turn it into a real failure and pass
# every other status through unchanged
pytest -m "not slow" tests/
rc=$?
if [ "$rc" -eq 5 ]; then
  echo "NOTHING COLLECTED"
  exit 1
fi
exit "$rc"

rc, not status: zsh reserves status as a read-only synonym for $?, so the assignment fails outright and the guard then reads the failed assignment's own status rather than the command's. It fails toward a false red here, which is the safe direction, but the line does not do what it says in the shell this project uses.

Capture the status before you branch on it, and exit on it explicitly. A trailing [ $? -eq 5 ] && echo ... inverts the very signal it is meant to guard: an AND-list takes the status of the last command it actually ran, so a false test leaves the list failing, and the script or CI step that ends on it reports failure on a healthy run while the nothing-collected case it was written to catch reports success.

The hazard is not the AND-list but one whose truth is data-dependent and happens to land last, because then the source cannot tell you which status you get: for i in 1 2; do [ "$i" = "9" ] && continue; done exits 1 as a final statement, and the identical loop over 1 9 exits 0. set -e does not catch either.

The | tail pipe defeats both rules in this group at once: the status you read belongs to tail, and the output you read is truncated. It is the only place two of these fail on a single keystroke.

A marker or filter that selects nothing is the common cause: on the command line -m replaces the configured expression rather than intersecting with it, so a directory marked wholesale can deselect its entire contents and still exit successfully.

Gate on the command's own status

When a command's success decides whether you commit, push, or continue, branch on that command's status, never on a pipeline's. A gate built from a filter does not merely leak — it inverts. Filter hook output for lines other than "Passed" and commit when the filter finds one: failing hooks leave such a line, so the filter succeeds and the commit lands; a clean run leaves none, so the filter fails and blocks it. Exactly backwards, in both directions. Gate on the runner's own status:

prek run --all-files > hooks.log
rc=$?
[ "$rc" -eq 0 ] || exit "$rc"
git commit …

A wrong number eventually meets a second reader — someone re-derives it, or it contradicts another number. A wrongly green gate meets no one, because passing it is what licensed nobody looking.

Pin a comparison to an immutable id, and assert the relationship

State what a measurement was taken against by commit hash, not by branch or tag name, and check that the baseline really stands in the relation you assume — an ancestor is an ancestor only if git merge-base --is-ancestor says so. A ref name is not a pin, and "latest upstream" is not a baseline: comparing against a tip that has diverged reports the other side's progress as your own deletions.

The same applies to the environment: assert inside the run which installation you actually imported (print(module.__file__)), because a sibling checkout's editable install resolves silently and a console script's shebang can point outside the environment you believe you are in.

The claim outran its support

These fire on conclusions rather than on commands. They are what turns a defensible result into an overstated one.

Treat an inherited claim as carrying a timestamp

A figure or mechanism you got from another agent, an earlier round, or your own summary is a citation. Attribution is not freshness: a correctly attributed superseded claim is still a wrong claim, and re-attributing it launders it into the record as jointly held.

Name the round, message, or commit the figure came from, and confirm that source is still its latest form. If you cannot, mark it inherited-unverified and let the reader weigh it.

The same applies to stored artefacts. A frozen baseline, table, or calibration constant needs the commit and the numerical precision it was produced under recorded with it, or it cannot be compared to anything generated later.

Say what a sweep holds fixed

Varying one input usually moves several quantities at once. Before naming a cause, write down what the varied input does not change; if you cannot, the sweep cannot separate them and is evidence for none of them.

Two results agreeing corroborate only if they differ in what they hold fixed — otherwise it is one measurement reported twice, and calling it "two independent routes" is worse than reporting one, because it manufactures confidence that was never there. Two recollections of the same run are not two runs: if neither party can produce the invocation, the agreement is a shared memory, not evidence.

If the result is invariant by construction, say so and label the sweep as a check on the edges — subnormals, overflow, empty inputs — rather than offering it as the argument.

Name the second route, or declare the claim single-route

Re-checking your own number re-runs the same route and therefore separates nothing, by construction; no amount of attention fixes that. Before calling a result confirmed, name the second route — a derivation of what you measured, a measurement of what you derived, a different instrument, or a different agent. If you cannot name one, say the claim is single-route.

When you revise a claim, purge the old framing from the whole document

A retraction that lands in one section leaves every other section asserting the retracted thing, because each editing pass only looks at the part it is editing. Before shipping a revised document, grep it for the old framing and name the search string you used, then resolve every cross-reference written as a placeholder — "see below", "TBD", a table cell pointing at a section that was never written.

When you contradict someone who read the same code, produce the distinguishing observation

Being able to construct a counter-story is not evidence. Identify the observation on which the two accounts differ, make it, and report it — or concede.


Python Environment

Python Version

Minimum Python version is 3.14 unless a project specifies otherwise. Use 3.14+ features freely, including:

  • except ValueError, TypeError: without parentheses (PEP 758) — this is not Python 2 syntax. It is valid when there is no as clause.

Pixi Package Manager

Pixi is the required package and environment manager.

  • Run everything through it: pixi run python, pixi run pytest, pixi run pytask.
  • Add deps with pixi add (conda-forge) or pixi add --pypi (PyPI-only); commit pixi.lock for reproducibility.
  • Never use pip, conda, or uv directly, never run bare python script.py, never use the defaults conda channel.

Always re-lock before committing — and especially before pushing

Whenever pyproject.toml changes in any way — a dependency added, removed, or version-bumped, a git/URL pin updated, an environment or feature edited — run pixi lock and commit the regenerated pixi.lock in the same commit.

A stale pixi.lock passes locally but breaks CI, and the failure surfaces only after you push:

  • pixi install --frozen / pixi list --frozen (the locked CI jobs) fail outright.
  • pixi install silently regenerates the lock and dirties the worktree, which blocks any task that refuses to run on a dirty tree (e.g. benchmarks).

So treat pixi lock as mandatory before git commit, and double-check it before git push — pushing a stale lock burns a full CI cycle to discover a one-line fix.

Migrate feature system-requirements (cuda) via named platform variants

pixi deprecates feature-level system-requirements = { cuda = "12" } and its warning tells you to put the constraint on the platform as a feature-level inline table, platforms = [{ platform = "linux-64", cuda = "12" }]. That feature-level form does not parse — pixi lock fails with × expected a string, found table (and pixi info will not catch it: it only echoes the host's own virtual packages, so the edit looks fine until you lock). The migration guide's example is a workspace-level one; the per-feature translation the warning implies is what's unsupported. Still true as of pixi 0.84.2 — re-test before assuming it has been fixed.

Do migrate rather than live with the warning: pixi 0.81 converts the deprecated table into an auto-named platform variant on its own (linux-64-cuda-13, in older locks p1), and in a workspace with path-installed PyPI packages that conversion crashed the PyPI solve (build dispatch initialization failed), so the lock could not be regenerated at all.

The form that does work: declare named platform variants at the workspace level and point each cuda feature at its variant by bare string.

[tool.pixi.workspace]
platforms = [
  "linux-64",
  { name = "linux-64-cuda12", platform = "linux-64", cuda = "12" },
  { name = "linux-64-cuda13", platform = "linux-64", cuda = "13" },
]

[tool.pixi.feature.cuda12]
platforms = [ "linux-64-cuda12" ]              # bare string ref — parses
# target selectors still key on the BASE platform, not the variant name:
[tool.pixi.feature.cuda12.target.linux-64.pypi-dependencies]
jax = { version = ">=0.9", extras = [ "cuda12" ] }

Verified properties (pixi 0.81): locks with no warnings; target.linux-64 applies to the linux-64-cuda12 variant; and because a variant shares the base conda subdir, CPU/tests envs resolve to the same linux-64 packages on it (only the cuda features add the GPU wheels). The lock file still grows: every environment whose features do not restrict platforms lists the variant with its own full package list — measured at roughly 2.8k and 5.7k added lines in two projects. Always confirm with pixi lock, never pixi info.

Pin Python in every environment that now covers the variant, including the implicit default environment when Python only comes from py3XX features. Unpinned, default solved to Python 3.12 on the variant and 3.14 on linux-64, and pixi lock --check then failed immediately after every re-lock ("solved with system requirements incompatible with the tags on wheel (orjson)"). Declaring default = [ "py314" ] under [tool.pixi.environments] fixes it.

A separate, real warning — "target selector osx-arm64 does not match any of the platforms supported by the workspace" — means a feature references a platform not in [tool.pixi.workspace].platforms. That one is genuine: either add the platform to the workspace or drop the orphaned feature.

Package Structure

Use src layout — package code under src/<package>/, tests in a top-level tests/.


Code Quality

Naming Conventions

Standard PEP 8 casing is assumed. Beyond it:

  • Function names start with verb: create_, calculate_, convert_, get_
  • Private functions: _underscore prefix
  • Use func, not fn, when abbreviating "function" (e.g., apply_func)
  • Avoid: abbreviations, single letters (n, c, s, u conflict with debugger), built-in names (list, dict, type)
  • Avoid vague action nouns like "sweep", "pass", "handler" in identifiers, comments, and docstrings unless paired with a concrete qualifier (e.g., "annotation-stripping pass"). Prefer the verb form (resolve_*) or a specific noun (resolver, validator) that says what the thing actually does.

Module Layout

Write "deep" modules: important public function(s) at the top, private helpers below. Readers should see the API first without scrolling past implementation details. Code structure should be self-evident from function names and ordering, so never add decorative section-separator comments — the no-section-separator-comments pre-commit hook rejects them.

Docstrings

Use Google convention (pydocstyle.convention = "google"). Use MyST syntax (not reStructuredText) for markup inside docstrings: `code`, $math$, markdown links.

  • Imperative mood in summary lines ("Calculate utility", not "Calculates utility")
  • Use inline field docstrings (PEP 257) for dataclass attributes (see Frozen Dataclasses example above)

Docstring Style

Docstrings and inline comments describe the code's current state in user-facing terms. The 9-month-without-PR-context reader is the audience: a docstring that survives that test stays useful; one that rehearses the diff or the prior implementation rots immediately.

This applies to all docstrings and comments — source and tests. For tests specifically, see also the "Test docstrings — describe behavior, not history" subsection in the Testing section.

Describe state, not history

State what is true now. Don't reference prior designs, removed code, or what was changed. Words like "earlier", "previously", "now", "formerly", "the old", "before the fix" are red flags.

class _CacheEntry:
    """One cached download.

    Holds the file's path and checksum, never its bytes, so the cache
    index stays small however large the files are.
    """

No internal references, no model-specific magic numbers

A comment may not name anything a reader cannot reach from the checkout. The reader has no access to the conversation, review, or tracker. Banned in comments, docstrings, and test names:

  • PR and issue numbers — #123 fixed the timeout.
  • Audit and review finding labels — (E4, F7 guard), the F1 bug. F7 resolves only to a conversation that is over.
  • Review round numbers — round-3 audit F2.
  • Diff-relative vocabulary — pre-fix, the fix, no longer reads.
  • Internal design-document filenames — not in the repository, not a reference.

Delete the label and see whether the sentence still teaches anything. If not, rewrite it to say why the invariant holds.

Magic numbers tied to a specific model size or hardware (~2 MB at full size, fits on a 16 GB device) imply a fixed scale that's only true on whichever model/box the comment was written against. State the qualitative dependency instead.

# Frees each batch's buffers once the batch is written, so memory
# stays at one batch however many batches run.

The no-internal-references hook catches the labelled forms; unlabelled history stays a review responsibility.

Bulleted lists for enumerated cases

When describing a fixed set of cases (log levels, file formats, parameter types, dispatch strategies), use one bullet per case rather than running prose. Bullets scan; prose hides cases.

# Output falls out of the verbosity setting:
# - `"quiet"` ⇒ errors only
# - `"normal"` ⇒ adds warnings
# - `"verbose"` ⇒ adds per-step timings

Error Handling

Raise early, with the offending value named in the message. Factor validation into _fail_if_... helpers.

Testing

Test-Driven Development — always

Always write the test first, watch it fail, then implement. No exceptions for new behavior or bug fixes. Tests are not an afterthought, they are the spec.

The cycle:

  1. Red. Write a failing test that asserts the desired behavior in user-facing terms. Run it. Confirm it fails for the right reason (the missing behavior — not a typo, not an import error).
  2. Green. Write the smallest amount of code that makes the test pass.
  3. Refactor. Clean up while keeping the test green.

Apply per case:

  • New feature → red-green-refactor.
  • Bug fix → reproduce as a failing test before writing the fix. The test then prevents regression.
  • Refactor (no behavior change) → existing tests are the spec. Keep them green before, during, and after. No new test needed if behavior is unchanged; if you find a behavior gap, fill it with a new test before refactoring.

Test docstrings — describe behavior, not history

Test docstrings state what should be true, in user-facing terms. Pretend the reader has never seen the PR. They should not need to.

def test_parse_date_accepts_iso_week_format():
    """`parse_date("2024-W05-2")` returns 30 January 2024."""

Rule of thumb: would the docstring still make sense in 9 months without the PR context? If not, rewrite it.

Concrete-value assertions

Assert what the result is, not just that it didn't crash.

np.testing.assert_allclose(result["balance"], expected_balance, atol=1e-6)

An assertion that only checks for no NaN or no exception passes whether the math is right or not; it belongs in a CI smoke test, not in the unit tests for the feature.

Mechanics

Name tests test_<function>_<behavior> in test_<module>.py, and keep one assertion per test — parametrize rather than stacking assertions in one body.

Type Checking

Use ty (not mypy, not pyright). ty runs as a pre-commit hook (astral-sh/ty-pre-commit) — part of prek run --all-files — resolving third-party imports from the pixi environment named in [tool.ty] environment.python. Run pixi install once so that environment exists.

For pixi-managed projects, override the hook with entry: ty check and install ty==<version> through additional_dependencies, matching the hook's rev exactly. Update both pins together. The direct entry leaves environment selection to ty's configuration; the uv check wrapper can select its own environment even with --no-project. Keep the upstream whole-project checking behavior.

  • Suppress with # ty: ignore[rule-name] (never # type: ignore); always name the rule.

Verification After Changes

Run these checks after making code changes. Skip any that don't apply to the project.

  1. Lockfile: If pyproject.toml changed, run pixi lock and stage the updated pixi.lock. Never commit or push a pyproject.toml change without re-locking — a stale lock breaks CI (see "Always re-lock before committing").
  2. Pre-commit (incl. type checking): Stage new files, then prek run --all-files (or pixi run prek run --all-files). This runs ruff, formatting, and the ty hook. Fix any failures.
  3. Tests: pixi run tests (or the project's test task).
  4. Notebook diffs: If .ipynb files changed
    1. verify the diff looks like clean cell-content changes, not JSON noise (cell metadata, execution counts, output blobs). If the diff is bloated, the notebook was not properly stripped — run nbstripout before committing
    2. Make sure notebook cells are properly formatted (each line in a cell is a new json line, not one cell=one line).
    3. Use actual UTF-8 characters everywhere — in markdown cells, Python strings, and f-strings. Never write unicode escape sequences; write the actual characters (—, μ) directly.