📚 Add AGENTS.md

[GeigerJ2]

Rendered view here:
https://github.com/GeigerJ2/aiida-core/blob/docs/agents_contributing/AGENTS.md

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.84%. Comparing base (5974f8b) to head (8e128b3).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #7265      +/-   ##
==========================================
- Coverage   79.85%   79.84%   -0.00%     
==========================================
  Files         566      566              
  Lines       43962    43962              
==========================================
- Hits        35102    35099       -3     
- Misses       8860     8863       +3     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[GeigerJ2]

Suggested change

	It is written in Python (3.9–3.13) and uses PostgreSQL/SQLite for metadata storage, [`disk-objectstore`](https://github.com/aiidateam/disk-objectstore) for file storage, and RabbitMQ as a message broker.
	It is written in Python (3.10–3.13) and uses PostgreSQL/SQLite for metadata storage, [`disk-objectstore`](https://github.com/aiidateam/disk-objectstore) for file storage, and RabbitMQ as a message broker.

[danielhollas]

Very cool. Just had a very brief look at the CONTRIBUTING.md

[GeigerJ2]

TODO: As mentioned by @agoscinski, if this file is loaded automatically into the context of the agent, we should make sure it's not too extensive, or at least ensure that if it is, it does not cause unwanted side effects (e.g., degradation due to context pollution). I'd still need to check and verify this myself. Also, trying out a few LLM-generated PRs, with the file in place.

[agoscinski]

My understanding is that it is not automatically loaded so people can still choose to not use it. In case it does not provide additional benefit, it can be ignored. I think the overall shape looks good but I don't know how well it works in practice. I saw that one can do tests by give it an agent and compare token consumption. I personally don't have such a workflow yet so I suggest to merge it for testing and do QA in the future.

[khsrali]

@GeigerJ2 , worth a read:
https://tiangolo.com/ideas/library-agent-skills/#examples

[GeigerJ2]

@GeigerJ2 , worth a read: https://tiangolo.com/ideas/library-agent-skills/#examples

Thanks for sharing, @khsrali! Interesting, I wasn't aware of that. Seems like the landscape changes every day :D

If I understand correctly, the key distinction is that AGENTS.md (repo root) is for agents working on aiida-core (contributors), while SKILL.md (shipped inside the package at src/aiida/.agents/skills/aiida/SKILL.md) is for agents working on code that uses AiiDA as a dependency (plugin/workflow developers). The latter gets discovered from site-packages after installation, while the former is only available when the aiida-core repo is actually cloned.

I'd still like to have AGENTS.md as the single source of truth for everything related to contributing to aiida-core. Basically a TLDR of our developer guide. Instead, SKILL.md could be separate, user-facing content: usage patterns, API examples, pitfalls when writing workflows and plugins, etc. Some content overlap likely won't be avoidable, though, and I guess that's fine.

As this PR has been open for way too long for what it does, I suggest, we open an issue on adding a SKILL.md to the repo, and do that as a follow-up. That OK for you?

EDIT:
Just learned that SKILL.md doesn't have to live inside src/ (for downstream distribution), but can apparently also live at the repo root under .claude/skills/, where it would only be available to developers who clone the repo, similar to AGENTS.md. So there are really three options: AGENTS.md (repo root, cross-tool), .claude/skills/ (repo root, Claude Code contributors, or .agents/skills), and src/aiida/.agents/skills/ (shipped in the package, for downstream users). I'm not sure what is the best way to do it, tbh. Move some content what I now put into AGENTS.md to the skills at the repo root? Have some or no duplication? Idk...

Adding distributed skills via src could indeed also be useful for actual users, but this I'd do in a follow-up, as I mentioned.

[GeigerJ2]

OK, guys, we've come full circle ^^
After in-person discussion with @mbercx, I've used Claude to refine this file following the Claude Code best practices for CLAUDE.md/AGENTS.md files. This trimmed AGENTS.md from 582 → 382 lines (~34% reduction).
The core principle followed:

"For each line, ask: 'Would removing this cause Claude to make mistakes?' If not, cut it. Bloated files cause Claude to ignore your actual instructions!"

Would really appricate if you other passengers on the AI hype train, @agoscinski, @khsrali, @mbercx, could have a final look, and we can merge this soon. Doesn't have to be perfect, we can see how the agents perform with this file in place, and then further refine.

What stayed (and why)

• IMPORTANT banner at the top telling agents to use uv run, never bare python/pip. Without it, Claude frequently tries bare python and fails on test runs (e.g., due to missing dependencies as it's using the wrong executable).
• Development commands block kept in condensed form for the same reason — standard uv/pytest/pre-commit usage is apparently not reliably inferred (at least, it seems to be easier to quickly mention this here, rather than expecting the agent to always read pyproject.toml, .pre-commit-config.yaml, etc.)
• All "discoverable" sections (database/file storage, project config, formatting/linting, type checking, merge strategies, pre-commit hooks, test philosophy items, API design, pure functions, code quality advice) are shortened, but remain as brief one-line mentions (1-2 lines each). Same reason as above.
• Debugging section kept as its own section.
• AiiDA-specific gotchas, common patterns (adding Node/CalcJob/WorkChain/CLI), and key design concepts untouched — these can't be inferred from the code.

What was condensed to one-liners

• Database/file storage — 5 bullets → 2 lines
• Project configuration files — 6 bullets → 1 line
• Ruff/mypy details — multi-line rule-set list → 1 line each
• Docstring example block → one-liner reference to Sphinx style
• Copyright header block → "copy from any existing source file"
• Other pre-commit hooks list → 1 line
• Test philosophy standard items (isolation, one-behavior, deterministic, don't-test-framework) → 1 line
• API design (keyword args, minimize *args/**kwargs) → 1 line
• Standard code quality advice (pure functions, type annotations, docstrings) → integrated as one-liners
• Key entry points table: 27 rows → 11 most critical, rest → single "Other notable files" line
• Merge strategies → 1 line

What was removed entirely

• Internal ABCs table (infrastructure detail, discoverable from code)
• Commit style rationale paragraphs (kept the rules, dropped the explanations)
• Database inspection (verdi devel run-sql, verdi shell examples)
• Standard PR etiquette ("open PR only when ready", LOC-per-PR advice)

Small consistency fixes along the way

• Node immutability gotcha reconciled with the ProcessNode._updatable_attributes note in Key design concepts.
• Added a pointer to src/aiida/cmdline/commands/cmd_*.py so agents find verdi subcommand implementations.

[GeigerJ2]

My understanding is that it is not automatically loaded so people can still choose to not use it. In case it does not provide additional benefit, it can be ignored. I think the overall shape looks good but I don't know how well it works in practice. I saw that one can do tests by give it an agent and compare token consumption. I personally don't have such a workflow yet so I suggest to merge it for testing and do QA in the future.

ok, just looked this up here, and it is not auto-loaded indeed. One can add a tiny CLAUDE.md that just references AGENTS.md. I just added that in the latest commit. Up to the team to decide if we want it auto-loaded or not (I'd certainly want to...)

[mbercx]

Thanks a lot @GeigerJ2! I've finally started looking a bit into how to optimize these tools. I'll try to give a proper review next week, based on what I learned.

One thing I did come across while researching this is the following paper: https://arxiv.org/abs/2602.11988

I only read the abstract, but it seems like they tried to gauge the effectiveness of having an AGENTS.md file more rigorously. Might be worth a look to see if we can learn something from it.