AGENTS.md is extremely important - it's probably the highest leverage thing you can give your agent. It's injected into every turn, and the agents are trained to follow instructions. If anything, I think people are under-investing into AGENTS.md and going purely based on vibes.
For example, if I write a bad AGENTS.md for a repo with 100 engineers actively working in it, then every agent for every engineer gets worse, without anyone really noticing.
I think we should move towards data-based tuning of AGENTS.md, testing out changes, gathering data, and then making a decision on whether or not to ship it.
My advice, from doing this myself and reading best practices, would be:
- Keep it concise, use progressive disclosure / nested AGENTS.md for information expansion
- Give agent the high level repo structure if necessary
- Have a "why" section to align the agent, high level, what your code is doing
- Keep behavior instructions positive where possible, eg Always clarify intent before acting
cool. I agree with all the front points. The last part ```Keep behavior instructions positive where possible```, do you have good experience on it. I'm only asking since my own experience is they're constantly not followed.
Yeah, I've found that to be more effective. Going with the example "Always clarify intent before acting" > "Never act without getting intent first", seemingly because telling the agent NOT to do something sometimes primes it to do that exact thing
I wrote one yesterday, but what goes in them has changed. Now I only put what amounts to a table of contents and some highlights of important things. Other info goes in other markdown, either localized agents.md or a directory of references. Skills are useful too
Anthropic has a new post series on enterprise adoption, their first one is on the setup and AGENTS.md gets a good chunk of that
I now have agents write more of that stuff but deeply review it. As peer commenter points out, a bad instruction can do damage. Keep them lean and clean, adjust them as new models arrive.
AGENTS.md is extremely important - it's probably the highest leverage thing you can give your agent. It's injected into every turn, and the agents are trained to follow instructions. If anything, I think people are under-investing into AGENTS.md and going purely based on vibes.
For example, if I write a bad AGENTS.md for a repo with 100 engineers actively working in it, then every agent for every engineer gets worse, without anyone really noticing.
I think we should move towards data-based tuning of AGENTS.md, testing out changes, gathering data, and then making a decision on whether or not to ship it.
The project directory, sure. I'm more of talking about behavior rules here. What are you guys writing, is it effective
My advice, from doing this myself and reading best practices, would be:
- Keep it concise, use progressive disclosure / nested AGENTS.md for information expansion - Give agent the high level repo structure if necessary - Have a "why" section to align the agent, high level, what your code is doing - Keep behavior instructions positive where possible, eg Always clarify intent before acting
cool. I agree with all the front points. The last part ```Keep behavior instructions positive where possible```, do you have good experience on it. I'm only asking since my own experience is they're constantly not followed.
Yeah, I've found that to be more effective. Going with the example "Always clarify intent before acting" > "Never act without getting intent first", seemingly because telling the agent NOT to do something sometimes primes it to do that exact thing
Of course. Claude.md is symlinked, and I change it for every new major task. Keeps cost down
I wrote one yesterday, but what goes in them has changed. Now I only put what amounts to a table of contents and some highlights of important things. Other info goes in other markdown, either localized agents.md or a directory of references. Skills are useful too
Anthropic has a new post series on enterprise adoption, their first one is on the setup and AGENTS.md gets a good chunk of that
I now have agents write more of that stuff but deeply review it. As peer commenter points out, a bad instruction can do damage. Keep them lean and clean, adjust them as new models arrive.
[flagged]
[flagged]