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

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

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.

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

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.

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

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`

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.

Why wouldn't it already just do this though?

How long has "so far" been?

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

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.

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.

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!

Or a dynamic workflow. $$$ but lots of coverage.

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.

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

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

Exactly. I follow a similar workflow. I am still writing code by hand. Not all code. Parts are generated by Opus.

I like to also compliment the model on its very fashionable shoes as well, they love the flattery.

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

sounds like a recipe for over-commenting. The code should be self-documenting. Comments are for the places where there are dragons.

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

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.

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.

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

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

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.

Just pull the slot machine lever

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.

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.

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.

The comments that drive the most homicidal behavior are outdated or inaccurate comments rather than no comments.

I've seen a lot of human-written tests that wind up testing the testing framework and not the actual code.

Do you think it matters that it's a different model?

Or is it more about the review process and a context reset?

Pairs nicely with the fact that smell is the sense most likely to be experienced differently between two people :)

It's a good time to archive pre-LLM copies of the programs you use and make sure you can build them.

Not duplicating code is literally best practice. Why would it deviate from 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

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.

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.

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.

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.

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

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.

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.

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

Both can be true at the same time, we can be equal opportunity murderers who treat lazy verbosity and hippester terse code.

I have personally not found value in a different model. The review itself often is good.

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

Yeah... in at least some circumstances, "maintainable" means, like, 20 years. 8 months is not an adequate test.

Yeah, for personal software, enterprise practices don't make sense.

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.

I still code this way.

If it really is exponential intelligence should have already exploded. Go give away your certainties on a seer's forum

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.

Yeah, I miss the days of having perfectly deterministic humans writing our code.

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.

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.

Put your home address in the comments. Problem solved.

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

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.

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

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.

I moved after I wrote the comment. It's hard to keep everything up to date.

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.

My hypothesis is that Claude is inclined to write so many comments as a way of doing additional thinking

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

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.

Yeah, it's short form memory or something. Like writing a todo list.

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.

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.

Nice, I love this. That's pretty satisfying.

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.