Add AGENTS.md

[Scienfitz]

AGENTS.md files contain content intended for agentic operators. They are recognized by most coding frameworks (most importantly claude and opencode) and are injected into the context whenever an agent reads a folder where such a file is contained. They lead to more consistent code being generated and generally more in line with what has already been done without explicitly having to state this over and over again.

The content here is meant as a start and not as complete. We can continue to add rules as we evolve.

The content has been produced in the following manner:

• Analyze the entire code base and the last 200 PRs including comments
• Extract from this rules and conventions that apply to this repo
• The resulting files have then been compressed
• I then did one coarse round of human review and curation

[Copilot]

Pull request overview

Adds AGENTS.md guidance files intended to be injected into agentic tooling context to steer code, tests, docs, and examples toward existing BayBE conventions.

Changes:

• Introduce root-level AI-agent coding guide (AGENTS.md) covering architecture, typing, imports, CI, and workflow.
• Add test-suite conventions for pytest structure/fixtures/parametrization (tests/AGENTS.md).
• Add docs and examples conventions for Sphinx/MyST and runnable scripts (docs/AGENTS.md, examples/AGENTS.md).

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 10 comments.

File	Description
AGENTS.md	Project-wide agent guidance for BayBE coding patterns, tooling, and PR workflow
tests/AGENTS.md	Conventions for writing/organizing pytest tests and fixtures
docs/AGENTS.md	Conventions for Sphinx/MyST docs authoring and syntax
examples/AGENTS.md	Conventions for executable examples and CI smoke-test behavior

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[LeanAndMean]

Hey, nice work on the recent updates -- the fail-fast language in sections 2/8/16 reads well, and the admonition rewrite is much clearer.

I've been reviewing this alongside how I structure similar files in my repos and wanted to share a few thoughts. Happy to help implement any of these if useful, but also easy for you to pick up directly since they're mostly structural.

CLAUDE.md + symlinks: Have you considered making the canonical file CLAUDE.md? Claude Code automatically loads it into every conversation, and it supports subdirectory scoping -- a tests/CLAUDE.md is auto-injected when the agent works on files in tests/. That's a perfect match for the distributed structure you've set up here.

To keep other tools working, symlink from the root:

AGENTS.md -> CLAUDE.md
.github/copilot-instructions.md -> CLAUDE.md

Single source of truth, three consumers. The subdirectory files (tests/CLAUDE.md, etc.) don't need symlinks since the other tools don't have equivalent scoping.

Complementary content from /init: I ran Claude Code's /init command on this repo and it generated a CLAUDE.md that has some nice qualities that could complement what you've already built here:

• A full commands section covering install, test (pytest --fast, pytest -k "test_name"), lint, typecheck, and all tox environments -- including the python version append convention (tox -e mypy-py310) and tox -p for parallel runs. Your AGENTS.md covers conventions thoroughly but doesn't tell the agent how to validate its work; this fills that gap.
• The architecture section maps each domain concept to its file path (Campaign -> baybe/campaign.py, SearchSpace -> baybe/searchspace/, etc.), which gives an agent both "what is this" and "where to find it" in one pass.
• It distills design principles to the three an agent is most likely to violate: comp-rep boundary, lazy imports ("Non-negotiable"), and the serialization pattern. Useful as a complement to the fuller treatment in your AGENTS.md.
• It's 161 lines vs the current ~270, which matters for token budget since the root file is injected into every conversation.

I'm not suggesting replacing your work -- the AGENTS.md has valuable depth (validation patterns, deprecation strategy, the naming table, fixture architecture) that the /init output doesn't cover. But the commands and architecture-to-filepath mapping would be easy to fold in on your end. I can share the generated file if you'd like to compare.

Anti-pattern specificity: As m-aebrer mentioned, rules like "prefer local fixtures" are easier for agents to comply with when there's a concrete example. Even a one-liner showing the preferred pattern would help.

Let me know if any of this is useful -- happy to put together changes on a separate branch or contribute directly here, whichever you'd prefer.

[Scienfitz]

@LeanAndMean many thanks for the input. I'm turning your coment into several threads because otherwise it will be nearly impossible to converse about thes eeveral sub-suggestions made therein, feel free to comment in the respective threads

[m-aebrer]

also +1 to @LeanAndMean's point about CLAUDE.md vs AGENTS.md. I have my harness dreb set to load both, but as I switch to AGENTS.md for new projects, I have been making nearly empty CLAUDE.md files that just inline AGENTS.md, and it works pretty much exactly as you'd hope. Very effective solution.

[AdrianSosic]

I think my approach for reviewing this PR is simply a pragmatic one: test it and adjust where necessary =) I have very little motivation to read agent-created files meant for agents only, so let's me instead point out problems / express wishes as they emerge.

[AVHopp]

ONly one small suggestion to add a paragraph describing how we prefer examples to look like, other than that I'd say let's see how well this workd