As we think about how we has a community work with GenAI coding tools, a question that comes up a lot is can we start adding CALUDE.md or AGENTS.md files to our repos?
Often I’ve found that those files are simply alternative locations for good readmes and docs in a repo and that we would be better served with most of the info that lives in those files living in the README or other repo documentation.
The other types of items that I think could live in an AGENTS.md file are guidance specific for the tools on how they should write and break up code. Such as:
Asking it to make many smaller logical commits over one big commit with a large change to ease reviews.
When decisions get made, documenting alternatives and reasons behind decisions in commit messages.
Pointing to our conventional commit guidelines.
What are other things folks have been thinking about that would go in most/all of our AGENTS.md files?
The tl;dr is basically: good AGENTS.md files can make things slightly better, bad AGENTS.md files can make things worse.
I also feel like what makes sense to have in an AGENTS.md/CLAUDE.md file isn’t easy to agree on. I like feeling like I’m in control when using agents to code. If an agent isn’t doing what I want, it should be because I didn’t tell it what I wanted well enough, not because it’s doing what someone else told it to.
I personally feel like AGENTS.md/CLAUDE.md files shouldn’t be focused on what to do, but instead on how to do things. I want the agent to know how to change the time on the clock in my car, not to automatically do it when I drive into a new timezone.
Once place where AGENTS.md/CLAUDE.md files do feel helpful to be is as a band-aid for architectural tech debt. If a repo is hard to navigate and understand, then agents will struggle to navigate and understand it. In that case, an AGENTS.md/CLAUDE.md file can help until a refactor happens.
I’m curious as to others’ thoughts on this. It’s possible I’m the only person in the “don’t tell my agent what to do” camp.
If a repo is hard to navigate and understand, then agents will struggle to navigate and understand it. In that case, an AGENTS.md/CLAUDE.md file can help until a refactor happens.
And even then, that’s something that should be documented for humans. Can an agents file simply point to developer documentation that should be consulted/followed?
I asked, without anything specific in mind, and agree with the response that docs or a README meant for humans is a great place start (and possibly end). Not sure if an agent file pointing to the README really buys us much.