Add CLAUDE.md to assist development workflows with Claude Code

[glwagner]

This PR adds a CLAUDE.md document to help guide development with Claude Code. This document is loaded into the context of the model Claude is using when its started up inside the MOM6 directory. An introduction to the basic purpose of CLAUDE.md is written here:

https://www.humanlayer.dev/blog/writing-a-good-claude-md

The reason to add this to the repo itself is because, in addition to providing MOM6-specific guidance to Claude for any development task, the CLAUDE.md can also be used to catch "common mistakes" that Claude makes (eg it can say "make sure you don't do this"). This is actually not foolproof; sometimes Claude will make a mistake even if it is explicitly told not to. However, this can often be fixed with something like "review the code you've written and make sure you don't make any of the mistakes in CLAUDE.md". The common mistakes are things that have to be found empirically by using CLAUDE.md, so including it in the repo allows all MOM6 develops to collaborate on strengthening and improving the Claude dev workflow by contributing to CLAUDE.md.

Including this was an idea that came out of a conversation with @StephenGriffies !

I'll note that one can go much further with guidelines for Claude; for example many .md files can be developed for specific tasks. And so on.

PS let me know if I should try to contribute this file on a different branch than main

[adcroft]

I'm repeatedly impressed with these code analyses. This is one of the best quality CLAUDE.md I've seen so far, but it still guessed wrong on something: the build system for testing should only pass through .testing/Makefile, and I can't find any hint of CMake in the tree. Claude did this to me twice too, but oddly qwen3-coder got that part right first time.

@jkrasting mentioned on a previous PR that the context window size will be a problem for those on a government budget of zero. It is something to cognizant of but I think the size and complexity of the code far outweighs any problem with the length of a guidance file like this.

The reason to add this to the repo itself is because, ...

I was wondering about this, and I'm convinced by your argument.

We do have one issue to discuss before walking down this path: Claude is just one of the choices for coding assistant. We've been resisting using any one build system (mkmf, autotools, make, cmake, ...) to impose on the higher level repositories, even if we did choose a particular system in our CI. I'm similarly reticent to choose a favourite AI model on everyone's behalf. Maybe we could put all this guidance somewhere shared (like docs/) and then have lightweight redirects for the AI models?

PS let me know if I should try to contribute this file on a different branch than main

Intake is normally through one of the consortium forks, but leave this here for now. We can redirect later but it's good to be able to look at here - I have a feeling I know what our next dev call (or two or three) will be about...

[glwagner]

I'm repeatedly impressed with these code analyses.

Compiling analysis information (eg in a file like this) is especially helpful for further analysis. Asking questions about the code is an innocuous way to use an agent too.

The ability to read and review code remains paramount when using an agent. So a thorough human understanding of the codebase is nevertheless required for development either way. However, an agent that is well-informed might be able to help speed up implementation.

it still guessed wrong on something: the build system for testing should only pass through .testing/Makefile, and I can't find any hint of CMake in the tree.

Let's fix these before merging, if that ends up being desired! Also if there are other obvious things that should be recorded.

We do have one issue to discuss before walking down this path: Claude is just one of the choices for coding assistant. We've been resisting using any one build system (mkmf, autotools, make, cmake, ...) to impose on the higher level repositories, even if we did choose a particular system in our CI. I'm similarly reticent to choose a favourite AI model on everyone's behalf. Maybe we could put all this guidance somewhere shared (like docs/) and then have lightweight redirects for the AI models?

Actually, what we do on Oceananigans is to use the more agnostic filename AGENTS.md: https://agents.md/

You can direct Claude to look at AGENTS.md with a one line CLAUDE.md that merely says

@AGENTS.md

so, perhaps this file should be renamed AGENTS.md and some of the language changed.

@jkrasting mentioned on a #1690 (comment) that the context window size will be a problem for those on a government budget of zero. It is something to cognizant of but I think the size and complexity of the code far outweighs any problem with the length of a guidance file like this.

I don't have much wisdom to offer here, but we can try to reduce the size of the file and prioritize information. I think it's always important to optimize efficiency regardless of budget!

[jkrasting]

BLUF — The content in CLAUDE.md is great, but we should architect it as an ecosystem of files, skills, and rules rather than one monolithic file.

CLAUDE.md should be 30–100 lines. Anthropic’s guidance is to keep it under ~500 lines and move reference content to skills when it grows.

As instruction count increases, quality degrades uniformly across all instructions. Context rot kicks in, and the irony is that the most important information you defined up front is just as likely to get lost and ignored. It's better to keep CLAUDE.md short and load context around the time you actually need it through separate markdown files, .claude/skills, and .claude/rules. We also should use hooks for formatting, etc.

As we move to the agentic world, not every subagent needs the whole picture. In fact, sometimes it shouldn’t have it. A worker dedicated to algorithm development doesn’t need to know the rules for a git commit message. Compartmentalizing into separate files per task is better.

These files can also be crafted generally and sourced later, which avoids locking things into a particular AI system. @adcroft's AGENTS.md is a good example. CLAUDE.md can simply source it via @AGENTS.md.

Overall, the content is good. Just arguing for better architecture of the content ...

[marshallward]

Overall I think this is a good idea, thanks @glwagner

I did a first pass of changes that I think should be made to the file. But it probably needs at least a second pass. And maybe also reduced to avoid parsing, as @jkrasting suggests, but I don't know the cost. (I can't afford Claude)

I agree that an agnostic AGENTS.md would be a better than targeting a particular vendor. I also agree with @jkrasting that this should be divided into multiple files.

