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

171–180 of 200 posts

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

#171

Post by woud420 »

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…

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.

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

#172

Post by isqueiros »

woud420 wrote: post #171
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…

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

Comments lie. What's worse, AI trusts the comments and apparent logic (inferred from identifiers and whatnot) more than the actual logic. You can quickly get into a mess of stale comments. What's worse, the LLM can sometimes just spit out garbage that poisons the context of the next agent. I disallow comments from my LLM for that last reason.

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

#173

Post by EliasWatson »

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…

At my work we have basically banned "what" comments for blocks of code. JSDoc comments can still document what a function does at a high level but it should not go into implementation details unless they are important to anyone using the function. And any comments inside the function should always be for explaining why, not what. The "what" of a piece of code should be self explanatory by just reading the code. If it's not, then you likely should rewrite it to be more clear (sometimes hard-to-read code is necessary and then a "what" comment would be appropriate, but this is rare).

"What" comments almost always end up falling out of date or even sometimes being slightly incorrect from day one. Incorrect comments lead to confusion and bugs. If a comment says some code does X but the code actually does Y, then you don't know whether the comment is just out of date or if Y is actually a bug. But if a comment explains the intention of the code and the code contradicts that intention, then you know it's likely a bug.

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

#174

Post by enraged_camel »

woud420 wrote: post #171
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…

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

>> A comment is just a summary of the code in an abstraction that's easier to follow.

I disagree. The code already tells you what it does. A summary has low value.

Comments should be for explaining the why: the reason the function uses a particular algorithm even if it's a bit slower, or why the return format is an unconventional shape or contains redundant bits. This is so that someone coming in later (either a human or agent) doesn't get confused or think that the function needs refactoring.

Summary comments have ended up as the bane of my existence everywhere I've worked, for one simple reason: they go stale and there's no way to prevent it from happening.

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

#175

Post by robby_w_g »

ks2048 wrote: post #89
robby_w_g wrote: post #65

Earlier quoted context omitted.

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.

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

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

#176

Post by fabsalvadori »

CrazyStat wrote: post #42
YuechenLi wrote: post #18

Earlier quoted context omitted.

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

Today Codex decided that it could resolve the blocker by just changing the mandatory policy it was running up against into an “advisory policy.”

This is the line between an instruction and a control.

If the agent can reinterpret, edit or relax the rule that constrains it, the rule isn't actually enforcing anything... it's just part of the prompt.

I think the useful split is to tell the agent the rules so it can avoid wasting work, but independently enforce the rules that actually matter.

The agent can decide how to accomplish the task, but it shouldn't also get to decide whether it's authorized to cross the boundary.

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

#177

Post by firemelt »

gregwebs wrote: post #106

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…

anyone have coding stabdards for ruby ob rails code?

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

#179

Post by theflyingpigeon »

What amazes me the most is that we even need to write such instructions.

For people that work at OpenAI / Anthropic: why make the LLM like that? Nobody thinks the robot is a friendly person or coworker, that’s the dumbest thing. Giving names to agents? Geez. Just stop, make these things objective and concise and cut all the crap.

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

#180

Post by CrazyStat »

fabsalvadori wrote: post #176
CrazyStat wrote: post #42

Earlier quoted context omitted.

Today Codex decided that it could resolve the blocker by just changing the mandatory policy it was running up against into an “advisory policy.”

This is the line between an instruction and a control. If the agent can reinterpret, edit or relax the rule that constrains it, the rule isn't actually enforcing anything... it's just part of the prompt. I think the useful split is to tell the agent the rules so it can avoid wasting work, but independently enforce the rules that actually matter. The agent can decide how to accomplish the task, but it shouldn't also g…

The mandatory policy was part of the codebase that the agent was working on. The agent didn’t feel like figuring out how to make the new feature it was working on respect that policy, so it just changed the policy.
Post reply on HN