> The code they [LLMs] produce is often fine. It works. It passes tests. It might ship as-is.
I don't disagree, but I've been thinking about this a bit: a lot of _human_ written code was/is less-than-fine. And a lot of human devs didn't understand the context when they wrote it.
I'm not advocating that we fire devs, or evangelizing that LLms are awesome. But I do wish there was a slightly more honest take on the pre-LLM world: it's not just about cost reduction, it's about solving some long-term structural deficiencies of industry.
croemer 47 minutes ago [-]
Reads at least partially like LLM writing, for example:
> When code production gets cheap, the cost doesn't disappear. It migrates.
> It was true then. It is unavoidably true now.
superfrank 17 minutes ago [-]
Maybe it's just because I grew up spending way too much time on the internet, but I write like that and have since well before LLMs. As much as people like to attribute that style to AI, I don't think it's the dead giveaway that people act like it is.
lamename 13 minutes ago [-]
Exactly. HN darling Paul Graham writes this way.
I find the constant critique of punchy style a bit tiring. It would be more productive for the grandparent to think about the content and state an opinion.
amarant 6 minutes ago [-]
I swear the worst part about llms are their critics.
code_duck 10 minutes ago [-]
AI learned it from somewhere.
danaw 20 minutes ago [-]
i disagree and even if assisted the points are still valid
xienze 9 minutes ago [-]
Like clockwork, every single thread about something AI-related has someone expressing their disgust at passages of LLM-written text. In many cases by the same people who are enthusiastically embracing LLM-generated software. Why don't we show the same level of contempt for LLM-authored software as we do for even the slightest hint of LLM-authored text in a blog post?
bluebands 4 minutes ago [-]
code is not user-facing, functionality, ux, and specs are!
there are many apps with ai-generated ideas, specs, and functionality. nobody uses them because of the contempt.
in either case, the part that's user-facing is ai-resistant
lamename 31 minutes ago [-]
[flagged]
Forgeties79 19 minutes ago [-]
If I want a boring, rote LLM answer I will prompt it myself. I don’t read blogs to have a middleman between me and a prompt.
jraph 16 minutes ago [-]
It matters whether something is written using an LLM even if we put aside the ethical aspects. Firstly, if your text is deadly boring to read, your point might not get across optimally and one might not just be interesting reading slop. Secondly, you might just been reading the LLM's opinion, and I'm just not interested neither. Thirdly, even if you are just using the LLM as an assistant, we know that your opinion itself may be influenced by the suggestions and since you are still under the impression you are writing yourself (which you are somewhat, not saying), you may internalize the suggestions as your own opinion. There are recent (probably imperfect) studies about this stuff.
lamename 11 minutes ago [-]
I mostly agree with everything you said. Do you feel the same way about code written by an LLM?
rogerrogerr 20 minutes ago [-]
LLMs are running a gish gallop at Internet scale. It is not necessary or possible to disprove every sequence of tokens that emerges from one.
Forming a human opinion about slop is like asymmetrical warfare. Or maybe a closer analogy is a Gish Gallop. It can be generated with way less effort than it takes to comprehend it, much less form a coherent opinion on it.
pmmucsd 21 minutes ago [-]
Related (maybe the same thing): Whenever an agent is planning there are often architecture and product choices that it asks humans to make. None of this intent is captured in the code or comments. We started a decisions.md file and updated CLAUDE.md and AGENTS.md to create an entry in the decisions.md file everytime it has to ask a human about what to do. It captures the intent so at least we have doc that describes why certain choices were made.
Human coders have the same problem too - oftentimes the most important question that future maintainers have of the code is "Why was this decision made?", but that's not captured anywhere in the code itself.
The right place for this is usually in the design doc or commit message, and robust engineering organizations will ensure that commits are cross-referenced back to design and requirements docs so you can trace decisions from git blame back to the actual rationale.
The same process also works pretty well with LLMs. Google, for example, is internally championing a process where the engineer has a dialog with the LLM to generate a design doc, oftentimes with an adversarial LLM to poke holes in the design. Once the design is fully specified, the last step is to ask the LLM to turn the design doc into code. This creates a human-readable artifact that traces the decisions that the human and AI collaboratively made, which then can be traced back from the code.
CharlesW 7 minutes ago [-]
> Whenever an agent is planning there are often architecture and product choices that it asks humans to make. None of this intent is captured in the code or comments.
It must be in order to have an effective AI-assisted software engineering workflow, but it's not something that's magically done for you (usually). Knowledge management of project context is everything. Even the little music app I'm building has >100 ADRs (https://en.wikipedia.org/wiki/Architectural_decision), and that's just one form of project memory.
alexhans 15 minutes ago [-]
To me, design files living in the repo are what captures these high and low level decisions. They should express intent which is paramount for automation.
Where are you keeping your design? If it's a WYSIWYG doc like word, what would it take for you to switch to a more text driven world?
crooked-v 9 minutes ago [-]
The structure https://acai.sh/ uses feels to me like a decent starting point for this kind of thing that avoids the "single giant file" issue.
olsondv 9 minutes ago [-]
When I generate code with AI, I will read through each change as it makes them (babysitting). If I don’t understand it, then I ask for explanation right away. At least by the end I have a grasp on what each change does and the reasoning. Then, I can make a PR and highlight the same info for my reviewer and for longevity. Our codebase style is not to litter comments everywhere. We go back to the code review for details and discussion. Obviously, this only works if the changes are small.
andybak 1 hours ago [-]
Personally I've found one of the biggest gains with coding agents is in helping me read code. Actually - that's a lie. I don't read the code. Mostly (unless my spidey-sense goes off) I ask the LLM to read the code and tell me what it does.
And then I make a decision based on that.
I guess I'm wondering if the article is missing have the picture. Yes - AI is wrong some of the time (and that % varies based on a host of variables). But it can read code as well as just write it. And that does matter as it changes the trade-offs this article is weighing up.
Aurornis 6 minutes ago [-]
There are times when reading the code is necessary, but oh boy are LLMs so much faster at finding the part of the codebase I want to read.
Several projects I work on call into or interact with gigantic codebases. A couple years ago I would have to allocate 30 minutes some times to either trace through the code base or setup and attach a debugger to step through the code until I found the part I needed to know about.
Now I send an LLM to go find it and it comes back with a list of files and line numbers in minutes.
It’s still not perfect. I had a codebase walk this morning where even GPT-5.5 extra high failed to find something I knew was in there on the first pass. It got it with some more directed prompting. If you delegate trust 100% to an LLM you will get bit eventually.
dilyevsky 9 minutes ago [-]
The "It’s harder to read code than to write it" was always silly. The example spolsky gives to support it is basically "devs like to rewrite other devs code, therefore reading is hard" which is obviously bunch of nonsense. That's like saying reading poetry is harder than writing poetry because poets keep writing new poems despite the fact that Shakespeare already wrote it. Now that you can recruit LLM to explain any complicated codebase to you it's even less true.
foobarian 52 minutes ago [-]
It's been pretty great for ramping up into codebases too. "Give me a summary of project in current checkout in markdown form."
copperx 36 minutes ago [-]
do you enjoy reading markdown? I don't, even with the editor in preview mode.
kuboble 20 minutes ago [-]
I'm actually asking claude to make me eli5 htmls with svg diagrams of the code I want to understand.
Once I even asked him to create for me a manim video about it.
y3ahd0g 13 minutes ago [-]
I like to constrain it as much as possible to ignore variables and function names; the human stuff.
With a new code base my first goal understand how it CRUDs state. What structures and what operations?
Less concerned at the outset if its sorting carrots or processing orders for shirts.
AI seems to work way better for me when I tell it to ignore the use case and focus on surfacing runtime and mathematical operations embedded in the code.
Constraints on new abstraction and telling it to stick to math terms and types and objects also seems to help avoid hallucinations and layers of useless indirection.
esafak 47 minutes ago [-]
It lets you understand the code base at reduced granularity when you want. Or zoom in beyond the written lines to explain _why_ some code is the way it is.
chris_st 29 minutes ago [-]
I asked Claude to tell me why something was implemented the way it was, and got an excellent response. One data point, would love to hear more examples.
rectang 10 minutes ago [-]
I agree, Claude has been pretty great at explaining code. It even does well at explaining to me old code that I wrote by hand — including both non-intuitive quirks and flaws.
Claude in its default configuration has untapped potential for explaining and documenting code because it defaults to writing no comments. I added this to my global CLAUDE.md and so far so good:
# Comments
Keep existing comments unless they're wrong
or stale. Err slightly toward adding short
explanatory comments for non-obvious code.
ai_fry_ur_brain 24 minutes ago [-]
Why not just read the code.. Ya'll are literally letting your brain atrophy by using llms this way.
casper14 19 minutes ago [-]
How do I know this comment isn't just AI?
aspenmartin 15 minutes ago [-]
Why not just read the assembly?
kadhirvelm 56 minutes ago [-]
Curious what other teams are doing to keep encouraging people to think critically about their code? I’ve been finding it harder to keep people motivated, keep them engaged with all the changes coming in. And I can’t blame them, it’s been overwhelming. Is everyone else just using more AI..?
zeeveener 46 minutes ago [-]
Personally, guiding junior teammates down the path away from purely "Writer of Code" to "Implementer of Functionality" has been working well for me.
If you get them involved in the design process, they feel heard. Feeling heard is one surefire way to have a person feel involved. Feeling involved fosters a sense of ownership and pride which in turn helps keep a person engaged.
copperx 35 minutes ago [-]
Management 101.
somewhatgoated 23 minutes ago [-]
More AI is always the answer.
nabbed 1 hours ago [-]
I worried this blog post was going to pivot into a marketing pitch for some product, but no, it just describes the issue where the AI tool that generates your code probably won't document its reasons for the choices it makes. That documentation problem exists in the pre-AI era too, except that the reasons might exist in the heads of your co-workers and could possibly be teased out.
I know nothing about AI code generation (or about AI in general), but I wonder if you could include in your prompt a request that the AI describe the reasons for its choices and actually include those reasons as comments in the code.
localhoster 54 minutes ago [-]
I think the issue that majority of agentic developers don't understand their design fully. Those holes, perviously, were have to be closed by a person eventually, and inherently you gain understanding in the process.
This is not the case eny more. I never thought LLMs write bad solutions, but when you let it think for you you loose something important, understanding.
And when something brekas, some people consider this being a proof that the llm is the problem. And in a sense it is. But you are also to blame.
And that's exactly the issue with this all industry - in order to move faster you don't need to "type" faster. A person bashing his hands on the keyboard randomly at top velocity can get pretty high wpm.
In order to move master you need to _think_ faster, be _snappier_ and _sharper_ and most people aren't.
I like how one of my colleagues phrased it in a company meeting. He asked one of the c levels "for llm s to 10x me, I need to let them make all decitions and dictate intentions. By percentage, how much of the code you want me to _know_?"
jnovek 1 hours ago [-]
The AI can't really describe its reasoning, though. It can only look at its context history and find a justification (which it will then present as reasoning). In my experience asking the model "why did you do that" carries substantial hallucination risk.
0gs 1 hours ago [-]
True, though I have found that forcing (I use an agent skill to do this) an LLM's agent to document the reasoning behind each "decision" it makes seems to lead to better decision-making. Or at least, more justifiable decisions (even if the justification is bad).
dalmo3 18 minutes ago [-]
While you're technically correct, I found that a simple "give me the strongest arguments for and against this, cite your sources" works wonders.
ddosmax556 1 hours ago [-]
Perfectly possible IME, it just requires more time. Even if you understand all the (important) parts of your code and validate it, Ai still helps with productivity a lot. It's just not as fast as blindly vibe coding - not at first at least. Agents on their own without checks, and superficial prompts without understanding, result in agents either introducing bugs, or if you have an appropriate test harness, painfully slow, in my experience. It requires skill to use an agent effectively.
andybak 1 hours ago [-]
Isn't one of the common criticisms of AI code that it's a bit too keen to write extensive comments - even when they probably aren't needed?
rectang 34 minutes ago [-]
The default for Claude today is "no comments". Here's a conversation I had with Claude about it recently.
---
Me: I've notice that Claude is deleting my comments and tends not to insert many of its own. I don't want to go too crazy, but can we modify CLAUDE.md to dial up the comments a little? Like, try not to delete comments that are still relevant, and add a few explanatory comments.
Claude: [... proposal for modifying CLAUDE.md...]
Claude: Want me to apply this, tweak the wording, or place it differently? Note that your global ~/.claude/CLAUDE.md-style instructions (visible to me as system guidance) currently say "default to writing no comments" — the project-level rule above will override that for this repo, which is what you want.
Me: Where is this rule that says "default to writing no comments"? That seems crazy?
Claude: That text is part of the system prompt I'm given by Claude Code itself — it's not in any file in your project or in your ~/.claude/ config. It's baked into the harness's default instructions to the model.
Claude: Specifically, two lines from my system prompt:
Claude: Under "Doing tasks": "Default to writing no comments. Only add one when the WHY is non-obvious..."
Claude: Under "Text output": "In code: default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max."
mbauman 1 hours ago [-]
Well the comments tend to be superfluous "whats" (describing the code itself) instead of the more helpful "whys." And they're almost never the most useful "why nots".
idle_zealot 1 hours ago [-]
> And they're almost never the most useful "why nots".
Really? I find that Claude really likes to write "why nots" in comments when iterating on implementations and fixing bugs, to the extent that the comments grow into spot-logs of overly-specific documentation of what was tried and why it was scrapped.
Semaphor 1 hours ago [-]
IME the comments are not useful though. I'm not the biggest fan of AI code, but the codes still way higher quality than the "this is what this does" comments
zeeveener 44 minutes ago [-]
Isn't this what good commit messages are intended to address? If a person has gone so far as to allow an agent to write all their code, they're likely having it commit on their behalf too.
Writing a skill / set of rules around what makes a good commit message would encourage the LLM to record it's reasoning (however much we truly consider it to be "reasoning").
rectang 51 minutes ago [-]
By default, Claude is set to avoid comments. Eventually I got tired of it deleting my own explanatory comments and overrode the behavior with an addition to CLAUDE.md.
I think Claude is just behaving like all those programmers who make a VERY BIG DEAL about how much they HATE HATE HATE comments that might reiterate what the code does so will go to extreme measures to avoid them.
radicalbyte 47 minutes ago [-]
Very few developers do that especially on early / key parts of the codebase.
_diyar 47 minutes ago [-]
I think a huge gap in the market today is documentation that is both easy for humans to navigate and understand, but also readily ingestible for agents.
allthetime 38 minutes ago [-]
Self generating docs based on docstring comments are great. LLMs are capable of generating architectural overview docs from these. What more do you need?
gojomo 38 minutes ago [-]
The context of when that previous experience - Heartland outsourcing to India – happened would be helpful. The 90s? The 00s? The 10s?
lamename 27 minutes ago [-]
The link in the article that is right near the words you're talking about links to a wikipedia page that says the book is from 2005. So I conclude it was 2005 or soon after
1 hours ago [-]
54 minutes ago [-]
htx80nerd 1 hours ago [-]
>The cost of producing code has collapsed. AI tools can generate functional, adequate, perfectly average code at a speed and cost that would have been unimaginable even five years ago. And like the outsourcing wave of the early 2000s, the economics are real and rational. Nobody is wrong for using these tools. The code they produce is often fine. It works. It passes tests. It might ship as-is.
After using AI for months (Claude, Gemini, ChatGPT) it is extremely rare for their code to work 'as is' first shot and almost always requires several iterations and cleaning up edge-cases.
When it does work 'first shot' it's usually when it's transferring existing working code to a new project which is slightly different.
bluebands 2 minutes ago [-]
try gpt-5.5-xhigh fast in codex mac app, preferably with TDD and /goal, with a clearly defined end result
it's unbelievable, it will do the iterations for you, it will easily work 12 hours straight until it's a good output
simonw 39 minutes ago [-]
Have you tried the "use red/green TDD" trick?
I believe that increases the chances of one-shot code working, though it's also possible that it did that against Opus 4.5 and isn't necessary against Opus 4.7 but I haven't spotted the difference yet.
synapsehire 6 minutes ago [-]
[flagged]
Rendered at 20:45:21 GMT+0000 (Coordinated Universal Time) with Vercel.
I don't disagree, but I've been thinking about this a bit: a lot of _human_ written code was/is less-than-fine. And a lot of human devs didn't understand the context when they wrote it.
I'm not advocating that we fire devs, or evangelizing that LLms are awesome. But I do wish there was a slightly more honest take on the pre-LLM world: it's not just about cost reduction, it's about solving some long-term structural deficiencies of industry.
> When code production gets cheap, the cost doesn't disappear. It migrates.
> It was true then. It is unavoidably true now.
I find the constant critique of punchy style a bit tiring. It would be more productive for the grandparent to think about the content and state an opinion.
there are many apps with ai-generated ideas, specs, and functionality. nobody uses them because of the contempt.
in either case, the part that's user-facing is ai-resistant
https://en.wikipedia.org/wiki/Gish_gallop
The right place for this is usually in the design doc or commit message, and robust engineering organizations will ensure that commits are cross-referenced back to design and requirements docs so you can trace decisions from git blame back to the actual rationale.
The same process also works pretty well with LLMs. Google, for example, is internally championing a process where the engineer has a dialog with the LLM to generate a design doc, oftentimes with an adversarial LLM to poke holes in the design. Once the design is fully specified, the last step is to ask the LLM to turn the design doc into code. This creates a human-readable artifact that traces the decisions that the human and AI collaboratively made, which then can be traced back from the code.
It must be in order to have an effective AI-assisted software engineering workflow, but it's not something that's magically done for you (usually). Knowledge management of project context is everything. Even the little music app I'm building has >100 ADRs (https://en.wikipedia.org/wiki/Architectural_decision), and that's just one form of project memory.
Where are you keeping your design? If it's a WYSIWYG doc like word, what would it take for you to switch to a more text driven world?
And then I make a decision based on that.
I guess I'm wondering if the article is missing have the picture. Yes - AI is wrong some of the time (and that % varies based on a host of variables). But it can read code as well as just write it. And that does matter as it changes the trade-offs this article is weighing up.
Several projects I work on call into or interact with gigantic codebases. A couple years ago I would have to allocate 30 minutes some times to either trace through the code base or setup and attach a debugger to step through the code until I found the part I needed to know about.
Now I send an LLM to go find it and it comes back with a list of files and line numbers in minutes.
It’s still not perfect. I had a codebase walk this morning where even GPT-5.5 extra high failed to find something I knew was in there on the first pass. It got it with some more directed prompting. If you delegate trust 100% to an LLM you will get bit eventually.
Once I even asked him to create for me a manim video about it.
With a new code base my first goal understand how it CRUDs state. What structures and what operations?
Less concerned at the outset if its sorting carrots or processing orders for shirts.
AI seems to work way better for me when I tell it to ignore the use case and focus on surfacing runtime and mathematical operations embedded in the code.
Constraints on new abstraction and telling it to stick to math terms and types and objects also seems to help avoid hallucinations and layers of useless indirection.
Claude in its default configuration has untapped potential for explaining and documenting code because it defaults to writing no comments. I added this to my global CLAUDE.md and so far so good:
If you get them involved in the design process, they feel heard. Feeling heard is one surefire way to have a person feel involved. Feeling involved fosters a sense of ownership and pride which in turn helps keep a person engaged.
I know nothing about AI code generation (or about AI in general), but I wonder if you could include in your prompt a request that the AI describe the reasons for its choices and actually include those reasons as comments in the code.
This is not the case eny more. I never thought LLMs write bad solutions, but when you let it think for you you loose something important, understanding. And when something brekas, some people consider this being a proof that the llm is the problem. And in a sense it is. But you are also to blame. And that's exactly the issue with this all industry - in order to move faster you don't need to "type" faster. A person bashing his hands on the keyboard randomly at top velocity can get pretty high wpm. In order to move master you need to _think_ faster, be _snappier_ and _sharper_ and most people aren't.
I like how one of my colleagues phrased it in a company meeting. He asked one of the c levels "for llm s to 10x me, I need to let them make all decitions and dictate intentions. By percentage, how much of the code you want me to _know_?"
---
Me: I've notice that Claude is deleting my comments and tends not to insert many of its own. I don't want to go too crazy, but can we modify CLAUDE.md to dial up the comments a little? Like, try not to delete comments that are still relevant, and add a few explanatory comments.
Claude: [... proposal for modifying CLAUDE.md...]
Claude: Want me to apply this, tweak the wording, or place it differently? Note that your global ~/.claude/CLAUDE.md-style instructions (visible to me as system guidance) currently say "default to writing no comments" — the project-level rule above will override that for this repo, which is what you want.
Me: Where is this rule that says "default to writing no comments"? That seems crazy?
Claude: That text is part of the system prompt I'm given by Claude Code itself — it's not in any file in your project or in your ~/.claude/ config. It's baked into the harness's default instructions to the model.
Claude: Specifically, two lines from my system prompt:
Claude: Under "Doing tasks": "Default to writing no comments. Only add one when the WHY is non-obvious..."
Claude: Under "Text output": "In code: default to writing no comments. Never write multi-paragraph docstrings or multi-line comment blocks — one short line max."
Really? I find that Claude really likes to write "why nots" in comments when iterating on implementations and fixing bugs, to the extent that the comments grow into spot-logs of overly-specific documentation of what was tried and why it was scrapped.
Writing a skill / set of rules around what makes a good commit message would encourage the LLM to record it's reasoning (however much we truly consider it to be "reasoning").
I think Claude is just behaving like all those programmers who make a VERY BIG DEAL about how much they HATE HATE HATE comments that might reiterate what the code does so will go to extreme measures to avoid them.
After using AI for months (Claude, Gemini, ChatGPT) it is extremely rare for their code to work 'as is' first shot and almost always requires several iterations and cleaning up edge-cases.
When it does work 'first shot' it's usually when it's transferring existing working code to a new project which is slightly different.
it's unbelievable, it will do the iterations for you, it will easily work 12 hours straight until it's a good output
I believe that increases the chances of one-shot code working, though it's also possible that it did that against Opus 4.5 and isn't necessary against Opus 4.7 but I haven't spotted the difference yet.