The Week Before the Code

There's a line buried in my Summer 2026 post that I glossed over too quickly:

On a recent project, I spent an entire week doing nothing but brainstorming and writing PRDs with Claude - before the repo was even initialized.

People keep asking about the 10 PRs and the drive from Jacksonville. Nobody asks about the week before that.

That's the part that actually matters.

The automation makes your mistakes faster

Agentic coding doesn't make bad decisions good. It executes them at speed. If you start from a vague idea and point agents at it, you get a technically functional mess built at superhuman pace - complete with confident, well-commented code that does exactly the wrong thing.

The planning discipline exists specifically to prevent that. Not to slow you down. To make sure the machine is pointed at the right target before you let it run.

What a PRD actually does in an agentic workflow

A PRD in this context isn't a product management artifact. It's a contract between you and the agent.

It answers three questions:

What is this thing supposed to do? Not vaguely. Specifically. Edge cases, constraints, acceptance criteria.
What does it explicitly not do? Scope control is where agents need the most guardrails. An agent without a clear boundary will helpfully expand scope until you have a feature you didn't ask for.
How will we know when it's done? The acceptance criteria become the checklist the agent works against. If you can't write them, you're not ready to build.

When those questions are answered well, agents perform remarkably. When they're not, you spend the next three days untangling a beautiful mess.

The letter-grade trick

Once you have a draft PRD, ask your model to grade it.

Literally: "Give this PRD a letter grade, with reasoning."

What happens next is useful. The model infers a rubric, assigns a score, and explains the gap. If the grade is a B, ask what would make it an A. Then ask it to make those changes.

This isn't a party trick. It's one of the most efficient editing loops I've found. A few iterations of grade → gap → revision will get a mediocre PRD to a tight one faster than any other method I've tried. And the quality gap between a B PRD and an A PRD - in terms of what the agents actually build - is enormous.

I use this beyond PRDs now. Contracts. Architecture insights. Home repair estimates. Anywhere you want a fast, honest audit of your own thinking, it works.

Why a week?

A week sounds slow. It isn't.

A week of PRD work before a single line of code is written means:

Every feature is scoped, not assumed
Every edge case has been thought through at the planning layer, not discovered at 2am in a broken diff
The agents have a clear job to do on every issue they pick up
You can parallelize confidently because the work isn't tangled

The projects where I've skipped or rushed this step have one thing in common: I paid for it later. Not in a dramatic way. In the slow, grinding way where every sprint has a little more untangling than the last one, until the project starts to feel heavy.

One week of planning is cheap. Rebuilding something you built wrong is not.

The `docs/planning` folder

Practically, here's the setup:

Create a docs/planning folder in your repo. Every feature lives here as a markdown PRD before it becomes a GitHub Issue. Work through each one in a Claude Code Plan Mode session - describe what you want, let Claude draft, then iterate together until you have something you'd actually grade an A.

When the PRDs are ready, convert them to GitHub Issues using the GitHub CLI. Tell Claude to structure them as independent, non-blocking, agent-sized chunks. That's the last planning decision you make before the automation takes over.

From there, the hard thinking is done. The machine does the rest.

The operators who win

There's a temptation to look at agentic coding and optimize for the part that feels impressive: the automation, the parallel agents, the PRs that merge while you're on the road.

Those are downstream of the planning. The operators who are going to pull ahead aren't the ones running the most agents - they're the ones who've figured out how to think clearly before they run anything.

The automation is a multiplier. Multipliers need something worth multiplying.