Prompting for Architecture, Not Just Code

The default way people use AI coding tools: "Build me a React component that does X." And the AI does it. Sometimes it's good. Sometimes it's a 400-line component with three abstractions you didn't ask for and a state management pattern from 2019.

The problem isn't the code generation. The problem is that you skipped the thinking.

I've been using AI heavily across 9 projects now, and the pattern that keeps proving itself is this: the earlier in the process you involve AI, the better the output at every stage after it. Not earlier as in "start coding faster." Earlier as in "start thinking through the problem before anyone writes a line."

The Concept Brief: 30 Minutes That Save 30 Hours

Before I write any code on a new project, I work through a concept brief. It's a one-page document that answers four questions: what am I building, who is it for, why does it need to exist, and is it feasible?

Here's the actual brief for this site:

That took one conversation with Claude. Not "write me a concept brief." More like "I have this idea for a site that documents my dev process. Here's what I'm thinking. Help me pressure-test it."

The AI pushed back on a few things. Asked about monetization (none, intentionally). Asked who the audience really was (indie devs, not enterprise teams). Asked whether a blog with categories would accomplish the same thing (no, because phase-organized navigation is the differentiator). By the end of that conversation, the concept was sharper than what I walked in with.

If I'd skipped this and just said "build me a developer blog," I'd have gotten a generic developer blog. The concept conversation is what made it something specific.

Requirements: Forcing Scope Decisions Before Code Exists

After the concept brief, I write requirements. Epics, user stories, acceptance criteria. For this site, that was 7 epics and 20 stories with MoSCoW prioritization.

This is where AI really shines as a thinking partner. The conversation goes something like:

"Here's my concept brief. I need to break this into epics and stories. The site needs methodology pages, a journal organized by phase, and a portfolio section. Help me scope this into Must Have vs Should Have."

Claude doesn't just list features. It asks clarifying questions. "Does the journal need comments?" No. "Does the portfolio need filtering?" Not in v1. "What about search?" Won't Have. Each question forces a scope decision I might have deferred until I was already building, which is where scope creep lives.

The output was a structured requirements document with acceptance criteria for every story. Things like:

Given a visitor on the journal page, When they select a phase filter, Then only entries matching that phase are shown.

That acceptance criterion became the exact feature I built. No ambiguity, no "I'll figure out the filtering later." The requirements conversation took maybe two hours. It would have taken the same time without AI, but the result would have been less rigorous because I wouldn't have had someone asking "what about this edge case?" at every turn.

Architecture: The Document That Prevents Rewrites

The architecture document is where the biggest leverage happens. This is the conversation where you decide how the pieces fit together before you start building them.

For this site, the architecture conversation covered:

• Content pipeline: How do MDX files become rendered pages? (Vite plugin at build time, not runtime)
• Routing strategy: File-based or explicit? (Explicit, for control over pre-rendering)
• Data flow: Where does content indexing happen? (Build-time glob imports, not API calls)
• Deployment model: SSR or SSG? (SSG with ssr: false for pure static Cloudflare Pages)
• What we're not building: No backend, no database, no user accounts, no CMS

That last bullet is the most important architectural decision in the whole project, and it came directly from the concept brief. The AI knew the constraints because we'd already established them two conversations earlier.

The architecture document included a system diagram:

Content Authoring (MDX)
        ↓
Build Pipeline (Vite + React Router v7)
  - MDX compile → React components
  - Frontmatter extraction → content index
  - SSG pre-render → static HTML
        ↓
Cloudflare Pages CDN
  - Static HTML + JS + CSS
  - Zero server-side logic

Every technical decision in that diagram traced back to a constraint from the concept or requirements phase. That's the whole point. When you prompt for architecture with full context, you get decisions that fit together. When you prompt for code in isolation, you get code that works in isolation.

The Compounding Effect

Here's what happens when you use AI at each phase before writing code:

1. Concept brief establishes constraints (no backend, static hosting, indie dev audience)
2. Requirements scope the work against those constraints (20 stories, not 50)
3. Architecture designs a system that fits the scope and constraints
4. Code implements a well-defined architecture with clear boundaries

By the time I actually asked Claude to write React components, it already knew the content pipeline, the routing model, the deployment target, and the scope boundaries. The code conversations were fast and focused because all the hard decisions were already made.

Compare that to starting with "build me a developer blog in React." The AI has no constraints, no scope, no architecture. It'll make reasonable guesses about all of those things, and every guess is a decision you'll either live with or have to undo later.

How to Start

You don't need the full Playbook to get this benefit. Before your next project, try one thing: have a conversation with AI about what you're building before you ask it to build anything.

Not a prompt. A conversation. Explain the idea. Let it ask questions. Disagree with some of its suggestions. Make decisions and write them down.

Then, when you do start coding, paste that document into the context. "Here's what we decided. Now let's build it."

The code will be better. Not because the AI got smarter, but because you gave it something worth building.