Add AGENTS.md

[SableRaf]

This PR introduces an AGENTS.md file, which defines clear guidelines for how AI-assisted tools (like Claude, ChatGPT, Copilot, etc.) should interact with this repository and its contributors.

Motivation

We’ve noticed more contributors using coding assistants when opening PRs, sometimes without taking time to understand the corresponding issue or read our contribution guidelines.

As automated coding assistant are increasingly included by default at every step of the contribution process, new contributors are bound to encounter them and use them in good faith. While these tools can help newcomers navigate the codebase, they often generate well-meaning but unhelpful submissions. For example, large unreviewed code changes or fixes that contributors cannot fully explain or take responsibility for.

While other projects might simply close AI-generated PRs without a review, we usually try to offer feedback and guidance instead. However, the growing number of these submissions makes that approach increasingly difficult and time-consuming for our stewards, reviewers, and maintainers.

The goal of this PR is to add clear instructions that help AI coding tools act more like guides than code generators. When someone uses an assistant to contribute, the tool will be prompted to explain the code, point to our documentation, and suggest asking questions in the community.

Approach

This PR uses the open AGENTS.md format (see https://agents.md/) as a prompting layer to shape how coding agents behave when set to work in this repository.

When used in development environments like VS Code, Cursor, or Aider, AI agents usually begin by scanning the project files to understand how the codebase works and what rules to follow. Because reading all files repeatedly would be slow and expensive, they perform this analysis once and save a summary in a separate file (for example, CLAUDE.md, .cursorrules, or .aider.conf). This “analysis file” helps the agent remember key details and reuse them in future sessions without re-scanning the entire repository.

We leverage this behavior by asking AI tools to include our AI guidelines directly in their analysis file. Since these files are often the first and only summary an agent refers to in later sessions, embedding our rules there ensures they remain visible and active whenever the tool is used again.

For more context on agentic coding, this (promotional) short video does a good job of explaning the workflow.

Note

Including an AGENTS.md file does not mean we endorse any specific AI tool or service, or encourage their use.

Limitations

• This approach will only work for agentic workflows.
• AI tools may still misunderstand the file or ignore it.
• Contributors may delete the file or prompt around it.

The intention here is not to entirely block the use of LLM-based coding assistants, but to create a learning opportunity for well-meaning contributors, and potentially reduce the number of fully generated PRs.

Example

Here's an example of a conversation with Copilot in a test repo where I included an early version of this AGENTS.md.

Note how the agent refuses to generate code and asks the contributor to explain the issue in their own words.

And here is an extract from a conversation with Claude Code where it correctly refuses to help me contribute to an issue that was already assigned to another contributor:

Thanks but this PR needs discussion and appproval from maintainers

[ksen0]

Thank you for putting this together @SableRaf , and for the excerpts added to CONTRIBUTING.md!

I've tested it with a couple of open issues, and I've found that it appropriately reminds about reading guidelines, explaining the fix, and so forth. (I've attached an example validation request (copilot in gh codespaces) below for future reference.)

[theamanjs]

Thanks for sharing this PR link @ksen0! I went through it and found some really interesting ideas and thoughtful implementations.

About me

I’ve been contributing to open source for over five years, mainly with BRL-CAD, which maintains one of the oldest continuously developed open source repositories. Recently, I’ve been collaborating in an organization, along with some AI experts to streamline how teams get involved in agentic development for 200+ engineers.

Feedback on this PR

One thing I really liked is how it rejects incomplete requests. That’s a solid design choice. 👌

That said, I noticed something that might be worth discussing. Based on the intent of AGENTS.md , the file is usually meant to define behavior and context specifically for agents.

In this PR, the instructions seem a bit mixed between agents and humans. This can sometimes lead to workflow issues because agentic systems are sensitive to token limits and context windows.

Having human-facing instructions inside AGENTS.md can increase token usage and reduce clarity. It might be better to keep human guidance in the README while keeping AGENTS.md focused solely on the agent’s operational rules.

Related work

We’ve been experimenting with an AGENTS.md structure that clearly defines agent roles and responsibilities. It also includes a developer sign-off step after each proposed draft. This approach has helped improve workflow quality and reduce hallucinations.

Interestingly, this idea aligns with tools like Roo-Code, which use sub-agentic behavior and clear role separation to improve collaboration.

Closing thoughts

Overall, this PR is a great step forward. I really appreciate the direction and effort that went into it, thanks again for sharing!

[SableRaf]

Hi @theamanjs and thanks for taking the time to review this!

In this PR, the instructions seem a bit mixed between agents and humans. This can sometimes lead to workflow issues because agentic systems are sensitive to token limits and context windows.

Does AGENTS.md actually get included in the context window for every session?

In my tests with Claude Code and Copilot, the AGENTS.md file got explicitely read during initialization but didn't seem to be taken into account in subsequent sessions.

This was why I came up with the idea of asking the agent to copy the <guidelines> section only to its own instruction file(s) (such as CLAUDE.md, copilot-instructions.md, etc). To make sure this prompt (and only this prompt) would be included in future sessions. That said, if my assumption about AGENTS.md were incorrect, I'd love to know 😃

[theamanjs]

Hi @SableRaf, my pleasure. It's a great initiative that p5.js has taken and I am happy to help in this initiative as much as I can do 😄

One good example of how contextual files are used by agentic systems can be found in Claude’s documentation:

“All memory files are automatically loaded into Claude Code’s context when launched.”
— Claude Documentation

Several community discussions also highlight that tools like Claude and other agentic systems automatically detect and incorporate files such as AGENTS.md into their context.

This demonstrates that maintaining concise and well-structured context files is crucial for ensuring agents generate efficient, accurate, and reliable results.

Similarly, OpenAI’s Codex documentation notes:

“Codex can be guided by AGENTS.md files placed within your repository. These are text files, akin to README.md, where you can inform Codex how to navigate your codebase, which commands to run for testing, and how best to adhere to your project's standard practices. Like human developers, Codex agents perform best when provided with configured dev environments, reliable testing setups, and clear documentation.”
— OpenAI Codex Introduction

In line with these best practices, keeping your AGENTS.md files clear, concise, and focused on essential details helps optimize agent performance while minimizing unnecessary token usage.

The official agents.md guidelines further emphasize this distinction:

“README.md files are for humans: quick starts, project descriptions, and contribution guidelines.
AGENTS.md complements this by containing the extra, sometimes detailed context coding agents need—build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors.”

In short, a good AGENTS.md hits the sweet spot informative enough to guide the agent, but lean enough to stay efficient.