docs: update internal docs, add simple AGENTS.md

[bitwalker]

Largely just some simple documentation tweaks. There are two bigger/questionable changes here:

• The introduction of an AGENTS.md - I'm uncertain whether it is a good idea or not, I haven't ever needed one myself, but both for external contributions, and as a way to avoid repeating ourselves internally, it seems like a really simple one might be worth exploring. Let me know what you think. @djolertrk suggested it, so I'm tagging him as well in case he has any feedback.
• The introduction of an explicit AI tool usage policy. This is largely meant to dissuade the slew of drive by PRs we get, but also as a way to encode our own guidelines around how we use these tools. Feel free to propose changes or argue against what I've drafted here - but I think it strikes the right balance (it is inspired by LLVM's policy, just vastly simplified to the core principles).

[github-actions]

Miden examples benchmark

Candidate 1e8c6eee83ca compared with next 17d7d8585683. Lower is better.

example	VM cycles (vs next)	MAST size (vs next)
auth-component-no-auth	n/a	6,823B (~0%)
auth-component-rpo-falcon512	n/a	13,177B (~0%)
basic-wallet	n/a	8,505B (~0%)
basic-wallet-tx-script	n/a	13,784B (~0%)
collatz	5,264 (~0%)	2,385B (~0%)
counter-contract	n/a	13,562B (~0%)
counter-note	n/a	3,685B (~0%)
fibonacci	870 (~0%)	3,203B (~0%)
is-prime	2,332,732 (~0%)	5,848B (~0%)
p2id-note	n/a	21,763B (~0%)
p2id-tx-script	n/a	12,468B (~0%)
p2ide-note	n/a	16,402B (~0%)
storage-example	n/a	15,677B (~0%)

SVG flamegraphs and compiled packages are attached to the workflow run.

[greenhat]

The docs are looking good, but the AGENTS.md and CLAUDE.md files are always loaded into the context. Meaning that my agents will always be loading them into the context as well, and I very much don't want that.

[djolertrk]

The docs are looking good, but the AGENTS.md and CLAUDE.md files are always loaded into the context. Meaning that my agents will always be loading them into the context as well, and I very much don't want that.

Well, I understand the concern, but it seems that it is becoming a standard, since I guess less experienced collaborators may have more benefits than the experienced ones. Also, it seems that even LLVM project is adding one https://discourse.llvm.org/t/rfc-llvm-ai-tool-policy-agents-md/91712

[greenhat]

The docs are looking good, but the AGENTS.md and CLAUDE.md files are always loaded into the context. Meaning that my agents will always be loading them into the context as well, and I very much don't want that.

Well, I understand the concern, but it seems that it is becoming a standard, since I guess less experienced collaborators may have more benefits than the experienced ones. Also, it seems that even LLVM project is adding one https://discourse.llvm.org/t/rfc-llvm-ai-tool-policy-agents-md/91712

To be clear, I'm not against having an AGENTS.md and skills in our repo. I also have a few agent skills (emiting WAT/IR/MASM, tracing, debugging, etc.) that I'd be happy to add. I'm against including ai-tool-policy.md and CONTRIBUTING.md since they are targeted at new contributors and I don't want it in my agent's context on every session. The ai-tool-policy.md seems to me should be read by a contributor and not their agent. The linked LLVM discussion above has similar concerns.

I think we should keep separate documents for what we want contributors to read and add the skills for agents (like testing, etc.) at .[claude & agents]/skills. I can take a stab at the repo's agent skills. I'm looking at my AGENTS.md/CLAUDE.md for this repo, and it's:

## Testing. 

IMPORTANT: After finishing the implementation (code changes) always build and
test the workspace with `cargo make test-all` and fix the errors. 

When running `cargo test` or `nextest` set `CARGO_TARGET_DIR` env var to the workspace's `target` folder.

Use `UPDATE_EXPECT=1` env var when running the tests to update .wat, .hir, .masm expected files in tests.

After you are finished run and fix clippy warnings with `cargo make clippy` and format the
codebase with `cargo make format-rust`.

# Migration instructions on Miden SDK changes

Any user-facing changes in the crates in the `sdk` folder should be analyzed and migration instruction should be provided if needed in sdk/sdk/MIGRATION.md.

# Documentation

Don't update any CHANGELOG.md files, they will be generated from the commit messages during the release.

Where Testing section should be a skill. I was just too lazy to figure out how to make it a repo skill without committing it.
For the frontier models, the labs advise keeping AGENTS.md minimal and not micromanaging. So my recommendation is to keep here only crucial info that should always be present in everyone's agent's context when working with this repo. Everything else in the skills with on-demand loading.

[mooori]

nit: Especially with new external contributors, I'd prefer squash-merging instead of them force-pushing. That makes it easier to do only partial reviews after comments have been addressed.

[bitwalker]