Two other suggestions:

• Can this be moved out of the top directory? Maybe docs/? Probably more like "code-configuration" but most of this feels like documentation anyway.

  Would Claude understand @jkrasting's .claude/ suggestion? would .agents work? Or .agents/.claude?

• Does the agents file need to use Markdown? It's a soft syntax with a lot of fragmentation. This is one of the reasons I use reST.

[glwagner]

BLUF — The content in CLAUDE.md is great, but we should architect it as an ecosystem of files, skills, and rules rather than one monolithic file.

CLAUDE.md should be 30–100 lines. Anthropic’s guidance is to keep it under ~500 lines and move reference content to skills when it grows.

As instruction count increases, quality degrades uniformly across all instructions. Context rot kicks in, and the irony is that the most important information you defined up front is just as likely to get lost and ignored. It's better to keep CLAUDE.md short and load context around the time you actually need it through separate markdown files, .claude/skills, and .claude/rules. We also should use hooks for formatting, etc.

As we move to the agentic world, not every subagent needs the whole picture. In fact, sometimes it shouldn’t have it. A worker dedicated to algorithm development doesn’t need to know the rules for a git commit message. Compartmentalizing into separate files per task is better.

These files can also be crafted generally and sourced later, which avoids locking things into a particular AI system. @adcroft's AGENTS.md is a good example. CLAUDE.md can simply source it via @AGENTS.md.

Overall, the content is good. Just arguing for better architecture of the content ...

I think these are good suggestions and consistent with the advice in the linked post above:

https://www.humanlayer.dev/blog/writing-a-good-claude-md

(although that post may be slightly out of date, I am not sure)

Please feel free to edit my PR directly. I can also try to divide the file myself (I generated a lot of the file by asking Claude to analyze commits to MOM6 and learn coding practices that way, and I can try to repeat that process to identify tasks).

In my recent experience, a lot of my usage falls into "general development" and I wouldn't be able to easily categorize it. But I can imagine having different tasks for things like 1) general development or feature development, 2) refactoring / code improvement (for various objectives; clarity, length, modularity); 3) performance or memory optimization; 4) documentation development. Maybe others have ideas for subtasks.

I also wonder, given a lot of the statements here, whether higher-powered models can somehow work around imperfect instructions more easily than less powerful models.

[glwagner]

Overall I think this is a good idea, thanks @glwagner

thank you!

I did a first pass of changes that I think should be made to the file. But it probably needs at least a second pass. And maybe also reduced to avoid parsing, as @jkrasting suggests, but I don't know the cost. (I can't afford Claude)

I can address your changes -- would you like me to do that, or should we pursue a larger refactor via @jkrasting's suggestions?

I agree that an agnostic AGENTS.md would be a better than targeting a particular vendor. I also agree with @jkrasting that this should be divided into multiple files.

Two other suggestions:

• Can this be moved out of the top directory? Maybe docs/? Probably more like "code-configuration" but most of this feels like documentation anyway.

I think there is a canonical location. But the file there can redirect to another place. So you can have an AGENTS.md at top-level which has statements like

- For general development see `docs/general_development.md`
- For documentation tasks see `docs/generating_documentation.md`

etc

Would Claude understand @jkrasting's .claude/ suggestion? would .agents work? Or .agents/.claude?

Not sure.

• Does the agents file need to use Markdown? It's a soft syntax with a lot of fragmentation. This is one of the reasons I use reST.

I doubt that markdown is required (except perhaps AGENTS.md). I guess the choice of markdown for convention has some purpose but its probably not a technical one.

[glwagner]

@jkrasting @marshallward I will work on addressing @marshallward 's comments, hopefully this will be useful even if the file is broken up.

[marshallward]

@glwagner Thanks for giving so much of your time to make those modifications. I was only trying to document potential issues, but you (and Claude) have managed to create an extremely thorough technical documentation of the codebase.

I expect that this will eventually need to be routed to one of the nodes (e.g. dev/gfdl) but for now it makes sense to leave this PR open to include others in the discussion.

[glwagner]

@glwagner Thanks for giving so much of your time to make those modifications. I was only trying to document potential issues, but you (and Claude) have managed to create an extremely thorough technical documentation of the codebase.

I expect that this will eventually need to be routed to one of the nodes (e.g. dev/gfdl) but for now it makes sense to leave this PR open to include others in the discussion.

No problem and for your comments! I enjoyed learning a little bit about MOM6. A file like this might also be very helpful for newcomers like myself, who are more likely to be able to contribute nowadays! I'll leave this open and feel free to do with it what you all like.

[marshallward]

I came across an essay talking about some of the agent issues discussed here: https://madalitso.me/notes/why-everyone-is-talking-about-filesystems/

• It cites a paper which claims that agent files can reduce quality:

  [A]cross multiple agents and models, context files tended to reduce task success rates while increasing inference cost by over 20%. Agents given context files explored more broadly, ran more tests, traversed more files — but all that thoroughness delayed them from actually reaching the code that needed fixing. The files acted like a checklist that agents took too seriously.

  I only briefly read the paper, but the idea seems to be that human-friendly files cause the agents to work much harder and overlook essential code sections.

  The paper does not oppose agent files, rather that they should be defined as sparse constraints rather than thorough onboarding documents.

  Someone with more personal experience with agent files may be able to judge this conclusion.

• The essay raises several of the API-like issues that we have discussed - namely that AIs don't always know where to look - and that the companies are trying to figure this out, with Agent Skills being a potential point of convergence.

Not yet suggesting any particular action, but perhaps some things we should look into.