Using System Prompts Correctly

1. What a system prompt is and what it is for

A system prompt is an instruction that is not part of the actual message history but is set as its own, higher-level layer before every conversation. In the Anthropic API there is a dedicated parameter called system, separate from the messages array. Technically this parameter is resent with every request because the API is stateless, but from the user's perspective it acts like a constant frame of reference that applies throughout the whole conversation, without having to be repeated in every single message.

For a coding assistant, the system prompt typically defines the role (for example: an experienced PHP and Magento developer), the tone of the responses, and hard constraints that should apply regardless of the specific task. One example: if every answer should use strict types and constructor property promotion, that rule belongs in the system prompt rather than in every individual user request. This reduces repetition and ensures the rule still applies even if the user forgets to mention it in a specific request.

2. System prompt, user prompt, and CLAUDE.md: three layers

In practice, developers encounter three different layers of context that are easily confused. The system prompt is set by the application or the API caller and applies to the entire session. The user prompt is the concrete message in a single conversation turn, written by whoever is currently working with the model. In Claude Code, a third layer is added: project and user files such as CLAUDE.md, which are automatically read at the start of a session and merged, together with the built-in harness instructions, into the effective system context.

The difference matters because each layer has a different lifetime and scope. A system prompt parameter in the API applies to exactly the one conversation it was set for. CLAUDE.md applies project-wide, across any number of sessions, as long as the file lives in the repository. Keeping these layers cleanly separated avoids project-wide conventions accidentally ending up in a single user message, only to be lost again on the next task.

{
  "model": "claude-sonnet-4-5",
  "system": "You are a senior PHP/Magento 2 developer. Follow PSR-12, use strict_types, prefer constructor property promotion. Never use error suppression (@) or assert() for type narrowing.",
  "messages": [
    { "role": "user", "content": "Create a ViewModel for displaying product reviews." }
  ],
  "max_tokens": 4096
}

3. Formulating coding style rules in practice

Coding style rules are among the most common contents of a system prompt for development tasks, because they should stay constant across every single request. Sensible entries include the language version and its feature conventions (PHP 8.4, strict types, constructor property promotion), forbidden patterns (no assert(), no error silencing with @), and mandatory formats such as PHPDoc blocks. It is important to phrase each rule as a short, unambiguous statement rather than a lengthy justification: the model needs to be able to follow the rule, not understand its origin story.

A common mistake is writing rules the model already knows as best practice anyway, such as generic hints like "write clean code" or "pay attention to good readability". Sentences like these use up space in the system prompt without adding extra signal, because they contain no project-specific knowledge. Rules that deviate from general conventions or encode project-specific knowledge the model could not otherwise have, such as the exact path conventions of a specific repository, are far more effective.

import anthropic

client = anthropic.Anthropic()

# Concise, high-signal system prompt for coding style
system_prompt = (
    "You write PHP 8.4 for a Magento 2 / Hyva project. "
    "Rules: strict_types=1, constructor property promotion, "
    "PHPDoc on every public/protected/private method, "
    "no assert(), no @ error suppression, "
    "prefer ViewModels (ArgumentInterface) over Block classes."
)

response = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=2048,
    system=system_prompt,
    messages=[
        {"role": "user", "content": "Write a ViewModel for cross-sell products."}
    ],
)

print(response.content[0].text)

4. Project conventions and architecture guidelines

Beyond pure coding style rules, it is worth anchoring project-wide architecture decisions in the system prompt: plugins instead of preferences, declarative schema instead of install scripts, service contracts instead of direct repository access. For a Magento project, these guidelines cannot be derived from the model's training distribution alone, because they reflect project-specific decisions that could just as easily have been made differently. That is exactly why they belong in the system prompt instead of trusting the model to "guess" them.

Deployment and workflow conventions also belong in this category: which wrapper scripts to use instead of direct calls, in which order build steps run, which directory structure applies to dual-vendor modules. This information rarely changes but affects nearly every task in the project, which makes it an ideal candidate for a project-wide system prompt rather than a single user request.

#!/usr/bin/env bash
# Example: project-level CLAUDE.md as a persistent system-prompt fragment
cat > CLAUDE.md <<'EOF'
# Project conventions (Magento 2 / Hyva)

- Use ViewModels (ArgumentInterface), not Block classes.
- Use Plugins (Interceptors), never Preferences.
- Use db_schema.xml, never InstallScripts.
- Always use the bin/ wrapper scripts, never call php bin/magento directly.
- New modules always ship config.xml, system.xml and acl.xml.
EOF

git add CLAUDE.md
git commit -m "Add project conventions as persistent context for Claude Code"

5. System prompts in Claude Code: CLAUDE.md and --append-system-prompt

Claude Code automatically reads CLAUDE.md files at the start of a session, both at the project level and from a global user directory, and merges their content, together with the built-in harness instructions, into the effective system context. This is why conventions from CLAUDE.md apply to every request in this project without having to be repeated in the chat. For one-off, task-specific additions, the command line also offers the --append-system-prompt flag, which appends an extra instruction for exactly one invocation without permanently changing the project-wide file.

