Skip to content

docs: consolidate agent instructions into canonical AGENTS.md #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Jammy2211 merged 1 commit into from
Jun 23, 2026
Merged

docs: consolidate agent instructions into canonical AGENTS.md #37

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 93 additions & 0 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# PyAutoFit Workspace Test — Agent Instructions

This is the integration-test suite for **PyAutoFit**, run on the build server to verify the core
library works end-to-end. It is **not** a user-facing workspace — see `../autofit_workspace` for
examples and tutorials. These are the canonical, agent-agnostic instructions for this repo.

Dependencies: `autofit` (and `autoconf`).

## Repository Structure

```
scripts/ Integration-test scripts run on the build server
searches/ Non-linear search tests (Dynesty, Emcee, Nautilus, LBFGS, …)
features/ Feature tests (assertions, latent variables, minimal output, …)
database/ Database tests (directory, scrape, session)
graphical/ Graphical-model tests (EP, hierarchical, simultaneous)
model_composition/ Model-composition tests
prior_correctness/ Prior-behaviour correctness tests
jax_assertions/ JAX assertion tests
simulators/ Simulator utilities used by the other scripts
failed/ One .txt log per failing script (written by run_all_scripts.sh)
dataset/ config/ output/ Input data, YAML config, runtime fit results
```

## Running Scripts

Run a single script directly from the repo root — with no env applied, the non-linear search runs
for real (sampler limits like `n_like_max` keep it short):

```bash
python scripts/searches/DynestyStatic.py
```

## Testing

On CI, `smoke_tests.yml` gates every PR on Python **3.12 and 3.13**. The gate runs the smoke runner
(the definition of green):

```bash
python .github/scripts/run_smoke.py
```

It executes the curated entries in `smoke_tests.txt`, applying per-entry environment from
`config/build/env_vars.yaml`. That file sets `PYAUTO_TEST_MODE=2` (skip the sampler) as the default,
but **search and feature tests that must validate real inference `unset` it** (or set
`PYAUTO_TEST_MODE=1`, reduced iterations with a real sampler) — those are the cases where bypassing
the sampler would defeat the test. So the test-mode story is per-script, not a blanket "runs for
real." A failure under these flags signals a real problem.

For a local **full sweep** of every script under `scripts/`, use the stateless runner (logs each
failure to `failed/<script_path>.txt`):

```bash
bash run_all_scripts.sh
```

## Sandboxed / restricted runs

If `numba` or `matplotlib` cannot write to the default cache locations, point them at writable dirs:

```bash
NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python scripts/searches/DynestyStatic.py
```

## Bulk-edit safety

When editing the same region across many scripts in one pass, only rewrite the targeted region.
**Never produce a whole-file write unless you have read the entire current file** — a whole-file
write from a header skim silently deletes every section below the header.

## Related Repos

- Source libs: `../PyAutoFit`, `../PyAutoConf`.
- `../autofit_workspace` — the user-facing workspace; `../HowToFit` — the tutorial series.
- `../PyAutoBuild` — CI / build tooling.

## Task Workflows

When a library change lands, run the smoke suite, read any `[FAIL]` entries, and update the affected
test scripts to the new API (preserving intent). **Never edit a script to mask a real regression** —
if a library bug surfaces, flag it for PyAutoFit rather than papering over it. Note in your PR any
change that affects sibling repos (`autofit_workspace`, the source libraries).

## Clean state

Never rewrite history on a repo with a remote (no `git init` over a tracked tree, no force-push to
`main`, no rebasing pushed shared branches). To reset a dirty tree the only correct sequence is:

```bash
git fetch origin
git reset --hard origin/main
git clean -fd
```
89 changes: 5 additions & 84 deletions CLAUDE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,84 +1,5 @@
# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What This Repo Is

**autofit_workspace_test** is the integration test suite for PyAutoFit. It contains Python scripts that are run on the build server to verify that the core PyAutoFit functionality works end-to-end. It is not a user-facing workspace — see `../autofit_workspace` for example scripts and tutorials.

Dependencies: `autofit`. Python version: 3.11.

## Workspace Structure

```
scripts/ Integration test scripts run on the build server
searches/ Non-linear search tests (Dynesty, Emcee, LBFGS, etc.)
features/ Feature tests (assertions, grid search, latent variables, etc.)
database/ Database tests (directory, scrape, session)
graphical/ Graphical model tests (EP, hierarchical, simultaneous)
simulators/ Simulator utilities used by other scripts
failed/ Failure logs written here when a script errors (one .txt per failure)
dataset/ Input data files and example datasets
config/ YAML configuration files
output/ Model-fit results written here at runtime
```

## Running Tests

Scripts are run from the repository root **without** `PYAUTO_TEST_MODE=1` — the non-linear searches run for real (using sampler limits like `n_like_max` to keep runtimes short):

```bash
python scripts/imaging/model_fit.py
```

**Codex / sandboxed runs**: when running from Codex or any restricted environment, set writable cache directories so `numba` and `matplotlib` do not fail on unwritable home or source-tree paths:

```bash
NUMBA_CACHE_DIR=/tmp/numba_cache MPLCONFIGDIR=/tmp/matplotlib python scripts/imaging/model_fit.py
```

This workspace is often imported from `/mnt/c/...` and Codex may not be able to write to module `__pycache__` directories or `/home/jammy/.cache`, which can cause import-time `numba` caching failures without this override.

To run all tests and log failures to `failed/`:

```bash
bash run_all_scripts.sh
```

Each failed script produces a `.txt` file in `failed/` named after the script path (with `/` replaced by `__`), containing the exit code and full output.

Unlike `../autolens_workspace`, there is no resume/skip logic — every run executes all scripts in `scripts/` from scratch.

## Integration Test Runner

`run_all_scripts.sh` at the repo root:
- Finds all `*.py` files under `scripts/` and runs them in order (no test mode flag)
- On failure: writes a log to `failed/<script_path_with_slashes_replaced>.txt`
- Does not skip previously-run scripts (stateless, always runs all)

## Line Endings — Always Unix (LF)

All files **must use Unix line endings (LF, `\n`)**. Never write `\r\n` line endings.
## Never rewrite history

NEVER perform these operations on any repo with a remote:

- `git init` in a directory already tracked by git
- `rm -rf .git && git init`
- Commit with subject "Initial commit", "Fresh start", "Start fresh", "Reset
for AI workflow", or any equivalent message on a branch with a remote
- `git push --force` to `main` (or any branch tracked as `origin/HEAD`)
- `git filter-repo` / `git filter-branch` on shared branches
- `git rebase -i` rewriting commits already pushed to a shared branch

If the working tree needs a clean state, the **only** correct sequence is:

git fetch origin
git reset --hard origin/main
git clean -fd

This applies equally to humans, local Claude Code, cloud Claude agents, Codex,
and any other agent. The "Initial commit — fresh start for AI workflow" pattern
that appeared independently on origin and local for three workspace repos is
exactly what this rule prevents — it costs ~40 commits of redundant local work
every time it happens.
# autofit_workspace_test — agent instructions
The canonical, agent-agnostic instructions live in `AGENTS.md`. Claude Code loads them
via the import below; if your tool does not process `@`-imports, open `AGENTS.md` in
this directory and read it directly.
@AGENTS.md
Loading