71–80 of 398 posts
Earlier quoted context omitted.
I had the same thought as I read this example. Everything in the AGENTS.md file should just be in a good README.md file.
My READMEs don't have things like "don't run the whole test suite unless I instruct you to because it will take too long; run targeted tests instead".
Earlier quoted context omitted.
... most of which would also be valuable information to communicate when onboarding new devs.
Yeah I agree. I think the best place for all this lives in CONTRIBUTING.md which is already a standard-ish thing. I've started adding it even to my private projects that only I work on - when I have to come back in 3 or 4 months, I always appreciate it.
My current thought is that (human) contributors should be encouraged to `ln -s CONTRIBUTING.md CLAUDE.local.md` or whatever in their local checkout for their agent of choice, have that .gitignored, and all contributors (human and LLM) will read and write to the same file.
The "new" thing would be putting CONTRIBUTING.md into subfolders as appropriate - which could often be quite useful for humans anyway.
Make sure to check out https://agent-rules.org/ as well for more background on this initiative. More and more tools are adopting the standard. Amp used to have an "RFC 9999" article on their website for this as well but the link now appears to be broken. You can symlink your Cursor / Windsurf / whatever rules to AGENTS.md for backwards compatibility.
"Guidance for Use"
Your preference for bullet lists over headers is odd. This comes down to what works best with the models - they are interpreting it. This is a moving target. If you believe that your suggestion works best you should provide some sort of evidence. The default would be to not even get into that sort of thing.
Non-Hierarchical AGENTS.md
Claude-code, Gemini, and GHCP all support hierarchical context files. Your proposal and this new one from OpenAI and friends do not, and I think that is a shame.
So the solution to using AI so you don't have to code, is to try to write some kind of pseudocode in AGENT.md and hope the AI does a bit better? Why does it seem that the solution to no-code (which AI-coding agents are) always comes back to "no-code, but actually there is some code behind the scenes, but if you squint enough it looks like no-code".
Umm, no. Where did you get that idea?
The purpose of the agent.md file is to give it instructions. Nothing about no-code AI said there would be no instructions...
I'm still not convinced that separating README.md and AGENTS.md is a good idea.
I'm still not convinced that separating README.md and AGENTS.md is a good idea.
At this point, README.md becomes the "marketing/landing page markdown" and AGENTS.md/CLAUDE.md becomes the ones you visit to get an overview of the actual code/architecture/usage.
Why we don't treat coding agents as developers and have them reading CONTRIBUTING.md is baffling to me.
The agents instructions file needs to be hierarchical; It's a pain managing multiple agents.md files with a lot of duplication between them for different projects, even in a mono-repo. we probably need a tool for this. In any case, I increasingly question the use of an agents file. What's the point, then the agent forget about them every few prompt, and need to be constantly reminded to go through the file again and…
I would be deal-breakingly concerned if I thought someone was actively trying to hide the fact from me.
I am developing a coding agent that currently manages and indexes over 5,000 repositories. The agent's state is stored locally in a hidden `.agent` directory, which contains a configuration folder for different agent roles and their specific instructions. Then we've a "agents" folder with multiple files, each file has Agent only reads the file if its role is defined there. Inside project directory, we've a dot folder…
Tell me more!
This is the problem I’m tackling, and so far, the approach has been effective. It's simple enough for anyone to use: the agent makes a commit, and you can either undo, squash, or amend it through the Git UI.
The issue is that developers often skip reviewing the code properly. To counter that, I’m considering shifting to a hunk-by-hunk review process, where each change is reviewed individually. Once the review is complete, the agent would commit the code.
The concept is simple, but the fun lies in the implementation details—like integrating existing CLI tools without giving the agent full shell access, unlike other agents.
What excites me most is the idea of letting 2–3 agents compete, collaborate, and interpret outputs to solve problems and "fight" to find the best solution.
That’s where the real fun is.
Think of it as surgeons scalpel approach rather than "steam roller" approach most agents take.
I'm still not convinced that separating README.md and AGENTS.md is a good idea.
I find AGENT.md and similar functioning files for LLMs in my projects contains concise and specific commands around feedback loops such as testing, build commands, etc. Yes these same commands might be in a README.md but often there is a lot more text that I don’t want in the context window being sent with every turn to the LLM.
Isn't the promise of AI that we don't have to adhere to precise formats? We can just write it down in whatever format makes the most sense to us, and any impedance mismatch is on the machine to figure out?