Feat: add CLAUDE.md file

[jdeschamps]

Description

To best help us and potential contributors to make the best of Claude models when working with the CAREamics code-base, we should add a CLAUDE.md file that will guide the LLM into modifying the code while respecting its principles.

Because I am myself not using it extensively with project-wide context, this is better as draft for us to play around. So I just put some thoughts specifically for the next version of CAREamics (what we refer to as NG CAREamics, which is based around the NGDataset).

Things we could add:

• A section specifically about what we are more likely to accept (e.g. new implementation of one of our protocol, new algorithm that does not alter the code throughout) or not (e.g. support for another data format, features specific for a particular new algorithm but added to all the other algorithms)
• A section stating that the principles behind each module can be found in __ini__.py, which is currently not true but could be implemented throughout.
• A section on breaking down modifications into small self-contained PRs. (is this useful?)
  • Ask for a proof of principle in a separated module as first PR?
  • This is probably relevant as contribution guidelines
• CAREamics API examples.
• docstrings principles.
• Should we break it into several small Claude.md files distributed in the various modules? I'd prefer to put the relevant info in the __init__.py or a README.md since it will be relevant to other LLMs.
• Use "MUST" and "IMPORTANT" emphasis?\
• Description of how our tests are implemented (but first we need to agree on this and rewrite all tests).

@veegalinova @melisande-c @igor in particular, could you have a look and:

• Make suggestions via the review system to improve the descriptions (especially @melisande-c regarding the NG dataset)
• Try it out on your next PRs

Also please comment anything that comes to mind! In particular what can be useful in guiding the model effectively (also tagging @tlambert03 to benefit from his knowledge 😄).

We will probably also add a copy as .github/copilot-instructions.md to the same effect (or make it so it uses the same file).

[diyasrivas]

Tips on CLAUDE.md from Boris Cherny (Claude Code):

1. Keep the CLAUDE.md in version control and shared with the team (The Claude Code team maintains one shared CLAUDE.md in git that everyone contributes to multiple times a week).
2. Anytime Claude does something incorrectly, you should add a rule or note to CLAUDE.md so it knows not to do it again.
3. Include documention of team conventions, known pitfalls, patterns, and norms Claude should follow in your repo.
4. During reviews ,tag @.claude on PRs so a GitHub Action can help update the CLAUDE.md with new rules or clarifications as part of the PR process.
5. Create a root CLAUDE.md and additional ones in subdirectories, updating them systematically after major changes.

source: https://x.com/bcherny/status/2017742741636321619?s=20

[CatEek]

I have a couple of updates but in general looks good. Question is naming.
Claude wants CLAUDE.md, cursor uses AGENTS.md or .cursor/rules, etc. Possible solution is to have AGENTS.md and with explicit instructions to users to rename it depending on what they use. Or maybe just explicitly add it into context, this is what happens to it anyway with any agent.
Did anybody notice how these rules actualy affect agent's behaviour? Also @federico-carrara @tlambert03 plz comment :)

[tlambert03]

from what I understand, almost everyone is using AGENTS.md ... but claude is sort of the holdout:
anthropics/claude-code#6235

and this post suggests using AGENTS.md and then also having a CLAUDE.md file that just directs claude to it:

# Damn you Claude!
# https://github.com/anthropics/claude-code/issues/6235
echo 'See @AGENTS.md' > CLAUDE.md

---

my only other general tip would be not to overthink this first step. just get it in there. You will inevitably be happy with it in some ways and frustrated in other ways. When it does something stupid, just keep updating it.

[melisande-c]

Left over from copy and paste of Pydantic AI's version?