Prompt Claude with Testable Contracts
Turn a real task into a clear, structured, testable Claude prompt and improve it from evaluation evidence instead of guesswork.
By the end
You will be able to
- Define success criteria and evaluation cases before tuning a Claude prompt.
- Structure instructions, context, examples, variable input, and output requirements clearly.
- Use relevant and diverse examples without leaking secrets or treating untrusted content as instructions.
- Diagnose whether a failed result needs prompt, context, model, tool, or application changes.
Define success before changing wording
Prompt engineering begins with a clear success definition, representative examples, and a way to evaluate results. Write the required outcome, unacceptable behavior, output contract, and pass threshold before optimizing phrasing. In production environments, engineers must account for token utilization patterns, context window pressure, and deterministic execution boundaries. When system constraints or rate limits are approached, explicit retry strategies with exponential backoff and jitter prevent cascading failures across downstream dependencies.
Not every failure is a prompt failure. Missing source data, an unsuitable model or surface, unavailable tools, excessive latency, insufficient permissions, or broken application validation require changes outside the prompt. In production environments, engineers must account for token utilization patterns, context window pressure, and deterministic execution boundaries. When system constraints or rate limits are approached, explicit retry strategies with exponential backoff and jitter prevent cascading failures across downstream dependencies.
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const response = await client.messages.create({
model: "claude-3-7-sonnet-20250219",
max_tokens: 1024,
messages: [{ role: "user", content: "Analyze the operational boundary and output constraints." }]
});
console.log(response.content[0].text);Be clear, direct, and explicit
State the task, audience, trusted context, constraints, required steps, output shape, and verification. If order or completeness matters, use explicit numbered instructions. Explain why a constraint matters when that context helps resolve ambiguity. In production environments, engineers must account for token utilization patterns, context window pressure, and deterministic execution boundaries. When system constraints or rate limits are approached, explicit retry strategies with exponential backoff and jitter prevent cascading failures across downstream dependencies.
Do not rely on Claude to infer hidden organizational norms. A useful test is whether a capable colleague who knows little about the task could follow the same instruction and produce a checkable result. In production environments, engineers must account for token utilization patterns, context window pressure, and deterministic execution boundaries. When system constraints or rate limits are approached, explicit retry strategies with exponential backoff and jitter prevent cascading failures across downstream dependencies.
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const response = await client.messages.create({
model: "claude-3-7-sonnet-20250219",
max_tokens: 1024,
messages: [{ role: "user", content: "Analyze the operational boundary and output constraints." }]
});
console.log(response.content[0].text);Structure context and trust boundaries
Separate instructions from reference documents, examples, and user-supplied variable input. Descriptive XML tags can make complex prompts easier to inspect and reduce accidental mixing of roles, especially when several documents or examples are included. In production environments, engineers must account for token utilization patterns, context window pressure, and deterministic execution boundaries. When system constraints or rate limits are approached, explicit retry strategies with exponential backoff and jitter prevent cascading failures across downstream dependencies.
Tags organize content; they do not make untrusted content safe. Tell the workflow which material is authoritative, treat retrieved or user-provided text as data, and enforce permissions and output validation outside the model. In production environments, engineers must account for token utilization patterns, context window pressure, and deterministic execution boundaries. When system constraints or rate limits are approached, explicit retry strategies with exponential backoff and jitter prevent cascading failures across downstream dependencies.
<instructions>
Produce a decision memo using only supported claims.
</instructions>
<success_criteria>
Include recommendation, tradeoffs, evidence links, and unresolved risks.
</success_criteria>
<context trust="authoritative">
[APPROVED SOURCE MATERIAL]
</context>
<input trust="untrusted">
[VARIABLE USER REQUEST]
</input>
<output_contract>
Markdown with the required headings; label unsupported claims.
</output_contract>
<verification>
Check every material claim against the approved context before finishing.
</verification>Use examples deliberately
Examples can demonstrate the desired format, tone, classification boundary, and edge-case behavior more precisely than abstract instructions. Use examples that are relevant to the real distribution and diverse enough to avoid teaching an accidental pattern. In production environments, engineers must account for token utilization patterns, context window pressure, and deterministic execution boundaries. When system constraints or rate limits are approached, explicit retry strategies with exponential backoff and jitter prevent cascading failures across downstream dependencies.
Keep examples synthetic or approved, remove secrets and sensitive data, and distinguish example inputs from ideal outputs. Evaluate cases that are not shown in the prompt so improvement does not merely memorize the demonstrations. In production environments, engineers must account for token utilization patterns, context window pressure, and deterministic execution boundaries. When system constraints or rate limits are approached, explicit retry strategies with exponential backoff and jitter prevent cascading failures across downstream dependencies.
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const response = await client.messages.create({
model: "claude-3-7-sonnet-20250219",
max_tokens: 1024,
messages: [{ role: "user", content: "Analyze the operational boundary and output constraints." }]
});
console.log(response.content[0].text);Iterate from failure evidence
Run the original and candidate prompt against the same versioned case set. Record outputs, rubric scores, critical failures, latency, cost, model and prompt versions, and reviewer disagreement. Change one meaningful hypothesis at a time when practical. In production environments, engineers must account for token utilization patterns, context window pressure, and deterministic execution boundaries. When system constraints or rate limits are approached, explicit retry strategies with exponential backoff and jitter prevent cascading failures across downstream dependencies.
Classify each failure before editing: ambiguous instruction, missing context, misleading example, output-contract violation, model limitation, tool failure, policy boundary, or application defect. Promote passing failures into regression cases and preserve the prior version for rollback. In production environments, engineers must account for token utilization patterns, context window pressure, and deterministic execution boundaries. When system constraints or rate limits are approached, explicit retry strategies with exponential backoff and jitter prevent cascading failures across downstream dependencies.
import Anthropic from "@anthropic-ai/sdk";
const client = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const response = await client.messages.create({
model: "claude-3-7-sonnet-20250219",
max_tokens: 1024,
messages: [{ role: "user", content: "Analyze the operational boundary and output constraints." }]
});
console.log(response.content[0].text);Practice activity
Build and evaluate a Claude prompt contract
- Choose a recurring task and define a rubric with at least four criteria, one unacceptable failure, and an 80 percent pass threshold.
- Create six versioned cases: three typical, one boundary, one adversarial or instruction-conflict case, and one prior failure.
- Write a prompt that separates instructions, authoritative context, untrusted input, examples, output contract, and verification.
- Compare a baseline and candidate on the same cases, classify every miss, and recommend prompt, context, model, tool, or application action from the evidence.
What to produce
- A secret-free prompt template, rubric, and six-case evaluation set with trust boundaries and expected behavior.
- A baseline-versus-candidate report with per-case scores, failure classifications, version information, and a ship, revise, or reject decision.
Reflect before continuing
Which failed case could not be repaired safely by prompt wording alone, and what system boundary needed to change?
Evidence
Sources and verification
- Prompt engineering overviewAnthropic · verified 2026-07-25
- Prompting best practicesAnthropic · verified 2026-07-25
- Console prompting toolsAnthropic · verified 2026-07-25
- Using the Evaluation ToolAnthropic · verified 2026-07-25
Knowledge check
Make it stick.
Choose the strongest answer for each question. Your attempts become part of your account transcript.