Introduce AGENTS.md files to guide AI coding assistants #9199

Is your feature request related to a problem? Please describe.

More and more contributors work on MONAI with an AI coding assistant at their side (Claude Code, Codex, Copilot agent mode, Cursor, Gemini CLI, Jules, Aider, ...). Today these tools arrive in the repository with no project context: they do not know that PRs target dev, that every commit needs a DCO sign-off, that ./runtests.sh --autofix is the formatter, that optional dependencies go through monai.utils.optional_import, that a new public API must be added to docs/source/*.rst, that a slow test is marked with skip_if_quick, or that a test module needing an optional dependency is listed in exclude_cases of tests/min_tests.py. They rediscover (or miss) these rules on every session, which shows up in review as avoidable churn.

AGENTS.md has become the de facto, tool-agnostic convention for this: a plain Markdown "README for agents" that most coding assistants read automatically, with the file closest to the edited code taking precedence. It complements the AI contribution policy merged in #9106 (from #8914): the policy says what is acceptable, AGENTS.md tells the tool how this codebase works, so that what a human ends up reviewing and signing off is closer to mergeable from the start.

Describe the solution you'd like

A small, layered set of AGENTS.md files: one root file that routes, plus a short leaf file in each subpackage that carries real, package-specific traps. Detail lives next to the code it describes.

1. Layout

AGENTS.md                      # root: overview, map, commands, repo-wide rules, routing table
monai/transforms/AGENTS.md
monai/networks/AGENTS.md
monai/data/AGENTS.md
monai/losses/AGENTS.md         # losses and metrics could share one file if preferred
monai/metrics/AGENTS.md
monai/bundle/AGENTS.md
monai/apps/AGENTS.md
monai/auto3dseg/AGENTS.md
monai/engines/AGENTS.md        # engines + handlers
monai/csrc/AGENTS.md           # C++/CUDA extensions
tests/AGENTS.md
docs/AGENTS.md

Not every folder needs one. A leaf file earns its place only if it says something an agent would otherwise learn the hard way; a file that is just a directory listing should be dropped. Do not add files to build output, caches or tests/testing_data.

2. Root AGENTS.md: suggested sections

Keep it short (ideally under ~200 lines). Suggested skeleton:

# AGENTS.md

## Project overview
One paragraph: what MONAI is, who uses it, supported Python/PyTorch range (link to setup.cfg/pyproject, do not copy versions).

## Repository map
| Path | Purpose |
|------|---------|
| monai/transforms | array/dict transforms, lazy resampling, invertibility |
| monai/networks   | nets, blocks, layers |
| ... one line per top-level folder ... |

## Where the detail lives
| File | Covers |
|------|--------|
| monai/transforms/AGENTS.md | ... |
| tests/AGENTS.md | test layout, min_tests, skip decorators |
| ... |

## Setup and commands
./runtests.sh --setup                 # dev deps + pre-commit hooks
./runtests.sh --autofix               # format (ruff/isort/black as configured)
./runtests.sh --codeformat            # check only
./runtests.sh --quick --unittests     # fast local verification
python -m pytest tests/<area>/test_x.py -k <name>   # single test
(every command listed here must be one you have actually run)

## Repo-wide conventions
- PRs target `dev`; every commit signed off (`git commit -s`), by the human author.
- Line length 120, Google-style docstrings, type hints, Apache 2.0 header on new files.
- Optional deps only via `monai.utils.optional_import`; never a hard import at module top.
- New public API: export it in the package `__init__.py` and add it to `docs/source/<area>.rst`.
- Deprecations go through `monai.utils.deprecated` / `deprecated_arg` with since/removed versions.
- Tests mirror the source tree under `tests/`.

## AI-assisted contributions
Link to the policy section of CONTRIBUTING.md (#9106). Do not restate it here.

## Do not
- edit generated files (`monai/_version.py`, versioneer output)
- commit data, weights or large binaries
- touch CI workflows unless that is the task

3. Leaf files: what goes in them

Each leaf file contains only its own tree: a short module to purpose table, commands run from/for that area, conventions, and traps first. Examples of the kind of content that is worth writing (contributors should verify each one against the code before writing it down):

• monai/transforms: array vs dictionary (*d) vs Rand* variants and how they relate; MetaTensor must be preserved through a transform; lazy resampling and InvertibleTransform contracts; randomness must go through self.R / set_random_state, not the global RNG; a new transform needs its dict and random variants plus an entry in docs/source/transforms.rst (and transforms_idx.rst if applicable).
• monai/networks: support for both 2D and 3D via spatial_dims; TorchScript/ONNX export expectations; where shared blocks/layers live so nets do not reimplement them.
• monai/data: dataset caching classes and their persistence/hashing behaviour; image readers depend on optional backends (ITK, nibabel, pydicom...).
• monai/losses / monai/metrics: shape conventions (B, C, spatial...), one-hot / include_background / reduction semantics, ignore_index behaviour.
• monai/bundle: config syntax (@, %, $, #), link to docs/source/config_syntax.md and the bundle spec rather than repeating them.
• monai/csrc: how extensions are built (BUILD_MONAI), and that a pure-Python fallback is expected.
• tests: file naming, tests/min_tests.py exclude_cases for modules needing optional deps (not for slow tests, which use skip_if_quick), the skip_if_* / SkipIfNoModule decorators in tests/test_utils.py, --net tests that download data, how to run one file.
• docs: building the docs locally, that every new public symbol needs an rst entry.

4. Cross-tool compatibility

AGENTS.md is the single source of truth. For tools that still look for their own filename, prefer pointers over copies so nothing drifts:

• Claude Code: add a one-line CLAUDE.md containing @AGENTS.md at the root (only if maintainers want it; discuss below).
• GitHub Copilot: optionally .github/copilot-instructions.md pointing to AGENTS.md.
• Gemini CLI / others: can be configured to read AGENTS.md; no extra file needed.

Personal, machine-specific instructions (local paths, preferred models, etc.) belong in the user's own config (~/.claude/, CLAUDE.local.md gitignored, etc.), never in the repository.

5. Writing guidelines (please read before opening the PR)

1. Write what the code cannot say for itself. Surprising defaults, load-bearing ordering, deprecated paths and what replaces them, optional dependencies that only fail at runtime. Skip generic advice ("write clean code") and anything a config file already declares.
2. Every command must be one you ran. No aspirational targets. Copy from runtests.sh -h, CI workflows and CONTRIBUTING.md.
3. Verify every fact against the code, and enumerate names/counts programmatically rather than from memory. A confidently wrong table is worse than no table.
4. Link, do not duplicate. CONTRIBUTING.md stays the canonical human guide; AGENTS.md links to its sections. Do not copy version pins or dependency lists.
5. Keep it short and imperative. These files are loaded into a model's context on every session; every line costs tokens for every contributor.
6. No secrets, tokens, internal URLs or personal paths.
7. Add a line to CONTRIBUTING.md telling contributors that AGENTS.md exists and must be updated when a convention it describes changes (treat it like docs).

6. Suggested sequencing (each step can be its own PR)

1. Root AGENTS.md + the CONTRIBUTING.md pointer. Small and easy to review; good first PR.
2. tests/AGENTS.md and monai/transforms/AGENTS.md (highest-traffic areas).
3. Remaining leaf files, one or a few per PR, so domain owners can review their area.
4. (Optional) tool pointer files from section 4 once maintainers agree.

Contributors picking this up: please comment here with which step / package you are taking to avoid duplicate work.

Acceptance criteria

• Root AGENTS.md exists, follows the skeleton above, and every command in it runs on a fresh dev checkout.
• Root file's routing table links to every leaf AGENTS.md, and every link resolves.
• Each leaf file has at least one trap genuinely specific to its package (not just a listing).
• No content duplicated from CONTRIBUTING.md or the AI contribution policy; links instead.
• CONTRIBUTING.md mentions AGENTS.md and the expectation to keep it current.
• Sanity check: open an assistant of your choice on the branch, ask it to "add a new dictionary transform with tests and docs" (or similar for your package), and confirm it follows the documented conventions (dev target, sign-off, optional_import, rst entry, skip_if_quick / min_tests). Mention the result in the PR description.

Describe alternatives you've considered

• Tool-specific files only (CLAUDE.md, .cursorrules, .github/copilot-instructions.md): fragments the guidance per vendor and drifts. AGENTS.md is supported by most tools and is vendor-neutral.
• A single large root file: easier to start, but it grows into a wall of text loaded on every session, and package experts have no natural place to own their section.
• Relying on CONTRIBUTING.md alone: written for humans, long, and not automatically loaded by agents.

Additional context

• Spec and tool support list: https://agents.md/
• Related: AI Contribution Policy For MONAI #8914 (AI contribution policy) and Add Tool-Assisted Contribution Policy #9106 (policy added to CONTRIBUTING.md).

Open questions for maintainers:

• Should a CLAUDE.md / .github/copilot-instructions.md pointer be committed, or should AGENTS.md be the only file?
• Should losses and metrics (and engines and handlers) share leaf files?
• Should a lightweight CI check verify that the links in the routing table resolve?

This is a good first issue: it requires reading the codebase and CONTRIBUTING.md carefully but no changes to library code.