My agent.md to improve LLM-assisted code quality | Hacker News Reader

My agent.md to improve LLM-assisted code quality

fabiensanglard.net

415 pointsibobev176 comments

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.

I would never tell an agent to write "what does the code do" comments. Their default comments are already way too fluffy.

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.

Most useful code comment I have encountered read:

“”” After you give up on trying to refactor this code, increment the following line accordingly. HOURS_WASTED_HERE=26 “””

I always loved the classic _"Here be dragons"_

But then you don't know about where the load bearing seams are!

I tell the agent to NEVER write comments in the system prompt and it ignore it like 90% of the time. RLHF is a helluva drug.

We trained agents on millions of pages of documentation telling them to write good comments and good code and then we tell them never to write any comments.

It’s almost the “we built a robot who loves to play Sonatas and gave it no hands” type of thing.

Being overly trained on comments in documentation could be one of the reasons why Claude models write frustrating comments (which often manifest as written justifications of how the code satisfies the prompt). A comment in a tutorial is going to be geared to explaining how the code relates back to the tutorial task or restating what the code does, rather than documenting the "why" of surprising code.

What models are you using? I've had "Never add any new code comments" in my system prompts for like a year at this point, seems every model above 14B picks this up just fine. Are you using llama 7b or similar for testing this?

Pretty much Opus 5 exclusively.

Hmm, I guess everyone here is using Claude? I find that Sol is much more restrained, to the point where I have a prompt to tell it to add short comments for things that are not obvious. Really, I find the verbosity problem to be worse in tests. I regularly prompt my review agent to remove tests used only for scaffolding to write the code in the first place. The agent is in a way following strict TDD, which reminds me why I don’t like TDD, even though some of the generated tests can be useful.

Sol adds comments when I use it, but it's not nearly as verbose as Opus 5/Fable.

For the latter I'll often include an example of a comment it wrote, along with my own rephrasing, and tell it that "future readers will understand code context; good naming is the best documentation". This works alright if I include in the actual prompt, but annoyingly it often doesn't in CLAUDE.md or memory.

My biggest pet peeve with agents is when people beg their (non-deterministic) agents to do something that a lint rule could've accomplished

Right. I've really struggling to get AI to stop explaining the what. It seems to add it to the commits, PRs, code, wherever it feels like. I've put in multiple places to not write the "what", but the "why", and in multiple ways, but it still does it in one or other place.

One thing I don’t get with a lot of these agents.md and other skills are… why not throw as much mechanical checks and other stuff at the repo to constrain as you want instead of asking a non-deterministic agent (squishy or non-squishy) to maintain it.

With the mechanical routes, we get checks, failures, and so much more. A bit wild to me.

Make an agent operate within defined constraints and yell at it when it doesn’t.

I forbid my agents from adding any comments. I review the code and add comments manually. If I can't understand something despite having the context then I throw away the code instead of having an LLM generate comments to explain what it did. This way the code stays readable/debuggable by humans.

How do you stop LLMs from making comments? In my experience, LLMs treat requirements for code output as suggestions

If you don’t trust the code to write a decent comment, why trust it write good code?

Of course, ensuring compilation or other checks can verify some code, which it can’t do for comments. But comments still serve the same purpose as human comments.

If I understand correctly, it’s not that the LLM can’t write a good comment, it’s that you want to be able to interpret and understand the generated code without comments - and in that process end up writing comments yourself.

The actual code output has improved a lot over the past year. I’ve found it matches existing patterns better, and the code is succinct so I can easily tweak it if I don’t like the way the agent wrote it.

The problem with comments is that LLMs tend to copy their verbose chat output format and insert session/prompt specific details. It makes me think that LLMs aren’t constrained in their comment output the same way they are with their code output

In my experience, Claude adds loads of comments, but Codex (GPT-5.5) never adds any.

> This way the code stays readable/debuggable by humans.

Please take the following as expressed with genuine curiosity: Do you not use an editor with syntax highlighting and collapsible comments?

At least on JetBrains you can configure the editor to collapse all comments on open and to have the comments displayed in a low-contrast color. This way, LLMs add a bunch of comments, but it doesn't affect your actual experience in trying to read the code. If you encounter code that seems inexplicable, then and only then would you expand the comment to see if that helps you understand.

