📝 Add repository instructions for AI tooling

[burgholzer]

Note

This issue is part of unitaryDESIGN 2026; note that you have to be registered to complete this issue. Learn more about the PR review process here. 

A message from unitaryDESIGN about AI Slop: "While we are open to collaboration with LLMs for unitaryDESIGN, please note that fully AI-generated PRs are not acceptable. It is up to the discretion of the individual maintainers whether or not LLM-generated PRs are the right fit for their issues, and they have the right to reject those that appear fully AI-generated."

Learn more about unitaryDESIGN rules and opportunities here!

One of the biggest challenges when using AI tools such as Claude Code, Cursor, Copilot, etc. is how to best instruct/prompt them and make them understand the repository, how to perform certain tasks, and what practices should be followed.
While there does not seem to be a real standard format for providing such instructions (yet), there are a handful of guides on how to best instruct agents/AI systems, such as

• https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions?tool=jetbrains (.github/copilot-instructions.md and .github/prompts, e.g., for changelog creation or release preparation)
• https://agents.md (AGENTS.md)
• https://www.reddit.com/r/ClaudeAI/comments/1mecx5t/how_we_structure_our_claudemd_file_and_why/ and https://www.anthropic.com/engineering/claude-code-best-practices (CLAUDE.md)

From what I could gather, AGENTS.md seems to be emerging as a quasi standard and all the tooling that we are using consumes it.

The goal in this issue would be to curate such a file for this project, clearly emphasizing the commands that shall be executed for building, testing, listing, etc. as well as the best practices for development and the things that we value.
I personally liked https://github.com/astral-sh/ruff/blob/main/CLAUDE.md as an inspiration, and the suggestion from the blogpost above to run the prompt improver on the respective file.

The documentation of CodeRabbit seems to indicate that it also natively supports AGENTS.md, which would also be great for reviews.

---

The file should, at least, cover the following aspects

• how to build the C++ part of the library (cmake etc.)
• how to run the C++ tests (maybe in various granularity)
• how to build the Python package using uv (and not pip or something else); this should also include where to find build files of the Python build (build folder)
• how to run our pre-commit checks (either via uvx nox -s lint or via uvx prek run -a)
• how to build the docs (nox -s docs) and where everything is placed
• how to generate the stub files (nox -s stubs); stub files must not be edited manually
• that we use C++20, CMake 3.24+, Python 3.10+, LLVM 21+, ruff for linting and python formatting (not pylint, black, etc), ty for type checking (not mypy), uv for package management (not pip).
• that our ruff configuration enables ALL and, hence, all rules by default, and only selectively disables some in the pyproject.toml configuration
• (how to build in debug mode)
• (how to test with the lowest dependency versions)
• that we run on Linux, macOS, Windows for x86 and arm64 architectures
• ...

The file should follow established practices and be curated to be as effective as possible.
We expect more than a simple Claude \init call here and solutions that have not been fine-tuned/curated may be rejected.