How to effectively write quality code with AI (opens in new tab)

I second this. This* is the matter against which we form understanding. This here is the work at hand, our own notes, discussions we have with people, the silent walk where our brain kinda process errors and ideas .. it's always been like this since i was a kid, playing with construction toys. I never ever wanted somebody to play while I wait to evaluate if it fits my desires. Desires that often come from playing.

Outsourcing this to an LLM is similar to an airplane stall .. I just dip mentally. The stress goes away too, since I assume the LLM will get rid of the "problem" but I have no more incentives to think, create, solve anything.

Still blows my mind how different people approach some fields. I see people at work who are drooling about being able to have code made for them .. but I'm not in that group.

That's also how I feel.

I think you have every right to doubt those telling us that they run 5 agents to generate a new SAAS-product while they are sipping latté in a bar. To work like that I believe you'll have to let go of really digging into the code, which in my experience is needed if want good quality.

Yet I think coding agents can be quite a useful help for some of the trivial, but time consuming chores.

For instance I find them quite good at writing tests. I still have to tweak the tests and make sure that they do as they say, but overall the process is faster IMO.

They are also quite good at brute-forcing some issue with a certain configuration in a dark corner of your android manifest. Just know that they WILL find a solution even if there is none, so keep them on a leash!

Today I used Claude for bringing a project I abandoned 5 years ago up to speed. It's still at work in progress, but the task seemed insurmountable (in my limited spare time) without AI, now it feels like I'm half-way there in 2-3 hours.

I still do this, but when I'm reviewing what's been written and / or testing what's been built.

How I see it is we've reverted back to a heavier spec type approach, however the turn around time is so fast with agents that it still can feel very iterative simply because the cost of bailing on an approach is so minimal. I treat the spec (and tests when applicable) as the real work now. I front load as much as I can into the spec, but I also iterate constantly. I often completely bail on a feature or the overall approach to a feature as I discover (with the agent) that I'm just not happy with the gotchas that come to light.

AI agents to me are a tool. An accelerator. I think there are people who've figured out a more vibey approach that works for them, but for now at least, my approach is to review and think about everything we're producing, which forms my thoughts as we go.

Exactly. 30 years ago a mathematician I knew said to me: "The one thing that you can say for programming is that it forces you to be precise."

We vibe around a lot in our heads and that's great. But it's really refreshing, every so often, to be where the rubber meets the road.

Historically software engineering has been seen as "assembly line" work by a lot of people (see all the efforts to outsource it through spec handoffs and waterfall through the years) but been implemented in practice as design-as-you-build (nobody anticipates all the questions or edge cases in advance, software specs are often an order of magnitude simpler than the actual number of branches in the code).

For mission-critical applications I wonder if making "writing the actual code" so much cheaper means that it would make more sense to do more formal design up front instead, when you no longer have a human directly in the loop during the writing of the code to think about those nasty pops-up-on-the-fly decisions.

I also second this. I find that I write better by hand, although I work on niche applications it’s not really standard crud or react apps. I use LLMs in the same way i used to used stack overflow, if I go much farther to automate my work than that I spend more time on cleanup compared to if I just write code myself.

Sometimes the AI does weird stuff too. I wrote a texture projection for a nonstandard geometric primitive, the projection used some math that was valid only for local regions… long story. Claude kept on wanting to rewrite the function to what it thought was correct (it was not) even when I directed to non related tasks. Super annoying. I ended up wrapping the function in comments telling it to f#=% off before it would leave it alone.

Using AI or writing your own code isn't an xor thing. You can still write the code but have a coding assistant or something an alt/cmd-tab away. I enjoy writing code, it relaxes me so that's what I do but when I need to look something up or i'm not clear on the syntax for some particular operation instead of tabbing to a browser and google.com I tab to the agent and ask it to take a look. For me, this is especially helpful for CSS and UI because I really suck at and dislike that part of development.

I also use these things to just plan out an approach. You can use plan mode for yourself to get an idea of the steps required and then ask the agent to write it to a file. Pull up the file and then go do it yourself.

>but the code to me is a forcing mechanism into ironing out the details, and I don't get that when I'm writing a specification.

This is so on point. The spec as code people try again and again. But reality always punches holes in their spec.

