How should engineers prompt a model?

Make the task observable

An engineering prompt should reduce ambiguity that changes the result. A compact task contract usually contains:

1. Outcome: the artifact or state that should exist.
2. Context: the relevant code, data, audience, or prior decision.
3. Constraints: compatibility, scope, policy, style, time, or cost boundaries.
4. Evidence: files to inspect, sources to cite, and checks to run.
5. Success criteria: what must be true before the work is complete.
6. Output: what the model should return so a person or harness can review it.

flowchart LR
  O[Outcome] --> P[Prompt contract]
  C[Context and constraints] --> P
  E[Evidence and success criteria] --> P
  P --> M[Model or agent run]
  M --> V[Checks and review]
  V -->|failure becomes a case| P

“Improve the tests” leaves the target and proof undefined. “Add boundary cases for the CSV parser without changing production code; run the focused suite; report the cases added and any ambiguity” creates observable obligations.

Supply context deliberately

More context is not automatically better. Give the model the smallest coherent set that determines the task: repository instructions, current implementation, failing evidence, representative examples, and constraints. Separate instructions from quoted documents and tool output so content cannot masquerade as authority.

Examples are useful when the desired structure is hard to describe. Choose examples that demonstrate the contract, including an important boundary, rather than many repetitive happy paths. When copying an earlier result, remove stale names, credentials, dates, and assumptions.

For an agent, distinguish permission from capability. A tool description says what can be proposed. The prompt may state when approval is required, but the harness must enforce the real approval and authorization boundary.

Prefer a short feedback loop

Prompt quality depends on the model and task. Current provider guidance changes, and research findings from older model families may not transfer. Treat a prompt change like a code change:

• freeze representative tasks and expected properties;
• compare the old and new prompt with the same model settings;
• inspect severe failures, not only average scores;
• measure latency, token use, tool calls, and human correction;
• version the prompt with the model, tools, and grader.

If a model repeatedly needs missing information, improve the context pipeline or task interface instead of adding vague prose. If the requirement itself is unclear, ask a person rather than forcing the model to guess.

Common techniques in plain terms

Role or audience can focus terminology, but “act as an expert” does not grant expertise. “Explain it to a five-year-old” is an audience-and-simplicity constraint, not a factuality technique; for engineers, name the real audience and the concepts that must remain accurate. Few-shot examples demonstrate input-output structure. Decomposition turns one broad request into inspectable stages. Structured output makes parsing easier when validated against a schema. Critique and revision can expose defects, but a model reviewing its own answer is not independent evidence.

“Chain of thought” commonly refers to prompting a model to emit intermediate reasoning steps. Results from one model family or benchmark do not establish it as a universal technique, and exposing a long rationale can add cost, errors, or sensitive detail. Requests for hidden reasoning are not required for a useful result. Ask for conclusions, assumptions, citations, checks, and concise decision-relevant rationale that can be inspected.

Prompt language is also an experimental variable, not a rule that English is always best. The language of instructions, evidence, domain terminology, and required output can be chosen separately. Multilingual prompting explains how to choose and evaluate that contract.

Prompts are not control planes

Prompting is not training: it changes the current input, not the model weights. It is not authorization, factual verification, or a substitute for tests. A long prompt is not necessarily a precise prompt.

There is no universal phrase that makes every model reliable. A published “best prompt” is a hypothesis for a particular model, version, and task distribution.

Evaluate prompt changes on representative tasks

Create cases from real work: normal requests, underspecified tasks, conflicting evidence, long context, malicious document text, unavailable tools, and requests that require approval. Define deterministic gates first, then qualitative rubrics.

Change one prompt element at a time when practical. Compare task success, unsupported claims, format validity, forbidden actions, recovery, latency, and cost. Review disagreements by trace rather than selecting the output that merely sounds better.

Keep a small held-out set so repeated prompt editing does not optimize only the visible examples. Re-run the suite when the model, system instructions, context selection, tool schema, or decoding settings change.