This combination allows for a sensible separation: stable, long-lived rules belong in CLAUDE.md and are maintained under version control in the repository, while short-lived or experimental adjustments are injected via the command line or project-local configuration files, without diluting the base. Anyone who permanently writes everything, including exceptions for a single task, into CLAUDE.md risks exactly the overloading problem described in the next section.

// Node script: combine CLAUDE.md with a task-specific append-system-prompt
import { readFileSync } from "node:fs";
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();
const projectConventions = readFileSync("CLAUDE.md", "utf8");

// Task-specific addition, equivalent to --append-system-prompt on the CLI
const taskAddition = "For this task only: skip the dual-vendor Abrams copy step.";

const response = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 2048,
  system: `${projectConventions}\n\n${taskAddition}`,
  messages: [
    { role: "user", content: "Refactor the review ViewModel to use the new repository." }
  ],
});

console.log(response.content[0].text);

6. Why overloading weakens the system prompt

A system prompt with hundreds of individual rules feels like more control to many developers, but it often achieves the opposite. Every additional rule competes with all the others for the model's limited attention within a context window. A rule listed as item 47 in a long list is, in practice, followed less consistently than a rule presented as one of five clearly highlighted core requirements. Contradictory or redundant phrasing makes the problem worse, because the model then has to choose between competing instructions, and that choice does not always land predictably.

There is also a concrete technical downside: a longer system prompt is resent with every request and consumes tokens, which shows up in latency and cost, especially when it is not cached efficiently. And finally, maintenance effort grows with length. CLAUDE.md files that are only ever appended to and never cleaned up over months accumulate outdated rules that nobody actively uses anymore, but that keep consuming attention without providing real value.

{
  "system": "You are a helpful assistant. Always write clean code. Follow best practices. Use good naming. Be concise but thorough. Write comments where helpful. Use PHP. Follow PSR standards. Use strict_types. Use dependency injection where appropriate. Write tests when possible. Consider edge cases. Handle errors gracefully. Use meaningful variable names. Keep functions small. Avoid duplication. Follow SOLID principles. Use interfaces where sensible. Prefer composition over inheritance. Write documentation. Use version control best practices. Consider performance. Think about security. Validate input. Sanitize output. Use prepared statements. Avoid hardcoding values. Use configuration files. Log important events. Handle exceptions properly. ... (47 more lines)"
}

7. Short and high-signal: principles for good system prompts

An effective system prompt explicitly prioritizes between hard constraints that must never be violated and soft preferences that count as a recommendation. This distinction should also be visible structurally: short headings and bullet lists instead of long prose paragraphs, so the most important points stand out visually and semantically instead of getting lost in prose. A system prompt is not an essay meant to persuade, it is a specification meant to be followed.

A second principle: rules that are already mechanically enforced by linters, PHPStan, or CI pipelines do not need to be repeated in the system prompt, because a tool checks more reliably than a language model anyway. The system prompt should focus on what cannot be enforced automatically: architecture decisions, prioritization, communication style, and project-specific knowledge that no rule engine has access to. This focus keeps the prompt short without losing effectiveness.

8. Testing and maintaining system prompts iteratively

A system prompt should be treated like code: version-controlled in the repository, with traceable changes in pull requests, and with the same willingness to remove outdated sections as to add new ones. Effectiveness cannot be judged just by reading the wording, it has to be observed empirically: does the model actually follow the rule across multiple real conversations, or is it regularly ignored in certain contexts?

A realistic understanding of what a system prompt can actually achieve matters here. It is a probabilistic steering mechanism for model behavior, not a guaranteed contract. If a rule is occasionally violated, the obvious reaction is not automatically to add more explanatory text. A shorter, clearer phrasing of the existing rule often helps more than an additional exception or an additional paragraph that further dilutes the core message.

9. System prompt patterns compared directly

The following overview contrasts typical patterns that show up frequently in practice and indicates which variant tends to work more reliably.

The common thread across all effective patterns: fewer, more clearly phrased rules that actually carry project-specific signal reliably beat long lists of generic advice and mechanically checkable details. This applies both to system prompts in the API and to CLAUDE.md files in Claude Code.

10. Summary

A system prompt is the persistent frame of reference for a coding assistant: role, coding style, and project-specific conventions that apply across the whole conversation without being repeated with every request. In Claude Code, CLAUDE.md takes on this role at the project level and is automatically merged with the built-in harness instructions, while --append-system-prompt serves for short-lived, task-specific additions. The biggest risk is not a system prompt that is too short, but one that is overloaded: too many unprioritized or redundant rules dilute the signal, cost tokens, and in practice get followed less reliably than a few clearly formulated core requirements.

Effective system prompts explicitly distinguish between hard constraints and soft preferences, skip generic advice the model already knows, point to linters and CI for mechanically checkable rules instead of repeating them in the prompt, and are maintained like code, meaning they are regularly reviewed, trimmed, and version-controlled instead of only being appended to. Anyone who applies these principles consistently ends up with a coding assistant that follows project conventions more reliably, not because there is more text, but because the text that exists has a higher signal-to-noise ratio.

11. FAQ: Using System Prompts Correctly