A spec that wasn't exercised in code, is like a drawing of a car, no matter how detailed that drawing is, you can't drive it, and it hides 90% of the complexity.

To me the value of LLMs is not so much in the code they write. They're usually to verbose, start building weird things when you don't constantly micromanage them.

But you can ask very broad questions, iteratively refine the answer, critique what you don't like. They're good as a sounding board.

In 1987 when I first started coding, I would either write my first attempt in BASIC and see it was too slow and rewrite parts in assembly or I would know that I had to write what I wanted from the get go in assembly because the functionality wasn’t exposed at all in BASIC (using the second 64K of memory or using double hires graphics).

This past week, I spent a couple of days modifying a web solution written by someone else + converting it from a Terraform based deployment to CloudFormation using Codex - without looking at the code as someone who hasn’t done front in development in a decade - I verified the functionality.

More relevantly but related, I spent a couple of hours thinking through an architecture - cloud + an Amazon managed service + infrastructure as code + actual coding, diagramming it, labeling it , and thinking about the breakdown and phases to get it done. I put all of the requirements - that I would have done anyway - into a markdown file and told Claude and Codex to mark off items as I tested each item and summarize what it did.

Looking at the amount of work, between modifying the web front end and the new work, it would have taken two weeks with another developer helping me before AI based coding. It took me three or four days by myself.

The real kicker though is while it worked as expected for a couple of hundred documents, it fell completely to its knees when I threw 20x documents into the system. Before LLMs, this would have made me look completely incompetent telling the customer I now wasted two weeks worth of time and 2 other resources.

Now, I just went back to the literal drawing board, rearchitected it, did all of the things with code that the managed services abstracted away with a few tweaks, created a new mark down file and was done in a day. That rework would have taken me a week by itself. I knew the theory behind what the managed service was doing. But in practice I had never done it.

It’s been over a decade where I was responsable for a delivery that I could do by myself without delegating to other people or that was simple enough that I wouldn’t start with a design document for my own benefit. Now within the past year, I can take on larger projects by myself without the coordination/“mythical man Month” overhead.

I can also in a moment of exasperation say to Codex “what you did was an over complicated stupid mess, rethink your implementation from first principles” without getting reported to HR.

There is also a lot of nice to have gold plating that I will do now knowing that it will be a lot faster

I dunno. On the one hand, I keep hearing anecdata, including hackernews comments, friends, and coworkers, suggesting that AI-assisted coding is a literal game changer in terms of productivity, and if you call yourself a professional you'd better damn well lock the fuck in and learn the tools. At the extreme end this takes the form of, you're not a real engineer unless you use AI because real engineering is about using the optimal means to solve problems within time, scale, and budget constraints, and writing code by hand is now objectively suboptimal.

On the other hand, every time the matter is seriously empirically studied, it turns out that overall:

* productivity gains are very modest, if not negative

* there are considerable drawbacks, including most notably the brainrot effect

Furthermore, AI spend is NOT delivering the promised returns to the extent that we are now seeing reversals in the fortunes of AI stocks, up to and including freakin' NVIDIA, as customers cool on what's being offered.

So I'm supposed to be an empiricist about this, and yet I'm supposed to switch on the word of a "cool story bro" about how some guy built an app or added a feature the other day that he totally swears would have taken him weeks otherwise?

I'm like you. I use code as a part of my thought process for how to solve a problem. It's a notation for thought, much like mathematical or musical notation, not just an end product. "Programs must be written for people to read, and only incidentally for machines to execute." I've actually come to love documenting what I intend to do as I do it, esp. in the form of literate programming. It's like context engineering the intelligence I've got upstairs. Helps the old ADHD brain stay locked in on what needs to be done and why. Org-mode has been extremely helpful in general for collecting my scatterbrained thoughts. But when I want to experiment or prove out a new technique, I lean on working directly with code an awful lot.

That's because many developers are used to working like this.

With AI, the correct approach is to think more like a software architect.

Learning to plan things out in your head upfront without to figure things out while coding requires a mindset shift, but is important to work effectively with the new tools.

To some this comes naturally, for others it is very hard.

> A lot of how I form my thoughts is driven by writing code, and seeing it on screen, running into its limitations.

If you need that, don't use AI for it. What is it that you don't enjoy coding or think it's tangential to your thinking process? Maybe while you focus on the code have an agent build a testing pipeline, or deal with other parts of the system that is not very ergonomic or need some cleanup.

