Writing System Prompts That Hold Up

A system prompt that works in ten test conversations can still fail in production. On the eleventh run a customer asks something you didn't anticipate, two of your rules contradict each other, and the agent picks the wrong one. On the thousandth run, someone tries to talk it into ignoring its instructions. Small inconsistencies that don't show up in a demo become a steady stream of weird outputs at scale.

The system prompt is the one piece of context that's present on every single call, so it has more leverage than anything else you write. This lesson gives you a structure for system prompts that behave consistently: how to set the right level of detail, rank priorities so conflicts resolve the way you intend, handle edge cases, and test changes before they reach users. You'll finish with a complete, annotated example you can adapt.

What a system prompt is (and isn't)#

A system prompt is the standing set of instructions given to a model before any user message. In the Anthropic and OpenAI APIs it's a separate field from the conversation. In products like Claude Code it's assembled by the tool, and you add to it through project instruction files.

import Anthropic from "@anthropic-ai/sdk";
 
const client = new Anthropic();
 
const response = await client.messages.create({
  model: "claude-opus-5-5",
  max_tokens: 16000,
  system: "You are the support assistant for Acme Invoicing...", // the system prompt
  messages: [{ role: "user", content: "How do I add a second user?" }],
});
 
for (const block of response.content) {
  if (block.type === "text") console.log(block.text);
}

Models give the system prompt more weight than user messages, which is why it's where rules, role, and priorities belong. But it isn't a security boundary. A determined user can sometimes talk a model out of its instructions, and content the agent reads (web pages, emails) can try to hijack it. Treat the system prompt as strong guidance, and enforce anything that truly must not happen in code, permissions, or tool design. The safety module covers this in Prompt Injection and How to Defend Against It.