Back

Text is for machines. Maps are for us.

In October 2024, I bought a whiteboard company called CardBoard. That was the bet: my career, on the idea that people think best when the work is laid out where they can see it. I saw part of what was coming. AI was getting good at writing code, and half the bet was that I could modernize CardBoard’s code with AI myself. What I didn’t factor in was how disruptive AI would be for collaboration. Teams weren’t far behind me, running their own experiments, and because these machines are built on language, all that energy poured into words: prompts, PRDs, specs, markdown files. Whatever the future of building software was going to be, it was going to be made of text.

Last Tuesday I sat down to redesign CardBoard’s onboarding. I started with a spec. Claude Code read the modern onboarding playbooks and came back blunt. Kill the product tour. Stop collecting demographics disguised as account setup. Get to the moment of value fast. The trends gave me conviction, and conviction gave me ideas to capture. For the first stretch of the spec I was all the way in with tangible outcomes in my own words.

Then the spec got into the weeds, and my attention went with it. I couldn’t hold the plan details and the big picture at once, and somewhere in there I stopped reviewing and started assuming: the build rules and tests would catch it. I was nodding along to a review I was no longer performing. The man who bet his career on whiteboards, drowning in a text file about them.

That nod is the most important product problem in software right now. Not the agent’s capability. Ours.

The reader changed, not the artifact

The machine doesn’t share my limit. It reads every word, every time, and that fact is why spec-driven development is everywhere this year.

  • July 2025: AWS launches Kiro, an IDE built around requirements docs and task lists as first-class files.
  • September 2025: GitHub ships Spec Kit, an open-source toolkit formalizing a constitution → specify → plan → tasks → implement pipeline.
  • June 2026: Google publishes “Spec-Driven Production Grade Development in the Age of Vibe Coding,” a whitepaper in its AI Agents course arguing that code is disposable and the behavior spec is the source of truth.

Three of the largest developer platforms, inside a year, bet on an idea the industry spent twenty years mocking as waterfall cosplay.

Specs didn’t get better. Writing precise specifications was always expensive, and for decades the ROI was negative. Every spec writer knows the real insult: the developer didn’t read it anyway. They skimmed the ticket, walked over to your desk, and asked. The value that survived was the writer’s. Long prose forces you to work out your thinking, which is why Amazon built a culture on six-page memos and press releases written before the product exists. Writing to think earned its keep. Writing to be executed didn’t, because no one executed from it. So we ritually wrote specs, ritually let them rot, and the agile revolt was right to call it ceremony.

Then the spec got its first reliable reader. The agent is an amnesiac savant: inhumanly fast, and it knows nothing you didn’t write down. It reads a 4,000-word spec every time, without skimming. After decades of specs nobody read, writing it all down finally pays. The artifact is the same. The reader is different.

Which should have settled it: write the spec, let the reliable reader read it. Except my spec kept bothering me. It felt like it had gaps, and staring harder at the markdown never showed me one. I could only feel them.

Diagrams versus maps

The problem wasn’t reading; it was seeing. Humans are built to read space, but only when position means something. Simon Wardley makes a distinction most of us ignore: almost everything business people call a map is a diagram. Take the boxes-and-arrows slide from your last strategy deck. Rearrange the boxes and it says the same thing, because the positions never said anything. Now rearrange a road map. North stops being north, the half-inch to the next town becomes a hundred miles, and the map is ruined, because on a real map, position is the information. That’s what a map can do that a document can’t: show you order, hierarchy, dependency, and absence, all in a single look. A gap is visible on a map. A gap in a list is invisible, because a list is only ever what it contains.

Four things a map shows that a list can't Four napkin panels. Order: cards read left to right as a sequence. Hierarchy: cards stacked top to bottom, the top one highlighted, fading downward by rank. Dependency: one card linked by an arrow to another it needs. Absence: a row of cards with one empty dashed slot, highlighted — the gap you can see. Order left to right is the story Hierarchy top to bottom is what matters Dependency this one needs that one Absence the gap you can see

So Wednesday night we turned the spec into a story map: a backbone running left to right from “Sign up” to “Create first card,” requirements hung under the steps they serve. The structure started paying immediately, and not just for me.

The map had a card from Tuesday’s research: signup collects email and password, nothing else. A day later I told Claude to add a step asking for the user’s name. Not to fill a data model, but because collaboration is better when your peers are names, not email addresses. Two instructions. In a spec they’d both sit in the list, and an agent would pick one and build it with confidence. The nod again, performed by the machine this time. On the map they landed on the same step, and Claude asked me which one I meant. I hadn’t noticed I was contradicting myself. We settled it before anything got built: the form stays email and password, and name gets its own screen right after, because the name is what shows up on every card, board, and invite email.

