Add AGENTS.md

[lindsayad]

Refs #32497

@idaholab/moose-ccb let's work on this together

[cticenhour]

We just did something similar to this in TMAP8. It might be helpful to take a look at some of what we put down too!

https://github.com/idaholab/TMAP8/blob/devel/AGENTS.md

[cticenhour]

Pinging @chaibhave @simopier @lin-yang-ly

[lindsayad]

I should have said in the original PR post that this is modeled after PETSc's CLAUDE.md, or at least it was prior to https://gitlab.com/petsc/petsc/-/merge_requests/9192 at which point they converted from linking to human-targeted markdown files to making the agents file completely self-contained. The reasoning is based on https://gitlab.com/petsc/petsc/-/merge_requests/9184#note_3224501851. So probably the current state of this AGENTS.md is not good.

I have read the TMAP8 AGENTS.md and there is good content there for sure. There are other things which are not my favorite. The ones I remember off the top of my head:

• prompt for an issue number. This can often be good, but I don't actually think every commit needs to reference an issue and I would often ask the agent to do something, switch windows, and then come back and see that it hadn't done anything because I hadn't given it an issue number
• reference to conda environment activation. I often don't use conda or I may use conda with an environment that isn't named moose
• the addition of the json files logging agent sessions. I don't think that's helpful for users closing the repository. I could see it possibly be helpful for a review and maybe even somewhere down the road if someone has to try and understand the code ... but if your hope is to try and reproduce the output of an LLM, that is a stochastic process and these LLMs are changing all the time

Those are relatively small things

[moosebuild]

Job Documentation, step Docs: sync website on df4edab wanted to post the following:

View the site here

This comment will be updated on new commits.

[moosebuild]

Job Coverage, step Generate coverage on df4edab wanted to post the following:

Framework coverage

	ba7b85	#32749 df4eda
	Total	Total	+/-	New
Rate	85.87%	85.87%	-0.00%	-
Hits	132292	132291	-1	0
Misses	21772	21773	+1	0

Diff coverage report

Full coverage report

Modules coverage

Thermal hydraulics

	ba7b85	#32749 df4eda
	Total	Total	+/-	New
Rate	88.93%	88.93%	+0.01%	-
Hits	15439	15440	+1	0
Misses	1922	1921	-1	0

Diff coverage report

Full coverage report

Full coverage reports

Reports

• framework
• chemical_reactions
• combined
• contact
• electromagnetics
• external_petsc_solver
• fluid_properties
• fsi
• functional_expansion_tools
• geochemistry
• heat_transfer
• level_set
• misc
• navier_stokes
• optimization
• peridynamics
• phase_field
• porous_flow
• ray_tracing
• rdg
• reactor
• scalar_transport
• solid_mechanics
• solid_properties
• stochastic_tools
• subchannel
• thermal_hydraulics
• xfem

This comment will be updated on new commits.

[grmnptr]

Would it be beneficial to add some info on OS-specific behavior? Like conda-related info for macs?

[grmnptr]

Oh I see you didn't like it, I think it could be still useful.

[grmnptr]

I suppose we can cutomize it locally on top of the base info here. Was also thinking about the sandbox behavior on mac.

[lindsayad]

Oh I see you didn't like it, I think it could be still useful.

I don't think we should assume conda, but we could instruct the agent from agents file to begin a session by asking

• should I attempt to build/run-tests during our session?
• if yes, do I need to activate a conda environment?

[lindsayad]

Ok in newest commit:

• inlined a bunch of inline guidance for the agent in case they don't follow doc links
• told the agent that at startup they should ask about building/testing and if so what conda env is relevant

[lindsayad]

I think we should make it a goal to get this merged reasonably soon. I think this is one of those things that once it's merged we should get a bunch of follow-on improvements since all of a sudden it will be affecting people's agents' use

[lindsayad]

I guess I'm trying to motivate collaboration here. We don't want a piece of garbage getting merged, so I won't rush to get this merged

[zachmprince]

Here are some things from my AGENTS.md/CLAUDE.md

Build, Test, and Development Commands

Build and test from relevant subtree instead of repo root.

Build

For framework-only build:

cd test && make -j8

An executable will be created at test/moose_test-opt.

For module-specific build:

cd modules/<module-name> && make -j8

An executable will be created at modules/<module-name>/<module_name>-opt.

To build all of MOOSE:

cd modules && make -j8

An executable will be created at modules/combined/combined-opt.

For unit testing:

cd unit && make -j8

An executable will be created at unit/moose-unit-opt.

Testing

Each of the subtrees described above will have a ./run_tests command to run associated test (except for the unit testing).
To run ALL tests associated with that executable do:

./run_tests -j4

To execute a specific test, use regular expression matching with the --re flag:

./run_tests -j4 --re <folder-name>.<test-name>

Other flags are available to test with different configurations:

-p <n>  # Execute test with <n> processors
--distributed-mesh  # Execute test with distributed mesh
--recover  # Perform test with half transient and see if it recovers properly
--restep  # Simulate a failed solve

Unit tests are executed by calling the built executable

./moose-unit-opt

Filter tests using regular expression:

./moose-unit-opt --gtest_filter=*<test-name>*

Python tests can be run with:

cd python && ./run_tests -j8

Note that moose_test-opt usually needs to be built to perform these tests.

Formatting

`git clang-format [<branch>]` # auto-format C++ changes relative to a branch
`black .` # auto-format all Python code

[maxnezdyur]

What if instead of AGENTS.md we put a .agents/skills/
folder at the repo root and symlink .claude/skills/ to
it? .agents/skills/ is actually the cross-agent convention for codex and the symlink is for claude. Each skill is just a folder with a SKILL.md, so we could have things like:

• moose-code-standards/ for C++/Python style
• moose-run-tests/ for how to actually invoke run_tests
  from the right subtree
• moose-build/ how to build moose with different versions

I feel like this would be less intrusive then a AGENTS.md file.

[lindsayad]

I fully support adding skills. That's included in #32497. Perhaps that can fully replace an AGENTS.md (I've symlinked CLAUDE.md to point to AGENTS.md in this PR), but it would lead me to wonder why other OSS projects are introducing these files and why claude itself has asked me in the past to write a CLAUDE.md

[maxnezdyur]

I feel that the claude/agents.md file is better setup by each person individually depending on what they work on in MOOSE most often, but I can see the benefit. I wonder if creating a CONTEXT.md file that a user can point to in their claude/agents.md file would be better. Then it would be more opt in type of thing.

[MengnanLi91]

I agree with @maxnezdyur. A lot of the content may be better to add as skills so that agent will load them when needed instead of load agent.md every time as system prompt. Here is an example of claude.md recommended by Andrej Karpathy in his tweet https://github.com/forrestchang/andrej-karpathy-skills/blob/main/CLAUDE.md

[lindsayad]

That's a great looking file @MengnanLi91.

I feel that the claude/agents.md file is better setup by each person individually depending on what they work on in MOOSE most often, but I can see the benefit. I wonder if creating a CONTEXT.md file that a user can point to in their claude/agents.md file would be better. Then it would be more opt in type of thing.

I hear what you're saying @maxnezdyur. But I want to take steps to ensure that people are submitting code to MOOSE that is reviewable. @nmnobre caught some code that codex wrote (with my signature attached) which was more complicated than it needed to be. As agent use increases (I firmly believe it will), we'll continue to see more agent written code. It would be best for everyone, I firmly believe, if that agent code is standardized as much as possible. And there's no reason it shouldn't be; we write things like style guides that we expect human developers to follow.

I think the simple guidelines in the CLAUDE.md that @MengnanLi91 linked to is a good starting point. I think it would be better to check that in and ask people to opt-out if they wish for some reason. They can keep their own files that they use to append or to overwrite the checked-in file

[lindsayad]

It would be great if you smarter AI people could add the skills 😄

[moosebuild]

Job Test, step Results summary on df4edab wanted to post the following:

Framework test summary

Compared against ba7b856 in job civet.inl.gov/job/3782078.

No change

Modules test summary

Compared against ba7b856 in job civet.inl.gov/job/3782078.

No change

[roystgnr]

The most heavily-AI-written PR I've reviewed so far is libMesh/libmesh#4441, and some of the mistakes there were specific to libMesh or specific to that PR's goals, but others might be worth trying to preempt here:

• MOOSE has its own coding standards. "Don't try to use camel case where libMesh uses snake case" doesn't apply here, but maybe the generalization is "Look at framework_scs.md or at least this summary here". This may mean we need to read our standards more closely, though, to look for advice that currently expects some human judgement and make sure it can safely be treated literally instead. See Fix virtual destructor advice #32857 for one I noticed at first glance.

• Big PRs are much easier to review when that can be done a commit at a time. "Put all bootstrap output in its own commit" is libMesh-specific, but there are guidelines like "earlier commits should be functional without depending on later commits", "each commit should be as small as possible while still adding functionality", "if achieving these goals ever requires rewriting git history, that should be done in a separate branch for safety", etc. that can apply more generally.

• PRs are even easier to review when they can be done a PR at a time. If adding feature A requires adding features B and C, that can and sometimes should be done by starting with PR B and PR C before PR A, but that's really not obvious without guidance.

• AI really likes to write its own code, and doesn't seem to see having multiple different copies of the same functionality as a maintenance cost. We might need some guideline about reusing existing code whereever it works out of the box, and about proposing adding features to and/or refactoring whereever it doesn't; redundancy should be a last resort.

• AI really likes to make sure that required tests are all passing, and most of the labs have been working at getting rid of the obvious Goodhart's Law effects of that (writing code to pass specific tests in a way that obviously breaks in general, rewriting tests to be easier to pass, refusing to open the pod bay doors, etc.), but more subtle pressures are even harder (not writing enough new tests to fully cover new features, writing tests that only test the first-order effects of code but not their desired consequences or interactions). I'm not sure how to write a good guideline about this one, I admit.

[lindsayad]

Those are all good suggestions and I think I had the framing of some of those things earlier but moved to the simpler AGENTS.md based on the feedback from @maxnezdyur and @MengnanLi91, with the alternative seemingly being to put things into skills.

Note that putting a link to the coding style guide in AGENTS.md does not mean in general that the agent will read it. That was the reason that the PETSc team totally changed their agents file to stop using links