Write code like a human will maintain it(unstack.io)
unstack.io
Write code like a human will maintain it
https://unstack.io/write-code-like-a-human-will-maintain-it
299 comments
My experience is the more things you add to the list, the worse agents perform (I'm not exactly the first person to notice this)
I actually have a pretty simple set of instructions right now and Claude still regularly messes them up. Like, my first instructions are:
Then it gets even more fun, because if I politely correct it in the session, it will understand, but then there's a decent chance it will be completely unable to commit anything in the session going forward. Phd level intelligence!
Anyway, my point is, if you're asking it to review a list of 200 items I guarantee it's quietly messing up on a lot of that list.
I actually have a pretty simple set of instructions right now and Claude still regularly messes them up. Like, my first instructions are:
- Never commit to git without permission.
- Never sign commit messages
Then it gets even more fun, because if I politely correct it in the session, it will understand, but then there's a decent chance it will be completely unable to commit anything in the session going forward. Phd level intelligence!
Anyway, my point is, if you're asking it to review a list of 200 items I guarantee it's quietly messing up on a lot of that list.
Sometimes the fact you mentioned “signing commit messages” is exactly why it starts signing commit messages, and it’s better to start with no prompt at all.
Negative prompting is very unreliable. Giving exact instructions on how you want commits made will give you better results.
Negative prompting is very unreliable. Giving exact instructions on how you want commits made will give you better results.
How am I supposed to take this tool seriously if it struggles with the concept of "dont"?
if what you're suggesting is true, then more important instructions like "Don't delete the production database" are a problem. I shouldn't need to consider how to phrase "Don't delete the production database" in a positive manner. Isn't the point of an AI agent that it understands my intent and I don't need to hold its hand? I'm not saying your suggestion is wrong, I just think that suggests a limit to what these tools should be used for if that's the case.
My guess though is that it probably ignores some of the positive instructions too, and the hardcore AI users mostly don't notice because they probably aren't reviewing the work.
if what you're suggesting is true, then more important instructions like "Don't delete the production database" are a problem. I shouldn't need to consider how to phrase "Don't delete the production database" in a positive manner. Isn't the point of an AI agent that it understands my intent and I don't need to hold its hand? I'm not saying your suggestion is wrong, I just think that suggests a limit to what these tools should be used for if that's the case.
My guess though is that it probably ignores some of the positive instructions too, and the hardcore AI users mostly don't notice because they probably aren't reviewing the work.
Absolutely. It should simply
not have permissions to delete your production database, can’t rely on prompting alone for that kind of safety.
These are still stochastic machines, guardrails must be inserted at the system level.
They are getting better every day about managing their own guardrails, so we will get there eventually.
These are still stochastic machines, guardrails must be inserted at the system level.
They are getting better every day about managing their own guardrails, so we will get there eventually.
I entirely agree, although I think this is counter to the narrative that we should just let the agent do everything that the labs want to sell.
There's a really major problem with the concept of human-in-the-loop though, which is just that humans are not built for that that kind of work. It's like all those tests against the TSA where they manage to sneak something through that should have been caught. But the problem is, a TSA agent sees probably like 1000 things they can ignore to the 1 thing they need to look at, and it's easy to just start rubber stamping things.
There's a really major problem with the concept of human-in-the-loop though, which is just that humans are not built for that that kind of work. It's like all those tests against the TSA where they manage to sneak something through that should have been caught. But the problem is, a TSA agent sees probably like 1000 things they can ignore to the 1 thing they need to look at, and it's easy to just start rubber stamping things.
If you're relying on asking the LLM "pwease don't delete" then you're already in trouble. This kind of stuff doesn't work with people either and they generally exhibit actual signs of intelligence.
Sure; it's an example, I would never rely "Please don't delete" for real important data. However, we're being sold an idea that we should just let the agent do everything, so I think it's important to point out how utterly insane that idea actually is.
My assumption is somewhere in the harness toolchain there's a prompt inject that says:
- Always sign commit messages
I do the opposite. I force LLM to "do jj new -m <desc>" after every logical batch of edits.
No signing is easy - make signing interactive and requiring a password.
Anyway, telling agent to NOT do something is always worse than telling agent to do something.
That's why you should say something like "Use constants instead of magic strings/numbers" rather than "Do not use magic strings/numbers".
Also whatever review its doing against the list of checks - must be a fresh context.
No signing is easy - make signing interactive and requiring a password.
Anyway, telling agent to NOT do something is always worse than telling agent to do something.
That's why you should say something like "Use constants instead of magic strings/numbers" rather than "Do not use magic strings/numbers".
Also whatever review its doing against the list of checks - must be a fresh context.
> Anyway, telling agent to NOT do something is always worse than telling agent to do something.
> That's why you should say something like "Use constants instead of magic strings/numbers" rather than "Do not use magic strings/numbers".
Pro tip: This is good guidance for communicating with humans as well. Don't just block people but give them a path forward. (But don't force them down that path, because people really hate feeling like their agency is being impinged.)
> That's why you should say something like "Use constants instead of magic strings/numbers" rather than "Do not use magic strings/numbers".
Pro tip: This is good guidance for communicating with humans as well. Don't just block people but give them a path forward. (But don't force them down that path, because people really hate feeling like their agency is being impinged.)
I personally find that models are trending towards ignoring any instructions given to them, so depend more on vendor-instilled behavior. Anecdotal, but I had bad experiences with OAI's new 5.6.
Same for me. Not sure if its intentional (do they want to push people towards workflows that will burn more tokens?) or if it's just a side effect, but it's very annoying. I refuse to use tools that dictate how I develop, I'm just going to switch models to less opinionated ones.
I let it have elevated permissions and it started doing some crazy things like figuring out I had zsh and running zshell commands instead of the common ones.
I have dedicated checkpoint and commit skills. Checkpoint has it run my review skill, then run my commit skill. The commit skill just asks it to suggest commit messages for my review. Having these skills in place has resulted in claude preferring to use the commit skill instead of committing on its own, and suggesting commit messages to me before actually doing the commit.
Why are you having it commit or write commit messages unless you have no idea what it’s doing?
Who likes writing commit messages? In the abstract, perfectly spherical developer mindset, I'd spend hours writing the best commit message to go with the most elegant and perfect, beautiful code that I'm comitting, but the real world with meetings and life demands is greasier and grimer than that. Letting the LLM start off with the commit messages for me to edit with additional details has been a boon to productivity. Staring at an empty $EDITOR my brain goes blank, but with a framework of what's going on, I find the details for me to add flow more easily.
I have commit signing enabled by default. I run my harness in a sandbox which doesn't have access to my signing key, and I always tell it not to commit. When it ignores me, the commit fails because it can't access the signing key... so the agent commits without signing. Tragic.
The commit signatures are a setting, you have to disable it in config
I’m not a Claude code user, is there really no way to get it to not commit to git other than “asking it nicely in a prompt”? I thought there was some sort of permission system?
There are options, but they're not great.
I could ban it from using git, but having access to git logs helps it do work so I don't want to go that far. I could probably ban the subcommand, but as a convenience I do like to be able to ask it to make a commit. (I'm not super attached to this, I frequently commit myself just to avoid these issues). It does tend to write good commit messages, so sometimes I ask it to generate the commit message and then just do the operation myself, which kind of sucks in the sense of feeling like reverse-centaur (Cory Doctorow term). (The reason I do that is sometimes it gets confused where if I greenlit one commit, it assumes all future commits are greenlit)
I guess the other option would be to not use "auto" mode, but god there's just no way I want to sit around and it "yes" 50x a session. I'd rather just sandbox it and nuke it if it does something too stupid.
I could ban it from using git, but having access to git logs helps it do work so I don't want to go that far. I could probably ban the subcommand, but as a convenience I do like to be able to ask it to make a commit. (I'm not super attached to this, I frequently commit myself just to avoid these issues). It does tend to write good commit messages, so sometimes I ask it to generate the commit message and then just do the operation myself, which kind of sucks in the sense of feeling like reverse-centaur (Cory Doctorow term). (The reason I do that is sometimes it gets confused where if I greenlit one commit, it assumes all future commits are greenlit)
I guess the other option would be to not use "auto" mode, but god there's just no way I want to sit around and it "yes" 50x a session. I'd rather just sandbox it and nuke it if it does something too stupid.
Deny:
Bash(“git * commit *”)
And for bonus points you can have the agent write you a Pre Bash hook. Tell it to make the hook look in the command for anything that’s a git commit. The vaguer your instructions here the better. Let it pull some crazy regex out of its hat. You’ll be impressed.
Bash(“git * commit *”)
And for bonus points you can have the agent write you a Pre Bash hook. Tell it to make the hook look in the command for anything that’s a git commit. The vaguer your instructions here the better. Let it pull some crazy regex out of its hat. You’ll be impressed.
Run it in a Docker container and give readonly access to the .git folder.
This way the agent can read git logs (this is very useful) but cannot commit directly (I don't see any value in this).
This way the agent can read git logs (this is very useful) but cannot commit directly (I don't see any value in this).
If I’m going to be responsible for the code that Claude writes on my behalf, I’m also going to take full responsibility for the moment that it is added to the project history, so I’m going to at least review every line before I allow that to happen.
The automatic coauthor line is also just a pet peeve. It’s a tool, not a person. I don’t say that a commit was coauthored by vim - why should Claude get special treatment?
The automatic coauthor line is also just a pet peeve. It’s a tool, not a person. I don’t say that a commit was coauthored by vim - why should Claude get special treatment?
In opencode you can get granular, allow `git log *`, deny `git add *` and `git commit *`
I never ran into it making commits before but when I tried Fable it made a bunch of commits signed by Claude, but then in the next prompt I just said "don't make commits anymore" and it was like "okay" and saved its own little md file and it hasn't happened sense.
I want to be clear that I'm not saying this to discredit the people saying they can't get claude to stop making its own commits, I'm just adding data to the "wow this is inconsistent" collection.
I want to be clear that I'm not saying this to discredit the people saying they can't get claude to stop making its own commits, I'm just adding data to the "wow this is inconsistent" collection.
> You know what it constantly does? Commits without permissions
You know what solves this? A deny rule. That’s right, you can solve it committing without permissions by.. not giving it permissions.
> it's quietly messing up on a lot of that list.
If only there was some way to know. But alas, code review won’t be invented until 50 years ago.
You know what solves this? A deny rule. That’s right, you can solve it committing without permissions by.. not giving it permissions.
> it's quietly messing up on a lot of that list.
If only there was some way to know. But alas, code review won’t be invented until 50 years ago.
>and then I ask it
Why? It has no idea why it does what it does…
Why? It has no idea why it does what it does…
Use hooks.
> Any time I notice something in code review and have to get the agent to fix it.. I throw it on the list! My list is like 200 items now.
This is a gripe I've had with AI tools for a while now. Though it's gotten somewhat better in time, but we don't really know what to expect from the tool in terms of quality. Ex. I'd expect a human engineer to probably not use a brand new assertion library for a new test when there are 200 tests using an existing one. But Claude has done this to me multiple times. So I have to add yet another item to the list, like you have, and tell it to look for testing conventions before writing. But, there is plenty we don't have to tell it, like what a function is or a test should probably cover the change in the diff. But we don't really have a list of what things are on each side so we're just left to sort of hunt and peck to build a viable solution.
This is a gripe I've had with AI tools for a while now. Though it's gotten somewhat better in time, but we don't really know what to expect from the tool in terms of quality. Ex. I'd expect a human engineer to probably not use a brand new assertion library for a new test when there are 200 tests using an existing one. But Claude has done this to me multiple times. So I have to add yet another item to the list, like you have, and tell it to look for testing conventions before writing. But, there is plenty we don't have to tell it, like what a function is or a test should probably cover the change in the diff. But we don't really have a list of what things are on each side so we're just left to sort of hunt and peck to build a viable solution.
You're forced to document every check and thought related to development until you're wiring a manual on how to be laid off (unless self employed or otherwise critical).
Which is fine. One should write quality docs and all that. But it seems exactly like training my offshore contract replacement instead of building tools for my own use. Except that income doesn't even go to a human just a black box datacenter company and shareholders.
Which is fine. One should write quality docs and all that. But it seems exactly like training my offshore contract replacement instead of building tools for my own use. Except that income doesn't even go to a human just a black box datacenter company and shareholders.
I find project-wide or subpackage-wide (for sufficiently large projects) CLAUDE.md's that document patterns (including for tests) solves this.
/init will make a project-wide one, or you can instruct it to "Create CLAUDE.md in any sub-directory that is sufficiently complex" then modify from there.
/init will make a project-wide one, or you can instruct it to "Create CLAUDE.md in any sub-directory that is sufficiently complex" then modify from there.
My review command isn’t an AI tool, it is is a text file.
You don’t need a SaaS when you can use a text file instead.
Just be incrementally aware of and closing gaps in the list of things you care about, and make it part of your day!
You don’t need a SaaS when you can use a text file instead.
Just be incrementally aware of and closing gaps in the list of things you care about, and make it part of your day!
Can you share your list?
I am curious what does it contain, for me a lot of times its a back and forth with agent until it "looks good to my eyes and taste", but haven't written any such list yet, because it is context dependant, in some projects I forgive minor issues, or allow magical numbers, but in other projects I force agent to use constants with meaningful names `SECONDS_IN_A_DAY = 24 * 60 * 60`
I am curious what does it contain, for me a lot of times its a back and forth with agent until it "looks good to my eyes and taste", but haven't written any such list yet, because it is context dependant, in some projects I forgive minor issues, or allow magical numbers, but in other projects I force agent to use constants with meaningful names `SECONDS_IN_A_DAY = 24 * 60 * 60`
It is interesting that the output of code is associated with sight and taste, while the quality of the code itself is associated with smell.
https://en.wikipedia.org/wiki/Code_smell
*edit: that wikipedia page ^ itself is a pretty answer to your request for a list of things to avoid when writing maintainable code.
https://en.wikipedia.org/wiki/Code_smell
*edit: that wikipedia page ^ itself is a pretty answer to your request for a list of things to avoid when writing maintainable code.
I think that's because you can usually smell when food is close to being rotten before you can see it...
EDIT: reading the WardsWiki reference from that Wikipedia page, there's also the point made by early users of the term that smells are something you have to check out, but don't always mean something needs fixing - e.g. a bad smell may be a gas leak, or it may just be a rubbish bin.
EDIT: reading the WardsWiki reference from that Wikipedia page, there's also the point made by early users of the term that smells are something you have to check out, but don't always mean something needs fixing - e.g. a bad smell may be a gas leak, or it may just be a rubbish bin.
Pairs nicely with the fact that smell is the sense most likely to be experienced differently between two people :)
Is that actually true? Just because English treats scents as only describable by analogy doesnt mean all languages do. There are a number of languages with scent descriptions for aspects of a smell that are transferrable. [1] That suggests everyone is capable of decomposing a scent into components the same way.
If that's true, we're left with a question equivalent to "does everyone see the same red?". As far as I know, the pure version of that question cannot be answered because subjective experiences of sensation cannot be transferred. And at that point, I'd say the manner in which they're experienced differently is equivalent.
1. https://youtu.be/w3KswMaEBiI
If that's true, we're left with a question equivalent to "does everyone see the same red?". As far as I know, the pure version of that question cannot be answered because subjective experiences of sensation cannot be transferred. And at that point, I'd say the manner in which they're experienced differently is equivalent.
1. https://youtu.be/w3KswMaEBiI
It’s not my area of expertise, but a friend in the field told me the fun fact originally.
Looking into it, it seems like smell has the most potential for genetic variance: https://pmc.ncbi.nlm.nih.gov/articles/PMC3990440/
That said, I can’t find any direct research comparing perceived senses. So they (and now I) might have oversimplified.
Thanks for the link, looks interesting!
Looking into it, it seems like smell has the most potential for genetic variance: https://pmc.ncbi.nlm.nih.gov/articles/PMC3990440/
That said, I can’t find any direct research comparing perceived senses. So they (and now I) might have oversimplified.
Thanks for the link, looks interesting!
Somewhat out of date (it’s grown a lot!)
https://github.com/cadamsdotcom/CodeLeash/blob/main/.claude/...
https://github.com/cadamsdotcom/CodeLeash/blob/main/.claude/...
I've codified mine into a reusable workflow https://github.com/nothingnesses/agent-scaffold . To be honest, this isn't fool-proof though, since the agents can simply choose to ignore them, so I also like to pair this with deterministic linting and compile time checking.
For a Rust project, I created macros that output compiler errors when documentation and tests are not in a shape I want them to be, like missing function invocations or assertions, which forces the agent to address them, where otherwise they would've just worked around them by adding stupid trivial assertions like `assert_eq!(true, true)`.
That still isn't fool-proof either, but it helps minimise those instances. I'm bullish on the idea of integrating formal methods and model-checking with AI. I think that combo feels like a promising avenue for constraining the stochastic side of AI-generated code with something closer to deterministic verification. Provided you can write correct specs of course!
For a Rust project, I created macros that output compiler errors when documentation and tests are not in a shape I want them to be, like missing function invocations or assertions, which forces the agent to address them, where otherwise they would've just worked around them by adding stupid trivial assertions like `assert_eq!(true, true)`.
That still isn't fool-proof either, but it helps minimise those instances. I'm bullish on the idea of integrating formal methods and model-checking with AI. I think that combo feels like a promising avenue for constraining the stochastic side of AI-generated code with something closer to deterministic verification. Provided you can write correct specs of course!
I have good experience with using open-code-review:
* https://github.com/alibaba/open-code-review
** https://layandreas.github.io/personal-blog/posts/beyond-vide...
* https://github.com/alibaba/open-code-review
** https://layandreas.github.io/personal-blog/posts/beyond-vide...
I have my own review skill (I think it predates when Claude added theirs) and one thing I'd add to your description is tell it to examine all the code and then, based on the changes, do a multi-role review of the code again using the most appropriate N of the following roles based on the changes: ... (where ... is a long list I have like Senior Engineer, Security Engineer, WCAG specialist, etc). Claude will spawn those reviews in parallel and then consolidate the feedback. I do spec based development so I just have my skill append the issues to the spec so I have a trail of issues and decisions.
You should do an experiment of splitting that up to multiple reviews that are logically together. My hypothesis is that you may be losing signal due to the amount of text expected back.
Yeah. I have a set of 5 review prompts attacking different problems, an adversarial review, and then a final synthesis, with the best results gotten by multiple passes using multiple models (the adversarial review stage combining all passes into one review per model and the synthesis picking the best of the two or three adversarial reviews). Expensive but it actually finds real problems that the single pass reviews rarely seem to find.
Or a dynamic workflow. $$$ but lots of coverage.
I do the same and I'm having the most incredible success.
Here is an example of the skills I define. [0] It will copy the repository into a /tmp/ folder, load all the dependencies, change all the code at the important places injecting debug statements that print to file with timestamps and meta data, and even if the code works it will still analyze the output. It will also use a snapshot test utility which is several times less expensive after performance tuning than any MCP or browser use service, drive user journeys looking for any place it isn't pixel perfect. (hmmm I didn't fold the snapshot util into that project because the project is a testing tool to begin with). Here is the snapshot utility. [1] With any front end code it will run it in Playwright using Chrome DevTools Protocol to do performance testing. [2]
It does this in iterations with little friction and my sh*t is flawless! Moreover, Fable offer no benefit over Opus with this approach. Plus, the red-team and especially any adversary testing utility or skill will trigger Fable.
[0] https://github.com/adam-s/goldseam/tree/main/.agents/skills
[1] https://github.com/adam-s/HNswered/blob/main/scripts/snapsho...
[2] https://github.com/adam-s/HNswered/blob/main/scripts/perf-pr...
Here is an example of the skills I define. [0] It will copy the repository into a /tmp/ folder, load all the dependencies, change all the code at the important places injecting debug statements that print to file with timestamps and meta data, and even if the code works it will still analyze the output. It will also use a snapshot test utility which is several times less expensive after performance tuning than any MCP or browser use service, drive user journeys looking for any place it isn't pixel perfect. (hmmm I didn't fold the snapshot util into that project because the project is a testing tool to begin with). Here is the snapshot utility. [1] With any front end code it will run it in Playwright using Chrome DevTools Protocol to do performance testing. [2]
It does this in iterations with little friction and my sh*t is flawless! Moreover, Fable offer no benefit over Opus with this approach. Plus, the red-team and especially any adversary testing utility or skill will trigger Fable.
[0] https://github.com/adam-s/goldseam/tree/main/.agents/skills
[1] https://github.com/adam-s/HNswered/blob/main/scripts/snapsho...
[2] https://github.com/adam-s/HNswered/blob/main/scripts/perf-pr...
> My list is like 200 items now. Know what? Agents don’t care that they just got a wall of generic feedback, they happily look into all the bullet points.
Yes, yes, there has been a library of information on HN by now about how to use agents effectively. (And I'm grateful for that, because I can keep current and in the loop without feeling enslaved to the new style of development.)
None of that is a reason not to do what the title of TFA says. If your review process is doing the right thing, you should observe that it results in your agent moving the code in the "human-maintainable" direction. If you, for whatever reason, actually directly make commits yourself any more (read this ironically; I genuinely can't understand why anyone would want to give up on that, no matter how good the generated code gets, because "the LLM could do better" is not the point), then of course you should write it to be human-maintainable.
The reason humans find "human-maintainable" code to be maintainable is because maintainability is one of the precious few worthwhile at-least-vaguely-objective metrics of code quality we have.
Every time I see someone try to make a point about the fact that some code actually is just better than other code, only to be met with more of this sort of advice, I start to wonder whether I was alone in ever actually enjoying programming.
Yes, yes, there has been a library of information on HN by now about how to use agents effectively. (And I'm grateful for that, because I can keep current and in the loop without feeling enslaved to the new style of development.)
None of that is a reason not to do what the title of TFA says. If your review process is doing the right thing, you should observe that it results in your agent moving the code in the "human-maintainable" direction. If you, for whatever reason, actually directly make commits yourself any more (read this ironically; I genuinely can't understand why anyone would want to give up on that, no matter how good the generated code gets, because "the LLM could do better" is not the point), then of course you should write it to be human-maintainable.
The reason humans find "human-maintainable" code to be maintainable is because maintainability is one of the precious few worthwhile at-least-vaguely-objective metrics of code quality we have.
Every time I see someone try to make a point about the fact that some code actually is just better than other code, only to be met with more of this sort of advice, I start to wonder whether I was alone in ever actually enjoying programming.
This technique incrementally codifies the subset of my personal definition of code quality that can be codified. I’ve found a discovery based approach is better than anticipatory, because it forces everything you spend tokens to prove its worth.
I still do code review - how else would I know what to codify! But since starting this about a year ago, I don’t review menial dumb AI mistakes anymore.
I still do code review - how else would I know what to codify! But since starting this about a year ago, I don’t review menial dumb AI mistakes anymore.
Why wouldn't it already just do this though?
Unless prompted to do so, why would it? From the article: "Every shortcut you merge into your codebase is a signal about how things are done here."
It does. Claude has a built in review and it’s pretty good. But it doesn’t know exactly what you want. This is a way to tell it.
Good way to double your token use though, if you’re concerned about that.
Good way to double your token use though, if you’re concerned about that.
> But it doesn’t know exactly what you want. This is a way to tell it.
What ever happened to communicating through code?
Agents can follow examples and infer patterns, and they can read commit history and diffs. Real-world commit logs for human-only projects are dominated by short commits (well, at least the ones where the humans are skilled, appreciate version control, care about the project, etc.) with thoughtful commit messages.
cf. https://wiki.c2.com/?JustCorrectDontPoint
What ever happened to communicating through code?
Agents can follow examples and infer patterns, and they can read commit history and diffs. Real-world commit logs for human-only projects are dominated by short commits (well, at least the ones where the humans are skilled, appreciate version control, care about the project, etc.) with thoughtful commit messages.
cf. https://wiki.c2.com/?JustCorrectDontPoint
Just one thing
A model might be able to follow 200 different instructions at the same time, while another model will choke on it
A model might be able to follow 200 different instructions at the same time, while another model will choke on it
Yes and this is a really important point.
I actually have no data on how other models do - feeling very spoiled by Claude to be honest.
Would love to hear how it goes if you try it with other models!
I actually have no data on how other models do - feeling very spoiled by Claude to be honest.
Would love to hear how it goes if you try it with other models!
> My list is like 200 items now
Do human developers check for 200 items when they do code review? How long would that take? It's quite clear that AI code review could be better even with some error.
What's easy for human to review is also easy for AI (small code base, small PRs). What's hard for AI is also hard for human, if not more. But the time cost is so different that it's almost a nobrainer to choose AI to code and review, especially considering most software out there is not so critical :)
Do human developers check for 200 items when they do code review? How long would that take? It's quite clear that AI code review could be better even with some error.
What's easy for human to review is also easy for AI (small code base, small PRs). What's hard for AI is also hard for human, if not more. But the time cost is so different that it's almost a nobrainer to choose AI to code and review, especially considering most software out there is not so critical :)
Humans pattern match against thousands upon thousands of criteria subconsciously.
AI is a different intelligence - a 200 point list shoved in its face all at once doesn’t overwhelm it. That’s only 5-10k tokens!
Bear in mind though, because I added all the items on the list I’ve seen the reasons they’re there & act as a backstop against it missing things. There’s always got to be a quality bar, it’s part of being a professional and signing your name on your work.
AI is a different intelligence - a 200 point list shoved in its face all at once doesn’t overwhelm it. That’s only 5-10k tokens!
Bear in mind though, because I added all the items on the list I’ve seen the reasons they’re there & act as a backstop against it missing things. There’s always got to be a quality bar, it’s part of being a professional and signing your name on your work.
> Do human developers check for 200 items when they do code review? How long would that take? It's quite clear that AI code review could be better even with some error.
We (humans) don't do 200 point inspection, but we also don't review every code change in a spherical vacuum without prior knowledge of the project. However, we do check a lot of things.
> What's hard for AI is also hard for human, if not more.
That's just plain wrong. AI straight up suffers with counting things, and I'm not just talking about counting 'r' in strawberry. Some things are easier for AI some are easier for human.
We (humans) don't do 200 point inspection, but we also don't review every code change in a spherical vacuum without prior knowledge of the project. However, we do check a lot of things.
> What's hard for AI is also hard for human, if not more.
That's just plain wrong. AI straight up suffers with counting things, and I'm not just talking about counting 'r' in strawberry. Some things are easier for AI some are easier for human.
Given all the hype that LLMs have got and the valuations these AI companies are getting, I am disappointed at how even the "best" coding agents degrade over time.
WTF - I need to implement a review command to guide to do its job properly.
Can you imagine any other industry charging people money for a product like this ?
When you are charging people money - scratching the surface cannot be an excuse.
WTF - I need to implement a review command to guide to do its job properly.
Can you imagine any other industry charging people money for a product like this ?
When you are charging people money - scratching the surface cannot be an excuse.
There’s a saying for this - “don’t ship your first draft”.
Its first attempt WILL be crap. You can refine its output in the loop as a human, or let it go and then do a quality pass post-hoc.
The beauty of the latter is you can codify and automate a subset of the work, and the agent can loop until those bars are cleared then you get a higher quality work product to look at.
Its first attempt WILL be crap. You can refine its output in the loop as a human, or let it go and then do a quality pass post-hoc.
The beauty of the latter is you can codify and automate a subset of the work, and the agent can loop until those bars are cleared then you get a higher quality work product to look at.
Nice. I had a file with code samples (old code I wrote), including formatting and I asked to use it as a reference.
Will try your approach to distill the code to bullet points.
Will try your approach to distill the code to bullet points.
I've been finding that they can write surprisingly elegant code, you just have to ask them to. It seems to be kind of like the old generative AI art days where you still had to add "+quality -bad" to the prompt.
Failing that they default to the most common style they were trained on. Which, at this point, is mostly code they wrote...
Failing that they default to the most common style they were trained on. Which, at this point, is mostly code they wrote...
Yes, and, write custom linters for things you want to prevent forever. Have a look at https://github.com/cadamsdotcom/CodeLeash/blob/main/scripts/... for an example (enforced before all commits via https://github.com/cadamsdotcom/CodeLeash/blob/main/.pre-com...)
Basically I got sick of telling the agent to put dynamic imports at the top of the file so I made them into an error that blocks commits.
Now I don’t even need that in the review.md because it can’t make it though to /review.
Basically I got sick of telling the agent to put dynamic imports at the top of the file so I made them into an error that blocks commits.
Now I don’t even need that in the review.md because it can’t make it though to /review.
This sounds like gold to me, thanks. I'm going to try it.
Crazy how many engineers in here just say they are using another prompt on top. From my experience that makes things worse. It does abstractions, but the wrong ones. It overcomments, confusing future calls of the LLM.
To me building on multiple scalable systems this has been the most dangerous part of LLMs. On a good codebase it will work good, but it will maek it worse, so you keep using it, till it doesnt work and then you have to pay the bill and fix for what you didn’t build before.
If you put an agent on a fresh codebase 2 things are often given:
-> You have a mental model of the code -> The code is somewhet concise
After multiple iterations both is lost and LLM performance degrades. To solve this you can regular refactor, but it’s not a nice experienc. So my best solution is:
I use LLMs for exploration and for review, but I write the code myself. I find it hard to believe why so many engineers try to avoid it. It’s not consuming much of my time. And it’s actually the most enjoyable part.
Sometimes I race AI i give it a prompt /bug to fix and at the sametime im greping/symboling through the codebase and tryto fix it myself. AI isn’t always faster.
To me building on multiple scalable systems this has been the most dangerous part of LLMs. On a good codebase it will work good, but it will maek it worse, so you keep using it, till it doesnt work and then you have to pay the bill and fix for what you didn’t build before.
If you put an agent on a fresh codebase 2 things are often given:
-> You have a mental model of the code -> The code is somewhet concise
After multiple iterations both is lost and LLM performance degrades. To solve this you can regular refactor, but it’s not a nice experienc. So my best solution is:
I use LLMs for exploration and for review, but I write the code myself. I find it hard to believe why so many engineers try to avoid it. It’s not consuming much of my time. And it’s actually the most enjoyable part.
Sometimes I race AI i give it a prompt /bug to fix and at the sametime im greping/symboling through the codebase and tryto fix it myself. AI isn’t always faster.
> I write the code myself. I find it hard to believe why so many engineers try to avoid it.
Gradually over its recent booming years, software work went from one of several practical engineering refuges for curious tinkers and puzzle-addicts to a career path for financially ambitious bright people akin to finance, law, or medicine.
Many people carrying a "software engineer" title now never really enjoyed that part of the work at all but were suitably clever and responsible to accomplish what modest ends they were tasked to by their very generous employers. Mostly (but not entirely), those people are the ones most eager to have AI agents shield them from rigorous design and puzzle work and enable them to leverage their innate cleverness more lazily. They never really internalized the coding and engineering principles of the industry and so can't foresee what might be down the road for them with this technique, especially when they're surrounded by peers with the same mindset.
> AI isn’t always faster.
It is when coding was an extremely frustrating and high friction experience for you in the first place, as is the case for many who work among us now.
Gradually over its recent booming years, software work went from one of several practical engineering refuges for curious tinkers and puzzle-addicts to a career path for financially ambitious bright people akin to finance, law, or medicine.
Many people carrying a "software engineer" title now never really enjoyed that part of the work at all but were suitably clever and responsible to accomplish what modest ends they were tasked to by their very generous employers. Mostly (but not entirely), those people are the ones most eager to have AI agents shield them from rigorous design and puzzle work and enable them to leverage their innate cleverness more lazily. They never really internalized the coding and engineering principles of the industry and so can't foresee what might be down the road for them with this technique, especially when they're surrounded by peers with the same mindset.
> AI isn’t always faster.
It is when coding was an extremely frustrating and high friction experience for you in the first place, as is the case for many who work among us now.
100 times this. Maybe this was the thing all along that was so difficult to put our finger on for why some engineers seem to have "it" while so many others, despite being productive, don't. It's just that they loved it. It brings me so much sadness to see so many people happily relegate themselves to typists instead of a person with real motivations and skills.
I remember the first time I encountered someone that said they chose software because it paid well. They were such an oddity to me, including their thought process when it came to code. Now, in the cooperate world, I work with people who all admit they cheated their way through school (what an insane group conversation that was), and are very far from "nerds". I haven't worked with someone that gave a single damn in nearly a decade now. I feel incredibly out of place, and increasingly angry that nobody cares about anything. And, this has nothing to do with AI (which I enjoy). It's just a big group of people who do the absolute minimum for any task, who don't have any engineering rigor/care at all, and just try random shit until it works.
I'm trying VERY hard to get into their mindset, and be more like them, but it so hard to not care. I wish I could have sooner.
I'm trying VERY hard to get into their mindset, and be more like them, but it so hard to not care. I wish I could have sooner.
If there's one thing I've remarked, even before LLM tooling, is that there's a class of people that is ready to try things for weeks until it magically work (with no guarantee it will hold), instead of spending one hour designing it and formalizing it. They won't get functional abstraction, maintainability means nothing to them, and architecture don't matter.
They're the one copy-pasting straight from StackOverflow, and if it does not work, will copy-paste something over it. When something works, they will copy-paste it all over the codebase regardless of context.
For those people, LLM tooling are the Second Coming. Because it helps them eliminate all the telltale signs of bad works they've been doing. For them, "Use the AI" is the new mantra because they can't imagine not needing to use it.
They're the one copy-pasting straight from StackOverflow, and if it does not work, will copy-paste something over it. When something works, they will copy-paste it all over the codebase regardless of context.
For those people, LLM tooling are the Second Coming. Because it helps them eliminate all the telltale signs of bad works they've been doing. For them, "Use the AI" is the new mantra because they can't imagine not needing to use it.
This is exactly why I advocate people write code, even in a world where agents code “better”
It’s not enough to read code. You don’t internalize it. You need to experience it painfully :)
Also agents frequently defensively wrap old code instead of questioning whether legacy paths should exist. You get this nested doll layering effect of extremely large amounts of defensive code.
https://softwaredoug.com/blog/2026/07/09/write-code
It’s not enough to read code. You don’t internalize it. You need to experience it painfully :)
Also agents frequently defensively wrap old code instead of questioning whether legacy paths should exist. You get this nested doll layering effect of extremely large amounts of defensive code.
https://softwaredoug.com/blog/2026/07/09/write-code
>> AI isn’t always faster
It is always faster if you don't care about quality and need to churn out code as fast as possible to close tickets.
It is always faster if you don't care about quality and need to churn out code as fast as possible to close tickets.
And as time goes on?
You get promoted and let other people deal with the mess.
The truth is that no one in management cares about your perfect code, they only care about the projects you deliver, the features you push out and the meeting KPIS.. Your customers don't care about your perfect abstractions either, they just want the button to work when it's clicked.
You can always argue about maintenance, but who is going to listen? By the time it's an issue, the business is throwing money at the problem to make it go away. Heck, even major security issues are a nothing burger.. I've lost count on the number of breaches big companies have had in the last decade..
Such is the plight of our industry.
The truth is that no one in management cares about your perfect code, they only care about the projects you deliver, the features you push out and the meeting KPIS.. Your customers don't care about your perfect abstractions either, they just want the button to work when it's clicked.
You can always argue about maintenance, but who is going to listen? By the time it's an issue, the business is throwing money at the problem to make it go away. Heck, even major security issues are a nothing burger.. I've lost count on the number of breaches big companies have had in the last decade..
Such is the plight of our industry.
> The truth is that no one in management cares about your perfect code, they only care about the projects you deliver, the features you push out and the meeting KPIS.. Your customers don't care about your perfect abstractions either, they just want the button to work when it's clicked.
I don't think most developers care about perfect code (if such thing exists). What they care about is maintainability, so that the project is delivered on time, features keep getting pushed and KPIS can be actually met. And that the customers have a working button.
Instead we got projects that keeps being dragged around (until it's put out of its misery), half baked features, and KPIs that are twisted until they're barely looks like what was stated at the beginning of the quarter. And the customer is complaining about another button breaking.
What I do is never ask for permission, because that's an engineering concern, not a product/management one. I just tidy the code I work on, one step at a time.
I don't think most developers care about perfect code (if such thing exists). What they care about is maintainability, so that the project is delivered on time, features keep getting pushed and KPIS can be actually met. And that the customers have a working button.
Instead we got projects that keeps being dragged around (until it's put out of its misery), half baked features, and KPIs that are twisted until they're barely looks like what was stated at the beginning of the quarter. And the customer is complaining about another button breaking.
What I do is never ask for permission, because that's an engineering concern, not a product/management one. I just tidy the code I work on, one step at a time.
Exactly. I follow a similar workflow. I am still writing code by hand. Not all code. Parts are generated by Opus.
have been doing "racing to debug" things with AI for quite some time too. Have to say, before Opus 4.8, there wasn't even a comparison for anything slightly complex.
Opus 4.8 has been the turning point though. I am not winning many races compared to Opus 4.8, especially if it is something more complex.
I think if everyone was using Opus 4.8 (or better) for every single task/question/etc, you would have much different overall sentiment. I don't think you would have many AI disbelievers left.
Opus 4.8 has been the turning point though. I am not winning many races compared to Opus 4.8, especially if it is something more complex.
I think if everyone was using Opus 4.8 (or better) for every single task/question/etc, you would have much different overall sentiment. I don't think you would have many AI disbelievers left.
> I use LLMs for exploration and for review, but I write the code myself. I find it hard to believe why so many engineers try to avoid it. It’s not consuming much of my time. And it’s actually the most enjoyable part.
At my workplace, there is more work to be done than there is engineers, and approximately 2 engineers per service. I can spin off multiple Claude Code instances on unrelated work, steering them occasionally, and then finally reviewing the output. After I have reviewed it, I post it for team review.
You're absolutely right that my depth of familiarity is lesser with this code, but we are absolutely shipping more as a result of increased parallelization.
The bottleneck now is typically reviews - both pre-push and team reviews.
At my workplace, there is more work to be done than there is engineers, and approximately 2 engineers per service. I can spin off multiple Claude Code instances on unrelated work, steering them occasionally, and then finally reviewing the output. After I have reviewed it, I post it for team review.
You're absolutely right that my depth of familiarity is lesser with this code, but we are absolutely shipping more as a result of increased parallelization.
The bottleneck now is typically reviews - both pre-push and team reviews.
This seems to assume more code shipped equals more work done. I am still not convinced that this is necessarily the case. Sometimes it is. Sometimes it is not. You mentioned that reviews are now the bottleneck and that your familiarity with the code has decreased. That tradeoff might eat into the parallelization gains over time.
Definitely not - the biggest risk with this increased speed is going full-bore in the wrong direction. A product mindset (and a critical eye to architecture) matters more now than ever.
Most people hyping their AI use mention the short-term gains without taking into account how it affects overall long-term success. We are creatures of convenience.
Considering most teams have only switched to heavy AI use in the past few months, the verdict is still out on this.
That said, I've had lots of success using AI to learn, refactor and clean up codebases.
I notice another trend were a lot of AI naysayers haven't really spent a ton of time getting intimately familiar with AI.
That said, I've had lots of success using AI to learn, refactor and clean up codebases.
I notice another trend were a lot of AI naysayers haven't really spent a ton of time getting intimately familiar with AI.
> To solve this you can regular refactor, but it’s not a nice experienc.
Really? I always thought that was the best part of programming. And now that I can direct an LLM to identify a specific pattern and rework it in a certain way, or to extract a function for a specific purpose and then use it where possible (with my review, of course), so much the better.
I agree with you about the joy of writing things directly, overall. But being able to get a few hundred lines of new approximately-what-I-wanted-to-type code (which I generally can read and fix much faster than I would have written it from scratch) definitely improves the experience, when my brain is racing ahead of my fingers. Certainly it gets me more motivated to actually start on a new feature. Similarly for all the not-exactly-exact find-and-replace tasks.
(I'm not a slow typist, but I slow myself down when I write the code, by thinking too much about details that won't be important until after the tests run.)
Really? I always thought that was the best part of programming. And now that I can direct an LLM to identify a specific pattern and rework it in a certain way, or to extract a function for a specific purpose and then use it where possible (with my review, of course), so much the better.
I agree with you about the joy of writing things directly, overall. But being able to get a few hundred lines of new approximately-what-I-wanted-to-type code (which I generally can read and fix much faster than I would have written it from scratch) definitely improves the experience, when my brain is racing ahead of my fingers. Certainly it gets me more motivated to actually start on a new feature. Similarly for all the not-exactly-exact find-and-replace tasks.
(I'm not a slow typist, but I slow myself down when I write the code, by thinking too much about details that won't be important until after the tests run.)
>Sometimes I race AI i give it a prompt /bug to fix and at the sametime im greping/symboling through the codebase and tryto fix it myself. AI isn’t always faster.
+1 - this is also my experience. I also "race" the AI on some tasks, especially when it's simple and the AI is taking forever to return a result - so it even has a head start, and I often complete it faster or around the same time.
For some things maybe it is faster, but it isn't really returning a better result. It often turns into spaghetti, doing things I didn't ask it to do.
+1 - this is also my experience. I also "race" the AI on some tasks, especially when it's simple and the AI is taking forever to return a result - so it even has a head start, and I often complete it faster or around the same time.
For some things maybe it is faster, but it isn't really returning a better result. It often turns into spaghetti, doing things I didn't ask it to do.
Wild idea: just write code.
I know. It’s an unbelievable concept in this AI era. Write code? Isn’t that what dinosaurs did?
If you expect that a human will need to read and maintain that code you might as well write it for them. You’ll get annoyed by having to read overly-verbose copy-pasted code. So will they. So write the code yourself and bringo: you’ll fix things yourself and write things in a way that makes sense for other humans to maintain.
Or you can come up with a convoluted web of markdown files to try and coax your agents and loops to understand what future human maintainers will expect the code to look like.
I’m not sure what path will be easier in the long run. Anyone inherit a loop-based agent-driven code base yet and have to try to understand it?
I know. It’s an unbelievable concept in this AI era. Write code? Isn’t that what dinosaurs did?
If you expect that a human will need to read and maintain that code you might as well write it for them. You’ll get annoyed by having to read overly-verbose copy-pasted code. So will they. So write the code yourself and bringo: you’ll fix things yourself and write things in a way that makes sense for other humans to maintain.
Or you can come up with a convoluted web of markdown files to try and coax your agents and loops to understand what future human maintainers will expect the code to look like.
I’m not sure what path will be easier in the long run. Anyone inherit a loop-based agent-driven code base yet and have to try to understand it?
It’s not crazy. I always add a simple message to my prompts: “leave 20% solutions empty and I’ll implement them myself”.
It work wonders for me.
It work wonders for me.
I have good results with this prompt after every larger change: Now do a final code check. Is everything tidy and do the components adhere to the principle of separations-of-concerns. Is everything in an understandable and maintainable state? Do we make any assumptions that may not be true anymore? Is any code left over from previous edits or experiments that does not belong into the codebase? Is the documentation still representing the current state of code?
I usually just say “make sure this code is professional and ready to deliver as a senior engineer” and it usually infers all that stuff you said plus more things as well. I try to give it the goal and let it decide what to do.
One thing I usually keep having to point out directly is to remove all “progress tracking” code comments and make sure all comments are appropriate for long term maintenance in the code base. Claude tends to leave comments like “button click causes save now, no longer uses onBlur” when the code really never used onBlur, that was just a thing Claude wanted to do earlier in the same task/branch and I redirected it at some point.
One thing I usually keep having to point out directly is to remove all “progress tracking” code comments and make sure all comments are appropriate for long term maintenance in the code base. Claude tends to leave comments like “button click causes save now, no longer uses onBlur” when the code really never used onBlur, that was just a thing Claude wanted to do earlier in the same task/branch and I redirected it at some point.
For things the agent forgets to obey often, at least in Claude Code, there are also "output styles" that are more deeply embedded - into a system prompt - and agent is also periodically reminded of them during the session: https://code.claude.com/docs/en/output-styles
I haven't used them so far but maybe these would work better than basic instructions for such cases.
I haven't used them so far but maybe these would work better than basic instructions for such cases.
In practice output styles are just more context (equivalent to CLAUDE.md or memory) ... but with a slightly increased weight.
didn't know of that. I'll switch it to learning mode at work, wondering how long it's going to last.
Just pull the slot machine lever
Yeah, I miss the days of having perfectly deterministic humans writing our code.
>Yeah, I miss the days of having perfectly deterministic humans writing our code
If most people by your account are subpar programmers before AI, why do you believe they'll suddenly be better with AI?
Also, these comments always come off more than a bit anti-social. It's like hating your coworkers correlates strongly with AI-adoption.
If most people by your account are subpar programmers before AI, why do you believe they'll suddenly be better with AI?
Also, these comments always come off more than a bit anti-social. It's like hating your coworkers correlates strongly with AI-adoption.
I like to also compliment the model on its very fashionable shoes as well, they love the flattery.
good, but this is just a verbose "make no mistakes"; it'd probably make more sense to just setup a nightly cron job that loops through the prior days' work and writes some morning tasks of the same character.
The models will interpret this willynilly; but nonetheless, it's often a better than doing nothing.
The models will interpret this willynilly; but nonetheless, it's often a better than doing nothing.
It means the same thing to you, but not to the whole spectrum of people using AI. You literally see it on Reddit all the time where people are complaining about the same model either over-engineering or doing too much, vs it being requiring too much steering or not being autonomous or capable enough to hand off tasks to on its own.
The reason prompting it to review its own work for loose ends, record any new undocumented or noteworthy behavior, suggest changes to tests/processes to make it go more smoothly the next time, etc is that it’s prescriptive and process-oriented (and thus easily verifiable/done in-context) rather than descriptive and outcome oriented (which to do properly could require way more context than the model has, because it doesn’t know what it doesn’t know about your particular work, only what it’s seen so far).
Even promoting it to do these after-the-fact vs as an upfront requirement can have a big impact IMO. If you make “maintainability” part of the task before it’s seen the real work it will focus on general “best practices” crap rather than the real work, so either way if this is something you care about it doing you have to give it guidance for how you want it done.
If you were to review the logs of a model after the fact, you’d also not really save on input tokens unless you compressed the context or sharded it out, which can easily miss the small details that constitute the difference between “what actually happened” vs “how the LLM models this general class of problems” unless the first pass involves the entire context anyway. That said I do think there’s a lot of value in building some kind of pipeline for validating and aggregating these “learnings” across sessions.
The reason prompting it to review its own work for loose ends, record any new undocumented or noteworthy behavior, suggest changes to tests/processes to make it go more smoothly the next time, etc is that it’s prescriptive and process-oriented (and thus easily verifiable/done in-context) rather than descriptive and outcome oriented (which to do properly could require way more context than the model has, because it doesn’t know what it doesn’t know about your particular work, only what it’s seen so far).
Even promoting it to do these after-the-fact vs as an upfront requirement can have a big impact IMO. If you make “maintainability” part of the task before it’s seen the real work it will focus on general “best practices” crap rather than the real work, so either way if this is something you care about it doing you have to give it guidance for how you want it done.
If you were to review the logs of a model after the fact, you’d also not really save on input tokens unless you compressed the context or sharded it out, which can easily miss the small details that constitute the difference between “what actually happened” vs “how the LLM models this general class of problems” unless the first pass involves the entire context anyway. That said I do think there’s a lot of value in building some kind of pipeline for validating and aggregating these “learnings” across sessions.
the problem is when you ask it to review it's own work in it's own context is you've already primed it to sniff it's own farts and say everythings fine.
This is a good example of AI native thinking. Teach AI everything and ask it if it has learnt throughly learnt. The results are surprisingly good.
I am following similar steps from this article https://www.lucasfcosta.com/blog/backpressure-is-all-you-nee...
I am following similar steps from this article https://www.lucasfcosta.com/blog/backpressure-is-all-you-nee...
> The next time you ask the LLM for another endpoint with the same access rules, the model won't start from first principles. It'll start from the other four copies already sitting in your repo.
To be honest I'm not sure how true this is. I think it's more that there does seem to be quite a baked-in bias to repeat basic structures and not reuse (much less come up with) abstractions. So where that is the existing pattern it looks like it's keeping with that, when in reality it would often do that either way.
There have been many cases where I've started a piece of work by laying down very rigid abstractions and a few examples of using them, and I explicitly prompt to not only exclusively use the specific abstraction API but also copy the way I've used it. And the (frontier) LLM does neither, it just steams ahead re-implementing things from scratch from bottom up basic structures, partially and often totally ignoring the abstractions.
I don't know exactly why this should be the case but my naive suspicion is that there's just an awful lot of this type of stuff in the masses of training code and the weights just somehow 'know better' how to get results this way, rather than using your more novel abstractions/patterns.
To be honest I'm not sure how true this is. I think it's more that there does seem to be quite a baked-in bias to repeat basic structures and not reuse (much less come up with) abstractions. So where that is the existing pattern it looks like it's keeping with that, when in reality it would often do that either way.
There have been many cases where I've started a piece of work by laying down very rigid abstractions and a few examples of using them, and I explicitly prompt to not only exclusively use the specific abstraction API but also copy the way I've used it. And the (frontier) LLM does neither, it just steams ahead re-implementing things from scratch from bottom up basic structures, partially and often totally ignoring the abstractions.
I don't know exactly why this should be the case but my naive suspicion is that there's just an awful lot of this type of stuff in the masses of training code and the weights just somehow 'know better' how to get results this way, rather than using your more novel abstractions/patterns.
“ There have been many cases where I've started a piece of work by laying down very rigid abstractions and a few examples of using them, and I explicitly prompt to not only exclusively use the specific abstraction API but also copy the way I've used it. And the (frontier) LLM does neither, it just steams ahead re-implementing things from scratch from bottom up basic structures”
Yup, this is the sad state of affairs that we’re currently in, and the only way to avoid this is to specifically instruct the model on how exactly to implement things.
From my point of view, I think this is fine, to be able to use these LLMs as fast implementation engines. The challenge is to make it surface these types of implementation decisions before it goes off doing it the wrong way.
Yup, this is the sad state of affairs that we’re currently in, and the only way to avoid this is to specifically instruct the model on how exactly to implement things.
From my point of view, I think this is fine, to be able to use these LLMs as fast implementation engines. The challenge is to make it surface these types of implementation decisions before it goes off doing it the wrong way.
There is an old quote:
"Add comments to your code under the assumption that the next person to maintain it is a homicidal maniac who knows where you live"
"Add comments to your code under the assumption that the next person to maintain it is a homicidal maniac who knows where you live"
Right now the comments that upset me the most are LLM TMI-style comments that break encapsulation by talking about the behavior of specific current callers of a function right above the function definition.
I recently reacted angrily in a PR review comment after encountering one for the umpteenth time... that caught me off guard. I didn't know I was capable of that.
I recently reacted angrily in a PR review comment after encountering one for the umpteenth time... that caught me off guard. I didn't know I was capable of that.
This is what has been frustrating me most lately. Even though I have a rule in my global CLAUDE.md that says:
> Only write comments to explain the why when it is not obvious from the code (rationale, gotchas, constraints). Do not comment on the what — well-named code already says it. Do not comment on how a framework works.
It still keeps adding these bad comments. When I then ask it to review the comments based on my preferences it then deletes most of them or improves them.
Today I asked Claude why it disrespects my preference and it said that the surrounding code was like that and it followed that style. It suggested I add this line to my global CLAUDE.md file:
> The comment rule above beats the style of the surrounding code: neighboring files with what-style comments are not license to write more of them, and comments carried along when porting or copying code must be re-judged against the rule, not kept for consistency.
Let's see if that improves things.
> Only write comments to explain the why when it is not obvious from the code (rationale, gotchas, constraints). Do not comment on the what — well-named code already says it. Do not comment on how a framework works.
It still keeps adding these bad comments. When I then ask it to review the comments based on my preferences it then deletes most of them or improves them.
Today I asked Claude why it disrespects my preference and it said that the surrounding code was like that and it followed that style. It suggested I add this line to my global CLAUDE.md file:
> The comment rule above beats the style of the surrounding code: neighboring files with what-style comments are not license to write more of them, and comments carried along when porting or copying code must be re-judged against the rule, not kept for consistency.
Let's see if that improves things.
In Claude Code there are also "output styles" that are more deeply embedded - into a system prompt - and agent is also periodically reminded of them during the session: https://code.claude.com/docs/en/output-styles
Maybe these would work better for such cases.
Maybe these would work better for such cases.
My hypothesis is that Claude is inclined to write so many comments as a way of doing additional thinking
Yeah, it's short form memory or something. Like writing a todo list.
This drives me nuts as well. I hate also hate when LLMs use plan-document references in comments/doc strings too. “Landed in stage 1…”
I have a lot of CLAUDE.md rules to restrict this stuff, but realize the “encapsulation” language is something I’m missing.
I have a lot of CLAUDE.md rules to restrict this stuff, but realize the “encapsulation” language is something I’m missing.
There's a cluster of issues like comments like "use a set instead of ..." after changing something which will just confuse people in the future. Or comments referring to irrelevant details of the planning/implementation process.
It's as though the machine can't separate the chat and planning docs from the code itself and so they meld into each other. As though it can't fully grasp that the code will outlive the current session by years.
Anyway I find a checklist approach works well to sort this out. I don't consider looking at machine generated code until after a checklist covering all this sort of stuff has been applied. My checklist approach currently has about 50 items which I have the machine apply by splitting it up across about 20 subagents. Pretty silly but it seriously improves the first-pass quality vs only a few subagents. I find this checklist can effectively eliminate words like "genuine" and "landed" from the code too. Eliminates vague and made up terminology. Makes it less nauseating
It's as though the machine can't separate the chat and planning docs from the code itself and so they meld into each other. As though it can't fully grasp that the code will outlive the current session by years.
Anyway I find a checklist approach works well to sort this out. I don't consider looking at machine generated code until after a checklist covering all this sort of stuff has been applied. My checklist approach currently has about 50 items which I have the machine apply by splitting it up across about 20 subagents. Pretty silly but it seriously improves the first-pass quality vs only a few subagents. I find this checklist can effectively eliminate words like "genuine" and "landed" from the code too. Eliminates vague and made up terminology. Makes it less nauseating
Yeah, agreed. These have started popping up a lot more recently, where I get a 5 sentence paragraph explaining how function overloading works in c++.
Claude Code and Opus 4.8 love to describe changes in comments (perhaps because that’s what’s on its “mind” at the time), like “this used to do A but that did a bad thing so now it does B”. I’ve almost convinced it that changes go in the commit message, not the comments.
Well, on the one hand, Hyrum's Law: "With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviors of your system will be depended on by somebody."
so that can be useful information in some situations.
On the other hand, what a horrible out of date mess of comment that can turn out to be a little bit later. Taken as gospel by the next entity (human or llm) to massage that function.
so that can be useful information in some situations.
On the other hand, what a horrible out of date mess of comment that can turn out to be a little bit later. Taken as gospel by the next entity (human or llm) to massage that function.
I have tried prompting it out and providing strong guidelines in my AGENTS.md against it, but I still get _way_ too many useless "explain the code" style comments no matter how much I try. I usually have to do something like "Look at all commits in the past X days and remove (DO NOT TRIM) all comments that are not truly exceptional"
Normally when I can't get claude to follow a prompt I try a lint hook, but it's tough to lint something that subjective.
Normally when I can't get claude to follow a prompt I try a lint hook, but it's tough to lint something that subjective.
Used to work with a guy who would frequently say "a comment is an apology" i.e. the comment is there because the code itself is not clear. That can be the case, but I generally find more comments better than fewer, especially if they relate the code to actual business or functional requirements and don't just restate what the code is doing.
Years ago I would often write comments first. I.e. start with describing the overall goals. Then break it down into routines and order of operations, all still in plain english. Once I was happy with that, I'd break up the comments with blocks of code. I guess this is sort of like "literate programming" though I was doing it long before I ever heard that term and I still have never read much about it. It's almost more like I was prompting myself towards the end goal. The downside of this approach is that the comments do end up more or less just explaining in english what the code is doing, so maybe aren't quite as useful to future maintainers.
Years ago I would often write comments first. I.e. start with describing the overall goals. Then break it down into routines and order of operations, all still in plain english. Once I was happy with that, I'd break up the comments with blocks of code. I guess this is sort of like "literate programming" though I was doing it long before I ever heard that term and I still have never read much about it. It's almost more like I was prompting myself towards the end goal. The downside of this approach is that the comments do end up more or less just explaining in english what the code is doing, so maybe aren't quite as useful to future maintainers.
I really wish Literate Programming had caught on.
The big problem is folks misunderstood it as documentation (arguably plain.tex should have also been the sourcecode for _The TeXbook_ and that it wasn't is a big part of this) --- it could be, but usually that's better as a separate text/chapter....
I've been trying to collect books on Literate Program/notable Literate Programs published as books:
https://www.goodreads.com/review/list/21394355-william-adams...
and I will note that my own programming took a quantum leap forward when I purchased and read:
https://www.goodreads.com/book/show/39996759-a-philosophy-of...
and applied its principles one chapter at a time to a project which I was able (w/ a bit of help) to get into Literate Programming form:
https://github.com/WillAdams/gcodepreview/blob/main/literati...
The big problem is folks misunderstood it as documentation (arguably plain.tex should have also been the sourcecode for _The TeXbook_ and that it wasn't is a big part of this) --- it could be, but usually that's better as a separate text/chapter....
I've been trying to collect books on Literate Program/notable Literate Programs published as books:
https://www.goodreads.com/review/list/21394355-william-adams...
and I will note that my own programming took a quantum leap forward when I purchased and read:
https://www.goodreads.com/book/show/39996759-a-philosophy-of...
and applied its principles one chapter at a time to a project which I was able (w/ a bit of help) to get into Literate Programming form:
https://github.com/WillAdams/gcodepreview/blob/main/literati...
There was a phase, which I also got sucked into at the time, that comments are bad. Problem is, to make your code be so self-explanatory that it conveys business decisions, background stories for how you've arrived here, research-based choices made, you would have to name your variables and functions in a batshit_insane_way_that_obfuscates_behavior_among_the_names. It doesn't make anything better.
Use short names where they're contextually clear. Use long names where they're contextually weird/non-belonging. Use comments to explain the "whys" of your code.
Use short names where they're contextually clear. Use long names where they're contextually weird/non-belonging. Use comments to explain the "whys" of your code.
I still code this way.
The comments that drive the most homicidal behavior are outdated or inaccurate comments rather than no comments.
Sure, but the proportion of code that drives homicidal behavior is heavily weighted towards non-comments. You're a lot more likely to piss off whoever inherits your code with the code that actually does something being bad or a lack of documentation than with comments.
I'm quite fine with no comments but correctly named variables and functions. This can't become out of sync contrarily to "out of band" comments. I take this over commented code with poorly named stuff any day.
I've also seen a lot of comments that restate what the code already says and that's just noise, more work to keep in sync, an additional thing that can fail, and more cognitive load because you have to read twice the same thing (best case, if code and comment are still in sync). That's the result you risk when you think you must comment your code.
I appreciate the occasional comment that explains why something seems overly tricky or weird or not immediately intuitive. Once, I had left such a comment that saved myself years later from making a mistake. Of course, this should be kept at a minimal level. It leads to me liking clear code with few comments the most. (Some guidelines, even if it's not perfect, to limit complexity and spaghetti code help a lot).
Function, class, module documentation is also useful so you don't have to read the whole thing and you know what it's intended to provide (which is slightly different than simply what it provides, and this differences is important).
I've also seen a lot of comments that restate what the code already says and that's just noise, more work to keep in sync, an additional thing that can fail, and more cognitive load because you have to read twice the same thing (best case, if code and comment are still in sync). That's the result you risk when you think you must comment your code.
I appreciate the occasional comment that explains why something seems overly tricky or weird or not immediately intuitive. Once, I had left such a comment that saved myself years later from making a mistake. Of course, this should be kept at a minimal level. It leads to me liking clear code with few comments the most. (Some guidelines, even if it's not perfect, to limit complexity and spaghetti code help a lot).
Function, class, module documentation is also useful so you don't have to read the whole thing and you know what it's intended to provide (which is slightly different than simply what it provides, and this differences is important).
Yep, I think I agree with pretty much all of this. There are a lot of cases where clearer naming can avoid needing comments, but there are also some cases where the code itself won't be clear enough. My personal stance is that in a world where nobody is immune from accidentally making a mistake in logic and writing a bug, comments that clarify the intent of code that might otherwise look strange are valuable for future readers of the code (whether human or LLM); at worst, they can potentially help someone avoid wasting time going down a rabbit hole because Chesterton's fence didn't have a signpost on it, and at best they actually expose gaps in what's handled when someone is able to notice a discrepancy between what's documented and what's actually happening.
Clear code takes precedence over commented code if either of them could be used to solve the problem of communicating what's going on; comments are still useful in the cases where clear code isn't always enough. Of course, being able to discern whether there's a way to make the code cleaner to avoid needing a comment is an art rather than a science, and it's a skill that I think few people excel at (and judging by how so much LLM-generated code is littered with inane comments, one that's also pretty rare in agents)
Clear code takes precedence over commented code if either of them could be used to solve the problem of communicating what's going on; comments are still useful in the cases where clear code isn't always enough. Of course, being able to discern whether there's a way to make the code cleaner to avoid needing a comment is an art rather than a science, and it's a skill that I think few people excel at (and judging by how so much LLM-generated code is littered with inane comments, one that's also pretty rare in agents)
I worked with this guy. He'd write the code, and comment where needed, and then he would ask "How can I make this comment unnecessary?" The answer was usually to rename something, so that what he was doing was obvious.
Nice, I love this. That's pretty satisfying.
Ignorance will always be a better starting point for discovery than wrong assumptions. If you leave comments, they must reflect what the code is actually doing. If during edit it's no longer the case, at least mark them as stale. The next best thing is indeed to remove them.
Both can be true at the same time, we can be equal opportunity murderers who treat lazy verbosity and hippester terse code.
For the record…
“Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability.” — John F Woods in comp.lang.c++ Sep 24, 1991
“Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability.” — John F Woods in comp.lang.c++ Sep 24, 1991
sounds like a recipe for over-commenting. The code should be self-documenting. Comments are for the places where there are dragons.
In a similar vein, here's my favorite prompt: "Please review the tests you've written. Will the tests actually test what they're meant to? If the code breaks, will the test fail?" It's amazing how often LLMs will write tests that don't test anything.
I've seen a lot of human-written tests that wind up testing the testing framework and not the actual code.
yeah but it'll be one or two at a time that you find like that. LLMs will output two dozen tests for one line of real code, where you maybe needed one
My workflow is:
- Write the test first, confirm it fails
- Write the minimum code to make that test pass
- Confirm it is green
TDD like this is a very good system for a lot of things, especially brownfield development - gotta make sure you understand the error space before you know you’ve fixed the error. :D
We still need to discuss this things for real? Aren't they already taken for granted after all this "experimenting" with LLMs? I'm wondering when we will discuss hand coding again without treating it like a taboo anymore. LLMs can be useful in so many ways it's tiring knowing people are delegating the entire source code typing to agents, to me it's like hearing from people that the web is good and we should be happy with it
I wonder how effective it would be to just put the blog's title as a line in your AGENTS.md...
This is kinda the "this could have been an email" of AI complaints.
As an AI acolyte, I strongly believe that AIs should be being trained for this sort of mode by default, but they tend to be optimized (or at least tested) to solve the single shot benchmarks rather than multi-step stuff that you really need in a long term maintainable project.
There is a https://www.scbench.ai/ SlopCodeBench that checks this and a variety of others. These don't seem to often come up when frontier labs are advertising their new models.
This is kinda the "this could have been an email" of AI complaints.
As an AI acolyte, I strongly believe that AIs should be being trained for this sort of mode by default, but they tend to be optimized (or at least tested) to solve the single shot benchmarks rather than multi-step stuff that you really need in a long term maintainable project.
There is a https://www.scbench.ai/ SlopCodeBench that checks this and a variety of others. These don't seem to often come up when frontier labs are advertising their new models.
I continually run codebases through different models to have them look for bad code smells like repeated code. That's been pretty effective. You do have to maintain over time or else you end up with a sloppy mess which I can only imagine compounds.
What do you think of traditional AST-based static analyzers (like SonarQube, Rubocop, etc.) that catch cyclomatic complexity and code duplication deterministically?
You can even put them on the build pipeline, even. No tokens spent at all!
You can even put them on the build pipeline, even. No tokens spent at all!
> continually run codebases through different models
When I have spare usage before a reset, I just throw a part (depending on how much usage left) of a non-critical codebase to refactor overnight and push to PR.
If it's marginally more maintainable/better after review it's good to merge.
When I have spare usage before a reset, I just throw a part (depending on how much usage left) of a non-critical codebase to refactor overnight and push to PR.
If it's marginally more maintainable/better after review it's good to merge.
The article is conflating LLM usage with bad habits.
When you start a project not everything is DRY, and you don't start pulling out shared helpers until they're called for. If you're a slacker and expect the agent to magically fix everything with one-off prompting and only moving forward, it's not going to work. Agents prefer to carry existing patterns forward, just like many humans.
The shared helper example from the article requires intent to refactor. If you ask the agent look for smells and refactor, it will happily assist you with that. If you ask it to add a feature, which happens to add duplication, you get a feature with duplication because you didn't specify anything else.
Better yet, add tooling like static code analyzers (shout out to Credo) to your development pipeline and catch stuff like this regardless of LLM. Verify against a mechanical baseline, with LLM judgement layered on top as-needed.
"The most frustrating part: I thought I was outsourcing maintenance to the LLM, but the slippery slope I found myself on was actually training it to have ever-worsening habits."
That's on you. The LLM is a tool and you're not using it well. Build a good foundation for the agents to anchor on, and you'll get good results moving forward.
When you start a project not everything is DRY, and you don't start pulling out shared helpers until they're called for. If you're a slacker and expect the agent to magically fix everything with one-off prompting and only moving forward, it's not going to work. Agents prefer to carry existing patterns forward, just like many humans.
The shared helper example from the article requires intent to refactor. If you ask the agent look for smells and refactor, it will happily assist you with that. If you ask it to add a feature, which happens to add duplication, you get a feature with duplication because you didn't specify anything else.
Better yet, add tooling like static code analyzers (shout out to Credo) to your development pipeline and catch stuff like this regardless of LLM. Verify against a mechanical baseline, with LLM judgement layered on top as-needed.
"The most frustrating part: I thought I was outsourcing maintenance to the LLM, but the slippery slope I found myself on was actually training it to have ever-worsening habits."
That's on you. The LLM is a tool and you're not using it well. Build a good foundation for the agents to anchor on, and you'll get good results moving forward.
I've seen lots of code that people have maintained for 20 years and its full of these duplication and worse.
In fact I'm sad to say that majority of code I've seen people write and maintain is worse than what LLMs produce today.
Often it is inexperience, sometimes it is willful negligence, but most often it is just tight deadlines and pressure to do finish whatever is being done right now. People know how to do it better, but nobody got the time and budget to actually do it.
LLMs also learned from that.
This. Before LLMs there was copilot which repeated a lot. Then before that we had copy paste and stack overflow.
Most programming best practices were created to solve for the same problem LLMs face: limited context. The principles around well-crafted code strove to make it modifiable by future agents who are not the author. Maintainable code stabilizes around the invariants of the domain it address while providing a spectrum of modifiability to future users, running from UI > configs > cleanly abstracted code > core.
The fact that people have to resort to hacks and tricks to do basic coding tells me that the quality of code generated by these frontier models is mediocre at best. And I’ve had the same happen - the code, the comments, is at the level of a junior developer. AGI my ass.
I have been impressed with them as a “on this line” or “the next couple lines” autocomplete, though.
My first real use with them as that was during an interview with Jetbrains’ assistant enabled and I repeatedly went “oh! Huh!”, so … in that form, it seems very good but that’s first impressions and everything feels like magic at first
My first real use with them as that was during an interview with Jetbrains’ assistant enabled and I repeatedly went “oh! Huh!”, so … in that form, it seems very good but that’s first impressions and everything feels like magic at first
This is an agreeable article, sure, but the idea that an LLM fueled group or team will collectively have this discipline is... idk... bemusing and saddening at the same time.
Or we start writing code without LLMs.
No one is stopping you. It's only if you want someone to pay you for hand writing code that you might feel a certain competitive pressure that makes it economically difficult, let's say.
One reason to write by hand is to have intellectual property, since it was ruled that AI generated code is in the public domain by default, so licensing is hard.
Another thing is competitive edge, if you use claude and your competitors use claude then nothing really gives you an edge. AI is a commodity, not competitive edge.
The competitive pressure should drive human work because it's unique.
Another thing is competitive edge, if you use claude and your competitors use claude then nothing really gives you an edge. AI is a commodity, not competitive edge.
The competitive pressure should drive human work because it's unique.
The competitive edge lies with the higher attraction layer, not the nitty gritty implementation detail (any more). Is that still software programming? The human work lies in the what and why and in broad strokes how
That's not always the case imho.
Think about advances in running inference, any innovation will happen in the details. Higher layer can stack gpu's but the implementation can still be improved.
Often small technical changes like "making a service 5% faster" are worth millions for large companies. That's all implementation.
Often small technical changes like "making a service 5% faster" are worth millions for large companies. That's all implementation.
I don't see why a strong model wouldn't significantly outperform any human in this sort of low level optimization work. We don't hand optimize assembly either.
It's about the competitive edge.
If a public model can do it, everyone has access to it so nobody has advantage.
If you want LLMs to be your advantage you can train your own, that's completely valid.
Let's say you want to have a company that runs inference 5% faster, if everyone can do it your business model is worthless.
If you want LLMs to be your advantage you can train your own, that's completely valid.
Let's say you want to have a company that runs inference 5% faster, if everyone can do it your business model is worthless.
Cat is out of the bag. Other than recreational programming I doubt many will write code without any form of LLM.
There are plenty of us. I have slowed down because I'm reviewing more PRs. That might sound like productivity but the LLM ones take more rounds of feedback.
If everyone is using LLMs then nobody has advantage
In that case, humans with superior skills who can write code become the advantage.
That is important for companies that compete with each other.
In that case, humans with superior skills who can write code become the advantage.
That is important for companies that compete with each other.
> If everyone is using LLMs then nobody has advantage
LLMs are a tool like any other - and like any tool there will be people who are better at utilising the tool to achieve an outcome than other users of the tool.
Those differences typically come down to a combination of experience, in-depth understanding of your subject/objective and an awareness of the strengths and weaknesses of the tool.
TBH the rise of LLMs reminds me a lot of the era when google search emerged. People's ability to utilise a search engine to achieve their aims was massively varied.
* Some people were absolutely useless - they struggled to use a search engine to find anything beyond the most basic of things.
* Others were ok - they'd be able to dig a little deeper, they knew a few of the tricks of the searching trade and they had a bit of an understanding of where to look/how to look for something obscure.
* Some were good - they knew all the key search constraints, they had a good understanding around how data is structured and what keywords and approaches to use when to get to the thing they need
* and some had 'google fu' - those people seemed to have a god-like ability to navigate the internet to find the most obscure things in a matter of seconds.
LLMs are different to search engines but their rise shares many similarities to them - they are changing the rules of the game in a monumental way; they have fundamentally reduced the barriers to entry in many fields.
The skills that made someone valuable in a pre LLM world do still matter, but IMO we're currently starting to go through a major change where the people who learn how to best utilise LLMs within their field will find themselves leapfrogging people with stronger skills who obstinately seek to avoid using the new tools becoming available to them.
LLMs are a tool like any other - and like any tool there will be people who are better at utilising the tool to achieve an outcome than other users of the tool.
Those differences typically come down to a combination of experience, in-depth understanding of your subject/objective and an awareness of the strengths and weaknesses of the tool.
TBH the rise of LLMs reminds me a lot of the era when google search emerged. People's ability to utilise a search engine to achieve their aims was massively varied.
* Some people were absolutely useless - they struggled to use a search engine to find anything beyond the most basic of things.
* Others were ok - they'd be able to dig a little deeper, they knew a few of the tricks of the searching trade and they had a bit of an understanding of where to look/how to look for something obscure.
* Some were good - they knew all the key search constraints, they had a good understanding around how data is structured and what keywords and approaches to use when to get to the thing they need
* and some had 'google fu' - those people seemed to have a god-like ability to navigate the internet to find the most obscure things in a matter of seconds.
LLMs are different to search engines but their rise shares many similarities to them - they are changing the rules of the game in a monumental way; they have fundamentally reduced the barriers to entry in many fields.
The skills that made someone valuable in a pre LLM world do still matter, but IMO we're currently starting to go through a major change where the people who learn how to best utilise LLMs within their field will find themselves leapfrogging people with stronger skills who obstinately seek to avoid using the new tools becoming available to them.
> If everyone is using LLMs then nobody has advantage
People with more capital will always have an advantage. This is a large part why the american market fails to produce convincing competition.
People with more capital will always have an advantage. This is a large part why the american market fails to produce convincing competition.
We're addicted to LLMs.
I agree, but “write code like a human will maintain it” can also be limiting: if LLMs reduce the cost of maintaining more explicit or verbose code, we should use that to raise the standard, not preserve compromises made for human convenience.
Will it? Okay, first we need to ask "which humans" - there are many humans who don't see a point in the things we call best practices. I've work with programmers who are faster than me to getting low bug count code out the door, despite writing 70,000 line functions - he didn't understand why nobody else wanted to add new features to his code.
The standards most "good developer" humans demand were learned from many decades of painful experience about what happens when you do it the other way. These are not only compromises for human convenience, they often are things that we have learned will come back to bite you later even though they just add more work today for no gain.
The standards most "good developer" humans demand were learned from many decades of painful experience about what happens when you do it the other way. These are not only compromises for human convenience, they often are things that we have learned will come back to bite you later even though they just add more work today for no gain.
Aren't LLMs trained on and optimized for human code? In general, anything that is concise is more effective as context for the LLM, whether it be your CLAUDE.md or code, since LLMs are meant to model human language.
Humans can share context outside the code, while LLMs need it to be more explicitly structured inside. And if we keep the slightly verbose good practices that already help humans understand the intent, we kind of get the best of both worlds.
However, an argument can be made that such Literate Programming code can be easier/better for an LLM to work with:
https://news.ycombinator.com/item?id=47300747
https://news.ycombinator.com/item?id=47300747
I disagree.
The general intent is fine, and I'm certainly not abandoning everything we've learned as an industry - but LLMs are not people, people are not LLMs, and there's no reason to believe that the coding practices we've found to be good for humans will be good for LLMs.
Each time we apply a practice like this, we should ask ourselves what problem it was intended to solve, whether that problem still exists for LLMs, and if the existing practice is the best fit for LLMs.
The general intent is fine, and I'm certainly not abandoning everything we've learned as an industry - but LLMs are not people, people are not LLMs, and there's no reason to believe that the coding practices we've found to be good for humans will be good for LLMs.
Each time we apply a practice like this, we should ask ourselves what problem it was intended to solve, whether that problem still exists for LLMs, and if the existing practice is the best fit for LLMs.
Heat death is inevitable in a codebase built mostly by coding agents.
Maybe we should start writing code like the LLM will maintain it. I’d be curious if there are weird optimizations that the LLM can drive that might not be things that help us humans like DRY etc.
Edit: this small things drive me crazy when I’m coding with LLM… which is basically all the time these days, but I also read all the code as well.
Edit: this small things drive me crazy when I’m coding with LLM… which is basically all the time these days, but I also read all the code as well.
The problem of duplicated code described in the article, goes in a different way in reality: AI does not update 4 places in the same way, but implement them a slightly different. I found diverged business logic all the time. For example, file upload dialog for a document with the same meaning: in one place, it accepts pdf only. Another allows to upload pdf or docx. The last accepts pdf, doc, docx, and txt.
That sounds like a good idea, but shipping 10x as many features and bugfixes sounds better.
I started using AI with the best intentions. Checking everything before committing. Improving output by hand if it didn't quite follow the existing code style guidelines or variables were not named as well as they should be. Or if it did something sloppy or hacky.
Now, AI GOES BURRRRRRRRRRRR! If the tests pass it's good to ship. AI can deal with the problems it may create. No problems so far.
I started using AI with the best intentions. Checking everything before committing. Improving output by hand if it didn't quite follow the existing code style guidelines or variables were not named as well as they should be. Or if it did something sloppy or hacky.
Now, AI GOES BURRRRRRRRRRRR! If the tests pass it's good to ship. AI can deal with the problems it may create. No problems so far.
How did you know you're not stuck at a local optimum where the AI could iterate even faster if you enforced higher quality on what it produced?
To make up some hypothetical numbers in order to illustrate with math: if you ship bugfixes 10x faster but then have 11x more bugs you need to fix, that's not a net improvement. Even if it's only 5x more bugs, maybe you could reduce that to 2x if you changed how you worked to only be 8x as fast in a way that produced higher quality code. Similarly, maybe you could cut the time it needed to produce a new feature by 50% if your code were higher quality by moving 20% slower.
My point in all of this isn't that you literally need to work the same way you did before you had these tools, but that framing it as either "move fast and ignore the code" and "use the same exact heuristics you would in the pre-LLM days for what code is acceptable" is a false dichotomy. If you aren't thinking about how effectively you're using these tools and whether there are changes you could make to move even faster because "AI go brrr", I think you've lost the plot in the same way you probably think that other people in this thread have.
To make up some hypothetical numbers in order to illustrate with math: if you ship bugfixes 10x faster but then have 11x more bugs you need to fix, that's not a net improvement. Even if it's only 5x more bugs, maybe you could reduce that to 2x if you changed how you worked to only be 8x as fast in a way that produced higher quality code. Similarly, maybe you could cut the time it needed to produce a new feature by 50% if your code were higher quality by moving 20% slower.
My point in all of this isn't that you literally need to work the same way you did before you had these tools, but that framing it as either "move fast and ignore the code" and "use the same exact heuristics you would in the pre-LLM days for what code is acceptable" is a false dichotomy. If you aren't thinking about how effectively you're using these tools and whether there are changes you could make to move even faster because "AI go brrr", I think you've lost the plot in the same way you probably think that other people in this thread have.
It’s a new form of development. The thing that the author didn’t state is that to work the code base at all, you must also use these tools and workflows.
Manual edits literally aren’t possible. You can’t grok the code growth and the new patterns fast enough to be productive.
This does work. I’ve seen it in real products. Nobody has a real mental model of the code flows. But with enough money in Claude credits it doesn’t matter.
The spend to support this development model is something like $50/day/developer.
Manual edits literally aren’t possible. You can’t grok the code growth and the new patterns fast enough to be productive.
This does work. I’ve seen it in real products. Nobody has a real mental model of the code flows. But with enough money in Claude credits it doesn’t matter.
The spend to support this development model is something like $50/day/developer.
I don't understand what anything you're saying has to do with what I said. My claim is that "groking the code" is not a binary, and you can balance between full vibe mode without ever reading it and requiring that you understand every single line, with the corollary that it's at least plausible that being on the far end of the spectrum where you never read it isn't safe to assume is the global optimum, and your rebuttal seems to be "well it's not the global minimum".
Are you my colleague? It's fine if it's your own personal app, but please don't do this in a large complex codebase in a team. It's entirely depressing. You can use AI and still write good code. I think it's actually probably easier to write maintainable code with AI.
> That sounds like a good idea, but shipping 10x as many features and bugfixes sounds better.
This work great until you reach a certain size, then good (or even "not bad") code is required otherwise the model spins its wheel trying to ensure the change is correct.
The way I've measured how good/bad the code is (for AI) is to have one "baseline fixed change" that I measure how long time it takes to implement. Always in the beginning (less than 10K LOC, as just some measurement), this baseline change will take 2-3 minutes. As you add more code, the same change starts to take 5-6 minutes, and once you hit 1 million LOC, it can take as long as 10 minutes, even though the change is the same.
It's when this baseline task starts to take longer time, that you need to update the design/architecture/layout/whatever, to better fit the task/domain, and to actually make it easy to maintain and still possible to add changes without spending 10 minutes. So its at this point you refactor, and once done, the baseline task will again be easy for the model to do.
So yeah, if all you do is smaller projects, then "shipping 10x as many features" is easy and doable, for the lifetime of the projects. But once the projects start to accumulate technical debt, the model will have a harder time making sure the changes are correct, and suddenly "shipping 2x as many features" is maybe doable, but you could still have had 10x if you just spend slightly more time on the actual design and architecture of the program.
This work great until you reach a certain size, then good (or even "not bad") code is required otherwise the model spins its wheel trying to ensure the change is correct.
The way I've measured how good/bad the code is (for AI) is to have one "baseline fixed change" that I measure how long time it takes to implement. Always in the beginning (less than 10K LOC, as just some measurement), this baseline change will take 2-3 minutes. As you add more code, the same change starts to take 5-6 minutes, and once you hit 1 million LOC, it can take as long as 10 minutes, even though the change is the same.
It's when this baseline task starts to take longer time, that you need to update the design/architecture/layout/whatever, to better fit the task/domain, and to actually make it easy to maintain and still possible to add changes without spending 10 minutes. So its at this point you refactor, and once done, the baseline task will again be easy for the model to do.
So yeah, if all you do is smaller projects, then "shipping 10x as many features" is easy and doable, for the lifetime of the projects. But once the projects start to accumulate technical debt, the model will have a harder time making sure the changes are correct, and suddenly "shipping 2x as many features" is maybe doable, but you could still have had 10x if you just spend slightly more time on the actual design and architecture of the program.
Yes, this resonates. I have noticed things slow down over time. But fortunately my app will never grow that big so I don't think it will be an issue.
The solution, as you say, is probably to break it down into isolated sub-components that are only aware of each other's APIs and nothing more.
The solution, as you say, is probably to break it down into isolated sub-components that are only aware of each other's APIs and nothing more.
Yeah, for personal software, enterprise practices don't make sense.
> shipping 10x as many features and bugfixes sounds better
I understand you're excited about the tool, but for the sake of earnest discussion here, maybe commenters like yourself can tone the hype down to plausibility?
Claims like this are just nonsense. It's not how product development works.
How do you even have so many bugs left to fix if the tool is so fast and productive? Surely, you didn't have a backlog of tens of thousands of bugs that you're still chewing through? And of course, the volume of new bugs much be minimal since the AI-composed additions introduce "no problems so far". If it works like you say, which we'll accept in good faith per HN guidelines, you must have exhausted your backlog long ago.
And if you've indeed exhausted your bug backlog long ago (incredible!), you're left to talking about shipping "10x as many features". Yet no product has a limitless capacity for features. Nobody would want to use software so bloated and churning that was gaining features at such a pace. And who is designing and specifying them so quickly anyway? If it works like you say, which we again accept in good faith, you must have stalled out on your feature list long ago.
If the AI indeed allows you to "[ship] 10x as many features and bugfixes", and we take what you say in good faith, then one of the following seems to be implied:
* you've fixed all your bugs and blew through your mature feature designs already, leaving your AI agents sitting idle for all but a few hours a week, while you're bottlenecked on feature design and your software product is bloated beyond imagination
* your coding productivity before AI was absolutely glacial by industry standards such that "10x" productivity for you is actually much closer to "0.5-2x" for others
Any insight into which of those it might be?
I understand you're excited about the tool, but for the sake of earnest discussion here, maybe commenters like yourself can tone the hype down to plausibility?
Claims like this are just nonsense. It's not how product development works.
How do you even have so many bugs left to fix if the tool is so fast and productive? Surely, you didn't have a backlog of tens of thousands of bugs that you're still chewing through? And of course, the volume of new bugs much be minimal since the AI-composed additions introduce "no problems so far". If it works like you say, which we'll accept in good faith per HN guidelines, you must have exhausted your backlog long ago.
And if you've indeed exhausted your bug backlog long ago (incredible!), you're left to talking about shipping "10x as many features". Yet no product has a limitless capacity for features. Nobody would want to use software so bloated and churning that was gaining features at such a pace. And who is designing and specifying them so quickly anyway? If it works like you say, which we again accept in good faith, you must have stalled out on your feature list long ago.
If the AI indeed allows you to "[ship] 10x as many features and bugfixes", and we take what you say in good faith, then one of the following seems to be implied:
* you've fixed all your bugs and blew through your mature feature designs already, leaving your AI agents sitting idle for all but a few hours a week, while you're bottlenecked on feature design and your software product is bloated beyond imagination
* your coding productivity before AI was absolutely glacial by industry standards such that "10x" productivity for you is actually much closer to "0.5-2x" for others
Any insight into which of those it might be?
OP is making toys, not enterprise software
How long has "so far" been?
I second that question
Since November.
Yeah... in at least some circumstances, "maintainable" means, like, 20 years. 8 months is not an adequate test.
Yeah, the flip side of the article is that Fable level models can fix the majority of codebases created from the past 3 years and one shot it to a fixable state that is "human maintainable"
That sounds like a good idea but how do you know what you’re shipping?
One does not exclude the other
Man, I bet Jia Tan is simultaneously kicking themselves and having a field day. All those years of wasted effort gaining trust and making good contributions to try to land a sophisticated backdoor into a tool via layers of indirection, and then not long after we have devs just going “I don’t need to read this code, or prioritise, or think about what makes sense, just prompt for fractals of kitchen sinks and ship it”.
Anthropic themselves have admitted you don’t need much to poison LLMs¹. I can’t wait for us to discover the backdoors that are being introduced. I hope it happens soon so people get to their senses. Bah, what am I saying, when (not if) that happens, the response will just be to throw more LLMs at it.
¹ https://www.anthropic.com/research/small-samples-poison
Anthropic themselves have admitted you don’t need much to poison LLMs¹. I can’t wait for us to discover the backdoors that are being introduced. I hope it happens soon so people get to their senses. Bah, what am I saying, when (not if) that happens, the response will just be to throw more LLMs at it.
¹ https://www.anthropic.com/research/small-samples-poison
It's a good time to archive pre-LLM copies of the programs you use and make sure you can build them.
I find myself doing this but then I worry that the slop will just compound and 3, 6, 12 months from now as my services scale I'll have a harder time operating them. Maybe I'm wrong.
The bigger problem is the number of things you don't understand will grow substantially from under your feet, and then you'll slip on it.
I have been on a quest to get AI to code like me, using pi harness, and any model that it can support. I'm mostly a Ruby programmer, so here's my journey so far.
1. Created a "coding" skill with every practice I posted on my blog website, as well as a bunch I had in the queue to blog about but never got a chance, summarized into "do this" kind of language. This is more or less good for any PL, but a bit Ruby-slanted.
2. Created a "rails" skill because that's my framework, where similarly I explained my approach to architecting Rails apps.
3. Created a "writing" skill where I literally fed it my entire blog, and tried to get it to write more like me (mixed success, weaker models did better for some reason, but I haven't tried the GPT-5.6 series yet).
4. Next, I really wanted it to format code exactly like I would, even things like "let's make this `if` into a ternary, let's split these assignment groups with a line break, let's vertically align here, but not there", but with GPT-5.5 (my primary driver up until yesterday) there's almost no way to make a skill of reasonable size that will be consistently applied. So instead I instructed the agent to write me a Rubocop cop for every single situation I ever encounter where I would've formatted code slightly differently. This was quite powerful, because I usually thought of linters as enforcers of objective consistency decisions in the codebase, but this was me going full format nazi on the agent. And the nice part is that these cops can contain some non-autocorrectable feedback, which AI will follow.
5. I'm working on a review loop where the most easily missed parts above get double checked. This is the first thing I'm doing with pi subagents. (I feel like I'm getting better results if I don't use subagents for code exploration, other tool calls). The idea here is that I want reviews to be in the implementation loop. I always read/review code in the end, but so want it to have gone through the review loop before it gets to me. Since implementation is already context-heavy, I want to be able to orchestrate this loop without adding to the implementation context.
6. I'm also adjusting all of the above for GPT-5.6, because it requires less guidance, so I'm carefully trimming the verbiage to save tokens.
So far the results have been surprisingly good. I want to experiment with GLM-5.2 running under these constraints.
One invariant in all of this: I read the code. My end product is not working software, it's good code (which also incidentally produces working software).
1. Created a "coding" skill with every practice I posted on my blog website, as well as a bunch I had in the queue to blog about but never got a chance, summarized into "do this" kind of language. This is more or less good for any PL, but a bit Ruby-slanted.
2. Created a "rails" skill because that's my framework, where similarly I explained my approach to architecting Rails apps.
3. Created a "writing" skill where I literally fed it my entire blog, and tried to get it to write more like me (mixed success, weaker models did better for some reason, but I haven't tried the GPT-5.6 series yet).
4. Next, I really wanted it to format code exactly like I would, even things like "let's make this `if` into a ternary, let's split these assignment groups with a line break, let's vertically align here, but not there", but with GPT-5.5 (my primary driver up until yesterday) there's almost no way to make a skill of reasonable size that will be consistently applied. So instead I instructed the agent to write me a Rubocop cop for every single situation I ever encounter where I would've formatted code slightly differently. This was quite powerful, because I usually thought of linters as enforcers of objective consistency decisions in the codebase, but this was me going full format nazi on the agent. And the nice part is that these cops can contain some non-autocorrectable feedback, which AI will follow.
5. I'm working on a review loop where the most easily missed parts above get double checked. This is the first thing I'm doing with pi subagents. (I feel like I'm getting better results if I don't use subagents for code exploration, other tool calls). The idea here is that I want reviews to be in the implementation loop. I always read/review code in the end, but so want it to have gone through the review loop before it gets to me. Since implementation is already context-heavy, I want to be able to orchestrate this loop without adding to the implementation context.
6. I'm also adjusting all of the above for GPT-5.6, because it requires less guidance, so I'm carefully trimming the verbiage to save tokens.
So far the results have been surprisingly good. I want to experiment with GLM-5.2 running under these constraints.
One invariant in all of this: I read the code. My end product is not working software, it's good code (which also incidentally produces working software).
What I'm seeing is the organizations that had written code standards:
* define the software layers, their function, and the max depth allowed
* establish a corp code formatter for each language, along with a process to PR it
* establish a business vocabulary and what the terms mean
* establish a data dictionary, make it part of the database schema/table/col comments
Are far more successful with LLMs. You _should_ have been doing this years ago, but with LLMs its a super power.
* define the software layers, their function, and the max depth allowed
* establish a corp code formatter for each language, along with a process to PR it
* establish a business vocabulary and what the terms mean
* establish a data dictionary, make it part of the database schema/table/col comments
Are far more successful with LLMs. You _should_ have been doing this years ago, but with LLMs its a super power.
## HARD RULE - design scope must always be maintained and no function should ever be longer than XXX lines and no class should have more than Y methods. Create new classes and subclasses and refactor until the criteria are met.
You'd be surprised how readable this makes the code when XXX is about the size of your vertical screen and Y is relatively small.
You'd be surprised how readable this makes the code when XXX is about the size of your vertical screen and Y is relatively small.
Similarly, I try to follow an “around 400 lines per MR” (violations can exist for test code if something is particularly gnarly).
I’ll build whole features and then break them apart into several MRs that chain off each other.
Everyone who has seen this style has been really grateful for it and finds my code much more readable. I encourage and embody the pattern everywhere I go.
Exception: For mass find/replace or auto-linter changes, that’s all one MR, and is usually pair programmed so the other person can confirm that’s all I did, still easing cognitive load.
I’ll build whole features and then break them apart into several MRs that chain off each other.
Everyone who has seen this style has been really grateful for it and finds my code much more readable. I encourage and embody the pattern everywhere I go.
Exception: For mass find/replace or auto-linter changes, that’s all one MR, and is usually pair programmed so the other person can confirm that’s all I did, still easing cognitive load.
but then you end up with a clusterfuck of classes?
You’d be surprised how often this doesn’t end up happening, especially in languages that are supportive of this style:
Kotlin, Python and Typescript, to name a few. A lot of functions you write are helper functions, wrapper functions, system functions, etc and all 3 languages support making things modules of interconnected concepts, extension functions, etc.
You can make code very readable this way - arguably more readable.
Have you ever had so many tests for a single class that you’ve broken the test class into a package and have a whole file / test class for each big method? Same idea! :)
Kotlin, Python and Typescript, to name a few. A lot of functions you write are helper functions, wrapper functions, system functions, etc and all 3 languages support making things modules of interconnected concepts, extension functions, etc.
You can make code very readable this way - arguably more readable.
Have you ever had so many tests for a single class that you’ve broken the test class into a package and have a whole file / test class for each big method? Same idea! :)
Start asking your peers to explain what their code does and alot will be surprised that they dont know
The key idea here is that your codebase is context that will be used for future changes. And context determines the model’s output, so it’s still worth having a well-designed codebase.
Easier said than done to be honest, especially if there are many people (and their agents) pushing code. It’s hard to keep up these days.
Easier said than done to be honest, especially if there are many people (and their agents) pushing code. It’s hard to keep up these days.
I’m not so sure this matters. My team manages a couple pretty new projects and I still see LLM tools doing this. I’m starting to suspect that vendors are building in these behaviors to ensure the output compiles (never throw an exception, null check every variable no matter what, never change a function or method but copy or inline its code and change that, etc.)
I think I would prefer code that is clear, understandable and simple even if it doesn’t compile and needs some straightforward polishing.
I think I would prefer code that is clear, understandable and simple even if it doesn’t compile and needs some straightforward polishing.
Could someone show me what a shared helper would look like in this case? This code looks easily readable to me and I fear abstracting it will just make it harder to reason about. Is it just variable_with_a_better_name = that conditional?
What you want is to guard at the outset of each API call is the same thing -- whether the user is not suspended, active, any other number of things (including more things as you add more functionality), so you want to shift the entire validation logic to its own module.
We therefore want to encapsulate the logic of all users being "qualified". I think the best way to realize this is to try to say in as few words as possible what we want. We want the user.toBe.qualified, but we can write that even more efficiently, user.isQualified(), so we can ASK at the top of each API `if !user.isQualified()` and then fail loudly and quickly if so, and then go do something afterwards otherwise. We presumably expect multiple users that will have a property of being qualified, so let's use a class:
```js
class User { constructor(data) { this.isAuthenticated = data.isAuthenticated; this.hasActiveLicense = data.hasActiveLicense; \\ many more details... }
// Now encapsulate the boolean property of being qualified, for all Users, in one place
isQualified() { return (this.isAuthorized && this.hasActiveLicense && this.hasPaidInFull && this.hasAdminPermissions); } }
// Now, we can use our isQualified() property at each of our API guard clause by checking if the user is NOT qualified:
if (!user.isQualified()) { return res.status(403).json({ "error": "Unauthorized access requested."}); }
// Critically, the API guard clause remains identical even if we change the criteria for validation and what it means to be "qualified"
```
There are of course many other ways to solve this problem beyond this approach. For instance, you could export a function called isUserQualified(user) (or more likely userId) then call it somewhat similarly:
```js
if (!isUserQualified(user)) { return res.status(403).send("Error: Unauthorized access requested"); }
```
The other approach I like is to use a factory pattern to build a userSession with function arrow notation. That's really helpful when you are getting raw data back from a database call, say as a JSON object. That would look like this:
```js
const createUserSession = (userData) => { return { ...userData, // here we use the ...notation for convenience but don't trust this as secure) isQualified() { return ( this.isAuthorized && !this.isSuspended ); } }; };
// Then you instantiate a user session from the request like this:
const user = createUserSession(res.session.user); if (!user.isQualified()) { return res.status(403).send("Error: Unauthorized"); }
```
There are actually loads other approaches too, like using class inheritance (define a parent User class and child QualifiedUser class, for instance), or types. I would say that readability here is less a concern than the issue that you have multiple APIs and if you refactor or change the logic for qualified users, now you have to refactor your most sensitive attack surface at multiple points. It's just safer to have that rewrite only happening once, wherever you put it, in my view.
We therefore want to encapsulate the logic of all users being "qualified". I think the best way to realize this is to try to say in as few words as possible what we want. We want the user.toBe.qualified, but we can write that even more efficiently, user.isQualified(), so we can ASK at the top of each API `if !user.isQualified()` and then fail loudly and quickly if so, and then go do something afterwards otherwise. We presumably expect multiple users that will have a property of being qualified, so let's use a class:
```js
class User { constructor(data) { this.isAuthenticated = data.isAuthenticated; this.hasActiveLicense = data.hasActiveLicense; \\ many more details... }
// Now encapsulate the boolean property of being qualified, for all Users, in one place
isQualified() { return (this.isAuthorized && this.hasActiveLicense && this.hasPaidInFull && this.hasAdminPermissions); } }
// Now, we can use our isQualified() property at each of our API guard clause by checking if the user is NOT qualified:
if (!user.isQualified()) { return res.status(403).json({ "error": "Unauthorized access requested."}); }
// Critically, the API guard clause remains identical even if we change the criteria for validation and what it means to be "qualified"
```
There are of course many other ways to solve this problem beyond this approach. For instance, you could export a function called isUserQualified(user) (or more likely userId) then call it somewhat similarly:
```js
if (!isUserQualified(user)) { return res.status(403).send("Error: Unauthorized access requested"); }
```
The other approach I like is to use a factory pattern to build a userSession with function arrow notation. That's really helpful when you are getting raw data back from a database call, say as a JSON object. That would look like this:
```js
const createUserSession = (userData) => { return { ...userData, // here we use the ...notation for convenience but don't trust this as secure) isQualified() { return ( this.isAuthorized && !this.isSuspended ); } }; };
// Then you instantiate a user session from the request like this:
const user = createUserSession(res.session.user); if (!user.isQualified()) { return res.status(403).send("Error: Unauthorized"); }
```
There are actually loads other approaches too, like using class inheritance (define a parent User class and child QualifiedUser class, for instance), or types. I would say that readability here is less a concern than the issue that you have multiple APIs and if you refactor or change the logic for qualified users, now you have to refactor your most sensitive attack surface at multiple points. It's just safer to have that rewrite only happening once, wherever you put it, in my view.
The title of this post reminds me of a favorite quote "Write code as if the next person to maintain it is a homicidal maniac who knows where you live!"
Wonder what LLM op is using? I find that using one LLM to review the other catches a lot of this. For example having Codex do the work then CC /simplify and /code-review. Claude md has three lines one of which is DRY.
You still have to look at the diffs because it won’t have external knowledge to the codebase or make the best decisions.
It does find bugs and keep things simple.
You still have to look at the diffs because it won’t have external knowledge to the codebase or make the best decisions.
It does find bugs and keep things simple.
Very much this. LLMs are not producing code humans can maintain unless you take your time with them and still care about the quality of the output.
Maybe someone has the perfect claude.md that solves this problem but I have not seen it.
Maybe someone has the perfect claude.md that solves this problem but I have not seen it.
CLAUDE.md (or AGENTS.md) is not good place to put all code change rules, because these rules would dillute the context and "distract" the agent e.g. during bugs triage or business analysis.
Instead modularize the knowledge with skills and specialized MD files. Agent should lazy load what is needed to do focused work.
Skills have usage description metadata, but with free files you can simply instruct agent with CLAUDE.md to load them, e.g.: "Before you attempt to change any frontend code first load and follow `docs/{JS|HTML|CSS}_coding_rules.md`".
Instead modularize the knowledge with skills and specialized MD files. Agent should lazy load what is needed to do focused work.
Skills have usage description metadata, but with free files you can simply instruct agent with CLAUDE.md to load them, e.g.: "Before you attempt to change any frontend code first load and follow `docs/{JS|HTML|CSS}_coding_rules.md`".
I have a meta review command, instructions is more or less:
- run the commands /code-review and /simplify in finding mode (read-only, no fix)
- run another review command internal to my company
Collect all findings and classify into Blocker/Maybe/Nits.
Very simple, but effective: I like it very much!
Collect all findings and classify into Blocker/Maybe/Nits.
Very simple, but effective: I like it very much!
Good advice, in this age of just moving forward and onward, having the common courtesty here will not only save yourself, but also anyone else that needs to wade through everything....
Write code like a coworker you really like will maintain it.
Write code like a coworker you really like will maintain it.
Write code like a human will maintain it — and that human is you at 3am six months from now, fueled by regret and cold coffee.
The first line of my AGENTS.md is: You are an engineer who writes code for *human brains, not machines*.
Taken from: https://github.com/zakirullin/cognitive-load/blob/main/READM...
Taken from: https://github.com/zakirullin/cognitive-load/blob/main/READM...
It might just be me, but AI has made my code more human-maintainable. They've been complaining about obsolete comments, separation of concerns, testability, global mutable state...
(Also performance and security issues, addressing which doesn't make the code more readable, but does make the program itself more robust.)
That being said... I have found them weirdly unsuitable for some tasks though, e.g. asking frontier LLMs to assist me with game development, I found that they were not able to add simple features to a simple Pong clone (nor even port a working Pong implementation) without constantly breaking things. (Yes, Pong, from 1972!)
So, I want to say YMMV, but just the past 2 weeks, my own mileage has varied very much! They seem to be extremely domain specific.
"Half the time, it works every time!"
(Also performance and security issues, addressing which doesn't make the code more readable, but does make the program itself more robust.)
That being said... I have found them weirdly unsuitable for some tasks though, e.g. asking frontier LLMs to assist me with game development, I found that they were not able to add simple features to a simple Pong clone (nor even port a working Pong implementation) without constantly breaking things. (Yes, Pong, from 1972!)
So, I want to say YMMV, but just the past 2 weeks, my own mileage has varied very much! They seem to be extremely domain specific.
"Half the time, it works every time!"
AI is so miserable for this. It's so focused on doing what you ask, it forgets that there's stuff worth doing that you didn't ask for, like defining reasonable abstractions.
Getting away from stuff like this is exactly why I want to use AI. When I say "implement this for idle but active users," I _want_it to define isUserActiveIdle() and stuff these 4 conditionals in it. Having to check the generated code for stuff like this undoes, like .... all the benefit of using AI.
AI makes all these little decisions for us. I can about some of these decisions. I just want to notice when it's doing this without having to make my eyes bleed reading 10k lines of generated code a day.
Getting away from stuff like this is exactly why I want to use AI. When I say "implement this for idle but active users," I _want_it to define isUserActiveIdle() and stuff these 4 conditionals in it. Having to check the generated code for stuff like this undoes, like .... all the benefit of using AI.
AI makes all these little decisions for us. I can about some of these decisions. I just want to notice when it's doing this without having to make my eyes bleed reading 10k lines of generated code a day.
It’s amazing what people will flag here sometimes. Guess this is of those threads where you can’t speak ill of LLM’s.
I have very mixed results with LLMs, but I actually find they're really GOOD at, unprompted, pointing out existing code that is redundant and could be simplified and so on.
Where it really, really struggles for me is in existing complex infra codebases.
Where it really, really struggles for me is in existing complex infra codebases.
I think the usable counterpoint here is that you can refrain from excessively DRY'ing code up and defer it until later.
There's a huge cost to Clean-Code-style DRY'ing of your codebase which is that you wind up creating all kinds of little functions that all add cognitive overhead to reading your codebase, and that premature DRY'ing can lead to picking the wrong abstractions.
If you can tolerate a bunch of copypasta, you can sit back after you've written 5,000 or 10,000 lines of code and can look at the actual result, instead of speculating, and make better-informed decisions about how to clean the codebase up. If you're making those decisions the first time you copy a bit of code around, you can wind up making a worse mess, since you often don't know where you're going.
There's a huge cost to Clean-Code-style DRY'ing of your codebase which is that you wind up creating all kinds of little functions that all add cognitive overhead to reading your codebase, and that premature DRY'ing can lead to picking the wrong abstractions.
If you can tolerate a bunch of copypasta, you can sit back after you've written 5,000 or 10,000 lines of code and can look at the actual result, instead of speculating, and make better-informed decisions about how to clean the codebase up. If you're making those decisions the first time you copy a bit of code around, you can wind up making a worse mess, since you often don't know where you're going.
My threshold is three. The third time I duplicate code/behavior is when I start to think about DRYing said code/behavior.
Write code like an agent will never touch it, that's my motto.
(Because it's true.)
(Because it's true.)
So the new prompt is "Write code like a human will maintain it" ?
code review is a dead end. the only way building with AI makes sense is in secure systems that can run unaudited code.
code review has always been a liability fig leaf. it is much harder to understand a system from reading the code than writing the code. if AI can write code 100X faster than humans it is simply impossible for humans to do real code review. effectively it is just pretending to do code review, and then running unaudited code without the proper systemic security guardrails in place.
code review has always been a liability fig leaf. it is much harder to understand a system from reading the code than writing the code. if AI can write code 100X faster than humans it is simply impossible for humans to do real code review. effectively it is just pretending to do code review, and then running unaudited code without the proper systemic security guardrails in place.
> There's a much cleaner way to do this - a shared helper
disagree, then you end up with something this this
function checkAll(target, conditions) { return Object.entries(conditions).every(([path, expected]) => { const value = path.split('.').reduce((o, k) => o?.[k], target); return typeof expected === 'function' ? expected(value, target) : value === expected; }); }
and const ok = checkAll({ user, account }, { 'user.isActive': true, 'user.isSuspended': false, 'account.status': 'open', 'user': u => u.hasPermission('read'), // predicate for the trickier bit });
how is that better?
disagree, then you end up with something this this
function checkAll(target, conditions) { return Object.entries(conditions).every(([path, expected]) => { const value = path.split('.').reduce((o, k) => o?.[k], target); return typeof expected === 'function' ? expected(value, target) : value === expected; }); }
and const ok = checkAll({ user, account }, { 'user.isActive': true, 'user.isSuspended': false, 'account.status': 'open', 'user': u => u.hasPermission('read'), // predicate for the trickier bit });
how is that better?
No, you've created a generic condition checker, which is where all of your complexity comes from. Further, you've left the actual check to be duped in all callers.
No. I will generate code in a way that makes it easier for clankers to maintain it, because they will actually be doing the maintaining. In practice, this means that most of my time is dedicated to improving the repo harness because the state of the repo harness directly determines the quality of the codebase as a whole.
At a minimum, there should be precommit checks and CI workflows that cause PRs to fail if the documentation is not up-to-date and synced with the other docs.
Then regular codebase analysis for improvement. This is where you find the bug sources, make new modules for consolidation, and get those +5000/-4000 PRs that people stuck in the world of manual code review hate.
At a minimum, there should be precommit checks and CI workflows that cause PRs to fail if the documentation is not up-to-date and synced with the other docs.
Then regular codebase analysis for improvement. This is where you find the bug sources, make new modules for consolidation, and get those +5000/-4000 PRs that people stuck in the world of manual code review hate.
It's interesting that the author didn't mention considering updating their agentic code review prompt to keep an eye out for repetitive/duplicate code.
For writing for human consumption, I’ve taken to hand writing the docs and having agents review and suggest improvements.
Wild(er) idea: expect future AI to maintain current AI-written code.
I think the biggest conceit here is the expectation that humans will continue to do this task in the medium to long term. This was good advice in the past but when inference is ubiquitous and most code ends up being Claudewritten anyways, there is little point. If you are writing C for NASA/ESA then yes of course. For the 99% of the rest of us, probably not so much in the coming years.
Before LLMs we didn't have time for code quality. LLMs make our jobs faster, so now we have time to dedicate to code quality, right?
I argue that is the case in my experience: https://javiergonzalez.io/blog/on-clean-code-2026/
Do you think the steel birds with the food in will come back if we light torches in long lines on the plateau again?
> Who cares about DRY? You don't have to be the one updating the same long conditional in four different files - the AI will just do it for you! Right?
One pattern I've really been enjoying lately has to do with a language called haxe. It's designed to be compiled into other languages (java, python, others). There's this extension called reflaxe which lets you make mini compilers for compiling haxe into pretty much anything.
So if I have anything with duplicate structure... like maybe I want the CLI subcommands to resemble the http API.
Previously I was using OpenAPI spec's and generators for this, but they wound up feeling like a black box that I ended up debugging all the time. The reflaxe setup is much more generic. So you end up with this mountain of generated code, but unlike LLM-generated code it's obviously generated (in .../generated/thingy.py or whatever) and a comment at the top of the file says where to look to learn how it's generated). I'm generating docs this way, accessor functions for database tables and SQL for making those tables, matching clients and servers in different languages... it replaces a lot of purpose built tools with just one, and LLMs are pretty good at it.
So even though the repo is large, the parts of it that are authoritative remain small. I find LLM's manage this boundary much better because it's so crisp an in their face. But they have to be told to do this, otherwise they'll just create context-size problems that they'll later struggle with.
Of course you could do this with yaml files or some such, but unlike yaml, haxe has a type system, you can write tests in it, so the agent can notice fundamental flaws before the generation happens... with yaml those flaws would be propagated into the generated code before they'd get noticed.
One pattern I've really been enjoying lately has to do with a language called haxe. It's designed to be compiled into other languages (java, python, others). There's this extension called reflaxe which lets you make mini compilers for compiling haxe into pretty much anything.
So if I have anything with duplicate structure... like maybe I want the CLI subcommands to resemble the http API.
$ foo bar --baz 6 # produces similar output as HTTP GET /foo/bar?baz=6
Previously I was using OpenAPI spec's and generators for this, but they wound up feeling like a black box that I ended up debugging all the time. The reflaxe setup is much more generic. So you end up with this mountain of generated code, but unlike LLM-generated code it's obviously generated (in .../generated/thingy.py or whatever) and a comment at the top of the file says where to look to learn how it's generated). I'm generating docs this way, accessor functions for database tables and SQL for making those tables, matching clients and servers in different languages... it replaces a lot of purpose built tools with just one, and LLMs are pretty good at it.
So even though the repo is large, the parts of it that are authoritative remain small. I find LLM's manage this boundary much better because it's so crisp an in their face. But they have to be told to do this, otherwise they'll just create context-size problems that they'll later struggle with.
Of course you could do this with yaml files or some such, but unlike yaml, haxe has a type system, you can write tests in it, so the agent can notice fundamental flaws before the generation happens... with yaml those flaws would be propagated into the generated code before they'd get noticed.
I think we have to accept the innovation, adapt to new reality and use it to our advantage, my 2 cents on this.
What happens when shit hits the fan in my exp is that I have to crack open the codebase and debug some portion of it, so I can explain it to myself in order to be able to explain what is wrong to the LLM.
Otherwise what I have found is that the LLM will add a new if statement which will handle the newly discovered issue and you start stacking them ifs. As the article mentions LLM's unlike humans aren't lazy, they will copy, paste add patches for every issue, why bother think and understand root cause :d.
So as part of our review we have a rule against that as well.
Otherwise what I have found is that the LLM will add a new if statement which will handle the newly discovered issue and you start stacking them ifs. As the article mentions LLM's unlike humans aren't lazy, they will copy, paste add patches for every issue, why bother think and understand root cause :d.
So as part of our review we have a rule against that as well.
Humans will do this as well, especially inexperienced junior SWEs. Adding a new boolean parameter and some if statements here and there. After a while a seemingly simple function takes four boolean parameters that each control a little bit of what the function does.
The benefit is that a human who is a junior might need at least a few weeks to months of guidance to have a good taste of when to duplicate and when to DRY. An LLM likely already has good judgment, and your prompt merely needs to be activate this judgment.
The benefit is that a human who is a junior might need at least a few weeks to months of guidance to have a good taste of when to duplicate and when to DRY. An LLM likely already has good judgment, and your prompt merely needs to be activate this judgment.
Been getting these vibe coded PRs ugh code PR submitter can't even explain
Coding Agents are the best reason to write Clean Code (TM)
Humans have been writing unmaintainable code well before LLMs came along.
But LLMs can do it much faster and more consistently.
They had good teachers. :-)
Counterpoint: This no longer matters because we are not going back to hand-writing these functions. These patterns were designed to make code easier for humans to read and write, but that is no longer the primary way software is built.
Code structure still matters for cost effectiveness and performance over time
https://arxiv.org/abs/2605.20049 https://arxiv.org/abs/2605.13280
https://arxiv.org/abs/2605.20049 https://arxiv.org/abs/2605.13280
Counterpoint: as long as context don't rot or it's less effective that starts maintaining repetitions only slightly different. Also
> we are not going back to hand-writing these functions
do you really think there isn't a good chunk, if not the majority outside some bubbles, of developers that still hand code? Crazy to hear, I bet you're not a programmer
> we are not going back to hand-writing these functions
do you really think there isn't a good chunk, if not the majority outside some bubbles, of developers that still hand code? Crazy to hear, I bet you're not a programmer
The change is exponential and happening daily. The future is smaller teams spending a lot of money on AI credits.
If it really is exponential intelligence should have already exploded. Go give away your certainties on a seer's forum
I run various forms of workflows to run dedicated QA, code review (of various flavors) simplification and text simplification agents. Especially the simplification goes a long way to remove dumb padding, duplication and efficiency. Dedicated docs/comment simplification is also becoming more and more necessary on recent models. For things like feature development in my workflow, the majority of time the agents run and tokens spent is critiquing the code from various perspectives and it's not close.
Of course, this doesn't solve the overall issue that agents don't write code like you and still requires a lot of human attention in planning and code review out to clean up leftover issues, and e.g. challenge bad assumptions about architecture and real-world context. A human is still very much needed to cull the slop (or, more gratuitously: align the agent). But IME it does help avoid a lot of pitfalls and makes the code high quality a lot more quickly.
Of course, this doesn't solve the overall issue that agents don't write code like you and still requires a lot of human attention in planning and code review out to clean up leftover issues, and e.g. challenge bad assumptions about architecture and real-world context. A human is still very much needed to cull the slop (or, more gratuitously: align the agent). But IME it does help avoid a lot of pitfalls and makes the code high quality a lot more quickly.
I'm not sure this guy is using the same LLMs as we do. A small AGENTS.md or CLAUDE.md easily prevents issues like that.
The fact this is controversial is wild and a grim sign for an already struggling industry.
Have a bit of a contrarian view on this tl;dr don’t write code for human consumption if you use AI; BUT you have to accept AI coding lock in and change how you work.
Funny enough, discussed this yesterday
Stop Optimizing Code for Humans https://youtube.com/live/eLn4-XA-KdQ?feature=share
Funny enough, discussed this yesterday
Stop Optimizing Code for Humans https://youtube.com/live/eLn4-XA-KdQ?feature=share
Given all the hype that LLMs have got and the valuations these AI companies are getting, I am disappointed at how even the "best" coding agents degrade over time.
WTF - I need to implement a review command to guide to do its job properly.
Can you imagine any other industry charging people money for a product like this ?
WTF - I need to implement a review command to guide to do its job properly.
Can you imagine any other industry charging people money for a product like this ?
I absolutely will not write corporate code like humans are maintaining it anymore, because I don’t have any confidence actual humans will be maintaining it.
For personal projects, I can trust that I myself will be maintaining things so I still write things like it matters, but I do not extend the trust to others.
For personal projects, I can trust that I myself will be maintaining things so I still write things like it matters, but I do not extend the trust to others.
For every feature prompt I do I have about 2 or 3 maintainance prompts. For example. Check code for smells and dead code. Check modularity of our application logic. Check for possible performance issues. Check for optimizations. Etc etc.
"Hey Sol, write this like your kids will maintain it, because I'm the sure hell not"
SOLID is a good idea that most coders I know don’t follow because they can’t be arsed. Turns out AI is really good at writing SOLID code (if you tell it to) and SOLID code is much easier for AI to reason about.
Yawn. So people are discovering SWE hasn’t actually changed in its basic principles. Is this going to be the new “how I use LLMs” article? Good night
Just run weekly cron job to assess code quality and highlight candidates for refactoring. In addition to doing the same in each PR, of course, but things can get through.
this article according to pangram was AI generated, ironic
my LLM does this pretty well with my coaching. i use a good model and i encourage it to make such improvements. and since the llm is trained on human maintainers it works fine.
linting tools, static analysis, CPD, etc. These are all old things you can continue to use and are much more robust than anything you can prompt. These should be standard when using LLMs. In fact, you can tighten the rules even more enforcing more restrictions so you ONLY get the output you want. put this behind a pre-commit hook and a CI job that runs on a PR, and it will work wonders.
You can have all the prompts you want on top of this, but if you don't have this automated stuff running behind the scenes, you aren't serious about these issues.
Looking through some of these comments here, I see lots of people rewriting concrete rules in markdown willing to spend tokens on the hope AI won't miss it where an actual program won't.
You can have all the prompts you want on top of this, but if you don't have this automated stuff running behind the scenes, you aren't serious about these issues.
Looking through some of these comments here, I see lots of people rewriting concrete rules in markdown willing to spend tokens on the hope AI won't miss it where an actual program won't.
Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live. Code for readability.
— John F. Woods (1991)
— John F. Woods (1991)
AI isnt taking my job. my company is supporting local AI for development. who ever comes after me will have the same hardware and models or better. unless a MBA is put in charge, my boss and predecessors can maintain and build out as needed.
bottom up AI use seems a godsend compared to the corporate AI rat race.
i setup some slop reporting systems and ensured my boss knows theyre great starting points but serious use requires real time investment.
bottom up AI use seems a godsend compared to the corporate AI rat race.
i setup some slop reporting systems and ensured my boss knows theyre great starting points but serious use requires real time investment.
And hope it works?
I’m pretty sure many people who use AI to write emails or blog posts add "make it sound like a human wrote it" to their prompts. We all know what the result usually looks like.
If AI is writing my code, I'd rather have it focus purely on correctness and efficiency than on making the code easy to read.
heck! I might even ask it to imitate Arthur Whitney’s style.
/s
I’m pretty sure many people who use AI to write emails or blog posts add "make it sound like a human wrote it" to their prompts. We all know what the result usually looks like.
If AI is writing my code, I'd rather have it focus purely on correctness and efficiency than on making the code easy to read.
heck! I might even ask it to imitate Arthur Whitney’s style.
/s
Invictus0(10)
u right
Mine starts with “Enter plan mode. Examine the differences on this branch vs. main. Consider: ...” and proceeds to a bullet list of things.
Any time I notice something in code review and have to get the agent to fix it.. I throw it on the list!
My list is like 200 items now. Know what? Agents don’t care that they just got a wall of generic feedback, they happily look into all the bullet points.
I added “ensure the new things aren’t duplicating code that already exists elsewhere” and it gave me such a surprise - it really truly started planning cleanups!
We are just scratching the surface. We have to give tools to our tools so they can use them to be better tools for us.