I was just thinking this the other day after I did a coding screen and didn't do well. I know the script for the interviewee is your not suppsed to write any code until you talk through the whole thing, but I think i woukd have done better if I could have just wrote a bunch of throw away code to iterate on.

> A lot of how I form my thoughts is driven by writing code, and seeing it on screen, running into its limitations.

Two principles I have held for many years which I believe are relevant both to your sentiment and this thread are reproduced below. Hopefully they help.

First:

  When making software, remember that it is a snapshot of 
  your understanding of the problem. It states to all, 
  including your future-self, your approach, clarity, and 
  appropriateness of the solution for the problem at hand. 
  Choose your statements wisely.

And:

  Code answers what it does, how it does it, when it is used, 
  and who uses it. What it cannot answer is why it exists. 
  Comments accomplish this. If a developer cannot be bothered 
  with answering why the code exists, why bother to work with 
  them?

I think of it differently: I’ve been coding so long that ironing out the details and working through the specification with AI comes extremely naturally. It’s like how I would talk to a colleague and iterate on their work. However, the quality of the code produced by LLMs needs to be carefully managed to assure it’s of a high standard. That’s why I formalized a system of checks and balances for my genetic coding that contains architectural guidelines as well as language, specific taste advice.

You can check it out here: https://ai-lint.dosaygo.com/

I liken it to manual versus automated industrial production. I think manual coding will always have its place just like how there are even still people who craft things by manual labor, whether it’s woodworkers only using manual tools or blacksmiths who still manually stoke coke fires that produce very unique and custom products; vs the highly automated production lines we have that produce acceptable forms of something efficiently, and many of them so many people can have them.

Some people like to lay the brick, some people like to draw the blueprints. I don’t think there is anything wrong with not subscribing to this onslaught on AI tooling, doing the hard work is rewarding. Whether AI will become a standard in how code is written in the future is still to be determined and I think there is a real chance that is where it goes, it shouldn’t hinder your love for doing what you do.

Any sufficiently detailed specification converges on code.

I couldn't agree more. It's often when you are in the depth of the details that I make important decisions on how to engineer the continuation.

Are there still people under the impression that the correct way to use Stack Overflow all these years was to copy & paste without analyzing what the code did and making it fit for purpose?

If I have to say, we're just waiting for the AI concern caucus to get tired of performing for each other and justifying each other's inaction in other facets of their lives.

> A lot of how I form my thoughts is driven by writing code, and seeing it on screen, running into its limitations.

I completely agree but my thought went to how we are supposed to estimate work just like that. Or worse, planning poker where I'm supposed to estimate work someone else does.

i go back and forth on this. when i'm working on something where the hard part is the actual algorithm, say custom scheduling logic or a non-trivial state machine, i need my hands in the code because the implementation is the thinking. but for anything where the complexity is in integration rather than logic, wiring up OAuth flows, writing CRUD endpoints, setting up CI pipelines, agents save me hours and the output is usually fine after one review pass. the "code as thought" argument is real but it applies to maybe 20% of what most of us ship day to day. the other 80% is plumbing where the bottleneck is knowing what to build, not how.

This is exactly the issue I’m facing especially when working with AI-generated codebases.

Coding is significantly faster but my understanding of the system takes a lot longer because I’m having to merge my mental model with what was produced.

Sounds like the coders equivalent of the Whorfian hypothesis.

I sometimes wonder if the economics of AI coding agents only work if you totally ignore all the positive externalities that come with writing code.

Is the entire AI bubble just the result of taking performance metrics like "lines of code written per day" to their logical extreme?

Software quality and productivity have always been notoriously difficult to measure. That problem never really got solved in a way that allowed non technical management to make really good decisions from the spreadsheet level of abstraction... but those are the same people driving adoption of all these AI tools.

Engineers sometimes do their jobs in spite of poor incentives, but we are eliminating that as an economic inefficiency.

I am similar but I think we just have to adjust. Learn and improve writings specs with all the details.