This is what bothers me about spec-driven development: I change my mind. Seeing the thing is how I learn what I want; it’s the working style agile exists to defend. But watch what happens when I change my mind. I don’t edit the spec, I type a new prompt, and Claude executes the prompt. So what happens to the original spec? One of two things. Either nobody tells it, and it keeps saying what I used to want while the code moves on. Or the revision gets appended, and the document becomes an argument with itself, and an agent reading an argument-with-itself picks a side silently. On a map there’s no separate place for the mind-change to happen: the new instruction lands on the surface where the old one lives, the collision is just sitting there, and I have to settle it. The spec got a reliable reader this year. It still has nothing that catches it arguing with itself.

Beware the visualization trap

If drawing the work is this good, why weren’t we already doing it? We tried. In the mid-nineties, Rational Software’s chief scientist, Grady Booch, and two collaborators unified the industry’s competing notations into UML: boxes, arrows, class hierarchies. A standard way to draw software. The industry fell in love with the drawings and bet a billion dollars on the wrong conclusion: that the pictures could replace the code. Rational Rose, the flagship tool, promised to generate your system from your diagrams. IBM paid $2.1 billion for Rational in 2003. The OMG, the industry’s modeling standards body, made it doctrine in 2001 with Model Driven Architecture: the diagram is the source of truth, code is merely output.

Booch spent the years after telling anyone who would listen that this was a misreading of his own invention: he had never intended UML to become a programming language. UML was for reasoning: put up some diagrams, argue the alternatives, throw the diagrams away, write the code. The industry did the opposite, and it lost to plain text for two reasons. Diagrams are worse than text at precision, and the diagram-to-code roundtrip always broke: developers patched the code under deadline, and the model quietly became a lie. Model drift is the same disease as spec drift.

But drawing only failed for the code itself, where precision demands text; for discovering and planning the code, it worked. The user story map Jeff Patton canonized in his 2014 book is that kind of drawing, and it passes Wardley’s test: left to right tells the user’s story, top to bottom ranks what matters, and a horizontal line across the whole thing marks a release. Move a card and you’ve changed the plan. And its cards solved the precision problem by refusing it. A story card was what Alistair Cockburn called “a ticket for a conversation,” deliberately incomplete, because the understanding lived in the people who’d talked it through. Incompleteness wasn’t a flaw. It was a feature.

We ran into UML’s problem by Thursday. I asked Claude to review the map and find gaps, and it came back with a batch of cards that belonged in the spec. But they were “How” cards: guard the non-web signups, migrate the tests that encode the old flow, rewrite the onboarding state machine. Important, every one. But too much How masks the Why, and the map ballooned past fifty cards until I couldn’t read it at a glance. So I went back to first principles with cards as action verbs for the user. Then we folded the How underneath: description, acceptance criteria, comments, markdown fields hanging off the card each one enables. Seven columns, twenty-nine cards. I could read the board again.

The inversion

Cockburn’s card could stay incomplete because the understanding lived in the room, in the people who had talked it through. The agent doesn’t join the room. It reads what the room writes down, and that’s the whole difference: a conversation doesn’t include the machine in the work; a detailed explanation does. So a card that’s a ticket for a conversation hands the fastest worker on the team a blank page. And it is fast. It writes more cards, plans, and code in an hour than you can honestly review in a day. Incompleteness flipped from feature to bug. The scarce resource stopped being how fast we build. It’s how much of that a person can still follow. The division of labor between text and space is inverting, both sides at once:

Text is for the machines now. Maps are for us.

The machine doesn’t care about your canvas; by the time a map reaches it, it’s a stream of text anyway. We’re the opposite. A picture is worth a thousand words, and for once the cliché is underpriced: nobody reads four thousand words at a glance, but anybody can read this board in one.

So the map’s job changed. It isn’t the poster we align around before the work starts; it’s the board state of a game in progress, where you see what each move costs and what it opens, and decide the next one, while an executor that never sleeps waits on your call. Not a whiteboard. A game board.

The board stays loose on purpose. Some cards are vibes, some are committed specs, and you can tell which is which from across the room. The precision the cards never carried lives in the markdown underneath, where Claude reads at machine speed. Humans get the map. Machines get the markdown. One artifact, both readers.

I tasked Claude with building from the map, and when the code came back I asked a second agent to review the changes against the map: security, UX, acceptance criteria. Two machines and one human, working from the same board.

Friday

By Friday I could do the thing I couldn’t do on Tuesday: hold the whole plan in one look. The Claude sessions that produced it are buried in chat history. The decisions aren’t. They live on the map, and the reasoning sits folded under the cards, where Claude reads it before every move. The nod hasn’t been back.

The nod was never just a review problem. It was a partnership going quiet: one of us producing, the other pretending to follow. The map made it loud again. Claude asked which instruction I meant, and I reversed a decision while reversing was still cheap. I’ll change my mind again. Next time, the collision lands somewhere I can see it.

Text is for machines. Maps are for us.