AI generates better code when it understands what you actually want to build.

This sounds obvious, but most teams skip the planning phase and jump straight into prompting (or builing todos/half-ass plans with prompts). They describe the feature in a few sentences, paste some code, and hope the AI figures out the rest.

The result is frantic back and forth with AI tools, with soul-searching waits in between, that ends up with code that technically works but misses the point. Features that solve the wrong problem. Architecture that has been altered drastically for minimal or no gain.

What actually happens

Without solid planning, AI makes assumptions. It fills in gaps with generic solutions. It optimizes for code that runs instead of code that solves your specific problem.

You ask for “a user authentication system” and get a textbook implementation with bcrypt hashing, JWT tokens, and password reset flows. But you needed something that integrates with your existing LDAP system and handles service accounts differently than human users.

The AI wasn’t wrong; your specification was incomplete.

Why planning for humans creates better AI output

When we plan for human developers, we create context that AI needs but can’t infer. You document:

  • Edge cases and constraints: “Authentication fails gracefully when LDAP is down”
  • Integration points: “Shares session state with the billing service”
  • Success criteria: “Users can log in with existing corporate credentials”
  • Non-functional requirements: “Handles 10k concurrent users, logs all auth attempts”

Humans would ask clarifying questions during implementation. AI just makes educated guesses.

What We Do Onstead

We start with a planning document that lives in the docs/plans/{issue}/specification.md, next to the code. This document, first and foremost for the engineers.

This is the only document we throughly review on the PR process any more. It gives the whole theam

The payoff

AI generates code that fits your actual requirements instead of textbook examples. You spend less time rewriting and more time extending. Features work in your environment, not just in isolation.

Your AI becomes a better pair programmer because it understands the context of what you’re building.

Plan first, review with humans. Everything else gets easier. This planning discipline works for both AI-assisted development and traditional team coordination—the same principles that make How We Work effective for human teams make AI collaboration more productive.