this is close to what i've landed on too. the pre-commit hook is non-negotiable. i've had Claude Code report "all checks pass" when there were 14 failing eslint rules. beyond the static analysis though, i keep hitting a harder problem: code that passes every lint rule, compiles clean, and greens the test suite but implements a subtly wrong interpretation of the spec. like an API handler that returns 200 with an empty array instead of 404, technically valid but semantically wrong. evaluating behavioural correctness against intent, not just syntax or type safety, is the gap nobody's really cracked yet. property-based testing helps but it still requires you to formalize the invariants upfront, which is often the hard part.

Not a catch all to fix issues agree with linting. Being very strict with linters has become very cheap with coding agents and it keeps you up to date with code standards and keeps code style homogenous which is very nice when you are reviewing professional code, regardless of who wrote it.

It’s also tricky otherwise if you have to occasionally review lazily written manual code mixed with syntactically formal/clean but functionally incorrect AI code.

My setup has some of the things mentioned and I found that occasionally the LLM will lie that something passes, when it doesn't.

These kinda things aren’t really the issues I run into. Lack of clarity of thought, overly verbose code, needlessly defensive programming - the stuff that really rots a codebase. Honestly some of the above rules you have I’d want the LLM to ignore at the times if we’re going for maximum maintainability.

Very nice.

BUT, what is the point of max line length enforcement, just to see if there are crazy ternary operators going on?

Except for dependency cruiser which I hadn't heard of, this is almost exactly what I've built up over the past few weeks.

For the pre-commit hook, I assume you run it on just the files changed?

> Custom script to ensure shared/util directories are not over stuffed (built this using dependency-cruiser as a library rather than an exec)

Would you share this?

It’s a solid post overall and even for people with a lot of experience there’s some good ideas in here. “Identify and mark functions that have a high security risk, such as authentication, authorization” is one such good idea - I take more time when the code is in these areas but an explicit marking system is a great suggestion. In addition to immediate review benefits, it means that future updates will have that context.

“Break things down” is something most of us do instinctively now but it’s something I see less experienced people fail at all the time.

> By the time you do everything outlined here you’ve basically recreated waterfall and lost all speed advantage.

Next: vibe brain surgery.

/i

Anyone who’s been a developer for more than 10 minutes knows that best practices are hard to always follow through on when there’s pressure to ship.

But there’s more time to do some of these other things if the actual coding time is trending toward zero.

And the importance of it can go up with AI systems because they do actually use the documentation you write as part of their context! Direct visible value can lead people to finally take more seriously things that previously felt like luxuries they didn’t have time for.

Again if you’ve been a developer for more than 10 minutes, you’ve had the discouraging experience of pain-stakingly writing very good documentation only for it to be ignored by the next guy. This isn’t how LLMs work. They read your docs.

These best practice protections become essential only when you give the work to really bad programmers - such as parrots.

Skip specs, and you often ended up writing the wrong program - at substantial cost.

The main difference now is the parrots have reduced the cost of the wrong program to near zero, thereby eliminating much of the perceived value if a spec.

Astronaut 1, AI-assisted developers: You mean, it's critical to plan and spec out what you want to write before you start in on code?

Astronaut 2, Tim Bryce: Always has been...

We’re not „thinking with portals” about these things enough yet. Typically we’d want a detailed spec beforehand, as coding is expensive and time consuming, thus we want to make sure we’re coding the right thing. With AI though, coding is cheap. So let AI skip the spec and write the code badly. Then have it review the solution, build understanding, design a spec for better solution and have it write it again. Rinse and repeat as many times you need.

It’s also nothing new, as it’s basically Joe Armstrong's programming method. It’s just not prohibitively expensive for the first time in history.

This. Historically there's been a lot of resistance to the idea of refactoring or refining features. The classic "It works, just ship it" mentality that leaves mountains of tech debt in its wake.

And there _was_ a good reason to resist refactoring. It takes time and effort! After "finishing" something, the timeline, the mental and physical energy, the institutional support, is all dried up. Just ship it and move on.

But LLMs change the equation. There's no reason to leave sloppy sub-optimal code around. If you see something, say something. Wholesale refactoring your PR is likely faster than running your test suite. Literally no excuses for bad code anymore.

You'd think it didn't need to be said but, given we have a tool to make coding vastly more efficient, some people use that tool to improve quality rather than just pump out more quantity.

