Your AI Agent Needs a Blueprint
- Rebellionaire Staff
- Jun 23
- 6 min read
If your AI agent keeps drifting, there’s a good chance the problem isn’t the model.
It’s the brief.
Most people sit down with an agent, describe the project once, and expect it to hold the whole thing in its head. The goal. The constraints. The files. The weird little decisions from three prompts ago. The thing you said you didn’t want but never wrote down.
Then the agent starts guessing.
Of course it does. You gave it a job site with no blueprint.
That’s the point of this video. Bradford isn’t talking about project management software. He’s talking about one markdown file in your repo. A plan file. Something the agent can read before it starts touching code.
Simple. Almost annoyingly simple.
But it changes the work.
The Plan Isn’t for You
This is the part most people miss.
The plan isn’t really for your brain. Your brain already has the context, or at least it thinks it does.
The plan is for the agent.
You know why you rejected one feature. You know which file is probably relevant. You remember the tradeoff from yesterday’s session. The agent doesn’t, unless that context exists somewhere it can read.
Anthropic has been pretty blunt about this idea: better AI work depends on giving the model the right context, not just clever wording. Their guidance compares prompting an AI to onboarding a new employee who needs background, goals, constraints, and examples before doing good work.
That’s exactly what a plan file does.
It tells the agent:
What we’re building
Why we’re building it
What’s already been decided
What comes next
Which files matter
What’s out of scope for now
That last one matters more than people think.
A good plan doesn’t just tell the agent what to do. It keeps the agent from wandering into “helpful” ideas that are absolutely not today’s problem.
Why Agents Drift
AI agents are built to act. That’s the appeal.
They can read files, write code, call tools, revise their work, and continue through a task. Google’s agent writing describes these systems as using models, tools, orchestration, and reasoning loops to pursue goals across multiple steps.
That power cuts both ways.
If the goal is clear, the agent can move fast.
If the goal is fuzzy, the agent still moves fast.
That’s where the mess starts. It edits a file you didn’t mean to touch. It builds a generic version of a feature because the specific one was never written down. It adds extra logic because “that might be useful.” It solves the shape of the problem, not the actual problem.
And honestly? That’s on us.
If you hired a contractor, you wouldn’t say, “Just build something house-ish.” You’d give them drawings. Measurements. Materials. Order of work. Constraints.
But with AI, people do the opposite. They hand the agent a loose paragraph and hope the model can infer the rest.
Sometimes it can.
Sometimes it builds the wrong wall.
One Markdown File Beats a Giant Prompt
The fix doesn’t need to be complicated.
Bradford’s workflow uses a plain markdown file in a plans/ folder. That’s it.
Not Jira. Not a separate app. Not a sacred productivity system that becomes its own full-time job.
One file the agent can read.
That matters because prompts disappear into the flow of the conversation. A plan sticks around. It can be reopened in a new session. It can be updated after a decision. It can show what’s done, what’s next, and what changed.
This is especially useful once the project gets bigger than one sitting.
Context windows fill up. Sessions end. You come back tomorrow. The agent doesn’t automatically remember the whole project the way you wish it did.
The plan becomes the handoff.
New session? Read the plan.Lost the thread? Read the plan.Disagreement about scope? Read the plan.Agent wants to add a new feature mid-step? Read the plan.
If it’s not in the blueprint, it’s not happening today.
The Workflow Before the Work
The best part of Bradford’s approach is that the agent helps create the plan before it starts building.
That matters.
You don’t want to sit alone and type a perfect plan from scratch. That’s how you end up writing fantasy requirements. The agent should read the actual code first, then ask questions.
The sequence looks like this:
The agent reads the relevant code.
The agent asks one question at a time.
You answer.
The agent writes the plan.
The agent reviews the plan for gaps before work starts.
That fifth step is the sleeper.
Before the agent builds anything, it acts like an inspector. It looks for missing dependencies, vague steps, bad paths, unclear scope, and places where the plan might fail later.
That’s not busywork. That’s where you catch the expensive mistakes early.
Bradford gives a good example in the video: a plan had an old file path buried deep in a later step. If the agent had run straight through, it would’ve crashed far into the build. The review caught it before the work started.
That’s the whole game.
Find the bad assumption while it’s cheap.
Don’t Tell the Agent to “Run the Whole Plan”
This is where people get themselves in trouble.
They finally write a plan, then tell the agent to execute all fifty steps.
Bad move.
That spreads the agent’s attention across too much work. It burns context. It skips checkpoints. It reduces your chance to catch a wrong turn before it becomes ten wrong turns.
Run one step.
Stop.
Review.
Then run the next one.
This lines up with what agent research has shown for years. The ReAct paper, one of the better-known papers in this space, showed that language models can perform better on interactive tasks when reasoning and action happen together in a loop instead of as one giant answer.
Same idea here.
Don’t ask the agent to renovate the whole house in one shot.
Ask it to frame one wall. Then look at the wall.
What Makes a Plan Step Useful
A bad step says:
“Build the API.”
That’s not a step. That’s a fog machine.
A useful step says something more like:
“Add the endpoint that saves a draft plan, using the existing auth middleware and validation pattern from the current project.”
Now the agent has something to work with.
A good plan step should name the action, the likely files or patterns, the constraint, and the stopping point. It should be small enough that the agent can finish it and show you what changed.
Bradford also recommends numbering steps with gaps: 2, 4, 6.
Tiny detail. Very useful.
Plans change. You will discover missing prep work. You will need to insert a step. If the numbering has gaps, the plan can absorb reality without turning into a renumbering chore.
That sounds boring because it is.
Boring is good. Boring ships.
The Plan Protects Future You
There’s another benefit that doesn’t show up until later.
The plan becomes a receipt.
Not just “what did we mean to build?” but “why does this code exist?”
Bradford talks about an 883-line module that sat in one of his projects unused. Nothing imported it. It had been built because an old plan said to build it, then the project moved on.
Without a plan, that kind of file can haunt a codebase forever. Nobody wants to delete it because nobody remembers whether it matters.
With a plan, the system can close the loop. The next pass caught the orphaned work and removed it.
That’s not glamorous, but it’s real.
Good agent workflows don’t just help you create more code. They help you stop carrying code that no longer belongs.
This Is the Bigger Shift
The lesson isn’t “write more documentation.”
Please don’t take that from this.
The lesson is: give the agent working context in a form it can use.
That’s the difference between a plan file and a corporate planning doc nobody reads. The plan file lives with the work. The agent reads it. The agent acts from it. The agent updates it as the project changes.
That’s why this matters for anyone building with AI agents right now.
Better prompts help.
Better context helps more.
And the plan is the context that holds the line.
Write the plan. Show it to the agent. Run one step at a time.
That’s the blueprint.
Start here: https://www.rebellionaire.com/clearstep
Comments