Lesson 1: The Prescription Spectrum

Why start with a spectrum?

Every time you hand a task to a coding agent, you make a decision you may not notice: who gets to decide what. Write "add caching to the product API" and the agent picks where the cache sits, which library to use, how long entries live, how they get invalidated and how the code is laid out. Write out the function signatures, the Redis key format and the TTL, and the agent is mostly typing.

Neither extreme is right by default. Think of a contractor. With some you hand over stamped drawings. With others you say "I need a kitchen that seats six" and let them design it. Most jobs sit in between: the wall stays, the plumbing goes here, pick whatever cabinets fit. This level gives you the vocabulary for that middle ground. Later levels cover how to choose a position. Here we only map the ground.

The scale, end to end

Note that the positions are not about how long the prompt is. A one-line brief can be tightly prescriptive ("use functools.lru_cache(maxsize=512) on get_price"), and a page of background can still leave every real decision open.

Three things you can prescribe

When you read a brief, sort each sentence into one of three bins:

1. Outcome: what must be true when the work is done. Behaviour, performance, a passing check. "Returns 429 after 100 requests per minute per API key."
2. Structure: the shape of the solution. Which module owns it, which interface it implements, what crosses a boundary. "Lives in middleware/, implements Limiter, stores state only through CacheClient."
3. Implementation: how the inside works. Algorithm, library, loop, variable names. "Use a sliding-window log in a Redis sorted set with ZREMRANGEBYSCORE."

A brief usually mixes all three. Problems start when you don't notice which bin a sentence is in. If you fix implementation details you don't care about, you get your guess instead of a possibly better one, and you spend review time on trivia. If you leave out an outcome you do care about, the agent fills the gap with something plausible that you discover later.

Gotcha: "Use best practices" and "keep it clean" belong in none of the three bins. They prescribe nothing, and the agent will read them however it already intended to.

Worked example: rewriting a vague brief

Here is a real-looking prompt from a team chat:

Add rate limiting to the public API. Make it robust.

Everything is delegated, including things the team has firm views on. Here is the same task with the decisions sorted:

## Task: rate-limit the public API

### Fixed (do not change)          <- structure + constraints
- Implement the existing `Limiter` protocol in `app/middleware/limits.py`.
- State goes through `CacheClient` only; no new services or dependencies.
- Must behave correctly with 4 app instances behind the load balancer.

### Outcome (how we judge it)        <- outcome
- More than 100 requests/min per API key -> HTTP 429 with a `Retry-After` header.
- `pytest tests/test_rate_limit.py` passes; add cases for the boundary (100th vs 101st).

### Yours to decide                  <- explicitly delegated
- Algorithm (fixed window, sliding window, token bucket): say which and why.
- Internal function names and file layout inside `limits.py`.

### Ask before                        <- escalation point
- Changing the `Limiter` protocol or any public response format.

The structure is the point here, not these exact headings. Every decision now has an owner, and the "Yours to decide" section matters as much as the "Fixed" one: it tells the agent where to use its judgement instead of hedging or asking. It also tells you what not to argue about in review.

Exercise: place five decisions from your codebase

Pick five recent decisions and give each one a position. For example:

Decision                                  Position              Agent free to decide
----------------------------------------  --------------------  -------------------------------
Public REST response format               Structure prescribed  Serializer internals
Auth token validation                     Fully prescribed      Nothing beyond typing it out
Admin dashboard CSS layout                Outcome prescribed    Components, styling approach
DB migration for new column               Constraints           Migration steps, within
                                                                "no downtime, reversible"
Internal CSV export script                Fully delegated       Everything

Write the third column every time. If you can't say what the agent may decide, you haven't placed the decision yet.

Where instruction files fit

Decisions you prescribe on every task belong in a standing instruction file rather than in each prompt. AGENTS.md is an open Markdown format for this. Its site reports use in over 60,000 open-source projects and support from more than 30 agents and tools, and it is now stewarded by the Agentic AI Foundation under the Linux Foundation. Some agents have their own equivalents, such as Claude Code's CLAUDE.md. Anthropic's current Claude Code guidance puts the job neatly: tell the agent what it can't see, give it a check to run, and enforce the rules that can't have exceptions. That works as a short test of what deserves prescribing at all.

Honest note on evidence (late 2026): Very little measured research compares levels of prescription directly. Most advice, including this lesson's framing, is practitioner opinion. One measured result is worth keeping in mind: METR's 2025 randomised trial found experienced open-source developers took 19% longer with AI tools while believing they were about 20% faster. Treat your gut feel about "what works" with agents as a hypothesis to test.

Key takeaways

• Directing an agent is a spectrum: fully prescribed, structure, constraints, outcome, fully delegated. Most real decisions sit in the middle.
• Sort every line of a brief into outcome, structure or implementation. Unsorted lines are where surprises come from.
• Prompt length isn't prescription level. What counts is which decisions you fix.
• Good briefs name what is fixed, what is yours to decide, how the work is judged, and when to ask first.
• Prescriptions you repeat on every task belong in an instruction file such as AGENTS.md.
• The evidence base is thin and mostly opinion. Hold any rule here loosely.