Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

My agent.md to improve LLM-assisted code quality

fabiensanglard.net

Post reply on HN
Print view View original

161–170 of 200 posts

Re: My agent.md to improve LLM-assisted code quality

#161

Post by bartread »

OptionOfT wrote: post #3

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 drawin…

> Then this one really is a pattern that creates a lot of churn:

> - Add a small, to the point, comment...

As if you even need to tell Claude to add comments. Over the past few weeks I've noticed Claude over-commenting everything. Massive PRs where you realise that fully half or more of the lines that have changed are comments.

It's no good at all: it just pollutes the context, causes token churn, ablates quality, and makes getting to a high quality outcome considerably slower and more expensive.

I get that sometimes knowing why a thing is the way it is can be useful and valuable, but this is what commit comments are for in my mind.

I've had to tell Claude to stop commenting code because the behaviour has become so problematic.

> The what _is_ the code.

Exactly.

If I don't know what the code does because it's arcane and not commented I can simply ask the LLM to explain it to me. I don't need an essay in comment form.

Re: My agent.md to improve LLM-assisted code quality

#162

Post by ghtbircshotbe »

Supermancho wrote: post #57

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 e…

One thing I've figured out of that qwen3.6 35b refuses to use 2 space indentation for python code, although it claims to be doing it. I know for a fact it is an easy thing to do.

Re: My agent.md to improve LLM-assisted code quality

#163

Post by arw0n »

solatic wrote: post #131
hawk_ wrote: post #38

Earlier quoted context omitted.

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.

> 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 experi…

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.

Re: My agent.md to improve LLM-assisted code quality

#165

Post by lucideer »

OptionOfT wrote: post #3

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 drawin…

This.

We've been using agents heavily for all code for a long time now in my company - everyone has comprehensive & opinionated AGENTS.md customisations & they're widely shared & discussed. Almost everything in this post seems incredibly naive day-one LLM user mistakes - especially everything related to coding style at line level granularity.

We've had non-LLM tooling for these kinds of standards for many years now & the great thing about agents is they're already versed in said tooling. If you haven't got a decent lint setup, ask your agent to set one up. It'll give you much better guarantees than this slop which is just going to drift from model to model & is completely unverifiable.

Re: My agent.md to improve LLM-assisted code quality

#166

Post by farlight »

what wrote: post #119
arialdomartini wrote: post #40

Earlier quoted context omitted.

Incidentally, I'm from the opposite school and consider every “if” followed by a braced block a smell. If a conditional body needs a block, it's doing enough to deserve a name, so I promote it to a single named call, à la "Extract till you drop".

So you’ll make a two line function to replace a braced block? Seems kind of unhinged.

The "Uncle Bob" school of thought follows this pattern. Look at his projects, I personally find them unreadable.

https://github.com/unclebob/fitnesse

Re: My agent.md to improve LLM-assisted code quality

#167

Post by andreareina »

OptionOfT wrote: post #3

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 drawin…

# save the request headers for later because we don't yet know which one we'll need

Re: My agent.md to improve LLM-assisted code quality

#170

Post by benregenspan »

bombcar wrote: post #94
throwatdem12311 wrote: post #61

Earlier quoted context omitted.

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.
Post reply on HN