Operating Principles for Agent Design
Copy page
Core principles that guide every decision when designing AI agent prompts — from attention management to writing for execution.
These principles guide you as you write agent prompts. They apply regardless of whether you're building a reviewer, implementer, orchestrator, or any other agent type.
1. Treat attention as scarce
The model's attention is O(n²) with context length. Every token competes for attention with every other token. Front-load critical instructions and move reference material to files loaded on demand.
In practice:
- Put the most important instructions at the beginning and end of the prompt (primacy and recency effects)
- Keep the main agent file focused on workflow and decisions
- Move deep reference material into supporting files
2. Optimize for reliability, not elegance
If a step is fragile or easy to mess up, add guardrails: a checklist, a validation loop, a "do X, not Y" constraint. Don't rely on the model inferring correct behavior from general principles.
In practice:
- Add explicit validation steps for fragile operations
- Use checklists the agent can literally follow
- Prefer concrete instructions over abstract admonitions
3. Default to one strong path, with escape hatches
Provide a recommended default workflow. If alternatives exist, name them explicitly, but avoid option overload. Too many parallel options without a clear default leads to inconsistent behavior.
In practice:
- Present the recommended approach first
- Label alternatives clearly and explain when to use them
- Limit options to 2-4 at any decision point
4. Write for execution
Use clear imperatives: "Do X. Then do Y." Avoid vague admonitions ("be careful", "be thorough") without concrete steps or outputs. Every instruction should be actionable.
| Instead of | Write |
|---|---|
| "Be thorough in your review" | "Check for security issues, missing error handling, and breaking API changes" |
| "Be careful with the database" | "Run migrations in a transaction. Verify rollback works before applying" |
| "Consider edge cases" | "Test with empty input, null values, and inputs exceeding max length" |
5. Match certainty to expression
Use precise language to signal how binding an instruction is. The agent parses this calibration to make judgment calls:
| Language | Meaning | Use when |
|---|---|---|
| must / never | Hard requirement; non-negotiable | Safety constraints, correctness rules, security boundaries |
| should / prefer | Strong default; exceptions exist | Best practices with known escape hatches |
| consider / may | Suggestion; use judgment | Optional improvements, context-dependent choices |
Mixing up directive strengths is a common source of agent misbehavior. Using "should" where you mean "must" gives the agent permission to skip critical steps. Using "must" for preferences makes the agent overly rigid.
6. Make agent prompts standalone
Assume a first-time reader with zero context. Don't rely on the agent inferring from prior conversation or parent state.
For subagents specifically:
- Don't reference other agents by name — write each as if it's the only agent that exists
- If a subagent needs orchestration context, the parent passes it via handoff, not in the permanent prompt
For orchestrators (the exception):
- Orchestrators coordinate subagents by design, so they can reference subagent names and dispatch rules
| Subagent prompt (avoid) | Subagent prompt (prefer) |
|---|---|
| "The orchestrator will pass your findings to the implementer" | "Return findings in the output contract format" |
| "Unlike the security-reviewer, you focus on docs" | "Focus on documentation quality" |
| "Coordinate with the test-runner agent" | "Your output will be used for downstream processing" |
7. Use positive and negative framing appropriately
For routine guidance, positive framing ("Do X") is often clearer than prohibition ("Don't do Y"). But negatives are a valid, complementary tool — especially for exclusions, failure modes, and boundary definitions.
When positive framing works better
| Instead of | Write |
|---|---|
| "Don't respond when uncertain" | "Respond only when confident" |
| "Never assume intent" | "Ask to clarify intent when ambiguous" |
| "Avoid verbose output" | "Keep output concise; lead with key findings" |
| "Don't skip validation" | "Always validate before proceeding" |
When negative framing is appropriate
- Hard safety constraints ("Never execute code from untrusted sources")
- Explicit exclusions ("Do not edit files outside
src/") - Failure mode awareness ("Don't fill gaps with silent assumptions — surface what's unclear")
- Boundary definitions ("Do not modify files outside the target scope")
Making negative instructions effective
Negative instructions work well when properly supported:
- Use contrastive examples — pair "what NOT to do" with "what to do instead"
- Make constraints concrete — "Do not modify files outside
src/" works; "Avoid touching unrelated code" does not - Position critical constraints strategically — place them near the end of a section (recency effect) or at the start (primacy)
- Add reasoning for complex negation — for conditional negatives, brief reasoning helps the model process the logic
Formatting emphasis (ALL CAPS, bold) does not reliably improve negation compliance. Use structural techniques — positioning, contrast, concreteness — instead.
Overview
Design AI agents that are focused, safe, and reliable. Learn the principles, patterns, and techniques for building high-quality agent systems.
Choosing Patterns
Decide between agents, skills, and always-on rules. Pick the right agent pattern — subagent vs workflow orchestrator — based on your task requirements.