From e8b1d67b2bba918c50697f9cacf1d7e5a7c0558c Mon Sep 17 00:00:00 2001 From: arxh80 Date: Wed, 21 Oct 2026 09:09:37 +0100 Subject: [PATCH 1/3] Add root-level AGENTS.md for AI coding assistants Scoped to #9199's root file: PRs target dev, DCO sign-off required, ./runtests.sh --autofix is the formatter, optional deps go through monai.utils.optional_import, new public API needs a docs/source/*.rst entry, slow tests go in tests/min_tests.py. Cross-references the AI/tool-assisted contribution policy from #9106 rather than duplicating it. Nested, package-level AGENTS.md files are left for a follow-up PR per the discussion on the issue. Co-Authored-By: Claude Sonnet 5 Signed-off-by: arxh80 --- AGENTS.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000000..4b798b4b3d --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,42 @@ +# AGENTS.md + +Guidance for AI coding assistants (Claude Code, Codex, Copilot agent mode, Cursor, Gemini CLI, Jules, Aider, ...) +working in this repository. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full human contributor guide and +[the AI/tool-assisted contribution policy](CONTRIBUTING.md) for what is and isn't acceptable when using these +tools — this file is about *how the codebase works*, not *whether AI assistance is allowed*. + +## Project overview + +MONAI is a PyTorch-based, open-source framework for deep learning in healthcare imaging. See +[setup.cfg](setup.cfg) / [pyproject.toml](pyproject.toml) for the supported Python and PyTorch versions. + +## Repository map + +| Path | Purpose | +|------|---------| +| `monai/` | the library itself: transforms, networks, losses, metrics, data, bundle, apps, engines, etc. | +| `tests/` | unit and integration tests, mirroring `monai/`'s layout | +| `docs/` | Sphinx documentation sources (`docs/source/*.rst`, `*.md`) | +| `runtests.sh` | the test and style-check entry point used in CI and locally | + +## Required workflow + +- Pull requests target the `dev` branch, not `main`. +- Every commit needs a DCO sign-off (`git commit -s`, i.e. a `Signed-off-by:` trailer). The DCO app fails PRs + with commits missing it; see [Signing your work](CONTRIBUTING.md#signing-your-work). +- Format and lint with `./runtests.sh --autofix` (runs `isort` and `black`) before committing. If pre-commit + hooks are installed (`./runtests.sh --setup`), the same checks also run on every `git commit`. + +## Code conventions + +- Optional third-party dependencies are imported lazily via `monai.utils.optional_import`, not a bare + `import`, so the package stays usable without every extra installed. +- A new public API needs a corresponding entry in `docs/source/*.rst` (or the matching `.md` file for guides), + not just a docstring. +- A slow test belongs in `tests/min_tests.py`'s exclusion list, not in the default fast suite. + +## What stays out of this file + +Package-specific traps (e.g. for `monai/transforms`, `monai/networks`, `monai/bundle`) are intentionally not +covered here — this root file only carries rules that apply repo-wide. Nested, package-level `AGENTS.md` files +can follow in later PRs if the maintainers want that detail; see the discussion on #9199. From 4ddae4a3d13681c9e527a3be7181086163487880 Mon Sep 17 00:00:00 2001 From: arxh80 Date: Wed, 21 Oct 2026 15:05:28 +0100 Subject: [PATCH 2/3] docs: fix review feedback on AGENTS.md - Fix broken CONTRIBUTING.md link/anchor for the tool-assisted contribution policy. - setup.cfg doesn't exist on dev; point to pyproject.toml and setup.py instead. - Correct the slow-test guidance: skip_if_quick marks a slow test, exclude_cases in tests/min_tests.py is for optional-dependency modules, not slow tests. Per review from garciadias on #9212. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_01STJRQtEaEPSLfiWGMn8Syr Signed-off-by: arxh80 --- AGENTS.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 4b798b4b3d..de43512858 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,13 +2,14 @@ Guidance for AI coding assistants (Claude Code, Codex, Copilot agent mode, Cursor, Gemini CLI, Jules, Aider, ...) working in this repository. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full human contributor guide and -[the AI/tool-assisted contribution policy](CONTRIBUTING.md) for what is and isn't acceptable when using these -tools — this file is about *how the codebase works*, not *whether AI assistance is allowed*. +[the tool-assisted contribution policy](CONTRIBUTING.md#tool-assisted-contribution-policy) for what is and isn't +acceptable when using these tools — this file is about *how the codebase works*, not *whether AI assistance is +allowed*. ## Project overview MONAI is a PyTorch-based, open-source framework for deep learning in healthcare imaging. See -[setup.cfg](setup.cfg) / [pyproject.toml](pyproject.toml) for the supported Python and PyTorch versions. +[pyproject.toml](pyproject.toml) and [setup.py](setup.py) for the supported Python and PyTorch versions. ## Repository map @@ -33,7 +34,8 @@ MONAI is a PyTorch-based, open-source framework for deep learning in healthcare `import`, so the package stays usable without every extra installed. - A new public API needs a corresponding entry in `docs/source/*.rst` (or the matching `.md` file for guides), not just a docstring. -- A slow test belongs in `tests/min_tests.py`'s exclusion list, not in the default fast suite. +- A slow test is decorated with `skip_if_quick` (`tests/test_utils.py`); a test module that needs an optional + dependency is added to `exclude_cases` in `tests/min_tests.py`. ## What stays out of this file From 9874094de0b61ebcb1a969bf64144fdf34763a3a Mon Sep 17 00:00:00 2001 From: arxh80 Date: Thu, 22 Oct 2026 14:26:21 +0100 Subject: [PATCH 3/3] docs: note that runtests.sh --autofix also runs ruff --autofix sets doRuffFix and doRuffFormat as well as the isort and black fixes, so it runs `ruff check --fix --unsafe-fixes` too (runtests.sh lines 291-297 and 626). The parenthetical only named isort and black. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01STJRQtEaEPSLfiWGMn8Syr Signed-off-by: arxh80 --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index de43512858..301d689e12 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -25,8 +25,9 @@ MONAI is a PyTorch-based, open-source framework for deep learning in healthcare - Pull requests target the `dev` branch, not `main`. - Every commit needs a DCO sign-off (`git commit -s`, i.e. a `Signed-off-by:` trailer). The DCO app fails PRs with commits missing it; see [Signing your work](CONTRIBUTING.md#signing-your-work). -- Format and lint with `./runtests.sh --autofix` (runs `isort` and `black`) before committing. If pre-commit - hooks are installed (`./runtests.sh --setup`), the same checks also run on every `git commit`. +- Format and lint with `./runtests.sh --autofix` (runs `isort`, `black` and `ruff check --fix`) before + committing. If pre-commit hooks are installed (`./runtests.sh --setup`), the same checks also run on every + `git commit`. ## Code conventions