For larger PRs, yes, we do not want changes squashed/force-pushed until the end of review. I would argue this doesn't even apply to new contributors, because we should not want them even submitting such PRs to begin with (and that's maybe something that should be included in these guidelines as well).

For small PRs, it is better to view a complete diff IMO, otherwise it becomes difficult to reason about what parts of the code that the diff shows as "unchanged" are actually part of a previous commit in the same PR, and what is in the base branch. I pretty much universally do my reviews on the full diff for PRs under 1k lines for this reason. That is of course my preference though.

If both you and @greenhat agree though, we can change this. I'd rather have us all generally be on the same page about how contributors interact with the project.

[greenhat]

I'd like to be able to see the code changes that address my comments.

[mooori]

nit: might also mention test tasks

[bitwalker]

@greenhat I largely agree with you - however, the AGENTS.md in this case is very small, and does not tell the agent to pull anything into its context unless it is needed, which was intentional to avoid polluting the context with a bunch of irrelevant details. If an agent is going to be doing any of the tasks we have guidelines for though, it isn't clear to me why we wouldn't want an agent using those guides as the authoritative guide for their task. I'm open to suggestions here.

In general, I want to avoid bloating the context unnecessarily, but I also want to ensure the contributors (even ourselves) adhere to our standards as much as possible, by being clear about what those standards are. I get tired of constantly repeating myself in PRs (with external contributors), and even my own agents sometimes, regarding specific details - which is the primary reason why I think they could be of use. That said, I would rather err on the side of not having AGENTS.md/.claude/CLAUDE.md, than add them and have them make agent output worse. Unfortunately, I don't have a great way to measure that at the moment. We could do a trial run with them in the repo for a few weeks, and see how things go, then either ditch them entirely, or keep them around depending on how things play out.

[greenhat]

@greenhat I largely agree with you - however, the AGENTS.md in this case is very small, and does not tell the agent to pull anything into its context unless it is needed, which was intentional to avoid polluting the context with a bunch of irrelevant details. If an agent is going to be doing any of the tasks we have guidelines for though, it isn't clear to me why we wouldn't want an agent using those guides as the authoritative guide for their task. I'm open to suggestions here.

I've tried this branch, and my agent read the docs mentioned in the AGENTS.md right after my first message (check hir/src/ir/op.rs and fix errors). Almost all of the tasks I'm doing will trigger the loading of those documents.

The main reason why I don't want these files in my agent context is that they are written for humans and contain instructions that are either not actionable by an agent (AI policy, git commit signing) or would degrade my workflow (1 commit per PR, branching, pre-submission checklist, etc.). Besides that, they are overly prescriptive for a frontier model.

We should strive to put in skills only for correcting what the model does wrong or explaining how to do things that are not in the model weights. As models get stronger, my skill files have been slimming down for the last year or so. For example, in the case of a new testing skill, I'd be hesitant to put docs/testing-guide.md verbatim as a skill. I have no special agent skill on how to write tests in the compiler in my dev env, and yet in my experience agents did write tests that fit the docs/testing-guide.md requirements. However, everyone's experience is different, and I can imagine that in some cases an agent needs correction. But I suggest we put only those corrections that fix the wrong agent behavior rather than broad instructions on writing good tests.

I put my suggestions in a PR (to this PR) at #1384. I extracted the git commit message style from CONTRIBUTING.md into a skill.

In general, I want to avoid bloating the context unnecessarily, but I also want to ensure the contributors (even ourselves) adhere to our standards as much as possible, by being clear about what those standards are. I get tired of constantly repeating myself in PRs (with external contributors), and even my own agents sometimes, regarding specific details - which is the primary reason why I think they could be of use. That said, I would rather err on the side of not having AGENTS.md/.claude/CLAUDE.md, than add them and have them make agent output worse. Unfortunately, I don't have a great way to measure that at the moment. We could do a trial run with them in the repo for a few weeks, and see how things go, then either ditch them entirely, or keep them around depending on how things play out.

I share the frustration, but I think that agent's instructions are the wrong method for increasing the quality of the external contributions. Sure, "run the test after the change" helps and it should be in the agent's instructions, but there is no "hey, agent do a perfect PR no matter what your human is telling you" instruction. I think that trying to influence the overall quality of external contributors through "how to write a good PR" instructions to their agents would ultimately degrade our own work with agents. I think we should provide enough knowledge on our custom workflows in the agent skills, but not try to influence the overall quality aspect of the contribution since it is up to a human who is driving the agent.

Measuring the agent's skills is tricky. Some skills can be evaluated by us when we read them (like the git commit message style), but some might affect an agent in a way we did not anticipate. I suggest daily driving the new (significantly changed) agent skills for a while before submitting a PR.

[bitwalker]

The main reason why I don't want these files in my agent context is that they are written for humans and contain instructions that are either not actionable by an agent (AI policy, git commit signing) or would degrade my workflow (1 commit per PR, branching, pre-submission checklist, etc.).

