./writing/gearious/steering-docs
Turning Documents Into Instructions
It's been a while since the last post, for two reasons.
The first is that this stretch of the work is the least postable part of the whole project. Writing guidance documents doesn't produce the kind of oh — this can really happen moment that the wireframe did, or the working prototype. It's quiet, careful, unglamorous work, and there's a stretch of it where you don't have anything worth writing home about because you're too busy doing the thing.
The second is that I took a genuine detour. Somewhere in here I started another project — a mobile app for metal-detecting hobbyists called Unearthd — that pulled my attention for a few months. It's a side quest, and a good one, with some genuinely transferable lessons about building this way that I'll get into in a post of its own. For now it's enough to say: the Gearious work paused while I went and learned some things somewhere else, and then I came back.
I came back with something I'd figured out in the meantime. The foundation documents from post 03 — the Product Overview, the requirements, the architecture plans, the release plans — were good documents. Thorough. The kind of traditional product documents I'd spent a career learning how to make. They did their real job, which was the deep thinking, and they did it well, and they still have that value. But as I researched how to actually point these AI tools at a build, I learned those documents, as good as they were, had been written for the wrong audience.
They'd been written for a human. The tools needed something else.
why the good documents were the wrong shape
The foundation documents were written for a person. Me, mostly, and any future collaborator who needed to understand what Gearious was and why. They're narrative. They explain. They have a voice. The Product Overview opens by telling you a story about a rider loading panniers in a driveway.
That's exactly right for a document a person reads to understand a product. It's simply not the shape a tool needs to build one — and I didn't learn that by faceplanting into it. I learned it by doing the reading. More YouTube, more LinkedIn posts, more write-ups from other people building the same way and sharing what worked. The more I took in about how people were actually setting these tools up, the clearer it got that a specific, differently-shaped set of documents was what set a build up for success — and that my beautiful narrative docs, for all their thoroughness, weren't it.
My first instinct was that everything belonged in one big file. A single CLAUDE.md holding every last thing the tool might need to know, top to bottom. Several blog posts talked me out of that. The better pattern, the one people kept converging on, was to break the information into focused documents — each with its own clear job — and have the main file point to them, with a line of instruction telling the tool what each one is for and when to reach for it.
There's no official set. No canonical list of files everyone agrees on, no standard a tool ships with and enforces. But the same patterns kept showing up across everything I read — what earned its own file, how people grouped the rest, which concerns got separated from which. What I ended up building is a consensus of what those sources suggested, adapted to what Gearious actually needed.
The move, in the end, wasn't to rewrite the foundation docs. Those stay exactly where they are — the source of truth, the narrative version, the thing a human reads to understand the product. The move was to distill a second layer out of them: terse, rule-first files that a machine reads to build it. Same information. Different shape. Different reader.
the steering files
I built that second layer with Claude, working through the foundation documents and parsing them down into a set of steering files — the narrative on one side, the instruction on the other, and Claude doing the distillation while I made the calls about what mattered. Six files came out of it, and they live in the repo itself, in a docs/ folder, right next to the code they govern.
product.md. What Gearious is, who it's for, the balance-indicator vision, the web-only build scope, and the product principles — the Product Overview compressed to the version a builder needs on hand. The story about the driveway is gone. What's left is the constraints the story was there to illustrate.
release-plan.md. The phased roadmap, condensed for reference during development, so the tool knows what's in scope for the current phase and what's deliberately deferred to a later one.
tech.md. The stack and the non-negotiable conventions. App Router. Supabase with row-level security. Weights stored as integer grams. The pure-function balance engine. API patterns, naming rules, environment variables, the commands to run. This is the file that gets the most traffic during a build, because it's the one that answers how do we do things here.
structure.md. How the codebase is organized — the route groups, where the API routes mirror resources, where components and hooks and stores live, the import patterns, and a plain guide for where new code is supposed to go. The file that keeps the tool from inventing a fresh folder structure every session.
audience.md. Who uses the app and how much complexity they can handle — the split between riders who know the domain cold and riders who are new to it, what they care about, where progressive disclosure applies, the tone, and the accessibility baseline. The file that keeps decisions grounded in the actual user instead of drifting toward whatever's easiest to build.
design-system.md. The visual language as tokens rather than prose. The color palette (taupe, olive, amber, orange, lime), the type and spacing scales, the radii, the motion rules, and the light/dark theming architecture — the design decisions rendered in the form the code consumes.
Six files. The writing itself wasn't the hard part — Claude did most of that. The work was in the deciding: what a builder actually needs from each document versus what was only ever there to help a human understand, and holding the line on the difference, file by file.
the file that made it a system
The steering files on their own were an improvement. What turned them from a pile of good files into an actual system was the file sitting above them: CLAUDE.md.
CLAUDE.md is the file the tool reads first, every session. It does three things, and each one solves a problem I'd read enough to know was coming.
First, it's an index. It lists every steering doc with a one-line description of what's in it, so the tool knows where to look for a given kind of answer instead of scanning all six files every time. Small thing. Enormous difference in how efficiently a session starts.
Second, it enforces the discipline that keeps the steering docs current — which is one of the highest-value things the whole setup does, and I built it in on purpose. The single biggest failure mode of this approach is drift: you make an architectural decision during a build session, the decision lives only in that chat transcript, the transcript closes, and the next session starts from steering docs that no longer match reality. So CLAUDE.md carries a rule, in writing, that any decision which changes a pattern or completes a phase gets written back into the relevant steering doc before the session ends — with a little table mapping each kind of change to the file it belongs in. Having the tool keep its own instructions current as decisions get made is a massive timesaver and the thing that keeps the whole build on track. And the reason it works is that the rule is written down: a rule that only lives in your head gets re-litigated every time it's inconvenient, and a rule written into the file holds.
Third, it sets the working rules — the guardrails for how the tool behaves as a collaborator. A GitHub workflow it follows without being reminded: branch naming, commit-message format, when to open a pull request, when to comment on an issue, and a short list of things it does not do without being asked (push to main, merge PRs, close issues manually). And a set of behavioral guidelines aimed at the most common ways these tools go wrong — think before coding, state your assumptions, don't add speculative features, make surgical changes instead of "improving" adjacent code, and define a verifiable success criterion before starting instead of declaring victory at the end.
That last set is the closest thing in this post to hard-won. Left to their defaults, these tools are eager, and eagerness in a collaborator sounds good right up until it means the tool refactors three files you didn't ask it to touch, adds configurability you'll never use, and reports success on a task it never actually verified. The behavioral guidelines are, functionally, the code review I'd give a talented junior engineer who's a little too fast for their own good. Written down once, applied every session, no reminding required.
the honest part
I want to be straight about what this stretch felt like, because the build-in-public genre has a bad habit of making every step sound like a breakthrough.
It was a grind. Distilling documents into other documents is not the exciting part of building something. There's no single moment of oh — this can really happen the way there was with the wireframe or the prototype. But — and this is the part the word "grind" undersells — it didn't feel like spinning wheels. It felt like progress, the steady kind, because I could watch the plan getting more solid with every pass.
The loop was the good part. I'd refine a file, then hand the whole set back to Claude and ask it to check my work — read across all of them for consistency, flag anything that contradicted, tell me where I'd been vague, and, more than once, actively try to punch holes in the plan. It found them. It caught places two files disagreed, gaps I'd left without noticing, a constraint I'd stated one way in one file and another way in another. I'd fix what came back and run the pass again. Each loop left the whole thing tighter than the loop before.
That's where the quality actually came from — not from any one file being written well the first time, but from the refining. It's the least visible work in the project and some of the most consequential, and it maps onto something every editor already knows: the value isn't in the draft, it's in what you do to the draft after. The difference here is that I had a collaborator with infinite patience for reading the whole set again from the top.
And the payoff arrived immediately once building started. A session that opens from good steering docs is a session where the tool already knows the stack, the structure, the conventions, the constraints, and the rules of engagement — and gets straight to work. A session that opens from thin or stale docs spends its first half re-deciding things I'd already decided, usually differently than last time. The hours spent hardening the docs up front are the hours that buy the flow later. Least postable work in the series. Quite possibly the highest-leverage.
If there's one thing I'd tell another designer starting a build like this, it's the thing I most resisted believing while I was in it: do the document work first, and do it properly. The tools reward it more than they reward almost anything else you can hand them.
where the project sits, and what's next
So that's the scaffolding. The foundation documents stand as the narrative source of truth. The steering docs stand as the machine-readable layer distilled from them. CLAUDE.md sits on top — indexing the steering docs, enforcing the discipline that keeps them current, and laying down the workflow and behavioral rules that make the tool a collaborator instead of a loose cannon. The instructions are written. The next thing that happens is the actual building — feature by feature, issue by issue, branch by branch, against the system all of this was setting up.
Which means the next posts get to be about the fun part again. The balance engine, built for real. The first feature that shipped clean on the first try, and the first one that absolutely did not. The moments where the steering docs paid off, and the moment I found a gap in them the hard way, mid-build. (There's also that Unearthd detour to circle back to, and what building a second thing taught me about building the first.)
I'll show the work, same as always. Even the boring work — especially the boring work, it turns out, since it was the part that mattered most.
The least I can do is show the work. Even the boring work.