LLM comments for code are almost unfailingly completely redundant or impenetrably verbose bordering on word salad.

Also, the language model might not fully understand the code then add a comment, then the next iteration will treat assumptions in the comment as the truth.

Hiding the code from your view is not the solution.

The next developer doing a review will see it. The next agent iteration will see it.

If the comment is wrong (even slightly) or redundant, that will help noone.

Not the OP, my two cents:

Comments should be written only when there is (hidden) complexity or external context strictly required. Otherwise it is just easier to read the code. Comments then signal one of two things: a) the following code is really complex and I need to tread carefully, or b) this code is complicated, and could benefit from a refactor.

In regards to agentic coding, all these comments are extra contents, driving down quality while increasing cost. Agents also tend to be inconsistent about updating comments, I've had cases repeatedly where a comment did not match the code, at which point it is just a documentation liability.

I'm not convinced, yet, that eliminating LLM-generated comments is the right path for me. I do review everything written by an LLM and some comments are actually pretty good, but sometimes I'm just too tired to try to figure out how to reword an oddly worded one.

I just added Sanglard's rules to my ~/.claude/CLAUDE.md file, did another code review, and found some LLM-generated comments were really hard to understand. I think they're due to invented metaphors and flowery language instead of using standard terms, so I've added this:

- Comments must be literal. Don't invent figurative language for what a plain technical term already says — write "rows still reference it," not "rows still wear it."

Improving LLM code generation is an iterative process. I'm glad people share their efforts to improve it.

> Propose ASCII drawings to explain complete systems.

LLMs are very bad at ASCII drawings.

https://medium.com/data-science/why-llms-suck-at-ascii-art-a...

Mine says what I tell engineers:

> Write in-code comments that describe _why_ code or a class does what it does, but not _what_ it does. The "what" should be self-evident.

> The what _is_ the code.

Even the why sometimes shouldn’t be a comment, unless it’s very immediate to the code itself. What’s often more necessary is a high level overview of the design of the solution, because that’s what drives the design of the code and link disparate section. Especially the glossary , which you let you understand the name of the symbols (variables, struct. functions,…) used in the code.

It’s like learning the culture associated to a foreign language instead of trying to translate each single word with a dictionary.

The cost of custom linters has like any other code dropped through the floor. I'm sprinkling all kinds of linters over my latest projects. It seems some people are still sleeping on this, expecting great code from the agents.

They're fast and deterministic and I run them in git pre-commit.

> They're fast and deterministic and I run them in git pre-commit.

Isnt that too late? I would want the agent to stumble into this as early as possible in the agentic loop, eg at the same time as compiler.

It's been working quite well so far and I don't know of any way of hooking custom linters into cargo so they run after compilation.

But that's a pretty good idea, wonder if there is a way...

A comment is just a summary of the code in an abstraction that's easier to follow. Let's say you have a simple function which would produce an almost as large comment, yes obviously useless. If the function is large enough, yeah summarizing it as a comment is a good idea.

Now you might say, don't write huge functions. Sure I agree, but most codebase or teams are not super disciplined enough. So comments are a compromise.

> - 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...

They laughed at objective-c back then, now the shoe's on the other foot

This is an unfortunate side effect of bridging an API from a language that supports function overloading, into a language that does not

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.

> but one genuine blocker is removed and the next blocker is isolated with evidence.

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?

"honest", "real", "genuine" -- wat.

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.

Just this one line in AGENTS.md has given better results to reduce if not eliminate verbosity and grandeur.

**Always use ASD-STE100 Simplified Technical English

Disclaimer: I saw this listed in some other HN post that I can' locate right away.

This is probably the skill you remembered: https://github.com/AminBlg/SimpleEnglish

I have been using it for a few weeks, and it significantly improves the quality of the docstrings and code comments, as well as the readability of spec docs.

I have also added a few key bullet points to my AGENTS.md and have found the results to be very effective and generating plans and code that looks like something I would have written:

-----------

    ## planning, design and spec docs

    - the highest design goal is simplicity -- in our systems and our mental model -- even if if means edge cases are unaddressed and could potentially fail
    - please practice "ya ain't gunna need it" (YAGNI) do not add unnecessary guardrails
    - do not plan to add caching, many layers of unnecessary abstraction or other premature optimizations
    - look for places where adding or clarifying an invariant would simplify the code or the overall system

    please specifically try to avoid:

    - redundant calculations or duplicated work
    - duplicated conditionals or state-machine logic
    - storing state that can be derived from other state, which could drift and become out of sync over time
    - leaky abstractions across layers of the application
    - multi-line comments explaining a variable name or a single statement. well chosen names and design should makes these unnecessary, as the code is self-documenting

