Code first feels faster. Open the editor, start typing, see progress immediately. But when you're building with AI, that instinct leads to endless rewrites. The AI generates plausible code for whatever you ask, whether it fits the bigger picture or not.
Planning first saves you from that trap. Spend 15 minutes thinking through the full scope before writing a single line. The AI becomes a much better partner when it understands the destination.
Brief like you're hiring a contractor
Write down what you want to build in plain English. Not technical requirements—user outcomes.
For FlowDoc, the brief was: "Build a Node.js CLI tool that captures browser workflows using Playwright and generates Markdown documentation with screenshots. Target user: a PM, QA person, or AI-assisted builder who wants to document a product flow quickly."
Notice what's in there: the user, their goal, the output format they expect. Notice what's not: database schemas, API endpoints, class hierarchies. Those come later.
Ask clarifying questions out loud
Good AIs will ask clarifying questions about scope. Let them. This conversation happens in planning mode—no code gets generated yet.
The FlowDoc planning session caught several decisions that would have caused rewrites:
- Screenshots could expose login screens → added a
--record-from-nowflag - Target audience doesn't want AI complexity → keep it simple, just capture and generate
- Output should be shareable → Markdown with embedded images, not a web app
Each question prevented a wrong turn that would have cost hours later.
Cross check with a second AI
Take your plan and paste it into a different AI for a fresh perspective. Ask: "What am I missing? What could go wrong?"
ChatGPT flagged the login screen privacy issue that the planning AI missed. It takes 30 seconds and often catches blind spots.
Make architectural decisions before implementation
Decide on the big structural choices while you're still thinking clearly:
- Language and runtime: Node.js with TypeScript gave us npm packages for Playwright and Commander
- No database: Keep it simple—just files on disk
- Single output format first: Markdown with screenshots, expand later
- CLI over web UI: Easier to build, easier to distribute
These aren't the only good choices, but they're choices made deliberately instead of by accident during implementation.
Plan for phases, not features
Think in terms of what you'll build in sequence, not what the final product might someday include. FlowDoc had clear phases:
- Core capture: Browser automation + screenshot generation
- Clean output: Post processing to merge related events
- Rich documentation: Audio narration + transcription
- Team features: Branching workflows, Miro export
- Desktop app: Packaging for domain experts
Each phase delivers something useful. You can stop after any phase and have a working tool.
Write the plan down
Don't keep it in your head. Write a document the AI can reference later. Include:
- What problem this solves
- Who the target user is
- What the output looks like
- What's explicitly out of scope
- The file structure you expect
- Key architectural decisions
This becomes your north star when the AI suggests features that sound cool but don't fit.
Planning saves implementation time
Fifteen minutes of planning prevents three hours of rewriting. The AI generates much better code when it understands the full context. And you make better decisions about trade offs when you're not already three files deep in implementation.
The temptation is to skip this step and jump straight to coding. Resist it. Plan like a PM first, then code like an engineer.