Rendered at 21:00:52 GMT+0000 (Coordinated Universal Time) with Cloudflare Workers.
OptionOfT 1 days ago [-]
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.
hawk_ 23 hours ago [-]
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.
robby_w_g 21 hours ago [-]
How do you stop LLMs from making comments? In my experience, LLMs treat requirements for code output as suggestions
ks2048 19 hours ago [-]
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.
Infernal 17 hours ago [-]
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.
manwe150 4 hours ago [-]
I don’t get that argument. Most of the time by the end of the session the comments from the agent encode tricky details that I told the agent to write down so it stops making “simplifying” assumptions. Thus comments at the end of a couple days of agent-only coding, when I start to actually read and edit the prose, contain the details which aren’t possible to know from reading the local code. It may help that my last couple sessions before I start reading the code myself are variations on telling the agent to self-review and improve the comments in specific ways, so the comments left are only those the agent thought remain meaningful at clarifying unexpected interactions between the local code and other code that needs to be referenced to understand it.
robby_w_g 6 hours ago [-]
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
miki_oomiri 21 hours ago [-]
Ask the agent to write a script to run after each changes, against the newly added code.
Use that script as a super linter.
That’s the only way I found to strictly enforce some rules, like the no comments rule, without enforcing them against my own changes or old code.
eru 16 hours ago [-]
You could run the script mechanically against the diff (assuming you use version control). No need to rely on the agent.
embedding-shape 14 hours ago [-]
Add "Don't add any code comments anywhere" to your system prompt.
If the model doesn't follow this, you want to start using a better model ASAP, because SOTA models for the last year or so, been able to following this without an issue.
yehoshuapw 13 hours ago [-]
I've come recently across arxiv 2604.20911
which claims "do" rules persist much better then "don't" rules.
embedding-shape 13 hours ago [-]
Alright, what you'd put instead of "Don't add any code comments anywhere"?
I agree with the general guidance, but it's a general one and not applicable for everything. Some things cannot be expressed in a "do" way rather than "don't".
yehoshuapw 13 hours ago [-]
I don't know. I fully agree, and never did really try out this in depth yet.
I suspect rules with negations are not the same as don't rules, but unknown if really true, if so:
"when writing code do not add comments, code should not need it" may work
embedding-shape 13 hours ago [-]
Your proposal is still a "Prohibition-type constraint" that the paper you linked earlier say "isn't good".
Some of these constraints we want simply aren't possible without adding "do not" somewhere in the line, even if you prefix/suffix it with other stuff, as you noticed yourself :)
wongarsu 9 hours ago [-]
I don't think changing "don't" to "do not" is what the paper authors had in mind
I use things like "Your code should be self-documenting, so as to require as few comments as possible. Add comments to explain "why" or give important context not apparent from the code itself, but keep them to necessary comments only"
But that's a much laxer rule. I don't think you can truly express "no comments, ever" without a "don't" rule.
sandos 12 hours ago [-]
Do add only code free from any comments.
gozucito 5 hours ago [-]
"Do write comment-less code" ?
21 hours ago [-]
nicky0 5 hours ago [-]
In my experience, Claude adds loads of comments, but Codex (GPT-5.5) never adds any.
solatic 14 hours ago [-]
> 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.
arw0n 9 hours ago [-]
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.
metek 14 hours ago [-]
LLM comments for code are almost unfailingly completely redundant or impenetrably verbose bordering on word salad.
jodleif 13 hours ago [-]
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.
shunia_huang 13 hours ago [-]
Sometimes I try to add comments in a new session and the agent just don't have enough context for it to give a comprehensive sentence with full context on the why, then the agent will just describe what it does.
Human comment is in another level to answer the questions mainly like "why do it like this" for the later collaborators or the forget-ed self, so the important blocks live when it is needed and can be eliminated when it does not.
dolmen 11 hours ago [-]
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.
digitalPhonix 13 hours ago [-]
I think “This way the code stays readable/debuggable by humans” is a proof by example (not that the generated comments are necessarily bad).
If the human can read/understand it well enough to comment it, then it is readable by humans.
watwut 12 hours ago [-]
> If the human can read/understand it well enough to comment it, then it is readable by humans.
No, because the one who is writing the comment has context later reader dont. The writer knows what the requirements are, what he was trying to achieve and what he struggled to comprehend. Writer also presumably spent more time trying to understand it then the person coming later should.
Lutger 10 hours ago [-]
It is not perfect, but the delta between 'cannot understand what agent wrote' and 'it makes sense to me right now' is already an improvement. That it may not be sufficient, doesn't mean it isn't a necessary condition.
Besides, it has always been like this. I sometimes can't even understand some of the things I wrote myself a couple of months ago, because I forgot the context. Good comments and documentation will help you re-acquire the context you need, not completely eliminate it.
watwut 13 hours ago [-]
Misleading and hard to read comments are worst then none at all for readability. If he did what you suggest, he would end up with tons of bad javadoc.
lkjdsklf 21 hours ago [-]
That seems like a really smart workflow
I wish my coworkers would adopt this.
I’m sick of reading a fucking Charles dickens novel for every fucking tiny function
jamesfinlayson 15 hours ago [-]
Ugh, this. Had a workmate recently churn out 4,000 lines of code using Claude and I'm sure half of it was just comments.
Mtinie 20 hours ago [-]
[flagged]
imagetic 16 hours ago [-]
Mad props to you for that. Smart.
getnormality 1 days ago [-]
I would never tell an agent to write "what does the code do" comments. Their default comments are already way too fluffy.
saghm 22 hours ago [-]
But then you don't know about where the load bearing seams are!
JSR_FDED 17 hours ago [-]
Honestly? That’s the kicker.
telotortium 20 hours ago [-]
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.
sampullman 16 hours ago [-]
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.
throwatdem12311 21 hours ago [-]
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.
bombcar 19 hours ago [-]
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.
benregenspan 7 hours ago [-]
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.
embedding-shape 14 hours ago [-]
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?
rustystump 24 hours ago [-]
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.
danielheath 23 hours ago [-]
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
“””
24 hours ago [-]
figmert 23 hours ago [-]
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.
jaggederest 22 hours ago [-]
The best way I've found to solve this is using LLM as CI - use a small cheap model to inspect the diff and look for those kinds of comments. Prompt left to the observer but using `claude -p` / `codex exec` gets you a lot cleaner output usually, and makes robots fight robots instead of you constantly having to reprompt and it ignoring you.
5thaccount 21 hours ago [-]
I've reached that point as well. Is there a preferred model and prompt you use for that?
jaggederest 15 hours ago [-]
[flagged]
culi 23 hours ago [-]
My biggest pet peeve with agents is when people beg their (non-deterministic) agents to do something that a lint rule could've accomplished
irishcoffee 23 hours ago [-]
Seems like 80% of agent use boils down to: grep | sed -i
Which is kind of cool if you’re unaware enough to know to do it yourself.
Oh, and find. Agents use find a lot.
eterm 22 hours ago [-]
So it turns out that a lot of these unix utilities have such bad UX that having a tool that knows how to really leverage them feels like a superpower.
If you've ever used an LLM to deal with ffmpeg you'll know exactly what I mean.
drfloyd51 20 hours ago [-]
It is incredibly difficult to make an UX that can beat simply typing what you need in your own words.
You think of what you need, and you type it. No need to even ask “what options should I use?”
skydhash 20 hours ago [-]
I would rather bet that people don’t know that their problem has been solved for ages. Either they don’t know about the tools or can’t make the leap to think of using something like awk or sed to quickly script out their use cases. Or even quickly draft up a quick function/plugin in something like vim, emacs, sublime,…
In “The Pragmatic Programmer”, the power of unix tools and editor fluency is well argued. There are plenty of other books like “Unix Power Tools”, “Small, Sharp Software Tools”,…
selcuka 21 hours ago [-]
Pi even installs ripgrep and fd if it can't find them in the path.
telotortium 19 hours ago [-]
It turns out that thinking about and executing these commands at a superhuman speed is, to ape Claude, the real unlock.
mpyne 17 hours ago [-]
Yeah, I've actually found in my own testing and usage of LLMs that this is where I get a lot of benefit. I already have fd, ripgrep, etc. installed and know how to use them, but it's not hard to tell the LLM to do it and it often finds things just as well. Or even better.
It's especially handy on modern style code where things get broken up across a multitude of files based on convention.
woud420 7 hours ago [-]
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.
isqueiros 7 hours ago [-]
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.
woud420 3 hours ago [-]
Code can "lie" too.
```auto a = 65535 + 1``` will give you a different answer depending on the architecture. You can then decide.. oh don't use auto or don't use c++ or whatever and have standards... like the standard you set for yourself "disallow comments from my LLM".
enraged_camel 6 hours ago [-]
>> 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.
woud420 3 hours ago [-]
That's your experience and it's valid. For me documentation AND comments have been useful on occasion.
The core thing that I agree with is that comments (or docs) can get stale and not follow what is actually being executed. The way I work with it is by being structured, consistent and follow standards. Unfortunately for me, not all developers follow the same guidelines.
EliasWatson 7 hours ago [-]
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.
tyre 22 hours ago [-]
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.
duttish 15 hours ago [-]
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.
DenisM 5 hours ago [-]
> 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.
duttish 2 hours ago [-]
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...
embedding-shape 15 hours ago [-]
> expecting great code from the agents
Yeah, I'm not sure what people are thinking. I keep reading stuff from folks like "I wish models had more common sense" and "I wish they wrote better code", not realizing this is 100% in your own hands, always been. There is no such thing as "clean code" that every programmer agrees on, you have your own subjective opinion and "good" taste about the code, instruct the models to follow it! And automate it while you're on it.
arialdomartini 23 hours ago [-]
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".
AdieuToLogic 21 hours ago [-]
Another phrase for this is "functional decomposition", which usually is a good thing.
Better yet is to identify conditional execution paths as early as possible in order to obviate conditionals in the call tree. For example, identifying a "create a new something" verses an "update an existing something" based on the workflow initially invoked greatly simplifies service and/or persistent store logic.
what 15 hours ago [-]
So you’ll make a two line function to replace a braced block? Seems kind of unhinged.
farlight 8 hours ago [-]
The "Uncle Bob" school of thought follows this pattern. Look at his projects, I personally find them unreadable.
It may happen. I guess you agree that most of the times conditional blocks exist they are more than 2 lines.
bartread 9 hours ago [-]
> 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.
0xfeba 23 hours ago [-]
> Propose ASCII drawings to explain complete systems.
Labs have now long understood that ASCII drawing is a core skill needed for coding agents. However, I would not trust them understanding what an existing drawing means, unless it has generated itself.
throwuxiytayq 19 hours ago [-]
[dead]
throwatdem12311 21 hours ago [-]
Linters and static analysis -> setup as hooks in your harness. Don’t rely on CLAUDE.md because it’ll ignore it a lot.
> ASCII drawings in code
Please don’t this is super obnoxious. Make proper diagrams and kee them in knowledge base. Link out to them if you need to and let the agent fetch them via MCP or API or whatever if it wants them.
vunderba 18 hours ago [-]
> A bunch of these should be enforce with linting
Agreed. One of the first rules I toss into Biome is `noNestedTernary` - LLMs seem to adore completely unreadable nested expressions.
libertas_quae_s 10 hours ago [-]
This! I also saw lot of potential work that could be done by linting tools. Remember to always prefer mechanical guards than agent instructions, as they cannot ignore them.
andreareina 7 hours ago [-]
# save the request headers for later because we don't yet know which one we'll need
16 hours ago [-]
lucideer 8 hours ago [-]
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.
skydhash 20 hours ago [-]
> 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.
_boffin_ 23 hours ago [-]
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.
IanCal 19 hours ago [-]
Do both. Instructions help avoid the first pass from making the same mistakes.
> Make an agent operate within defined constraints and yell at it when it doesn’t.
And tell it what the constraints are.
_boffin_ 15 hours ago [-]
[flagged]
andai 19 hours ago [-]
> - Keep function names short. Less than 30 characters.
Recently I asked GPT to port a browser game to Rust. It voluntered this gem:
They laughed at objective-c back then, now the shoe's on the other foot
egorfine 13 hours ago [-]
So much this. DoThisWithThatAndThatAndThis is a objective c convention and I love it so much that I use it everywhere.
Although a bit of taste is required to keep code legible and pleasant.
BrunoBernardino 15 hours ago [-]
I like long function names as long as they're still explanatory and not distracting.
swiftcoder 13 hours ago [-]
This is an unfortunate side effect of bridging an API from a language that supports function overloading, into a language that does not
YuechenLi 1 days ago [-]
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.
lelanthran 1 days ago [-]
> 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?
YuechenLi 24 hours ago [-]
"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.
CrazyStat 22 hours ago [-]
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.
CrazyStat 5 hours ago [-]
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.
chrisweekly 23 hours ago [-]
"honest", "real", "genuine" -- wat.
maccard 23 hours ago [-]
How often would you say step C happens and the agent stops when it can’t proceed?
YuechenLi 22 hours ago [-]
Not very often, but when it happens, usually it's time to sit down and brainstorm architecture with the LLM to figure out how to proceed next instead of looping blindly.
gregwebs 17 hours ago [-]
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.
anyone have coding stabdards for ruby ob rails code?
getnormality 1 days ago [-]
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.
Sammi 22 hours ago [-]
Yes, the interesting part about seeing other people's agent.md files, is getting to see what issues they have with working with agents. Seems different people run into very different issues, which probably is caused by how differently we work. So a the file probably should be personalised.
pianopatrick 20 hours ago [-]
Might also be per model. Different models might have different issues and require different instructions
Supermancho 22 hours ago [-]
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.
ghtbircshotbe 9 hours ago [-]
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.
oumua_don17 1 days ago [-]
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.
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
wpasc 1 days ago [-]
idk who came up with it first, but ASD-STE100 has been floating around more since matt pocock put it in one of his skills
mattjoyce 24 hours ago [-]
This will produce quite verbose prose. STE100 is good for specs and explanations but it works best with a glossary or terms. will burn tokens.
hartleybrody 5 hours ago [-]
This has not been my experience at all. I have been using this skill[0] for several weeks and when I ask it to rewrite existing AI slop docstrings to use this convention they are nearly always 10-20% smaller, plus easier to read and mostly free from the traditional "tells" of AI writing.
Do you give the model access to the ASD-STE100 spec for reference/review or are you just assuming that enough of it is baked into the model for it to mostly adhere to it?
statenjason 21 hours ago [-]
Agreed. ASD-STE100 makes automated code reviews tolerable.
sha-3 15 hours ago [-]
If we alter the way LLMs talk, will it noticeably affect the quality of code it produces?
newsomix9xl 24 hours ago [-]
A great piece.
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.
zbentley 21 hours ago [-]
> As much as possible try to minimize the number of changed lines when implementing a feature
Great way to get LLMs to start making an endless profusion of methods instead of adding parameters to or switching to a richer return type from an existing method, in my experience.
I’m tired of seeing “get_total_rounded_up” + “get_total_float” bloat when a few changes to unrelated code to round floats to ints would keep the method API surface small.
20 hours ago [-]
no-name-here 13 hours ago [-]
I find too often that models do the opposite - they'll pile small targeted band-aids on code blocks based on new requirements, etc, when having them analyze whether a changed (broader) design would result in a far better overall design?
bityard 20 hours ago [-]
An earlier version of Gemini used to do this a lot to me back when I used it for some light tinkering around on my projects. "Oh by the way, I fixed a misspelling in a comment file completely unrelated to the feature you asked for, so I fixed that as well, shall I commit everything now?" GAHHH. NO.
These days I have an instruction in my default AGENTS.md to bring issues unrelated to the prompt to my attention when found, but never to just automatically fix them.
meerita 22 hours ago [-]
This approach never worked for me. Explanation here:
But in summary: the more bloated your AGENTS.md is, the worse the context consumption gets. The best approach I use is telling the agent to first think about what it needs to do, then choose which rules apply. I got 100% consistency across every area of my projects.
Identifiers and UUIDv7 .agents/rules/18-identifiers-and-uuidv7.md
Thanks for sharing this approach, I'll give it a shot in my mono repo project.
meerita 21 hours ago [-]
I cannot recall why the 17 is missing. Maybe was some internal specific of the projects.
Geee 1 days ago [-]
I feel like claude.md is like Asimov's laws of robotics. Whatever you write there ends up eventually messing up everything.
jdiff 23 hours ago [-]
Anything that goes into the context window has that going for it. That's a huge part of why Claude's gone absolutely bonkers with genuine, brutal honesty. The system prompt's absolutely stuffed full of those keywords, so now every single output is tainted with that right from the start.
jurf 14 hours ago [-]
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.
nikitau 13 hours ago [-]
I'm also doing something similar, as for over-explaining state and momentary decisions, I have yet to find good wording for it too. I had a bit of success by running a reviewer at the end to look over comments and docstrings and judge if it is "evergreen", but feels a bit like a rain-dance.
dzhar11 23 hours ago [-]
From FAB's AGENT.MD:
> - Avoid magic numbers and strings by extracting recurring or meaningful values into descriptive constants (const) or enums.
---
I've been seeing the same thing with models like GPT5.6 and Opus4.8 in GH Cop CLI. They still introduce magic numbers, and in Scala they often put an entire 10-line Spark expression inside an if condition instead of extracting it into a meaningfully named value to keep "if" readable. I wonder when common sense instructions will be baked into the models.
vatsachak 22 hours ago [-]
What's the point of agents.md if you just use an LLM on a codebase?
Just say, complete this bit like how the rest is...
Even then they aren't great at it. Idk, the best case use for LLMs are extremely specific requests, for example "write an evaluator for this byte code and if you can't ask for clarification"
The ultimate specification language is code anyways so you might as well stick a to-do, a comment describing the semantics of the function and say "okay codex fill the to-do"
sejje 22 hours ago [-]
I have it pull out some guidelines by doing an analysis. Then I modify the result where I disagree.
It's much easier to follow the rules than it is to compute the rules on the fly all the time.
fergie 14 hours ago [-]
Would there be any disadvantage to simply having all of the code style stuff in a CONTRIBUTING.md file and the "how to talk to me" stuff in an AGENTS.md file, since code style stuff also applies to human contributions? Similarly, isn't the "how to talk to me" stuff personal and therefore not something that belongs in a repo?
GuB-42 4 hours ago [-]
Has anyone had success telling a LLM to essentially code golf, with the compromise that names should still be descriptive (so no hard minification).
The idea is to first make the code less verbose, LLMs tend to do that. But the other idea is to save tokens. I.e. make it easy for the LLM, not for a human reader.
And when it is time for a human to actually read the code, if it is too much, as a second pass, transform the code to make it more readable while keeping the structure.
afro88 5 hours ago [-]
> Give me the cold hard truth.
Does this actually work to get better answers, or does it now just say "the cold hard truth" instead of "the honest take"
imjonse 15 hours ago [-]
"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.
austin-cheney 13 hours ago [-]
There is an annoying phenomenon with LLMs called "context dilution" or "attention dilution" that was outlined in the Lost in the Middle paper. As the context grows, a model starts paying less attention to instructions in the middle of the context in favor of what is at the beginning and the end.
So then what happens if the agents.md file is colossal and precise and all the required execution instructions are buried in the middle? Do the agents then just fail to execute?
lhk931122 13 hours ago [-]
Yeah. That's why people these days avoid long descriptions and instead keep things as short as possible. in my experience, it seems like LLM can't recognize (or less attention value) unless it's structured in a deductive or inductive way
tajd 9 hours ago [-]
the author referenced this paper which I thought was really interesting https://arxiv.org/abs/2307.03172 - "Lost in the Middle" - are there any other papers a bit like this that summarise lessons to do with applying llms
I'm not necessarily looking for the latest and greatest - more papers that those in the community have coalesced around providing nice ways of summarising problems or as a good example of a specific area.
carlsborg 5 hours ago [-]
For Claude Code you can maybe save context by putting the commit message formatting in a skill, so only the front matter goes into context at startup and the details only when the skill fires.
impulser_ 21 hours ago [-]
I disagree with the less than 30 characters.
Im against restricting anything related to code length this goes for function names and length, file length ect.
I rather the dots be as close as possible than trust the agent connects the dots.
I dont care if the file is 5000 lines I rather the agent reads one file and get all the context than trust it will read all the need files.
I see so many review skills that puts hard limits on these thing and it just bad.
The function name shouldn't be limited they should be as clear as possible and if for some reason it over 30 chars so be it.
I want to read the function name and the logic and it match exactly. I don't want the agent being lazy because of some limit I set.
In fact I force my agents to write long functions because I specifically tell it not to break out repeated code that doesn't actually deserve a function.
A check on a function input doesn't need to be a function. A auth guard doesn't need to be it own function.
types.go types.ts absolutely the worst file to see in any code base. Put the type next to the code that uses it.
ttoinou 21 hours ago [-]
When it's instructions for agents it's not really "hard" limits, the agents can go more or less
jatins 11 hours ago [-]
My problem with latest models is that you can’t tell them anything or they’ll treat it as gospel and over do it
For example this says
> Reduce code indentation. Avoid Arrow Anti-Pattern. Leverage early return and continue.
You can bet sol is going bend over backward to reduce indentation now and write non idiomatic code
eschaton 23 hours ago [-]
I didn’t see anything in there instructing the LLM not to generate text about goblins.
doginasuit 20 hours ago [-]
I could understand "prefer enums to booleans" but "use enums instead of booleans" is a weird choice.
Then again, with the LLM capacity for nuance it would be the same thing.
a2ff6eeb0 16 hours ago [-]
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.
8cvor6j844qw_d6 21 hours ago [-]
Some of these are generic software engineering advice.
I noticed modern frontier models (e.g., Fable/Opus/Sol) need less procedural coaching than earlier models.
Are they sure it improves code quality?
jvwww 17 hours ago [-]
Some of these such as "Always use {}, even on a one-line "if" statement." should just be lint rules.
moktonar 13 hours ago [-]
The comments problem is a big one and no matter how hard I try the LLM will always write them verbosely. I find that including the rules in each prompt is fare more effective than once in the context
Luker88 1 days ago [-]
I had good results with making it add a few lines with a summary of RFC 2119/8147 keywords (SHALL/MUST...), and then using those, uppercase.
local llm remain more in line like that.
theturtletalks 21 hours ago [-]
I used to be big into agents.md files but read the latest SOTA doesn’t need them anymore. Have people still been getting value out of them?
fitsumbelay 15 hours ago [-]
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.
1saadcodes 19 hours ago [-]
I really like that you put architectural context in there, specifically the "why" behind certain decisions
Can't wait to modify my agent.md file and then forget about it until it becomes useless again
selcuka 21 hours ago [-]
The article refers to it as AGENT.md, but the standard name is AGENTS.md (plural).
dat999zx 18 hours ago [-]
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.
tomr75 23 hours ago [-]
I think this is dated. I wonder if the author has tried codex/other harnesses
theflyingpigeon 5 hours ago [-]
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.
chr15m 21 hours ago [-]
> Explicitly ask the harness to reload agent.md. "Reload agent.md" is enough when I see code quality dropping.
Having the LLM re-read the file is really silly and a common bug in harnesses. Even sillier is when the harness allows a file to be compressed away during summarisation. The harness should compose the context so this doesn't happen. Files should be "added" (by LLM or human) and then always be injected into context the same way forever. "Reload this file" is not something you should ever have to type.
FooBarWidget 1 days ago [-]
One tactic I’ve found helpful is multi pass quality improvement. First make it work. Then review for guidelines adherence. Loop until satisfied.
bellowsgulch 1 days ago [-]
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.
dan_ggggg 24 hours ago [-]
[flagged]
peter_d_sherman 5 hours ago [-]
These I especially like:
>"- Avoid superlatives and praise. Stop telling me I am absolutely right. Give me the cold hard truth."
>"Rule 5: Use the imperative mood in the subject line (e.g., "Fix bug," "Add feature," not "Fixed" or "Adds"). Test formula: It must complete the sentence: "If applied, this commit will [your subject line here]".
>"- Strictly adhere to the layered boundary hierarchy: each layer may only communicate with its immediate neighbor directly below it. Never "punch holes" through layers (e.g., controllers or UI components must never directly call database queries, raw hardware drivers, or low-level network clients; always route through the intermediate service/abstraction layer)"
Not crossing hierarchical/abstraction layers is very important for truly disciplined Software Engineering... at least in all Object-Oriented programming languages / languages that support Encapsulation, and possibly other languages/paradigms as well...
Anyway, lots of good things in this prompt!
thisismyopinion 14 hours ago [-]
Full of unneeded stuff. How is this upvoted.
dude250711 1 days ago [-]
It seems like everyone goes through a detailed AGENTS.md phase.
esafak 22 hours ago [-]
The problem is that linting AGENTS.md is risky. Everything added there was in response to mistakes. If I remove some instruction I run the risk of repeating the mistake.
18 hours ago [-]
jackskip22 14 hours ago [-]
I honestly think some of this stuff is wrong and constrains the models unnecessarily. Sometimes you're better off with simple adjectives and philosophical directions than getting so specific.
blamestross 20 hours ago [-]
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.
thomasnowhere 11 hours ago [-]
[dead]
semiinfinitely 15 hours ago [-]
> Use enums instead of booleans for function parameters
Agents.md are (and probably will continue to be) an ugly band-aid.
- new model comes out and a bunch of it becomes obsolete
- they get flat out ignored, esp. with larger context windows. The ai just responsds with, "your'e right I shouldn't have done that"
- they sometimes end up poisoning the reasoning because the rule gets interpreted in an unintended way.
acedTrex 1 days ago [-]
Agents.md is such a ridiculous concept, just write good contributing docs and then optionally @ the file in whatever agetn file you use.
That way everyone benefits.
svachalek 22 hours ago [-]
These days that sounds like a really good idea. 6 months ago, AGENTS.md would have contained a lot of instructions that would have been embarrassing to write out for a human audience.
FooBarWidget 1 days ago [-]
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.
anygivnthursday 1 days ago [-]
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.
formerly_proven 24 hours ago [-]
Symlinks exist, but it's kind of ridiculous all harnesses just ignore CONTRIBUTING, HACKING and friends.
acedTrex 1 days ago [-]
You put the @ in the context file the LLMs all use, claudemd agentsmd whatever the thing that most harnesses force load.
Then the model will go discover what it needs to.
latchkey 23 hours ago [-]
this was what i was doing 3-4 months ago. i just have AI write/update my agents.md file now as i find problems. i also have ai keep a set of design documentation that it can update as it goes too. oh and he should try omp+codex/xhigh, he will probably be less annoyed.
manganate06 4 hours ago [-]
[flagged]
reedlaw 7 hours ago [-]
[dead]
Linekiller89 7 hours ago [-]
[flagged]
styrum 9 hours ago [-]
[flagged]
JackCooper7 17 hours ago [-]
[dead]
fenestella 22 hours ago [-]
[flagged]
codelion 18 hours ago [-]
[flagged]
jing09928 19 hours ago [-]
[dead]
kevinbaiv 22 hours ago [-]
[flagged]
luciana1u 18 hours ago [-]
[dead]
sohaibqasem 23 hours ago [-]
[dead]
daralthus 13 hours ago [-]
[dead]
tyre 22 hours ago [-]
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"
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.
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 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
Use that script as a super linter.
That’s the only way I found to strictly enforce some rules, like the no comments rule, without enforcing them against my own changes or old code.
If the model doesn't follow this, you want to start using a better model ASAP, because SOTA models for the last year or so, been able to following this without an issue.
which claims "do" rules persist much better then "don't" rules.
I agree with the general guidance, but it's a general one and not applicable for everything. Some things cannot be expressed in a "do" way rather than "don't".
I suspect rules with negations are not the same as don't rules, but unknown if really true, if so:
"when writing code do not add comments, code should not need it" may work
Some of these constraints we want simply aren't possible without adding "do not" somewhere in the line, even if you prefix/suffix it with other stuff, as you noticed yourself :)
I use things like "Your code should be self-documenting, so as to require as few comments as possible. Add comments to explain "why" or give important context not apparent from the code itself, but keep them to necessary comments only"
But that's a much laxer rule. I don't think you can truly express "no comments, ever" without a "don't" rule.
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.
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.
Human comment is in another level to answer the questions mainly like "why do it like this" for the later collaborators or the forget-ed self, so the important blocks live when it is needed and can be eliminated when it does not.
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.
If the human can read/understand it well enough to comment it, then it is readable by humans.
No, because the one who is writing the comment has context later reader dont. The writer knows what the requirements are, what he was trying to achieve and what he struggled to comprehend. Writer also presumably spent more time trying to understand it then the person coming later should.
Besides, it has always been like this. I sometimes can't even understand some of the things I wrote myself a couple of months ago, because I forgot the context. Good comments and documentation will help you re-acquire the context you need, not completely eliminate it.
I wish my coworkers would adopt this.
I’m sick of reading a fucking Charles dickens novel for every fucking tiny function
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.
It’s almost the “we built a robot who loves to play Sonatas and gave it no hands” type of thing.
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.
“”” After you give up on trying to refactor this code, increment the following line accordingly. HOURS_WASTED_HERE=26 “””
Which is kind of cool if you’re unaware enough to know to do it yourself.
Oh, and find. Agents use find a lot.
If you've ever used an LLM to deal with ffmpeg you'll know exactly what I mean.
You think of what you need, and you type it. No need to even ask “what options should I use?”
In “The Pragmatic Programmer”, the power of unix tools and editor fluency is well argued. There are plenty of other books like “Unix Power Tools”, “Small, Sharp Software Tools”,…
It's especially handy on modern style code where things get broken up across a multitude of files based on convention.
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.
```auto a = 65535 + 1``` will give you a different answer depending on the architecture. You can then decide.. oh don't use auto or don't use c++ or whatever and have standards... like the standard you set for yourself "disallow comments from my LLM".
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.
The core thing that I agree with is that comments (or docs) can get stale and not follow what is actually being executed. The way I work with it is by being structured, consistent and follow standards. Unfortunately for me, not all developers follow the same guidelines.
"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.
> 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.
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.
But that's a pretty good idea, wonder if there is a way...
Yeah, I'm not sure what people are thinking. I keep reading stuff from folks like "I wish models had more common sense" and "I wish they wrote better code", not realizing this is 100% in your own hands, always been. There is no such thing as "clean code" that every programmer agrees on, you have your own subjective opinion and "good" taste about the code, instruct the models to follow it! And automate it while you're on it.
Better yet is to identify conditional execution paths as early as possible in order to obviate conditionals in the call tree. For example, identifying a "create a new something" verses an "update an existing something" based on the workflow initially invoked greatly simplifies service and/or persistent store logic.
https://github.com/unclebob/fitnesse
> - 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.
LLMs are very bad at ASCII drawings.
https://medium.com/data-science/why-llms-suck-at-ascii-art-a...
Labs have now long understood that ASCII drawing is a core skill needed for coding agents. However, I would not trust them understanding what an existing drawing means, unless it has generated itself.
> ASCII drawings in code
Please don’t this is super obnoxious. Make proper diagrams and kee them in knowledge base. Link out to them if you need to and let the agent fetch them via MCP or API or whatever if it wants them.
Agreed. One of the first rules I toss into Biome is `noNestedTernary` - LLMs seem to adore completely unreadable nested expressions.
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.
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.
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.
> Make an agent operate within defined constraints and yell at it when it doesn’t.
And tell it what the constraints are.
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...
Although a bit of taste is required to keep code legible and pleasant.
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?
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.
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...
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.
**Always use ASD-STE100 Simplified Technical English
Disclaimer: I saw this listed in some other HN post that I can' locate right away.
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:
-----------
[0]: https://github.com/AminBlg/SimpleEnglish
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.
Great way to get LLMs to start making an endless profusion of methods instead of adding parameters to or switching to a richer return type from an existing method, in my experience.
I’m tired of seeing “get_total_rounded_up” + “get_total_float” bloat when a few changes to unrelated code to round floats to ints would keep the method API surface small.
These days I have an instruction in my default AGENTS.md to bring issues unrelated to the prompt to my attention when found, but never to just automatically fix them.
- https://www.minid.net/2026/7/14/how-to-automatise-with-ai
But in summary: the more bloated your AGENTS.md is, the worse the context consumption gets. The best approach I use is telling the agent to first think about what it needs to do, then choose which rules apply. I got 100% consistency across every area of my projects.
In the post there's also a replica of one of projects rules I use, feel free to provide feedback: https://github.com/meerita/monorepo-nextjs-golang-rust-pytho...
Conditional logic .agents/rules/16-conditional-logic.md
Identifiers and UUIDv7 .agents/rules/18-identifiers-and-uuidv7.md
Thanks for sharing this approach, I'll give it a shot in my mono repo project.
- 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.
I've been seeing the same thing with models like GPT5.6 and Opus4.8 in GH Cop CLI. They still introduce magic numbers, and in Scala they often put an entire 10-line Spark expression inside an if condition instead of extracting it into a meaningfully named value to keep "if" readable. I wonder when common sense instructions will be baked into the models.
Just say, complete this bit like how the rest is...
Even then they aren't great at it. Idk, the best case use for LLMs are extremely specific requests, for example "write an evaluator for this byte code and if you can't ask for clarification"
The ultimate specification language is code anyways so you might as well stick a to-do, a comment describing the semantics of the function and say "okay codex fill the to-do"
It's much easier to follow the rules than it is to compute the rules on the fly all the time.
The idea is to first make the code less verbose, LLMs tend to do that. But the other idea is to save tokens. I.e. make it easy for the LLM, not for a human reader.
And when it is time for a human to actually read the code, if it is too much, as a second pass, transform the code to make it more readable while keeping the structure.
Does this actually work to get better answers, or does it now just say "the cold hard truth" instead of "the honest take"
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.
So then what happens if the agents.md file is colossal and precise and all the required execution instructions are buried in the middle? Do the agents then just fail to execute?
I'm not necessarily looking for the latest and greatest - more papers that those in the community have coalesced around providing nice ways of summarising problems or as a good example of a specific area.
Im against restricting anything related to code length this goes for function names and length, file length ect.
I rather the dots be as close as possible than trust the agent connects the dots.
I dont care if the file is 5000 lines I rather the agent reads one file and get all the context than trust it will read all the need files.
I see so many review skills that puts hard limits on these thing and it just bad.
The function name shouldn't be limited they should be as clear as possible and if for some reason it over 30 chars so be it.
I want to read the function name and the logic and it match exactly. I don't want the agent being lazy because of some limit I set.
In fact I force my agents to write long functions because I specifically tell it not to break out repeated code that doesn't actually deserve a function.
A check on a function input doesn't need to be a function. A auth guard doesn't need to be it own function.
types.go types.ts absolutely the worst file to see in any code base. Put the type next to the code that uses it.
For example this says > Reduce code indentation. Avoid Arrow Anti-Pattern. Leverage early return and continue.
You can bet sol is going bend over backward to reduce indentation now and write non idiomatic code
Then again, with the LLM capacity for nuance it would be the same thing.
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 noticed modern frontier models (e.g., Fable/Opus/Sol) need less procedural coaching than earlier models.
Are they sure it improves code quality?
local llm remain more in line like that.
Can't wait to modify my agent.md file and then forget about it until it becomes useless again
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.
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.
Having the LLM re-read the file is really silly and a common bug in harnesses. Even sillier is when the harness allows a file to be compressed away during summarisation. The harness should compose the context so this doesn't happen. Files should be "added" (by LLM or human) and then always be injected into context the same way forever. "Reload this file" is not something you should ever have to type.
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.
>"- Avoid superlatives and praise. Stop telling me I am absolutely right. Give me the cold hard truth."
>"Rule 5: Use the imperative mood in the subject line (e.g., "Fix bug," "Add feature," not "Fixed" or "Adds"). Test formula: It must complete the sentence: "If applied, this commit will [your subject line here]".
>"- Strictly adhere to the layered boundary hierarchy: each layer may only communicate with its immediate neighbor directly below it. Never "punch holes" through layers (e.g., controllers or UI components must never directly call database queries, raw hardware drivers, or low-level network clients; always route through the intermediate service/abstraction layer)"
Not crossing hierarchical/abstraction layers is very important for truly disciplined Software Engineering... at least in all Object-Oriented programming languages / languages that support Encapsulation, and possibly other languages/paradigms as well...
Anyway, lots of good things in this prompt!
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.
?????????
- new model comes out and a bunch of it becomes obsolete
- they get flat out ignored, esp. with larger context windows. The ai just responsds with, "your'e right I shouldn't have done that"
- they sometimes end up poisoning the reasoning because the rule gets interpreted in an unintended way.
That way everyone benefits.
Then the model will go discover what it needs to.
## 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.