Prompting for Reliable Agents: The Four-Part Specification

Up to this point, we’ve discussed the machinery behind agentic coding—loops, context, harnesses, and benchmarks. This chapter shifts from machinery to skill.

Prompting is where the discipline of agentic coding becomes visible. Not as magic words or page-long prompts, but as a way of describing work to an agent so it understands scope, goals, and success conditions well enough to act and verify its own output.

Goal / Context / Constraints / Done-When

The mental model that works for most prompts is a four-part structure:

1. Goal — What needs to change or be created?
2. Context — What files, folders, documentation, examples, or errors are relevant?
3. Constraints — What standards, architecture requirements, security rules, or conventions must the agent follow?
4. Done-When — What must be true before the task is considered complete?

The first three tell the agent what it’s doing and under what conditions. The last tells it how to know it succeeded.

The last item is most often overlooked and most critical for reliability.

Consider:

“Add authentication to this endpoint”

versus:

“Add authentication to this endpoint using the existing middleware, ensure unauthenticated requests return 401, and add integration tests for both authenticated and unauthenticated cases.”

The second prompt isn’t significantly longer. But it transforms the task from “write code” to a specification with success criteria.

Done-when is the checkpoint.

When you specify that tests must pass, behavior must change in a certain way, or a bug must no longer reproduce, you’re giving the agent something it can verify.

Without done-when, judging “complete” is left to the agent’s own judgment—and that’s a signal we shouldn’t rely on alone.

Declarative Over Procedural

The second principle: state what must be true at completion, not a rigid script of every step the agent must take.

This is the foundation of specification-driven development: define goals, constraints, context, and acceptance criteria, then let the agent choose the appropriate execution method.

The human instinct often goes the opposite way. We feel safe writing:

1. Open file A
2. Edit function B
3. Add function C
4. Run test D
5. Fix errors if any

The problem: this plan assumes you know the codebase better than the agent from the start, and that the structure you see remains correct when the agent begins work.

In real codebases, both assumptions may be wrong.

If you specify results and acceptance criteria and let the agent plan, you’re leveraging one of the agent’s most useful capabilities: adapting its plan based on what it discovers during work.

Use a hybrid:

• Acceptance criteria should be clear
• Constraints should be clear when there are architecture, security, or compliance reasons
• Execution method should remain flexible unless you have a specific reason to control it

Acceptance criteria are the contract. Method is where the agent uses its capabilities.

The Discipline of Not Over-Writing

Once you understand the four-part structure, another trap follows: putting everything into the prompt.

You might start including all coding conventions, the entire repository structure, all edge cases, and architecture descriptions every time you start a session.

This is moving the work of memory and skills back into the prompt.

Use the same question from Chapter 3: Is this true for every session, or only for this task?

If it’s a rule that applies to every session, put it in CLAUDE.md, AGENTS.md, or the appropriate memory file.

If it’s a reusable workflow, consider separating it into a SKILL.md.

If it’s task-specific information, put it in the prompt.

Separating these three keeps prompts short and meaningful:

• Memory — What the agent should always know
• Skill — Reusable ways of working
• Prompt — The task at hand

A prompt filled with durable rules is a form of technical debt, because the same rules get copied to every session and eventually each copy starts to diverge.

One Chat per Coherent Outcome

Good prompts don’t exist in isolation from session scope.

Tasks related to the same problem should live in the same session, because reasoning and context share value.

But when you start describing unrelated changes, stop and create a new session.

Two unrelated changes mean:

• Two prompts
• Two context scopes
• Two diff reviews
• And generally, two reasoning trails

This is the same principle from the previous chapter:

One session per coherent outcome.

A good prompt isn’t just well-written—it’s in the right session scope.

Prompting in the Agentic Loop

A prompt isn’t a one-shot message that ends the conversation. It’s the first step of the loop.

In a terminal agent, the prompt goes into the harness, which may continue as:

Prompt → Plan → Read → Edit → Test → Observe → Repair → Verify

So good prompting should be designed to support this loop.

Be Specific About Checks

One of the most valuable things you can put in a prompt is how to verify the work:

“Run npm test and npm run lint before stopping.”

This is verification-first prompting in its smallest form.

You’re not just telling the agent to write code—you’re requiring it to have evidence before declaring the task complete.

Point, Don’t Summarize

When you know the relevant files, point to them:

“Update src/auth/session.ts”

is better than:

“Update session handling”

File names and symbols are more meaningful than vague descriptions because they reduce the space the agent needs to search.

Of course, only point to what you know is relevant. If the change is likely cross-cutting, that’s where you need to specify additional retrieval.

Expose the Invisible 20%

Chapter 4 shows that agents often miss impacts outside their context.

If you already know the change touches:

• API consumers
• DTOs
• Authorization layers
• Audit logs
• Migrations
• Frontend/backend contracts

Specify it.

This information differs from general prompt information because it’s part of the invisible 20% the agent can’t infer from what it hasn’t seen yet.

When you know a dependency exists elsewhere, don’t test whether the agent will discover it—just tell it.

Short Prompts Aren’t Vague Prompts

This is an important distinction.

A short prompt can have a good specification:

Add retry to the payment client when upstream returns 503

Context: src/payment/client.ts and related tests

Constraints: Use existing retry policy. No retry for 4xx.

Done-when: Add tests for 503 and 4xx, and the related test suite passes.

No lengthy architecture paragraphs, no step-by-step instructions, no coding conventions the repository already knows.

But the agent has what it needs:

• Goal
• Starting point
• Constraints
• Success criteria

This is the difference between brevity and ambiguity.

A good prompt doesn’t need to be long. It needs to have the right information.

Prompt as Small-Specification

From a distance, prompting for agentic coding looks closer to writing specifications than writing chatbot commands.

You define:

Goal — the desired result Context — information the agent needs Constraints — what’s forbidden or required Done-When — evidence of success

Then the harness takes this specification to drive the loop.

That’s why a good prompt isn’t a “clever” prompt—it’s one that reduces ambiguity without stealing the planning work from the agent.

---

This article is adapted from Chapter 9 of the Agentic Coding book.