You are the Client Now

Maybe think before you get really mad at Claude

You’ve been working on a piece of software with Claude Code for a week. You’ve spent hours discussing your idea, your goals, what you need the software to do and what you don’t want the software to do.

Claude writes the spec. You the work with Claude to break down the work into user stories or cards. Tasks that are clearly defined with unambiguous requirements, both functional and non-functional. Clear acceptance criteria. Clear testing needs. Again, this took hours. Days, even.

You finally let Claude loose to work on your first project task. After 10 or 15 minutes, Claude tells you it’s done! You look at the code, the tests and carefully examine its code. It wrote a lot, but it has tests and the tests look good.

You fire up your application to test Claude’s work.

It’s trash. Nothing works.

Or, worse, it kind-of works. It does some things you want it to, but not well. It doesn’t do some things you want at all. And it does some things you never wanted it to do. There are bugs, and it’s clear that Claude didn’t actually understand the spirit of what you were trying to do.

This isn’t actually a new experience - just maybe new for you.

Ever since charging for computer programming was a thing people have been hiring programmers to write software for them - and ever since it was a thing, programmers have been misunderstanding requirements, cutting corners and making functional trade-offs without really communicating back to the user.

If you’ve ever done freelance, contract or agency type work, you’ll know the dread of getting client sign-off on your work. This is where the rubber meets the road and the client finally gets the product they’ve been paying you 5 or 6 figures to build. Hopefully y’all have had regular milestones for functionality checks, and the client generally knows what you’ve built, it’s limitations and how to get value from it.

Hahaha.

In reality, your client more than likely has never run your software before. No matter how many check-ins, milestone reviews, and user interview sessions you conduct, they nod and smile and say you’re doing great work. They approve milestones after a quick cursory glance just to keep the project moving. The first time the client has actually even really tried to use your software is at the end - final delivery.

As you can imagine, final delivery is usually rough. That’s when you, as the programmer/contractor/freelancer realize the client has been lying about checking your work, and the client finds out that you didn’t actually understand their vision as well as you both thought you did. People get upset, sometimes things can get heated, and you both scramble to fix the issues and save the project.

Sound familiar?

Clients are famously bad at explaining what they actually want. There’s all these assumptions about the world and business and technology and there’s often a huge gap in domain knowledge between the client and the developer. The client can’t see where the gaps in understanding are on the programmer side and the programmer doesn’t know enough to know what they don’t know, if that makes sense.

In this agentic programming world, you are the client. Claude is the programmer.

So are you actually surprised and angry that Claude didn’t actually build the thing you wanted exactly? Does being a software developer make us better at giving requirements to another programmer?

I would say no.

I remember in my college days, I had a “Systems Analysis” class. For six months, I and a small team of 3 or 4 other programmers met with a “client” (who was the professor) once/week and designed, planned and started executing on a large scale project. He apparently ran a kitchen remodeling business on the side and decided that it would be a good idea to have a bunch of college students build out a full digital servicing platform.

It was 20 years ago, so the details are fuzzy - the important thing is we didn’t even start building until toward the end of the class. The first 3 months were spent requirements gathering, designing systems, checking back in with the client for review, and repeating. I cannot tell you how many briefs, architectural diagrams, ERDs, Gantt charts, and all sorts of bullshit that we produced just to try to get everyone on the same page about what to build.

The client was our professor - a professional software developer who is teaching the next generation of software developers. If someone should be good at giving requirements, it’s him. Maybe he was good and that’s why it took us 3 months to document everything?

Do you and Claude spend months aligning on requirements? Or do you tell Claude to write a plan and 10 minutes later just go?

I’ve been building heavily with Claude over the last handful of months. I’ve been thinking a lot about how people interact with AI programming agents, how those agents work, what they’re good at and what they’re not good at. The more I think, the more I think we need to cut them a little slack.

One of the key take aways from my career in programming is that describing precise technical things with words is hard. As an expert, it’s hard to know that something you know is not obvious and important. Even when you think you are aligned on some topic, it’s very easy to not actually be in the same place due to both of these. Requirements are hard. Building software is hard. Programming is easy, in comparison.

You are the customer.

It’s on you to describe the thing you want to Claude and describe it well and in detail. If you leave any gaps or ambiguity in the plan and design, a human programmer will ask you questions. Claude guesses.

If you tell Claude to build a tire swing and it just wraps a board with rope on it to a tree, is that Claude’s fault or yours?