How to Understand What You're Building Before You Kick Off Codex or Claude Code

The most expensive moment in a vibe-coded project is about two weeks in, when you finally see what the agent built and realize it's not what you meant. The login works differently than you pictured, the data lives somewhere you didn't choose, it depends on three paid services you've never heard of, and it looks like every other AI app.

None of that is the agent's fault. You both started building before either of you could see the plan.

The fix: before any code, have the agent put the whole plan on one web page you can actually look at, then sign off on it. It takes 20 to 30 minutes and it's the best-spent time in the project.

Why a web page, not a chat message

Both Codex and Claude Code have a plan mode (/plan in Codex; plan mode in Claude Code) that writes out what the agent intends to do before it does it. Use it. But a plan in a chat is a wall of text, and it's easy to skim past the decision that matters.

A web page fixes that:

• You can see it. Wireframes and mockups show what text can't.
• It's one place. Architecture, services, costs and screens side by side.
• You can share it. Send it to a friend, a co-founder or a potential user and ask "does this make sense?"
• It becomes the spec. Save it in the repo and the agent builds against it, not against its own memory of the conversation.

Builders are already doing this

This fall, the most-shared planning posts on X all point the same way:

• @trq212, showed a Claude Code skill he was testing that writes plans as HTML pages that surface questions and include mockups before any build. It passed 560,000 views. In a follow-up he noted that structured HTML plans are more token-efficient than having the model redraw UI from scratch.
• @itsdavemartin had Codex save a single clickable HTML mockup of a help center, reacted to it, then handed the file to Claude to build. He says the result shipped as 23 pull requests and 95 help docs.
• @cathrynlavery has Codex review every Claude Code plan, read-only, before she approves it. A second model catches what the first one assumed.
• @davis7 and others turned on Codex's ability to ask multiple-choice questions mid-task, so it stops and checks instead of running with the wrong assumption.

There's a real counter-argument worth knowing. In September, Ayman Nadeem's essay "Plan mode is dead" (593 points on Hacker News) argued that nobody reads long AI-written specs, and that forcing "finish thinking, then build" fights how the work actually goes. Several commenters agreed that the useful part is making the model read the code and ask questions first, not the document itself.

We think both are right, and that's why the format matters. A long markdown spec doesn't get read. A page with pictures, a cost table and a short list of open questions does, especially if you're not a developer. Keep it short enough to read in ten minutes.

What the plan page should include

1. The one-sentence pitch. Who it's for, what it does, why they'd use it. If the agent can't write this clearly, the idea isn't clear yet.
2. User flows. The three to five paths someone takes, step by step: sign up, do the main thing, come back, pay.
3. Wireframes for each key screen. Gray boxes are fine. This is about layout and flow, not color.
4. Mockups for the two or three most important screens, in the actual look. (More on how below.)
5. Architecture diagram. Frontend, backend, database, and what talks to what.
6. Services used, each with what it does, why it was picked, the free tier, and what it costs at 1,000 users. This is where surprise bills and lock-in hide.
7. Data model. The main tables and what's in them, in plain words.
8. What's out of scope for version one.
9. Open questions. Anything the agent had to guess. This list is gold: it's every decision it would otherwise have made silently.

The prompt

Paste this into Codex or Claude Code (in plan mode, or with "don't write app code yet"):

Don't build anything yet. I want to understand the plan first.

Create a single self-contained HTML page at plan/index.html that explains what we're about to build, for someone who isn't a developer. Include: 1. A one-sentence pitch: who it's for, what it does. 2. The main user flows, step by step. 3. A wireframe for each key screen (simple boxes, drawn in HTML/CSS or SVG). 4. An architecture diagram showing frontend, backend, database and every outside service, and how they connect. 5. A table of every service and library we'll depend on: what it does, why it was chosen over alternatives, free tier limits, estimated monthly cost at 100 and 1,000 users, and how hard it would be to switch away later. 6. The data model in plain language. 7. What's out of scope for v1. 8. A list of open questions and every assumption you made.

Use plain language. Then open it so I can review it. We'll change the plan until I approve it, and only then start building. Once approved, reference plan/index.html in AGENTS.md (or CLAUDE.md) as the source of truth.

Open plan/index.html in your browser, read it top to bottom, and push back. "Why Firebase and not Supabase?" "Do we need accounts in v1, or can it be an email link?" "Cut the admin dashboard." Every change here costs one message. The same change after the build costs a day.

Get the mockups right before the code

Wireframes settle the layout. Mockups settle the look, and that's where AI-built apps go generic if you skip it. (Why: frontier models aren't great front-end designers on their own.)

In Codex: ask for the mockups with image generation first. OpenAI's own Codex guides recommend generating UI mockups with `gpt-image-2` before Codex implements the direction you choose. Ask for three or four different directions, pick one, iterate on the image, then add the approved image to the plan page.

Before building, use image generation to create three distinct visual directions for the home screen and the main app screen, desktop and mobile. Add them to plan/index.html with labels. I'll pick one.

In Claude: design the key screens in Claude Design, refine the prototype by clicking through it, then use its handoff to Claude Code so the build starts from your approved design.

Either way, the rule is the same: nothing gets built until you've said "yes, that one" to a picture.

What to check before you sign off

• [ ] I could explain the product to a friend from the pitch alone.
• [ ] The main flow is short. If it takes more than three steps to get value, cut.
• [ ] I know every service it depends on, and I'm OK with the cost at 1,000 users.
• [ ] Nothing important is locked into one platform without a reason. (See what makes Replit hard to leave for what this looks like when it goes wrong.)
• [ ] The mockups look like my product, not a template.
• [ ] Every open question is answered or consciously deferred.
• [ ] There's a plan for email signup and analytics from day one. (Why those two matter most.)

Keep the page alive

When you change direction mid-build, update the plan page first, then the code. When you come back to the project in three months, the plan page is the first thing you (and your agent) read. It's the best defense against a project you no longer understand, and the easiest way to reboot one later.

And when the build is done, the plan page has one more job: it's the first draft of your launch. The pitch is your headline, the flows are your demo, and the mockups show what people will get. If you'd like a read on what's still missing before launch, the free LaunchBuddy scan reviews your live site and shows you the gaps.