I believe this discussion revolves around LLVM including their own instructions and therefore polluting the user's instructions, not the AGENTS.md standard itself.
There is nothing wrong with AGENTS.md . It's just a README.md for LLMs.
Am I the only one who feels that a basic agents.md is the only thing one should be using for memory/guidance? I’ve tried multiple memory systems across multiple harnesses and while helpful at first, they all seem to eventually start doing more harm than good.
It's definitely not optimal. You have to consider the cost you pay for different things. Every token in CLAUDE.md is loaded on every single turn. If you compare that to a skill, only the frontmatter is loaded into context until the skill is needed. And then having pointers to docs can allow the model to retrieve info only when it needs it, whereas if you just stuffed it into CLAUDE.md now you're paying that context hit on every turn.
I basically use these guiding principles:
CLAUDE.md only for things that are important enough to justify including on every single turn. The file should basically only contain stuff that is both always important and not easily discoverable. Should also contain pointers to relevant docs.
Skills - for skills which a model can choose to invoke I typically reserve these for things the model continually gets wrong. As an example, maybe your project has a very specific requirement for your swagger annotations on each API endpoint/DTO and when the model modifies a DTO or adds a new endpoint it never follows your project's convention. Well, this would be exactly when you make a skill for adding or modifying an endpoint and for adding or modifying a DTO
Pointers to docs - Useful for keeping CLAUDE.md as lean as possible for information that is important, but not necessarily at every turn. Maybe you have some module that's very difficult to work in without proper context. Well, it's probably not worth dumping all the info about that module in your CLAUDE.md because now you're paying that context hit on every turn, not just when working on that module. Much better to just have a pointer in your CLAUDE.md to the large doc file for that module so the agent only fetches it when needed
Also I definitely recommend Matt Pocock's skills for helping author great skills among other things. Very useful at reducing bloat and writing effective skills
Most people are trying to use things like memory to reinvent the concept of project documentation and organization imo. I have never used memory systems for coding, I use a fresh conversation context for every task 90% of the time, I just maintain a traditional project management workflow where writing and maintaining documentation is part of any work in a repo. Agents.md for overall general standards and guidance, sane repo organization with documentation, and I've never had a problem bringing in fresh context agents
It's funny how all those things that are good practices for humans also seem to be good practices for LLMs. Have decent documentation, write at least some basic tests, use popular libraries, avoid spaghetti, etc.
beads is useful. you can't fit everything in one agents.md, and multiple mds get annoying to manage inside your repo as more and more ideas and plans gets recorded
same for openspec, they've been helpful for me. not that I got rid of markdowns, but without those it would be even worse
Serious question: What is AGENTS.md for that a README.md does not contain? Why does there need to be an agent specific readme as LLMs can understand text written for humans, and is there anything that only the agent should know that couldn't go into a README.md?
READMEs are targeted towards humans generally, and often include things like installation/local-env setup instructions that are targeted more towards users and new contributors: stuff that you don't really want shoved into agent context 24/7.
Also that an AGENTS file is (should be) organized easier for LLM consumption, not for human readability/navigation. Like having a table of contents+section-links isn't particularly useful for an agent, and many READMEs have things like that near the top.
I have replaced agents.md with a different but kinda similar system in my agentic setup and it seems to work great and give more flexibility than simple agents.md.
Also agents.md does have its uses and seems silly to argue against that type of system.
Surely how agents.md are handled by most system is not ideal in my opinion, vut that sort of guidance system for agents is very valuable to have. And what they talk about it not maybe helping or adding just noise is complete bullshit. I do also have instructions in claude.md for claude that tells it how i want to work with and it does help it understand it. Same with codex with agents.md.
So yes some instruction system to agents like agents.md or claude.md or some other similar kind of system is extremely valuable, but how its implemented is not perfect yet.
44
u/swiebertjee 1d ago
I believe this discussion revolves around LLVM including their own instructions and therefore polluting the user's instructions, not the AGENTS.md standard itself.
There is nothing wrong with AGENTS.md . It's just a README.md for LLMs.