My agent.md to improve LLM-assisted code quality
Fabien Sanglard shares his journey from being unimpressed by LLM-generated code in 2025 to finding a workflow that works in 2026. The key was creating an agent.md file that injects coding style preferences into every session, eliminating the need to repeat himself. His rules cover everything from naming and comments to commit messages and architectural boundaries. He also discusses the 'Lost in the Middle' problem and offers practical tips like starting fresh sessions per feature and asking the agent to reload agent.md when quality drops.
While this 'trick' has considerably improved the code generated, this is not a magic bullet that lets me avoid reading the code.
- OptionOfT
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.
The what _is_ the code.
- imjonse
"When writing something intended for human consumption, (comment, commit message, reply to prompt) use as few words as possible. Pick every word meticulously to reduce the volume to a strict minimum. Be down to the point. Less is more."
The irony in this first paragraph using many words and many ways to convey the same message about succintness. But this file is not for human consumtion so different rules should (still?) apply.
I find myself doing this in prompts, I guess it is a way of adding more weight to parts of the context we consider need emphasis, and shows a lack of trust in the llm's abilities to get the message if it is mentioned once.
- andai
> - Keep function names short. Less than 30 characters.
Recently I asked GPT to port a browser game to Rust. It voluntered this gem:
draw_image_with_html_image_element_and_sw_and_sh_and_dx_and_dy_and_dw_and_dh(...)
I thought it was smoking some good stuff, but it turned out, that is actually the name of the function!
https://docs.rs/web-sys/latest/web_sys/struct.CanvasRenderin...
- YuechenLi
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.
- gregwebs
Great stuff. AGENTS.md is not the ideal place for most of it though. Most of what is shown in this article can go in CODING_STANDARDS.md. The skills that I use find this document when it is needed (writing and reviewing code) so it doesn't pollute context when code is being read.
I also have sub-agent reviews (both of a planning phase and the produced code) that would catch some of these problems and demand revisions. [1]
> - If the prompt indicates that a bug is being fixed, don't write the fix right away. First write the test. Observe it failing. Then write the fix. And observe the test passing.
I always use /tdd [2]. Occasionally it results in some silly tests, but it produces much lower defect code. Its not just for bugs.
[1] https://github.com/gregwebs/skills-sdlc/
[2] https://github.com/mattpocock/skills/blob/main/skills/engine...
- Supermancho
It's interesting to read these things.
I would describe this as 13 code writing rules (interpreted to be at least 16 - Starting with reduce code indentation) plus a commit message instruction set which I chose to ignore - because it's style-specific and not interesting to me.
8 or 9 of these rules are not necessary. Basic CS is not something I have needed to ask agents, I use, to follow. eg Explaining that you need explicit interfaces is not a necessary instruction, nor is leveraging early return.
Unclear instructions are of limited utility. What "Let the reader of the code breathe" or "reduce code indentation" means is subjective and will rarely be effective. Maybe the training for the language being used has gaps, which others do not. If you want to measure, ask it to output a string when it applies a rule. You'll figure out what works, what doesn't and how often, quickly.
There's 3 or 4 style choices included.
The rest are not something I would use, but we all get burned by different things so I get it.
- fitsumbelay
the author's correct about using agents but tbh I thought this was widely understood to be the best practice. in fact, agents.md for all your repos and a seperate [claude|gemini|...].md for each repo.
- getnormality
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.