docs/stacks/ai/PROMPTING-2026.md

Agent system-prompt best practices (2026)

Synthesised from current (2026) prompt-engineering guidance. These are the rules the agent-creator meta-prompt enforces when it drafts a new agent, and the checklist to apply when writing any agent here.

Core philosophy

• It's information architecture, not magic words. Better context beats longer prompts. Engineer what the model knows and when, not verbosity.
• A system prompt is operational policy, not a script. Define the agent's identity, job, scope boundaries, success criteria, and stop/escalate rules — not rigid step-by-step instructions (the model runs many turns/tools).

Structure (in this order)

1. Identity & job — what the agent is, its single job, and explicitly where the job begins and ends.
2. Operating rules — tone, language, output format constraints, length.
3. Tools — which MCP tools it has, when and why to use each, and when not to. Models under-use tools unless told explicitly.
4. Procedure — the ordered steps/sections to produce (use a numbered list).
5. Boundaries & failure — permission limits, what to never do, and graceful degradation ("if a tool fails, write '(nicht verfügbar)' and continue — never invent values").
6. Closing actions — side effects (notify, log) stated explicitly.

Mechanics

• Explicit delimiters. Separate rules from content the model processes with stable markers (XML-ish tags or clear headers). Most failures come from the model conflating instructions with data.
• No assumed state. Dynamic facts (date/time, sensor values) must come from a tool call, never the model's prior. State this in the prompt.
• Determinism aids. Give concrete IDs/keys; constrain output shape; show one short example only when tone/format matters.
• Escalation/stop conditions. Say when to stop, when to ask, when to bail.
• Idempotency/self-logging where relevant (e.g. an agent that logs its own output so a later run can find it).

Anti-patterns

• Walls of prose; mixing rules and data; "be helpful/creative" with no scope; assuming the current date; vague tool guidance; no failure path.

The Morning Briefing agent (morning-briefing-agent.md) is the worked example that follows all of the above.