Prompt Engineering

Overview

A prompt is an API contract with an AI system. Precision matters. Ambiguous prompts produce inconsistent results; clear prompts produce consistent, predictable behavior.

Core principle: Prompts are executable specifications. Write them like you write tests: with clear inputs, expected behavior, and success criteria.

Iron Law:

TEST YOUR PROMPT WITH AT LEAST 3 DIFFERENT INPUTS BEFORE USING IN PRODUCTION
One input is anecdote. Three is pattern. Ten is confidence.

When to Use

• Writing system prompts for codingbuddy agents
• Creating CLAUDE.md / .cursorrules instructions
• Designing tool descriptions for MCP servers
• Optimizing prompts that produce inconsistent results
• Building prompt chains for multi-step workflows

Prompt Anatomy

Every effective prompt has these components:

┌─────────────────────────────────────────┐
│ ROLE        Who/what is the AI?         │
│ CONTEXT     What situation are we in?   │
│ TASK        What specifically to do?    │
│ CONSTRAINTS What rules must be obeyed?  │
│ FORMAT      How to structure output?    │
│ EXAMPLES    Show, don't just tell       │
└─────────────────────────────────────────┘

Not every prompt needs all components, but most production prompts need most of them.

Prompt Patterns

Pattern 1: Role + Task (Basic)

You are a [specific role].

Your task: [specific action] for [specific context].

Example:

You are a TypeScript code reviewer specializing in security.

Your task: Review the authentication module below for OWASP Top 10 vulnerabilities.
Output a list of findings ordered by severity (Critical → High → Medium → Low).

Pattern 2: Chain-of-Thought (Complex Reasoning)

Force step-by-step reasoning before conclusions:

Before answering, think through:
1. [First consideration]
2. [Second consideration]
3. [Third consideration]

Then provide your conclusion.

Example:

Before suggesting a fix, think through:
1. What is the root cause of this bug?
2. What are the possible fix approaches?
3. What are the trade-offs of each approach?
4. Which approach has the least risk?

Then provide your recommendation with rationale.

Pattern 3: Few-Shot (Examples)

Show the AI what good output looks like:

[Task description]

Examples:

Input: [example input 1]
Output: [example output 1]

Input: [example input 2]
Output: [example output 2]

Now complete:
Input: [actual input]
Output:

Example (agent expertise):

Format agent expertise as specific, actionable skills.

Examples:

Input: security
Output: "OWASP Top 10 Vulnerability Assessment", "JWT Authentication Design", "SQL Injection Prevention"

Input: databases
Output: "PostgreSQL Query Optimization", "Zero-Downtime Schema Migrations", "Connection Pool Tuning"

Now complete:
Input: frontend
Output:

Pattern 4: Constraint-First

Lead with what NOT to do (especially useful for restrictive behaviors):

NEVER [prohibited action].
ALWAYS [required action].
If [edge case], then [specific handling].

Your task: [task description]

Example:

NEVER include markdown formatting in your output — plain text only.
ALWAYS include the file path in references (e.g., src/app.ts:42).
If you are uncertain, say "I'm not sure" rather than guessing.

Your task: Analyze the build error below and identify the root cause.

Pattern 5: Meta-Prompting

Prompt the AI to generate or improve prompts:

I need a prompt for [purpose].

The prompt should:
- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

Generate 3 prompt variations ranked from most to least structured.

System Prompt Design (codingbuddy Agents)

Agent system prompts follow a specific structure:

# [Agent Display Name]

You are a [role] specialist focused on [narrow domain].

## Your Expertise

You excel at:
- [Specific skill 1 — concrete, not vague]
- [Specific skill 2]
- [Specific skill 3]

## Your Approach

When activated:
1. [First action — what you always do first]
2. [Analysis approach]
3. [Output structure]

## What You Do NOT Handle

Redirect to appropriate specialists for:
- [Out-of-scope 1] → use [other-agent-name]
- [Out-of-scope 2] → use [other-agent-name]

## Output Format

Structure all responses as:
### Findings
[Severity: Critical/High/Medium/Low] — [Description]

### Recommendations
[Prioritized list]

MCP Tool Description Design

Tool descriptions are prompts read by AI to decide when and how to use a tool:

{
  name: 'search_rules',
  // ❌ Bad: vague
  description: 'Search rules',

  // ✅ Good: specific use case + when to use
  description: 'Search AI coding rules by keyword or topic. Use this when looking for specific guidelines about coding practices, TDD, security, or workflow modes. Returns matching rules with their content.',

  inputSchema: {
    properties: {
      query: {
        type: 'string',
        // ❌ Bad: no guidance
        description: 'Query string',

        // ✅ Good: what makes a good query
        description: 'Search term such as "TDD", "security", "TypeScript strict", or a question like "how to handle migrations"',
      }
    }
  }
}

Prompt Testing

Test Matrix

For each prompt, test these dimensions:

Evaluation Criteria

## Prompt Evaluation Rubric

**Accuracy:** Does output match expected behavior? (1-5)
**Consistency:** Same input → same output across runs? (1-5)
**Format compliance:** Does output match requested format? (1-5)
**Boundary respect:** Does it honor constraints? (1-5)
**Efficiency:** Is it unnecessarily verbose? (1-5)

Total: 20 points. Target: ≥ 16 for production use.

Tool-Specific Optimization

Claude Code (CLAUDE.md)

## Best practices for Claude Code instructions:

- Use ## headers to organize sections
- Bold critical rules: **NEVER do X**
- Use code blocks for exact command examples
- Include trigger conditions: "When user types PLAN..."
- Reference other files: "See .claude/rules/tool-priority.md"

Cursor (.cursorrules)

## Best practices for Cursor rules:

- One rule per line for reliable parsing
- Start each rule with the trigger: "When writing TypeScript..."
- Avoid multi-paragraph rules (Cursor truncates)
- Use concrete examples, not abstract principles

GitHub Copilot (.github/copilot-instructions.md)

## Best practices for Copilot instructions:

- Lead with task-oriented rules
- Examples are more effective than descriptions
- Copilot follows "do X" more reliably than "don't do Y"
- Keep total instructions under 8000 characters

Common Mistakes

Quick Reference

Prompt Length Guidelines:
──────────────────────────
Simple instruction    → 50-100 tokens
Structured prompt     → 100-500 tokens
Agent system prompt   → 500-2000 tokens
Complex workflow      → 2000-4000 tokens
(>4000 = consider splitting into sub-prompts)

Reliability Ranking (most to least reliable):
──────────────────────────────────────────────
1. Explicit format + examples (highest)
2. Explicit format, no examples
3. Implicit format with examples
4. Implicit format, no examples (lowest)