This is the main thing I have learned too. I've been building an internal tool for myself to annotate lines in each commit diff as good (green) / needs refactor (yellow) / needs rewrite (red) and it has helped me keep track of this kind of tech debt. Basically does what you could do with "TODO refactor" comments all over, but is more comprehensive and doesn't litter your source code. Plan to open source it once I've dog-fooded it a little more

Underground Resistance Aims To Sabotage AI With Poisoned Data

https://news.ycombinator.com/item?id=46827777

The enthusiasm so many devs show for it is also quite bizarre, saying things like "AI makes me so much more productive," with the implication that they will be its primary beneficiaries, and that it won't result in a massive reduction in demand, compensation, and status for developers, adversely affecting them. Even more bizarre when you realize these devs aren't the ones optimizing some popular video codec or writing avionics software for a fighter jet, but instead gluing together NPM packages--probably the first or second rung on on the software "innovator's dilemma" ladder of disruption.

I’ll believe it when those same engineers fix CC’s awful performance (mostly kidding, though I do wonder why they can’t. Feels like it’s doable).

In reality that man is hoping to IPO in 6-12 months, if anyone is wondering why the “use claude or you’re left behind” is so heavy right now.

I'm still writing code. I'm doing it to solve a problem, there's more to writing code than than typing. Recently AI massively simplified "getting started", and all of the tips here are applicable to working well on a team.

My recent experience: I'm porting an app to Mac. It's been in my backlog for ~2 years. With Claude I had a functional prototype in under a day getting the major behavior implemented. I spent the next two weeks refactoring the original app to share as much logic as possible. The first two days was lots of fun. The refactoring was also something I wanted to flush out unit tests, still enjoyable.

The worst part was debugging really bugs introduced to my code from 5 years ago. My functions had naming issues describing the behavior wrong, confusing Claude, that I needed to re-understand to add new features.

Parts of coding are frustrating. Using AI is frustrating for different reasons.

The most frustrating part was rebasing with git to create a sensible history (which I've had to do without AI in the past), reviewing the sheer volume of changes (14k lines) and then deciding "do I want my name on this" which involved cleaning up all the linter warnings I'd self imposed on myself.

I’m finding it to be the opposite. I used to love writing everything by hand but now Claude is giving me the ability to focus more on architecture. I like just sitting down with my coffee and thinking about the next part of my project, how I’d like it to be written and Claude just fills it in for me. It makes mistakes at times but it also finds a lot of mine that I hadn’t even realized were in my code base.

A good bit of scaffolding and babysitting allows you to let the model run much faster and more efficiently. Building your tool faster. I don't code to code, I code to build something I want.

Also there is no "compiler" and "type checker" for your SPEC. If you get something wrong in some paragraph somewhere and or contradict something in your spec X paragraphs later - you have to use Mark-1 EyeBall to detect and fix this.

You have just transformed your job from developer to manual spec maintainer - a clerk who has to painstakingly check everything.

Sentiments like this make me wonder if perhaps the dream of the 90s was just ahead of its time. Things like UML, 4GLs, Rational were all being hyped. We were told that the future was a world where people could express the requirements & shape of the system, and the machines would do the rest.

Clearly that didn't happen, and then agile took over from the more waterfall/specs based approaches, and the rest was history.

But now we're entering a world where the state of the art is expressing your requirements & shape of the system. Perhaps this is just part of a broader pendulum swing, or perhaps the 1990s hopes & dreams finally caught up with technology.

  > repo will always win over documentation

it really does seem like this... also new devs are like that too: "i just copied this pattern use over here and there whats wrong?" is something i've heard over and over lol

i think languages that allow expression of "this is deprecated, use x instead" will be usefull for that too

None of this is new, it was pretty much all "best practice" for decades and so already in the training data for the first generation.

If the issue is SNR and the ratio of "good" vs "bad" practices in the input training corpus, I don't know if that's getting better.

They will also be reading all of the slop generated by the current and previous generations of LLMs

Each extra generation of AI produced crap AI consumes as training, the worse it gets. This has been mathematically proven.

> AI bots will read, train on and digest the million "how to write with AI" posts that are being written right now

Yes!

> by some of the smartest coders in the world

Hmm... How will it filter out those by the dumbest coders in the world?

Including those by parrots?

I'm finding Rust is perfect for me with LLMs.

I find rust generally easier to reason about, but can't stand writing it.

The compiler works well with LLMs plenty of good tooling and LSPs.

If I'm happy with the shape of the code and I usually write the function signatures/ Module APIs. And the compiler is happy with it compiling. Usually the errors if any are logical ones I should catch in reviews.

So I focus on function, compiler focuses on correctness and LLM just does the actual writing.

Do you think Rust will end up getting a boost from LLM adoption?

Same. Small units if work, iterate in it till it's right, commit it, push it, then do the next increment of work. It's how I've always worked like that, except now, I sometimes let someone else figure the exact API calls (I'm still learning react, but Claude helps get the basics in place for me). If the AI just keeps screwing up, I'll grab the wheel and do it myself. It sometimes helps me get things going, but it hasn't been a huge increase in productivity, but I'm not paying the bill so whatever.

