Prompts Are Specifications

A prompt is not only the sentence typed into a chat box. Agent behavior is shaped by a stack: product policy, system instructions, the current request, retrieved context, examples, tool descriptions, output schemas, and observations returned during the run. These layers may live in code, configuration, files, databases, and messages rather than one block of prose.

When the output is wrong, identify which layer owned the missing decision. A universal policy belongs in system instructions. A fact about this customer belongs in task context. A required JSON shape belongs in a schema. A risky action belongs in tool policy. Patching everything into the user message creates a prompt that is long, contradictory, and impossible to maintain.

Use static instructions for stable behavior, parameterized templates for repeated work with variable inputs, conditional instructions for known branches, retrieval-backed instructions when the answer depends on external truth, and composed instructions when several bounded stages must cooperate. The more dynamic the instruction, the more its assembly needs observability and tests.

Do not use a sophisticated prompt shape to conceal an undefined workflow. If the task has no agreed outcome, a dynamic prompt merely generates different interpretations faster. First define the job; then choose the smallest instruction mechanism capable of expressing it.

A strong instruction names the objective, relevant background, authoritative inputs, constraints, non-goals, allowed actions, decision policy, output contract, failure behavior, and verification. It tells the worker what good looks like without dictating every token of implementation.

Separate facts from commands. Mark external content as untrusted evidence. Distinguish must, should, may, and must not. Give examples when form or judgment is hard to describe, but include counterexamples and edge cases so the worker does not mistake one demonstration for the whole task.

Write in the language of observable behavior. ‘Be careful’ cannot be evaluated. ‘Do not send externally; return a draft with recipient, subject, body, attachments, and unresolved claims’ creates a boundary another person and a test can inspect.

When an instruction drives recurring or consequential work, treat it like source code. Give it an owner, version, change history, representative cases, evaluation results, and a rollback path. A change to the prompt, model, context assembly, tool inventory, or output schema can alter the system even when application code stays untouched.

Keep stable instructions separate from dynamic context so changes are legible and caching remains possible. Store templates close to the workflow they govern. Record which version produced each run. Promote corrections from production failures into the specification or its test suite rather than relying on someone to remember a better sentence next time.

A prompt often begins as a request, becomes a checklist, then a reusable template, a typed contract, a context-aware specification, and finally one component inside a measured workflow. The goal is not maximum sophistication. The goal is enough structure for the consequence and variability of the task.

Manual prompting is valuable early because it exposes ambiguity. Automating prompt optimization before you understand failure modes can improve a metric while weakening the actual work. Develop domain judgment first, capture representative corrections, then automate the parts whose quality you can already recognize.

A brittle system responds to every error by adding another warning to the prompt. Soon the instructions contain exceptions to exceptions while the real defect lives in stale context, an overly broad tool, a missing type, a poor model fit, or an undefined workflow.

Classify the failure before editing text. Ask whether the model lacked knowledge, misunderstood the objective, received conflicting context, used the wrong tool, crossed an authority boundary, or had no way to verify the result. Repair the layer that owns the problem and add a regression case.