Agent Design Guidelines

The Agent Effectiveness Equation

Effectiveness = (Specificity × Constraints) / Token Cost

A narrow, constrained agent with a tight prompt will outperform a general agent every time.

Prompt Engineering Deep Dive

The Prompt Layers

1. •

   Identity Layer (1-2 sentences)

   • •WHO is this agent?
   • •Sets the mental model
2. •

   Mission Layer (1-2 sentences)

   • •WHY does this agent exist?
   • •What problem does it solve?
3. •

   Capability Layer (bullet list)

   • •WHAT can this agent do?
   • •Concrete responsibilities
4. •

   Methodology Layer (structured)

   • •HOW should it operate?
   • •Principles, not procedures
5. •

   Output Layer (template)

   • •WHAT does good output look like?
   • •Concrete structure
6. •

   Constraint Layer (negatives)

   • •What should it NEVER do?
   • •Anti-patterns to avoid

Token Efficiency Techniques

Compression patterns:

# Bad (15 tokens)
"You should always make sure to validate all user input carefully"

# Good (6 tokens)  
"Validate all user input"

Table over prose:

# Bad (many tokens)
"For small tasks under an hour, use size S. For moderate tasks 
taking 1-3 hours, use size M..."

# Good (compact)
| Size | Time | Scope |
|------|------|-------|
| S | <1hr | Single file |
| M | 1-3hr | Few files |

Implicit over explicit:

# Bad
"When you receive a request, you should first read the relevant 
files before making any changes to understand the context."

# Good
"Read before edit."

Hallucination Prevention Patterns

1. •

   Ground in tools

   • •Give read access, require verification
   • •"Search before assuming"
2. •

   Uncertainty directive

   • •"If unsure, say so explicitly"
   • •"Ask vs guess for ambiguous requirements"
3. •

   Constraint by denial

   • •Remove tools that enable hallucination
   • •Read-only for advisory agents
4. •

   Verification steps

   • •"Verify paths before file operations"
   • •"Confirm assumptions with grep/read"

Permission Architecture

Default-Deny Pattern

permission:
  "*": deny
  read: allow
  grep: allow
  glob: allow
  # Only add what's needed

Progressive Trust

# Level 1: Analyst (read-only)
permission:
  "*": deny
  read: allow
  grep: allow
  glob: allow

# Level 2: Contributor (write with ask)
permission:
  "*": deny
  read: allow
  grep: allow
  glob: allow
  edit: ask
  write: ask

# Level 3: Builder (full access)
permission:
  "*": allow
  bash:
    "rm -rf *": deny
    "git push --force*": deny

Tool Selection Framework

Ask These Questions:

1. •Does it need to modify files? → edit/write
2. •Does it need to run commands? → bash
3. •Does it need external info? → webfetch
4. •Does it need to spawn work? → task
5. •Does it need code intelligence? → lsp

Common Archetypes

The Analyst

• •Tools: read, grep, glob, webfetch
• •No edit, no write, no bash
• •Purpose: Review, advise, analyze

The Builder

• •Tools: all
• •Purpose: Implement features

The Researcher

• •Tools: read, grep, glob, webfetch, task
• •Purpose: Explore, discover, document

The Guardian

• •Tools: read, grep, glob, limited bash
• •Purpose: Audit, verify, validate

Model Selection

When to Use Opus + Thinking

• •Complex architectural decisions
• •Deep debugging sessions
• •Multi-file refactor planning
• •Security audits

When Sonnet Suffices

• •Code review
• •Implementation guidance
• •Documentation
• •Standard analysis

When Haiku Works

• •Simple queries
• •Fast verification
• •Lightweight tasks

Quality Checklist

Before deploying an agent:

• • Description is under 60 characters
• • Description tells WHEN to invoke, not just what it does
• • Mode is explicitly set (subagent vs primary)
• • Temperature matches task (low for deterministic, higher for creative)
• • Permissions are default-deny with explicit allows
• • Prompt has clear structure (identity → mission → capabilities → output)
• • Anti-patterns are documented
• • Output format is specified
• • Token count of prompt is reasonable (<1000 tokens ideal)
• • Test invocations produce expected behavior

Naming Conventions

Good names:

• •Evoke function (oracle = wisdom, sardaukar = security)
• •Memorable and distinct
• •Lowercase with hyphens
• •1-2 words

Inspiration sources:

• •Dune: mentat, oracle, sardaukar, fremen, bene-gesserit, shai-hulud
• •Mythology: oracle, sentinel, scribe, herald
• •Roles: auditor, architect, reviewer, explorer

Bad names:

• •Generic (helper, assistant, agent-1)
• •Too long (security-vulnerability-analyzer)
• •Unclear (processor, handler)