Posted by datadrivenangel 4 days ago
That said, AGENTS.md doesn't seem like a good name, right?, technically, it's an instructions file read by a single agent, not necessarily for agents, so it always struck me as a bit odd
But until the next standardization, keeping just AGENTS.md is the best approach.
Isn't it literally all just more text you're adding to the prompt. How can you even be sure it isn't just clouding context with nonsense for whatever you're asking for?
Similar reasoning with claude.md except it always reads the entire thing(?)
you end up clouding that more with an agent having to re-understand concepts or conventions
AGENTS.md is good when it is a nested sparknotes for the project, you save context and turns overall, but keep them minimal and largely gotchyas or unusual workflows in your repo
In my experience, there are two classes of tasks: some are very "in-distribution", and for those LLMs can near-flawlessly perform the "architectural or deep algorithmic legwork", with maybe a single second round to fix the mistakes. For others, I have to break the tasks down myself, and often it's a "death through thousand papercuts", because the size of a task that I can quickly verify and the LLM will not screw up with > 50% probability is small enough that it's sometimes net negative time spent relative to doing it myself (and using LLMs only as glorified search engine and article summarizer).
I like to tell myself that I'm getting better at recognizing these two classes up front, but I'm still frequently surprised when "type 1" turns out to be "type 2".
But circling back to the main topic: with "type 2", agent instructions are paramount, if only to enforce the "small steps, pre-commit to scope and methodology, verification at the end, user doesn't even want to know about anything in between" rules, as agents naturally want to run ahead faster than I can keep up with.
Then when it comes to implementation time, things typically go much smoother for larger changesets. Be wary to not overplan, as we all know how often we realized we missed something once we get into the details. Here, I stop the session and go back to iterating on the design/plan doc. Not a step-by-step guide, if you don't instruct them to the difference, they will just pseudo-implement in the plan like they do in their thinking traces, need to be be explicit about the level of detail.
Congrats.
It was either this or Claude had to become a generic term like sheetrock.