so is the 10-20% in velocity worth the money and the process-complexity added? I'm assuming you're measuring your own velocity, not your team's, since that includes time to review and deploy etc.

Every engineering org should be pleading devs to not let AI write code, period. They continue to routinely get stuff wrong and can't be trusted any further than you can throw them.

"Stack Overflow that reads your codebase" — perfect. But Stack Overflow is stateless. Agent sessions aren't.

One session's scaffold assumes one pattern. Second session scaffold contradicts it. You reviewed both in isolation. Both looked fine. Neither knows about the other.

Reviewing AI code per-session is like proofreading individual chapters of a novel nobody's reading front to back. Each chapter is fine. The plot makes no sense.

Hi raphman,

i have written this text by myself except like 2 or 3 sentences which i iterated with an LLM to nail down flow and readability. I would interpret that as completely written by me.

> The suggestions you make are all sensible but maybe a little bit generic and obvious. Asking ChatGPT to generate advice on effectively writing quality code with AI generates a lot of similar suggestions (albeit less well written).

Before i wrote this text, i also asked Gemini Deep Research but for me the results where too technical and not structural or high level as i describe them here. Hence the blogpost to share what i have found works best.

> If not, I'd suggest to augment the post with practical examples or anecdotal experience. At the moment, the target group seems to be novice programmers rather than the typical HN reader.

I have pondered the idea and also wrote a few anecdotal experiences but i deleted them again because i think it is hard to nail the right balance down and it is also highly depended on the project, what renders examples a bit useless.

And i also kind of like the short and lean nature of it the last few days when i worked on the blogpost. I might will make a few more blogposts about that, that will expand a few points.

Thank you for your feedback!

Yes this is strange. There's nothing of substance here that hasn't been repeated many times before. BUT...I did click it out of interest. So maybe it just came at an opportune lull in these types of posts and during the inflection point of 4.6 and 5.3 release. Complete guess

That's the opposite. I've never read and re-read code more than i do today. The new hires generate 50 more code than they use to, and you _have_ to check it or have compounding production issues (been there, done that). And the errors can now be anywhere, when before you more or less knew what the person writing code is thinking and can understand why some errors are made. LLMs errors could hide _anywhere_, so you have to check it all.

They serve as guardrails for agents to not do stupid things.

If your goal is for AI to write code that works, is maintainable and extensible, you have to include as many deterministic guardrails as possible.

It makes it easier to make sure it runs right. Code that is easier to make sure is quality code. Code that is hard to make sure is not quality code.

This take is pretty uncharitable. I write high quality code, but also there's a bunch of code that could be useful, but that I don't write because it's not worth the effort. AI unlocks a lot of value in that way. And if there's one thing my 25 years as a software engineer has taught me is that while code quality and especially system architecture matter a lot, being super precious about every line of code really does not.

Don't get me wrong, I do think AI coding is pretty dangerous for those without the right expertise to harness it with the right guardrails, and I'm really worried about what it will mean for open source and SWE hiring, but I do think refusing to use AI at this point is a bit like the assembly programmer saying they'll never learn C.

Man, you are really missing out of the biggest revolution of my life.

This is the opinion of someone who has not tried to use Claude Code, in a brand new project with full permissions enabled, and with a model from the last 3 months.

Can you be specific? You didn't provide any constructive feedback, whatsoever.

Look up luddites on Wikipedia, might be too deep to see the similarities though.

small agents.md files are worth it, at least for holding some basic information (look at build.md to read how to build, the file structure looks like so), rather than have whatever burn double the amount of tokens searching for whatever anyways.