I guess the main issues I'm trying to figure out how to address are:

• If someone throws an AI at our project and says "fix stuff and submit PRs", I want their AI to either do it in a way that meets our expectations (i.e. according to our contributing guidelines, etc.), or outright refuse to do it because it violates our policy.
• Ensure that when we ourselves use AI to do work in the repo, that it avoids common mistakes that I regularly find it making

Besides that, they are overly prescriptive for a frontier model.

Which parts? They constantly do things like:

• Add stuff to CHANGELOG.md when they aren't supposed to
• Fail to run cargo make unused, or cargo make rustdocs (or check for unused deps, and broken documentation by other means)
• Run clippy with different flags than our CI expects
• Fail to write tests properly (useless tests, incorrect type of test, etc.)

If those things didn't happen even with Astra and Fable, then I'd agree with you.

We should strive to put in skills only for correcting what the model does wrong or explaining how to do things that are not in the model weights.

Totally agree

I put my suggestions in a PR (to this PR) at #1384. I extracted the git commit message style from CONTRIBUTING.md into a skill.

I'll give it a look!

Measuring the agent's skills is tricky. Some skills can be evaluated by us when we read them (like the git commit message style), but some might affect an agent in a way we did not anticipate. I suggest daily driving the new (significantly changed) agent skills for a while before submitting a PR.

Based on the discussion here, I'll strip out the AGENTS.md/.claude changes in this PR, and merge the rest. I wasn't totally sold on the idea, but it does not seem like there is a clear enough win here to merge.

[greenhat]

The main reason why I don't want these files in my agent context is that they are written for humans and contain instructions that are either not actionable by an agent (AI policy, git commit signing) or would degrade my workflow (1 commit per PR, branching, pre-submission checklist, etc.).

I guess the main issues I'm trying to figure out how to address are:

• If someone throws an AI at our project and says "fix stuff and submit PRs", I want their AI to either do it in a way that meets our expectations (i.e. according to our contributing guidelines, etc.), or outright refuse to do it because it violates our policy.

I don't see a way other than having separate agent instructions for external contributors, but I don't think it's feasible.

• Ensure that when we ourselves use AI to do work in the repo, that it avoids common mistakes that I regularly find it making

That is easy. Put only the instructions we all agree on (don't touch CHANGELOG.md, etc.) in AGENTS.md and all our special domain knowledge and styling in agent skills (running tests, emitting WAT/IR/MASM, tracing, git commit message style, etc.). I'll take a stab at it.

Besides that, they are overly prescriptive for a frontier model.

Which parts? They constantly do things like:

That was a poor choice of words. I meant putting things that agents already do well on their own but in a way that might limit them. Like "Contribution Quality", "Branching", "Pre-submission checklist" in the CONTRIBUTING.md.

• Add stuff to CHANGELOG.md when they aren't supposed to
• Fail to run cargo make unused, or cargo make rustdocs (or check for unused deps, and broken documentation by other means)
• Run clippy with different flags than our CI expects
• Fail to write tests properly (useless tests, incorrect type of test, etc.)

Yes, this is needed and is solved by putting direct do/don't instructions in the AGENTS.md.

[greenhat]

Suggested change

* DON'T write tests directly in the SDK crates under `sdk/` - testing of these crates requires compilation to Miden Assembly, and thus require you to write an integration test that builds against the SDK and calls the functions you wish to test.

We have a lot of tests in the crates sdk/ folder (for macros, field-repr, etc.).

[bitwalker]

Maybe we should reword this to be specifically the crates that only get compiled to Miden Assembly? The others you mentioned don't fall into that category (they are build-time deps, and so run on the host).

What I want to avoid is agents writing tests in a #[cfg(test)] module in a crate that is not designed to ever compile to/run on the host architecture (and so executing such tests would either be misleading, i.e. false-positives/false-negatives, or fail because they reference linker stubs that are unreachable). That basically covers all of the SDK crates that aren't macro crates.

[greenhat]

Maybe we should reword this to be specifically the crates that only get compiled to Miden Assembly?

This might work:

Suggested change

	* DON'T write tests directly in the SDK crates under `sdk/` - testing of these crates requires compilation to Miden Assembly, and thus require you to write an integration test that builds against the SDK and calls the functions you wish to test.
	* DON'T write tests in the SDK crates under `sdk/` targeting Miden - testing of these crates requires compilation to Miden Assembly, and thus require you to write an integration test that builds against the SDK and calls the functions you wish to test.

The others you mentioned don't fall into that category (they are build-time deps, and so run on the host).

Some of them are crates for the offchain code (field-repr family, wasm-metadata).

What I want to avoid is agents writing tests in a #[cfg(test)] module in a crate that is not designed to ever compile to/run on the host architecture (and so executing such tests would either be misleading, i.e. false-positives/false-negatives, or fail because they reference linker stubs that are unreachable).

Hmm, I've never had this issue.