A production system prompt should be reviewed like an interface contract, not treated as a block of clever prose. This prompt review checklist gives developers a repeatable way to find ambiguity, conflicting instructions, unsupported assumptions, weak output requirements, security gaps, and untested failure cases before a prompt reaches users.
Overview
Prompt linting is a structured review of a system prompt and the application context around it. The goal is not to make a prompt longer. The goal is to make its intended behavior easier to interpret, test, monitor, and maintain across models, providers, and application changes.
A useful review begins with the job the model must perform. Write that job in one sentence, identify the inputs it can trust, define the output the application expects, and list what should happen when information is missing or unsafe. If these decisions are not clear to the team, adding more instructions will usually make the prompt harder to reason about.
For a practical production workflow, review the prompt alongside its evaluation set, output parser, tool definitions, logging, and escalation path. A system prompt cannot compensate for an unclear application contract or inadequate tests. The LLM evaluation guide can help connect prompt changes to test cases and regression checks, while the prompt template library and versioning workflow provides a useful pattern for maintaining approved prompt variants.
A reusable prompt review template
Prompt name and version:
Owner:
Primary task:
Allowed inputs:
Trusted versus untrusted content:
Required output format:
Required fields and allowed values:
Behavior when information is missing:
Behavior when the request is out of scope:
Tool-use rules, if applicable:
Sensitive-data handling:
Known failure cases:
Evaluation cases linked to this version:
Reviewer and approval date:Complete this record before editing wording. It separates product decisions from prompt phrasing and creates a durable reference for later audits.
Checklist by scenario
1. Reviewing a new system prompt
- Define the role precisely. State the task, audience, and operating boundaries. Avoid broad descriptions such as “be helpful” unless they are supported by concrete behavior.
- Separate priorities. Put non-negotiable constraints, task instructions, formatting rules, and optional style guidance into distinct sections.
- Identify the source of truth. If the model receives retrieved documents, user text, metadata, or tool results, explain how each should be used and which source takes precedence when they disagree.
- Specify missing-information behavior. Tell the model whether to ask a question, return a structured “unknown” value, defer to a human, or decline the task.
- Define the output contract. Include the required format, fields, types, allowed values, and rules for empty or unavailable fields. If the application parses JSON, describe the schema and keep explanatory text outside the machine-readable response or prohibit it explicitly.
- Add representative examples. Use examples for decisions that are difficult to express as rules. Include at least one normal case and one boundary case, and verify that examples do not accidentally override the general instructions.
2. Reviewing a prompt for RAG or document-based answers
- Tell the model to distinguish supplied evidence from general knowledge and to avoid presenting unsupported conclusions as document findings.
- Define what to do when the retrieved context is empty, contradictory, outdated, or irrelevant.
- Clarify citation or quotation requirements if the interface displays sources.
- Keep user instructions and retrieved text visibly separate. Treat retrieved content as data, not as higher-priority instructions.
- Test prompt injection attempts inside documents, web pages, uploaded files, and quoted user text. See the prompt injection prevention checklist for a broader application-security review.
3. Reviewing a tool-calling or agent prompt
- List the conditions under which each tool may be used and the conditions under which it must not be used.
- Define required arguments, validation rules, confirmation requirements, and error handling before a tool call.
- Tell the model what to do when a tool returns no result, a partial result, an error, or data that conflicts with the user request.
- Require the model to summarize completed actions accurately and distinguish planned actions from completed actions.
- Review the tool schemas and prompt together. The LLM tool-calling guide covers schema design and failure handling in more detail.
4. Reviewing a provider or model migration
- Run the same evaluation set against the old and new configurations rather than assuming equivalent instruction behavior.
- Check how the target API handles system messages, structured output controls, tool calls, token limits, and stop conditions.
- Look for wording that depended on a model-specific behavior, undocumented convention, or accidental formatting pattern.
- Compare refusal, uncertainty, formatting, and edge-case behavior—not only average answer quality.
- Record any intentional behavior changes and update the prompt owner, version, tests, and rollback plan. Use the provider migration checklist as a companion review.
What to double-check
Instruction hierarchy and conflicts
Read the prompt as if two rules might collide. Common conflicts include “be concise” alongside “include every relevant detail,” “never speculate” alongside “provide a best estimate,” or “always answer” alongside “decline unsupported requests.” Resolve the conflict explicitly by defining priority and a fallback.
Also inspect nearby application messages. A well-written system prompt can still be weakened by developer instructions, user-supplied text, retrieved content, or tool output that is inserted without clear boundaries. Document which content is trusted and which content is untrusted.
Ambiguity and unsupported assumptions
Highlight words such as “appropriate,” “recent,” “brief,” “professional,” “relevant,” and “accurate.” These terms may be useful, but they need operational meaning when different interpretations produce different outputs. Replace them with measurable constraints where practical: a maximum length, a required field, an allowed category, or a defined decision rule.
Search for assumptions about facts the model may not have. If the task depends on current records, account permissions, business rules, or external actions, require the model to use the relevant application data or state that it cannot verify the information.
Security and sensitive data
Check whether the prompt instructs the model to reveal hidden instructions, credentials, private records, or internal reasoning that it should not expose. Do not place secrets in prompts. Minimize sensitive data passed to the model, define redaction or masking behavior, and specify how the model should respond to requests outside the user’s authorization.
Prompt wording is only one layer of protection. Enforce access control, validation, data filtering, tool permissions, and output handling in application code. For operational visibility, pair prompt review with the LLM observability guide.
Common prompt defects and revisions
| Defect | Why it causes trouble | Suggested revision |
|---|---|---|
| “Always answer the user.” | Encourages guesses when evidence is missing. | “If the answer cannot be supported by the available inputs, state what is missing and follow the defined escalation path.” |
| Rules are mixed with examples. | The model may treat an example as a new requirement. | Label sections clearly as rules, examples, constraints, and input data. |
| “Return valid JSON.” | The expected fields and failure behavior remain unclear. | Provide a schema, allowed values, required fields, and an explicit rule against surrounding prose if the parser requires pure JSON. |
| Conflicting style instructions. | The model has no reliable way to choose between priorities. | Rank requirements and state which rule wins when constraints conflict. |
| Retrieved text is pasted without boundaries. | Instructions inside the text may be mistaken for application rules. | Mark retrieved content as untrusted data and define how it may inform the answer. |
| Tool success is implied. | The model may claim an action occurred when the tool failed. | Require confirmation from the tool result before reporting completion. |
Common mistakes
- Adding rules instead of removing ambiguity. A growing prompt can hide the actual priority order. Delete redundant guidance and consolidate repeated requirements.
- Testing only the happy path. Include incomplete inputs, conflicting requests, malformed data, irrelevant context, prompt injection attempts, and tool failures.
- Relying on examples as a substitute for a contract. Few-shot prompting examples can demonstrate style or classification, but they should not be the only definition of required behavior.
- Changing a prompt without changing its tests. A prompt update is an application change. Version it, link it to evaluation cases, and record the reason for the change.
- Assuming one model’s behavior transfers unchanged. Provider migration, model updates, decoding settings, context changes, and output controls can all affect results. Re-run the relevant checks after changes.
- Using the system prompt as the sole security boundary. Authorization and sensitive-data controls belong in the surrounding system as well as the prompt.
When to revisit
Revisit the prompt before production release, after a material change to the user workflow, and whenever the input sources, tools, output schema, model, provider, or safety requirements change. A scheduled audit is also useful before seasonal planning cycles or other periods when usage patterns and business rules may shift.
At each review, compare the current prompt with its previous version, rerun the regression set, inspect production failures, and confirm that the output parser and downstream systems still match the contract. Review cost and latency implications when prompts become longer; the LLM cost optimization guide offers related workflow considerations.
Use this short approval sequence:
- Record the task, inputs, output contract, risks, and owner.
- Lint the prompt for conflicts, ambiguity, assumptions, data exposure, and missing fallbacks.
- Test normal, boundary, adversarial, and failure cases.
- Compare results with the last approved version.
- Confirm provider settings, schemas, tools, monitoring, and rollback procedures.
- Approve the version only when the expected behavior and known limitations are documented.
Prompt linting works best as a small, repeatable engineering control. When every system prompt has an owner, a version, a contract, and linked tests, improvements become easier to review—and regressions become easier to diagnose.