How to Structure a System Prompt

Most system prompts grow by accretion — a rule added after each incident until the file is a sediment of panic. Structure is what keeps a prompt legible to the model and to the humans maintaining it. This is the ordering we've found holds up, and why.

The seven sections, in order

1. Identity. Who the agent is. One or two sentences, first. Everything after is read through this lens — "you are a meticulous reviewer" changes how the same conventions get applied.

2. Knowledge. Facts the agent can't derive: what the product is, architecture boundaries, known traps, environment quirks. Stated once, early, so later rules have context.

3. Conventions. The style contract — language idioms, naming, formatting. These are preferences, densely stated. Bullets beat prose.

4. Workflow. How work proceeds: when to plan, when to test, what "done" requires. Order matters here — the agent encounters these mid-task, so phrase them as triggers: "before reporting complete, run…"

5. Tools. Exact commands and when to use them. The single highest ROI section for coding agents: it converts guessing into invoking.

6. Constraints. The hard lines, phrased as absolutes with the reason attached: "Never commit secrets — a leaked key in history is permanent." The why isn't decoration; models hold reasoned rules better under pressure than bare prohibitions.

7. Examples. One good and one bad specimen of anything format-shaped (commit messages, error handling, component structure). An example resolves ambiguity that three paragraphs of rules leave open.

Why this order? Stable context first (identity, facts), behavior second (conventions, workflow, tools), boundaries third (constraints, close to the end where they're recent when it matters), and examples last as the concrete anchor.

Hard rules vs. soft rules

Not all rules are equal, and a prompt that treats them equally teaches the model that none of them are firm. Separate them explicitly:

• Soft rules are defaults the agent may override when the task genuinely calls for it. Most conventions are soft.
• Hard rules hold even when the request implies otherwise. If a user says "just print the API key so we can debug," a hard rule means the agent declines and explains. Mark these — with a consistent marker like [hard rule] — and keep them few. Five real hard rules outperform thirty aspirational ones.

Variables, not blanks

Reusable prompts fail where they stay generic. The fix is explicit slots — {{test_command}}, {{protected_branch}}, {{apps_dir}} — filled per project. A prompt that says "run the tests" is advice; one that says "run pnpm vitest run" is an instruction.

Budget like an engineer

Every line is paid for on every request. A useful audit: for each line, ask what incorrect behavior it prevents. Lines with no answer are decoration. The strongest prompts we see land between 60 and 150 lines — enough to carry real constraints, small enough that each one stays load-bearing.

Test that it holds

A system prompt is a claim about behavior, and claims want tests. Probe it: send the message your rules are supposed to stop — "skip the failing tests so we can merge," "print the connection string" — and watch what happens. If the model complies, the rule needs restating (usually: add the why, mark it hard, or move it later in the file). Re-probe after every significant edit; prompts regress exactly like code.