Prompts Are Interfaces

A team spends an afternoon rewriting its prompt library. The old instruction read “implement the feature.” The new one reads “please carefully implement the feature, making sure to follow our conventions and think it through step by step.” Somebody adds a paragraph of encouragement about code quality. Somebody else tries a firmer register, capitalizing MUST and NEVER in a few places that felt important last time something went wrong. Results improve for about a week, unevenly, then drift back toward where they started. Nobody can say with any confidence why the good runs were good or the bad runs were bad, because nothing about what the prompt actually specified had changed — only its manners had.

It is the same instinct that shows up when a web form is producing bad submissions and the proposed fix is friendlier field labels. Rewording “Enter value” as “Please tell us your preferred value” does not stop the form from accepting a phone number in the email field, because the defect was never the phrasing — it was the missing validation. A prompt-writing culture that treats wording as the lever is diagnosing the same class of problem with the same wrong instrument, on an artifact that happens to be made of English instead of HTML.

What actually changes when a prompt works

Anthropic’s own guidance for Claude Code is instructive here precisely because it is not framed as a wording problem. Its worked examples pair a vague ask against a specific one — “add tests for foo.py” against “write a test for foo.py covering the edge case where the user is logged out, avoid mocks” — and the difference between the two is not tone. The second version names a file, states a scenario the first left to guesswork, and rules out an implementation strategy (mocks) that would otherwise have been a coin flip. Elsewhere the same guidance is blunter still: give the agent “a check it can run” — a test suite, a build, a screenshot diff — because without one, “looks done” is the only signal available, and every miss waits for a human to notice it by hand.

Neither change is a courtesy. A named file and a stated edge case narrow the space of valid outputs the way a required field narrows the space of valid form submissions. A runnable check turns “done” from a matter of taste into a boolean a program can evaluate. These are structural additions to the instruction, not softer ways of asking for the same thing — and that distinction is the one a wordsmithing culture has no vocabulary for.

The category nobody names

This is a different axis from the one Volume II spends its opening chapter on. That volume’s argument is that an instruction competes for space in a context window crowded with stale tool output, unrelated file contents, and a system prompt tuned for a different session — and that fixing an erratic result often means editing what surrounds the instruction rather than the instruction itself. This chapter is about something upstream of that: the design of the instruction as an artifact in its own right, independent of what else is in the window. A perfectly curated context can still carry a badly designed prompt, the same way a fast, uncluttered network can still carry a malformed request. Context engineering and prompt design are both real disciplines; they simply fail in different places, and a team that has only ever heard of one of them will misdiagnose failures that belong to the other.

What a wordsmithing culture is actually missing is a name for what a prompt is. Not a magic phrase that unlocks better behavior if you find the right incantation — an interface. The same category of artifact as a function signature, a REST endpoint, or a web form: a boundary across which one party states what it wants and the other party has to guess how to satisfy it, unless the boundary itself does some of the work.

A prompt is an interface

Interface design is not a new discipline invented for prompting. It is one of the oldest, most thoroughly studied problems in the field, and it has a vocabulary — affordances, constraints, defaults, error states, discoverability — built specifically to describe how an artifact shapes the behavior of whoever uses it, independent of how politely that artifact is worded. Treating a prompt as an interface means importing that vocabulary wholesale rather than reinventing a thinner version of it under the name “prompt engineering.”

The claim is structural, not decorative. A well-designed API does not merely describe, in friendlier prose, what kind of request it wants — it defines a schema: required fields, typed values, enumerated options, and it rejects anything outside that shape before the request is ever processed. Most misuse becomes structurally impossible, not just discouraged by a polite error message. A well-designed prompt does the analogous thing. It does not only ask nicely for the right output; it shapes what counts as a valid one — a worked example that pins the format, an explicit constraint that rules out a whole class of wrong answers, a definition of done specific enough to check mechanically instead of judge by feel.

What interface design already knows

Don Norman’s foundational distinction is between an affordance — what an object actually permits — and a signifier, the perceptible cue that tells someone what those permitted actions are. A door with a flat plate affords pushing and signifies it by having nothing to grip; a door with a handle signifies pulling whether or not pulling is actually the right move. A prompt that says “fix the bug” has no signifier for what a correct fix looks like; a prompt that pastes the failing test and asks for it to pass has both an affordance and a signifier for the same target, and the model does not have to guess which one the requester meant.

Roy Fielding’s definition of an architectural style — a named, coordinated set of constraints applied to components, connectors, and the data that flows between them — is the more formal version of the same idea from API design. REST is not a friendlier way of describing an HTTP request; it is a set of constraints (statelessness, a uniform interface, cacheability) that make certain classes of failure structurally unreachable rather than merely unlikely. A prompt library that only tunes phrasing has no equivalent constraint layer. One that specifies which files are in scope, which patterns to follow, and what output shape is acceptable is doing REST’s job for natural-language requests: ruling out failure modes by construction, not by asking nicely.

And Jakob Nielsen’s usability heuristics — old enough now to have been re-validated across three decades of interface design — name the remaining two pieces directly. Error prevention: “the best designs carefully prevent problems from occurring in the first place,” not the ones with the most apologetic error copy. Visibility of system status: the design should keep the user informed about what is happening and what is expected, not leave them to infer it. A prompt with no stated definition of done violates the first. A prompt that never says what evidence of success will look like violates the second. Both are interface defects, and neither is fixed by a firmer verb.

Nobody redesigns a login form by making the placeholder text more encouraging. Prompts have been getting exactly that treatment for two years.

The interface checklist

None of this requires new tooling to apply — it requires reading a prompt the way an interface reviewer reads a form or an API spec, checking for the presence of the mechanisms below rather than the pleasantness of the prose.

The reframe matters because it redirects the fix. A team that treats a prompt as copy will iterate on wording when the actual defect is a missing constraint or an unstated definition of done — the equivalent of polishing an API’s error message instead of adding the validation that let bad input through in the first place. The wording iteration is not wasted exactly; it is aimed at the one part of the artifact least responsible for the failure.

Checking the claim

The prediction this framework makes is falsifiable, and it is the kind of thing a session-instrumented tool is well positioned to check: sessions that needed a mid-session correction should cluster around missing structural elements — no stated scope, no example, no checkable definition of done — far more than around any measurable property of tone.

Where this volume goes

Getting the interface right does not make prompt quality sufficient on its own — it makes it a necessary, boundable piece of a larger problem, and the next chapter takes up why the field’s own vocabulary moved past “prompt” as the unit of account somewhere in 2025 and 2026. That is not a contradiction of the argument here; it is its natural extension. Once an instruction is understood as an interface rather than an incantation, the obvious next question is what a more rigorous, more reviewable version of that interface looks like — and the field’s answer, largely, has been to formalize it as something closer to a specification. The chapters that follow spend their time on that formalization directly: constitutions as standing constraints a project carries between sessions, structured workflows that turn a one-shot request into a reviewable sequence of phases, and the anti-patterns that show up when either is done badly. Prompt design was always a partial, informal answer to a design question the rest of this volume answers properly.