Init AGENTS.md

[cmdupuis3]

Closes #1668

Overview

This PR adds an AGENTS.md markdown file to help orient LLMs. A CLAUDE.md pointer markdown is also included, pointers for other LLMs are welcome as well.

PR Checklist

General

• An issue is created and linked
• Added appropriate labels (if your uxarray repo permissions allow it)
• Filled out Overview and Expected Usage (if applicable) sections

Testing & Benchmarking

• Adequate tests are created if there is new functionality
• Tests are not too basic (such as simply calling a function and nothing else)
• Tests cover all major paths in your new functions
• If this PR could affect performance, ran ASV benchmarks and confirmed they show expected behavior (add a new benchmark if necessary)

AI Disclosure

AI Usage: Claude Opus 5/Sonnet 5

• I take responsibility for all AI-generated content in my PR.
• I have tested all AI-generated content in my PR.

[cmdupuis3]

pre-commit.ci autofix

[rljacob]

Did you use ask claude or other to write this or is it by hand?

[cmdupuis3]

Mostly I used Claude to generate it, I edited some parts by hand on parts of uxarray I'm more familiar with. I'm hoping others can help review it so I'm not missing any blind corners.

[Sevans711]

Upon quick skimming, I noticed a few things:

1. The number of tests is wrong (it's 800+ not 546)
2. The file refers to Claude.md despite the file name being AGENTS.md
3. This file is a snapshot, not an oracle. Where it contradicts the repository, the repository wins, but establish that by dates, not by instinct. I am confused why the request is to establish that by dates. There are some things in this file which are probably currently incorrect, and I would want an LLM to always use the repository as ground truth rather than this file, I think?
4. JIT functions must be **module-level** and take/return plain arrays and scalars. `self`, `xr.DataArray`, and dicts cannot cross the boundary Is this really necessary? I would think that LLMs should be smart enough to "know" this generic statement about numba, without instructing them.
5. on failure raise a **typed error from `errors.py`** I don't think this is correct, you shouldn't always raise a custom error type. Lines above this clarified that already, this contradicts those lines.
6. I don't really know how to properly review something like this, especially since LLMs are not deterministic. Is there any way to test whether it is actually causing LLMs to produce improved results? Even if it's something you've run by-hand and not included anywhere in the automatic test suite, I think before this PR gets approved I would really like to see at least one example of "I gave an LLM the same prompt, without AGENTS.md, and with AGENTS.md, and it did a better job responding in the latter case." (To make sure order doesn't matter, also try doing in the reverse order. Maybe there is a need to disable "remember things across chats" somehow too.) This would at least provide some direct evidence that the file is plausibly providing an improvement for LLM usage. Alternatively, maybe there is some other way to show that evidence, such as existing tools which might review AGENTS.md files?

(Clarifying the following because you already requested review, which feels more official than just asking for help looking through the content) I'd be happy to properly give this a full review once you have indicated that you take responsibility for the AI generated content. I think the intention of those boxes is that an actual review (which is different from just providing suggestions or working together in thread) should not occur until you are ready to take responsibility for the content, in order to save reviewers' time.