--- title: "Structuring an agent prompt for a real codebase" source: https://www.taim.io/agentic-coding/structuring-an-agent-prompt-for-a-real-codebase published: Sat May 09 2026 10:51:17 GMT+0000 (Coordinated Universal Time) updated: Thu Jun 04 2026 17:17:24 GMT+0000 (Coordinated Universal Time) description: "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 shor" --- # Structuring an agent prompt for a real codebase 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. 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 - A five-part structure for an effective opening agent prompt - How to scope work so the agent stays inside its competence - When to start a fresh session instead of continuing one ## The five-part opening prompt 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: - Adding a new endpoint that mirrors an existing one. - Implementing a function whose signature, inputs, and outputs are already specified. - Adding test coverage for a known-correct piece of code. - Refactoring a single file or function whose behaviour is well-tested. - Adding type annotations or improving error messages. Work that goes poorly: - "Improve performance" without specific bottlenecks. - New cross-cutting features that touch many files for the first time. - Anything where you don't actually know what the right answer should look like — the agent will produce something plausible-but-wrong, and you won't catch it. - Large refactors that depend on careful judgement about boundaries. 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. ### 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. ### 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. ### Next steps - On your next agent session, write the five-part prompt before you start. Time it. - Pick a recent failed agent session. Identify which of the five parts was missing. - Add "propose a plan and pause for confirmation" to your default opening prompt template.