Structuring an agent prompt for a real codebase
ost failed agentic coding sessions come from the same place: the prompt was vague, the agent inferred the wrong thing, and you spent thirty minutes chasing AI-generated bugs that wouldn't exist if the first message had been precise. A short structure for the opening prompt — applied consistently — turns the agent from an unpredictable junior into a useful pair partner.
Agent Prompt Structure
- Opening promptuse
- Five-part structure
- Precise first message
- Bounded changes onlywithin
- Familiar code style
- Avoid design decisions
- Fresh session signals
Table of Contents
Quick reference
Five-part prompt
Goal, constraints, files, acceptance criteria, plan-first.
Plan first
Always ask for a plan before changes. Catches misunderstandings cheap.
Scope tight
If you can't describe done in two sentences, the work is too vague.
Files as pointers
List paths, don't paste content. Agent will read.
Reset on the second miss
Two wrong attempts = bad context. Start fresh.
End deliberately
Sessions are tools. Close them. Write a summary. Start the next.
Most failed agentic coding sessions come from the same place: the prompt was vague, the agent inferred the wrong thing, and you spent thirty minutes chasing AI-generated bugs that wouldn't exist if the first message had been precise. A short structure for the opening prompt — applied consistently — turns the agent from an unpredictable junior into a useful pair partner.
What you'll learn
The five-part opening prompt
The plan-first instruction
Before making changes, propose a short plan and pause for confirmation.
The acceptance criteria
How you'll know it's done.
The relevant files
Pointers, not full content.
The constraints
What it must do, must not touch, and must preserve.
The goal
The goal in one sentence. Plain English, no jargon.
A reliable opening prompt has five parts. Every part skipped is a chance for the agent to invent the wrong thing.
1. The goal in one sentence. Plain English, no jargon. "Add server-side validation for the email field on the signup form."
2. The constraints. What it must do, must not touch, and must preserve. "Use Zod for validation. Do not change the existing client-side validation. Keep the existing error-message styling."
3. The relevant files. Pointers, not full content. "app/(auth)/signup/page.tsx for the form, lib/auth/validation.ts for shared schemas, app/api/auth/signup/route.ts for the server handler." The agent will read them; you don't need to paste.
4. The acceptance criteria. How you'll know it's done. "Submitting an invalid email returns a 400 with a structured error. Existing tests still pass. New test in tests/auth-validation.test.ts covers the new behaviour."
5. The plan-first instruction. "Before making changes, propose a short plan and pause for confirmation." This single sentence is the most underused. It catches misunderstandings before any code is written.
A prompt with all five parts takes 60 seconds to write and saves 30 minutes of back-and-forth. The investment ratio is wildly in your favour.
Scope the work to the agent's competence
Agents are good at clearly-bounded changes within a familiar code style and bad at cross-cutting design decisions. Scope accordingly.
Work that goes well:
Work that goes poorly:
The rule of thumb: if you can't describe what done looks like in two sentences, the work is too vague for the agent. Either get the design clear yourself first, or work iteratively in much smaller steps.
When to start a fresh session
Long agent sessions degrade. The context fills up with old reasoning, old wrong turns, and stale assumptions. The agent starts repeating itself, ignoring earlier instructions, or producing low-quality code that wouldn't happen on a clean slate.
Start fresh when:
- The task changed. Don't pivot a session from "add validation" to "refactor the auth flow." Start a new session, with a new opening prompt.
- The agent has been wrong twice in a row. A second wrong attempt usually means the context has accumulated bad assumptions. Reset and re-prompt with the lessons learned.
- You're starting a different kind of work. Test-writing, refactoring, and bug-fixing all have different cognitive shapes. Mixing them in one session degrades each.
- The conversation is over 30 turns. Even on the same task, length is a quality risk.
The shift in mindset: a session is a tool, not a relationship. End it deliberately, write a short summary of what was done, and start the next one with full context budget.
Want a more guided way to practise this?
Common questions
Should I let the agent run autonomously or step-by-step?
Step-by-step for unfamiliar work, autonomous for repetitive or well-bounded work. For a new feature in a codebase the agent has worked on before, "go ahead and ship the plan you proposed" is fine. For a first attempt at a complex change, review each step.
What about specifying the exact functions or APIs to use?
Helpful when the agent doesn't know your conventions. "Use the existing useAuth hook from lib/auth/hooks.ts, not a new one." You don't need to spell out every detail — pointers to existing patterns are enough.
How do I get the agent to stop over-engineering?
Be explicit: "Make the smallest change that makes the test pass. Do not refactor unrelated code. Do not add abstractions for hypothetical future needs." Restate this in the constraints section if it's a recurring problem.
What if the agent insists it's right and I think it's wrong?
Almost always, the agent is wrong about details and you're wrong about how to express what you want. Re-prompt from the start with a clearer goal and constraints. If the agent still insists, run the code yourself and check.
Bottom line
A five-part opening prompt — goal, constraints, files, acceptance criteria, plan-first — turns the agent from an unpredictable junior into a useful pair partner. Scope the work to its competence, reset sessions when they degrade, and treat the prompt as the most important code you'll write that day.