Day 9 | How I harness AI: spec first, then plan

On day nine, I want to share how I use AI to build different features for my sites.

Last time I said I put taste and judgment near the top of the list. Once you're actually building a site, that gets very concrete. The AI suggests an approach: why would I take it? What problem is this feature solving? Once it's built, how am I going to use it?

I have to answer those myself first.

When AI offers three options, it's easy to start comparing them and just pick one. But the options it lists may not include the approach that fits you best. It might not know your habits yet, or what actually bugs you. Sometimes the better option is hiding in the things you haven't told it.

So I talk it through with the agent first, write down the goal and the trade-offs, and only then let it build. My order is: spec first, then plan, and the agent runs it only after I've reviewed it.

Step one: write the spec

A spec is a specification. I use it to say what we're building this time, and why.

Say I tell the agent "I want a content tool like Notion." That gives a rough picture, but it isn't enough for the agent to decide which features to build.

Do I want to edit pages? Organize posts? Or do I want a place where the agent's output is saved, so I can view and manage it on a page? Different goals lead to different designs.

Sticking with that example, suppose the problem this time is this: after the agent produces something, it can keep managing it, and I have a page where I can open it, edit it, and decide whether to publish.

Now the spec can get more specific.

First, content has to be stored in a form the agent can work with. Markdown could be one option on the table, and the page I read could render it as HTML. Then we need to work out how the two sides connect. After I edit on the page, which copy does the agent read next time? When it's done editing, where do I pick it up?

Whether to use them still comes back to the goal and how I work. I care about whether the whole flow keeps working end to end. A format isn't the answer just because AI suggested it.

For this example, a spec could start with:

Goal: Keep what the agent produces in one place, where I can read, edit and review it.

Flow: The agent submits a draft and I open it to edit. When I hand it back to the agent, it continues from the current version.

Content management: Where content is stored, and how my edits and the agent's edits connect.

Publishing: Who handles drafts, review and publishing, in a way that fits how I already work.

Done when: One piece of content goes through saving, reading, editing and reloading, and each step picks up where the last one left off.

That's a sketch of a spec, and the details still get settled in discussion. Once it's written to this level, the agent has a better chance of judging whether a feature it proposes actually helps.

Why the spec matters so much

Most of the time, I'm not watching the agent the whole way through.

It has to organize information, fill in details, and decide what to do first. If the goal only lives in a few early messages, then checking later whether it drifted means digging that discussion back up.

Once it's a spec, the agent and I work from the same document. When it proposes something new, I can ask: does this fit the problem we set out to solve? Did it change a flow we already agreed on?

When I say "don't go against the spec," I mean the later work is bound by those decisions. With a spec in place, I still check the result against it. One more file in the repo doesn't replace acceptance.

The content tool makes this easy to see. The screen can look great, but if the agent overwrites a post I edited with an old draft next time, the editing flow is broken. Adding a button and making content carry over correctly are problems of very different size.

This ties back to the yardstick from last time. The spec writes down what "done" means, so I can tell whether I'm looking at part of a feature or a flow I can actually use.

If halfway through we find the original plan doesn't fit, we can go back and change the spec. Write down what changed and why, so the plan gets updated with it. Otherwise the document says one thing, the build does another, and later nobody knows which standard to check against.

Step two: write the plan with writing-plans

Once the spec is settled, I use Superpowers' writing-plans to lay out the implementation plan.

This is the step where we get concrete: how the architecture works, how the SQL is written, which interactions the site's JavaScript handles, and which services need permissions set up.

The same example shows how the two documents differ.

The spec says: "When the agent edits a post again, it continues from the current version." The plan breaks that down: how to find the current version, where to read it from, where the edit is saved, and how to check it didn't overwrite something I already changed.

That's work that can be done one item at a time.

If a plan only says "build the backend, build the frontend, write the tests," it looks ordered, but a lot of decisions are still open. Once the agent starts, it has to fill those gaps on its own.

When I review a plan, I want to at least understand what each step delivers, what has to be ready first, and how to check it when it's done. Anything that needs me to grant access or provide settings should be listed up front, so I know which steps have prerequisites.

Not every line of code has to be written in advance. Decisions that shape the architecture or how the thing gets used should be settled here.

Step three: review, then hand it to the agent

Once the plan is written, I read it before handing it over.

In review, I hold the plan up against the spec. Once these steps are done, will they really solve the problem I started with? Did it schedule lots of features and miss the most important action? Are the places that need me spelled out?

Once the direction is confirmed, in my workflow I use Codex's goal to keep the agent working on tasks that take a while. The goal I give it includes the outcome, the scope and how to verify it, so it can tell what's still missing.

For the content tool, the task is more than "build the page." The agent has to walk through the flow in the spec: can content be saved and opened, and after an edit, does reloading give the latest version?

Then when the agent says it's done, I have something to check. If a step stalls because of missing access or settings, it should say what's finished and what's missing, so we can pick it up from there.

I don't need to watch every action, but at the end I still look at the real result. For the site, I go through the flow and the checks that go with it. For a post, I open it, read it, and confirm the content and where it's saved are both right.

Step by step means saying it clearly

For me, "step by step" with AI includes taking ideas I haven't fully put into words and shaping them until the agent can run them and I can verify the result.

It might start with nothing more than "I want a content tool." After talking it through, I should be able to say why I need it, how content comes in, where I take over, and how far it has to go before it counts as usable.

The spec keeps those decisions, and the plan turns them into real work. When the agent starts, it fills in details along a direction we've already confirmed, so the important choices don't all wait until someone is writing code.

So when AI gives me a few options, I first ask myself: have I fully described the problem I'm actually trying to solve? Have I told it my habits and limits? Once those are filled in, I'm in a much better position to judge whether its suggestion fits, and to know which direction goes into the spec.