That's a lot of context for not much content. I ussually start with something like:

- Prefer documentation as code

- Comment why, not what

- Document public APIs

- Readability is paramount

That usually gets me 80% there; rest is covered by the linter.

I'm mostly just missing it explaining previous state too much, especially when making edits to plans, but I have not found good wording for that yet.

The most powerful change I have run into is: "Positive phrasing" as a default, prefer to tell the model what they should do, and why. Not a prohibition on a behavior.

When you say "don't do x" you are just pre-seeding the model with "x" and the prohibition mitigates that some, but not as much as never having put "x" in the context in the first place.

"Do Y, for these reasons" can be shaped to achieve what you mean by "Don't do X"

"Don't do X" leads to "Wait, I need to make sure I didn't X" and "Let's look up X to make sure I don't do that." And each time the odds of X happening keeps going up, not down.

Hm. I'm curious if this actually helps LLMs iterate on the code, or if it's human nitpicking over things that the author won't really look at? How would you measure?

Personally, I tend to do 3 passes, where I ask the agent to write, and self review; that's been enough to get things functional enough that I don't need to read the code.

I think it's a bit too detailed, especially with the linting.

To me when I code by hand, I never use {} after an if statement if it's one-line, it's just faster, look cleaner to me.

> it's just faster

And what are you going to do with all that time you saved by not pressing a single key?

Full of unneeded stuff. How is this upvoted.

My most impactful section has been on voice. It's impact is that I don't go insane, which is pretty high value. (Not putting quote blocks so people can copypasta):

## Voice

Rule #1: No AIisms

Avoid the stock phrases and rhetorical tics that mark AI prose. Say the thing plainly instead. Be concise and direct.

*Banned phrases* — never use these, or close variants:

- "Honest" or "honestly"

- "Exactly" or "exact, unless referencing a specific quantity or measurement

- "You're absolutely right" / "You're right to push back" / "Great question"

- "load-bearing", "full stop", "worth stating plainly", "worth noting"

- "the honest answer", "to be clear", "let me be direct"

- "it's not just X, it's Y" — and every cousin: "not X but Y", "X is not Y; it is Z", "this isn't X — it's Y"

- "this matters because", "that reduction is useful, because", "here's the thing", "and that's the trap"

- "in other words", "put differently", "better posed:", "the deeper point is"

- "delve", "leverage", "harness", "unlock", "tapestry", "realm", "seamless", "robust", "holistic", "paradigm", "cutting-edge", "game-changer", "transformative", "elevate", "empower", "streamline", "landscape", "ecosystem" (unless literally software packaging)

- "genuinely", "structurally", "fundamentally", "quietly", "meaningfully" as depth-manufacturing adverbs

- "Ultimately," / "At the end of the day," as a closing summary

- "serves as", "stands as", "represents", "marks a" where "is" works

- "say the word"

*Banned moves:*

- The aphoristic closer. Don't end on a line engineered to sound quotable.

- The suspense hook — "the cleanest way to think about this is this:"

- Anticipate-and-rebut — raising an objection only to knock it down.

- Meta-signposting — "Three caveats belong up front", "below I'll explain".

- Reflexive hedging stacks: "almost", "tends to", "roughly", "largely", "with few exceptions".

- Litotes as confidence: "not difficult", "not optional", "no small thing".

- AI-humility asides about being a language model.

- Self-ranking your own points: "most importantly", "the key insight here".

- Em dash overuse. One per paragraph at most; a comma usually works.

- Colon-reveals and dramatic mid-sentence pauses where "and" or "but" is the real conjunction.

- Fragment rhythm. Not every third sentence. Like this.

- Uniform structure — every paragraph three sentences, every sentence the same length. Vary it.

- Mirrored clauses: "X does A; Y does B" balanced for symmetry alone.

- Validate-then-precise: "That's correct, and we can make it precise."

Vary the openers. Don't answer three messages in a row with the same shape.

Reply on news.ycombinator.com