Write code like a human will maintain it
70 points
59 minutes ago
| 20 comments
| unstack.io
| HN
cadamsdotcom
21 minutes ago
[-]
Write yourself a /review command. That is an empty markdown file at `.claude/commands/review.md`. In it, put a checklist of things the agent should look for. When you’re ready to have your agent review the code, type `/review`. The checklist will be examined and it’ll plan out some findings to ask you if you want them fixed.

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.

reply
dataviz1000
6 minutes ago
[-]
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...

reply
ebiester
4 minutes ago
[-]
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.
reply
alexpotato
44 minutes ago
[-]
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"

reply
hansonkd
33 minutes ago
[-]
The comments that drive the most homicidal behavior are outdated or inaccurate comments rather than no comments.
reply
saghm
19 minutes ago
[-]
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.
reply
minraws
29 minutes ago
[-]
Both can be true at the same time, we can be equal opportunity murderers who treat lazy verbosity and hippester terse code.
reply
gowld
20 minutes ago
[-]
Put your home address in the comments. Problem solved.
reply
exabrial
4 minutes ago
[-]
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.

reply
phaser
4 minutes ago
[-]
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...

reply
carimura
27 minutes ago
[-]
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.
reply
8cvor6j844qw_d6
21 minutes ago
[-]
> 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.

reply
wxw
8 minutes ago
[-]
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.

reply
schnebbau
36 minutes ago
[-]
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.

reply
saghm
3 minutes ago
[-]
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.

reply
embedding-shape
19 minutes ago
[-]
> 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.

reply
schnebbau
4 minutes ago
[-]
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.

reply
hansonkd
30 minutes ago
[-]
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"
reply
matt_kantor
30 minutes ago
[-]
How long has "so far" been?
reply
schnebbau
10 minutes ago
[-]
Since November.
reply
pauletienney
24 minutes ago
[-]
I second that question
reply
exabrial
3 minutes ago
[-]
One does not exclude the other
reply
geraneum
10 minutes ago
[-]
That sounds like a good idea but how do you know what you’re shipping?
reply
latexr
10 minutes ago
[-]
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

reply
carimura
26 minutes ago
[-]
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.
reply
cmrdporcupine
21 minutes ago
[-]
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.
reply
francisofascii
11 minutes ago
[-]
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?
reply
DCKing
10 minutes ago
[-]
One thing that can help a lot here is to spend a lot of tokens on QA steps. It's easy to see agents writing code very quickly and then just dumping the code in a PR to make it somebody else's concern. But agents can also speed up a lot of back and forth on bad code.

I've tried 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.

reply
dsagent
33 minutes ago
[-]
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.

reply
imhoguy
11 minutes ago
[-]
CLAUDE.md is not good place to put all code change rules, because these rules "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 refer to the from the CLAUDE.MD with e.g.: "Before you attempt to change any code first load `...`".

reply
cebert
38 minutes ago
[-]
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.
reply
trjordan
15 minutes ago
[-]
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.

reply
bdcravens
29 minutes ago
[-]
Humans have been writing unmaintainable code well before LLMs came along.
reply
BadBadJellyBean
28 minutes ago
[-]
But LLMs can do it much faster and more consistently.
reply
bdcravens
24 minutes ago
[-]
They had good teachers. :-)
reply
andrewjneumann
26 minutes ago
[-]
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

reply
deadbabe
32 minutes ago
[-]
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.

reply
Invictus0
41 minutes ago
[-]
If you are still handwriting code you are ngmi
reply
amarcheschi
14 minutes ago
[-]
Just this morning I was trying to scrape nitter, for funsies. One hour and neither gemini nor kimi were able to write something working, despite trying selenium (or playwright), beautiful soup, and a specific library that can be used to scrape it.

I eventually read the library docs and managed to build a scraper for what I wanted in a few mins. Llms are great for a lot of things, but sometimes you stumble in something that's just outside of what they know/can do and you're sol. And of all the thinks, I didn't expect they would fail at this, to be honest the opposite

reply
latexr
2 minutes ago
[-]
It’s bizarre to me that so many people feel the need to keep parroting this corporate talking point. What do you care? If you think people who eschew LLMs for coding “are not going to make it” or “are going to get left behind”¹, then let them. More opportunities for you, right? Go do your own thing.

¹ As if “moving forward” or “progress” were always a positive. It’s not. Just look at how many regulations we have to forbid or curtail uses of stuff we found to be harmful.

reply
gdulli
17 minutes ago
[-]
People are so desperate for this to be true. Maybe it comes from a subconscious recognition that their own self-imposed deskilling will inevitably catch up with them.
reply
OtherShrezzing
25 minutes ago
[-]
It's unlikely that AI will get to the point where it makes handwritten coders redundant, and then not immediately be at the point where vibe coders are redundant too. So if you earnestly take the position that handwriting code is a "ngmi" type activity, you also need to take the position that the vibe coder (or agent- assisted-developer/loop-architect, or whatever its nom de guerre is this week) is "ngmi".
reply
theultdev
19 minutes ago
[-]
He just means the development pace has picked up with AI.

I've been doing this for 15 years, I love coding manually.

However, with AI-assistance I can do projects in 3 days what would take 6 months.

It's not vibe coding, everything is controlled, reviewed, understood, refined by me in the end.

But still the dev time is magnitudes faster. I would not hire anyone that is adverse to AI.

I'm actually happier. With age and a family I was getting a bit slower.

Now I have more time to spend with them AND I'm getting more done. Including personal projects I never had the bandwidth for.

reply
tom_
23 minutes ago
[-]
I type it in myself, but occasionally i do write notes out by hand if I'm thinking about something away from my desk.
reply
klabb3
34 minutes ago
[-]
Why stop there? If you _use_ handwritten products you’re ngmi. I only use vibe coded operating systems, JavaScript sandboxes, compilers, TLS libraries, databases, rendering engines..
reply
tjwebbnorfolk
18 minutes ago
[-]
This is cute reductio ad absurdum, but it does nothing to refute the basic point made
reply
matt_kantor
28 minutes ago
[-]
If you don't understand the software you're creating (handwritten or not) you are ngmi.
reply
cmrdporcupine
19 minutes ago
[-]
None of us are "going to make it"

Gotta touch grass.

reply
cyanydeez
33 minutes ago
[-]
if your skillset is tied to corporate bullshit, yourre better off buying lottery tickets
reply
jdw64
24 minutes ago
[-]
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)

reply
cyanydeez
38 minutes ago
[-]
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.

reply
ing33k
22 minutes ago
[-]
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

reply
tristan666
57 minutes ago
[-]
u right
reply