A bunch of these should be enforce with linting, that way people who still hand-craft code get the same kind of feedback, e.g. Always use {}, even on a one-line "if" statement. & Keep function names short. Less than 30 characters.
Then this one really is a pattern that creates a lot of churn:
- Add a small, to the point, comment to explain what the block does and why. Use examples when possible. Propose ASCII drawings to explain complete systems.
I added to the memory, system prompts, and the prompt itself and every soa model still litters code with the most inane useless crap. I will then get code to review from a coworker using fable/opus. It has more lines of comments then code.
Maybe I am some god tier code reader (i am not) but i dont think i have ever found a comment in code to be useful in my day job. That isnt true, i once came across
// submit to the dark lord
Above the function that sent a payment to PayPal for processing. It made me laugh so I let it be.
"- Don't touch blocks of code unrelated to the feature you implement. e.g. Don't add comments to a block of code if you did not create it or modify it. As much as possible try to minimize the number of changed lines when implementing a feature."
The feature where you ask the LLM to fix one thing and it fixes three things.
Since we are sharing our AGENTS.md, I thought I'd share my own, because most of the time, this is pretty much all you need for LLMs to write good code, everything else can be added per project:
----
*Convergence rule*
Every substantial task must end in exactly one of three states:
A. Success
The intended capability works in the real path and the real motivating case materially improves.
B. Meaningful progression
The capability is not complete, but one genuine blocker is removed and the next blocker is isolated with evidence.
C. Honest stop
Further work would require overbroad scope expansion, excessive debt, brittle patching, or tangled logic. Stop and report the reason with concrete evidence.
Do not continue producing patches once the work stops converging.
Do not confuse activity with progress. A failed attempt is only acceptable if it leaves behind a narrower problem, stronger evidence, or a justified stop.
Any partial work must leave the codebase in a cleaner, more legible, and more diagnosable state than before.
----
A lot of the article's AGENTS.md just feel like telling the LLM agents either something they already know (for example, most of the time they know to use exhaustive switch/match statements instead of "arrow anti-pattern") or seems actively harmful ("keep function names short" seems arbitrary and may cause the LLMs to write weird abbreviations for functions that are harder to read and review.
"Genuine blocker" is mostly there because otherwise LLMs may consider the smallest thing that they couldn't immediately figure out to be blockers and stop without implementing anything. The rule is there to tell the LLM if they can figure out how to resolve the blocker by themselves, they don't have to ask me to help resolve the blocker.
This is a problem that people mostly have to solve themselves. Like, I've been working with Claude for almost a year now and I have never once seen it write "Arrow Anti-Pattern" code. That, and much of the rest, would be fluff in my projects. Agent instructions are best learned from experience project-by-project.
I've read a few of these over the years, and none of them seem to be useful. I have three sentences in my custom instructions, and those are basically all useless, too.
Even my second one, "Avoid decorative or section-header comments. Never use `----` or `====` as comment separators. Comments should explain only non-obvious behavior, rationale, constraints, or implementation details." seems to be ignored by models regularly, so I don't see the point.
But this is in my private harness. Perhaps other harnesses have better instruction following. My custom instructions are prepended to my first user message, not set as a system message.
No, why should I have to remember to @ in every prompt? Or ask contributors to remember. It just makes it easier to make human mistakes. I have better things to do than micromanagement. There is huge value in auto-included context.
The GP wrote @ it from the agents.md file, not from the prompt. Their point was that instead of writing "how to contribute" instructions for agents, you could explain that in the CONTRIBUTING.md and link it from your agents file, so both humans and agents read it from one place.
Then this one really is a pattern that creates a lot of churn:
- Add a small, to the point, comment to explain what the block does and why. Use examples when possible. Propose ASCII drawings to explain complete systems.
The what _is_ the code.
Maybe I am some god tier code reader (i am not) but i dont think i have ever found a comment in code to be useful in my day job. That isnt true, i once came across
// submit to the dark lord
Above the function that sent a payment to PayPal for processing. It made me laugh so I let it be.
I esp liked:
"- Don't touch blocks of code unrelated to the feature you implement. e.g. Don't add comments to a block of code if you did not create it or modify it. As much as possible try to minimize the number of changed lines when implementing a feature."
The feature where you ask the LLM to fix one thing and it fixes three things.
I kept noticing this in diffs.
**Always use ASD-STE100 Simplified Technical English
Disclaimer: I saw this listed in some other HN post that I can' locate right away.
A. Success The intended capability works in the real path and the real motivating case materially improves.
B. Meaningful progression The capability is not complete, but one genuine blocker is removed and the next blocker is isolated with evidence.
C. Honest stop Further work would require overbroad scope expansion, excessive debt, brittle patching, or tangled logic. Stop and report the reason with concrete evidence.
Do not continue producing patches once the work stops converging.
Do not confuse activity with progress. A failed attempt is only acceptable if it leaves behind a narrower problem, stronger evidence, or a justified stop.
Any partial work must leave the codebase in a cleaner, more legible, and more diagnosable state than before. ----
A lot of the article's AGENTS.md just feel like telling the LLM agents either something they already know (for example, most of the time they know to use exhaustive switch/match statements instead of "arrow anti-pattern") or seems actively harmful ("keep function names short" seems arbitrary and may cause the LLMs to write weird abbreviations for functions that are harder to read and review.
What's the difference between a "genuine blocker" and a "blocker"? Why is the next blocker not genuine? Does it become genuine only after isolation?
local llm remain more in line like that.
Even my second one, "Avoid decorative or section-header comments. Never use `----` or `====` as comment separators. Comments should explain only non-obvious behavior, rationale, constraints, or implementation details." seems to be ignored by models regularly, so I don't see the point.
But this is in my private harness. Perhaps other harnesses have better instruction following. My custom instructions are prepended to my first user message, not set as a system message.
AI users are overwhelmingly addicts who are lying to themselves and the people around them. I've lost patience for their kind.
That way everyone benefits.
Then the model will go discover what it needs to.