Introduction

This is the short, stubborn book of the four, and the one the others are really arguing for.

Most tools are built for humans, and then an agent gets bolted on the side: a second API, a flag, a special mode that does half of what the real product does. I think that is backwards. The claim here is simple. A tool should be first-class for both. A human should be able to drive it without an agent, and an agent should be able to drive it without a human, across the same surface, with no second-class door.

I came to this from building, not from theory. I make small Swift libraries and developer tools, and the ones that aged well were the ones where the core was clean enough that anything could call it. When agents showed up, those tools were already ready. The ones that were not are the ones I keep apologizing for.

If the Field Guide is the method, and Building Agents and Open Source Tooling are the evidence, this is the thesis they all serve. You do not need the other three to use this one. It is here to change how you look at the next tool you build or pick: ask whether it treats a human and an agent as the same kind of citizen, and watch how much follows from the answer.

It is short on purpose. Read it in one sitting.

Both citizens

A lot of my tooling comes from one idea: humans and agents are going to use the same tools.

So here's the definition the whole book runs on, up front and plain: first-class means a human drives the tool alone, an agent drives the tool alone, the same commands both ways. Not two products. One tool, two kinds of user, neither one the special case the other gets translated into.

When I say first-class, I mean it the way a programmer means it: a real, supported participant the tool was actually built for, not a guest it tolerates. Not a flight upgrade. A first-class user is one the tool was designed around, with a real way in. Not one that has to be translated into somebody else's shape first.

There can be agent-first tools, built only for agents. There can be human-first tools, built only for people. The interesting case, the one almost nobody is building for, is the tool that's both at once. That's what I mean by first-class for both, and what the rest of the book means too. It's a stricter thing than agent-first: agent-first only has to serve the agent, while first-class-for-both has to serve a person and an agent across the same surface without either side getting a worse version. Right now we mostly have human-first projects and we're bringing agents into them. The agent shows up late, to a tool that was built for somebody else, and we hope it figures the thing out.

What we actually need is human-and-agent-first projects. Built that way from the start.

"Human-first with agents bolted on" is the default because it's the path of least resistance. You already have the tool, it already works for you, and when an agent comes along the easy move is to wrap a little glue around the thing you've got. It works, kind of. You took a tool that was designed around a human's eyes and a human's hands and you asked a process with neither to pretend it had both. What that costs an agent (the hang on a prompt, the output it can't read, the relearning every run) gets its own chapter later. Here it's enough to say the agent ends up papering over a gap on every line that assumed a human.

So flip the assumption. Build the tool so it works first-class either way. That's the definition from the top, restated as a build instruction: you don't have a real product and an "API mode" stapled on the side, and you don't have a CLI and a separate agent shim that drifts out of sync the first time you change anything. Both are real users. Both are supposed to be there.

And here's the part that matters most to me. When the agent is a first-class user, the tool can actually help it, instead of making it guess at all the commands and how things work. A human can muddle through a confusing tool. They'll read the README, try a thing, read the error, try another thing, ask a coworker. An agent muddling through is just expensive guessing. A tool that was built for the agent tells it what's possible, hands it output it can use directly, and fails in a way that says what to do next.

This is the same tool humans want. Discoverable commands, output you can trust, errors that tell you what went wrong. The agent just can't paper over the gaps the way a human can, so building for the agent forces you to close them. Designing for both makes the software better.

People hear "build for agents too" and assume it means two products, or a compromise where each side gets a worse version of what it wanted. It's one good core with a step where you expose it to both. That's not double the work, and the next chapter shows why.

The reason I keep coming back to this is that the agents are only going to do more over time, not less. Today they fumble through human tools. Tomorrow they're doing a real share of the work, and the share goes up. If the tools we build now assume a human is always there to handle the prompt, read the screen, click the button, we're building a future on top of an assumption that's getting falser every month.

There's a bigger version of this argument too. We've had a decade of code written entirely by humans, and now AI is writing code on top of all of it, and at some point that mix tips. The tools are what decide whether that goes well or badly. That's a whole chapter on its own: the bridge.

For now the claim is just this: humans and agents will use the same tools. So build them for both, as equal first-class citizens, from the start.