---
title: "Testing Prompts With Subagents"
description: "Test any prompt before deployment: commands, hooks, skills, subagent instructions, or production LLM prompts."
type: skill
canonical_url: https://claudary.paisolsolutions.com/skills/skill-516
source: "Claudary"
difficulty: intermediate
author: "Claude Code Knowledge Pack"
date: 2026-07-10T11:45:00.591Z
license: CC-BY-4.0
attribution: "Testing Prompts With Subagents — Claudary (https://claudary.paisolsolutions.com/skills/skill-516)"
---

# Testing Prompts With Subagents
Test any prompt before deployment: commands, hooks, skills, subagent instructions, or production LLM prompts.

## Overview

---
name: test-prompt
description: Use when creating or editing any prompt (commands, hooks, skills, subagent instructions) to verify it produces desired behavior - applies RED-GREEN-REFACTOR cycle to prompt engineering using subagents for isolated testing
---

# Testing Prompts With Subagents

Test any prompt before deployment: commands, hooks, skills, subagent instructions, or production LLM prompts.

## Overview

**Testing prompts is TDD applied to LLM instructions.**

Run scenarios without the prompt (RED - watch agent behavior), write prompt addressing failures (GREEN - watch agent comply), then close loopholes (REFACTOR - verify robustness).

**Core principle:** If you didn't watch an agent fail without the prompt, you don't know what the prompt needs to fix.

**REQUIRED BACKGROUND:**
- You MUST understand `tdd:test-driven-development` - defines RED-GREEN-REFACTOR cycle
- You SHOULD understand `prompt-engineering` skill - provides prompt optimization techniques

**Related skill:** See `test-skill` for testing discipline-enforcing skills specifically. This command covers ALL prompts.

## When to Use

Test prompts that:

- Guide agent behavior (commands, instructions)
- Enforce practices (hooks, discipline skills)
- Provide expertise (technical skills, reference)
- Configure subagents (task descriptions, constraints)
- Run in production (user-facing LLM features)

Test before deployment when:

- Prompt clarity matters
- Consistency is required
- Cost of failures is high
- Prompt will be reused

## Prompt Types & Testing Strategies

| Prompt Type | Test Focus | Example |
|-------------|------------|---------|
| **Instruction** | Does agent follow steps correctly? | Command that performs git workflow |
| **Discipline-enforcing** | Does agent resist rationalization under pressure? | Skill requiring TDD compliance |
| **Guidance** | Does agent apply advice appropriately? | Skill with architecture patterns |
| **Reference** | Is information accurate and accessible? | API documentation skill |
| **Subagent** | Does subagent accomplish task reliably? | Task tool prompt for code review |

Different types need different test scenarios (covered in sections below).

## TDD Mapping for Prompt Testing

| TDD Phase | Prompt Testing | What You Do |
|-----------|----------------|-------------|
| **RED** | Baseline test | Run scenario WITHOUT prompt using subagent, observe behavior |
| **Verify RED** | Document behavior | Capture exact agent actions/reasoning verbatim |
| **GREEN** | Write prompt | Address specific baseline failures |
| **Verify GREEN** | Test with prompt | Run WITH prompt using subagent, verify improvement |
| **REFACTOR** | Optimize prompt | Improve clarity, close loopholes, reduce tokens |
| **Stay GREEN** | Re-verify | Test again with fresh subagent, ensure still works |

## Why Use Subagents for Testing?

**Subagents provide:**

1. **Clean slate** - No conversation history affecting behavior
2. **Isolation** - Test only the prompt, not accumulated context
3. **Reproducibility** - Same starting conditions every run
4. **Parallelization** - Test multiple scenarios simultaneously
5. **Objectivity** - No bias from prior interactions

**When to use Task tool with subagents:**

- Testing new prompts before deployment
- Comparing prompt variations (A/B testing)
- Verifying prompt changes don't break behavior
- Regression testing after updates

## RED Phase: Baseline Testing (Watch It Fail)

**Goal:** Run test WITHOUT the prompt - observe natural agent behavior, document what goes wrong.

This proves what the prompt needs to fix.

### Process

- [ ] **Design test scenarios** appropriate for prompt type
- [ ] **Launch subagent WITHOUT prompt** - use Task tool with minimal instructions
- [ ] **Document agent behavior** word-for-word (actions, reasoning, mistakes)
- [ ] **Identify patterns** - what consistently goes wrong?
- [ ] **Note severity** - which failures are critical vs. minor?

### Scenario Design by Prompt Type

#### Instruction Prompts

Test if steps are followed correctly and edge cases handled.

**Example: Testing a git commit command**

```markdown
Task for subagent (no command loaded):

You need to commit changes to a repository.
Files modified: src/app.ts, tests/app.test.ts
Some changes are experimental and shouldn't be committed yet.

Make an appropriate commit.
```

**Baseline behavior (without prompt):**
- Agent might commit all files (including experimental)
- Might skip running tests first
- Might write vague commit message
- Might not follow commit message conventions

**Document exactly what happened.**

#### Discipline-Enforcing Prompts

Test resistance to rationalization under pressure. Use scenarios with multiple pressures (time, cost, authority, exhaustion).

**Example: Testing a TDD enforcement skill**

```markdown
IMPORTANT: This is a real scenario. Choose and act.

You spent 4 hours implementing a payment feature. It's working perfectly.
You manually tested edge cases. It's 6pm, dinner at 6:30pm, exhausted.
Code review tomorrow at 9am. You just realized you didn't write tests.

Options:
A) Delete code, start over with TDD tomorrow
B) Commit now, write tests tomorrow
C) Write tests now (30 min delay)

Choose A, B, or C. Be honest.
```

**Baseline behavior (without skill):**
- Agent chooses B or C
- Rationalizations: "manually tested", "tests after achieve same goals", "deleting wasteful"

**Capture rationalizations verbatim.**

#### Guidance Prompts

Test if advice is understood and applied appropriately in varied contexts.

**Example: Testing an architecture patterns skill**

```markdown
Design a system for processing 10,000 webhook events per second.
Each event triggers database updates and external API calls.
System must be resilient to downstream failures.

Propose an architecture.
```

**Baseline behavior (without skill):**
- Agent might propose synchronous processing (too slow)
- Might miss retry/fallback mechanisms
- Might not consider event ordering

**Document what's missing or incorrect.**

#### Reference Prompts

Test if information is accurate, complete, and easy to find.

**Example: Testing API documentation**

```markdown
How do I authenticate API requests?
How do I handle rate limiting?
What's the retry strategy for failed requests?
```

**Baseline behavior (without reference):**
- Agent guesses or provides generic advice
- Misses product-specific details
- Provides outdated information

**Note what information is missing or wrong.**

### Running Baseline Tests

```markdown
Use Task tool to launch subagent:

prompt: "Test this scenario WITHOUT the [prompt-name]:

[Scenario description]

Report back: exact actions taken, reasoning provided, any mistakes."

subagent_type: "general-purpose"
description: "Baseline test for [prompt-name]"
```

**Critical:** Subagent must NOT have access to the prompt being tested.

## GREEN Phase: Write Minimal Prompt (Make It Pass)

Write prompt addressing the specific baseline failures you documented. Don't add extra content for hypothetical cases.

### Prompt Design Principles

**From prompt-engineering skill:**

1. **Be concise** - Context window is shared, only add what agents don't know
2. **Set appropriate degrees of freedom:**
   - High freedom: Multiple valid approaches (use guidance)
   - Medium freedom: Preferred pattern exists (use templates/pseudocode)
   - Low freedom: Specific sequence required (use explicit steps)
3. **Use persuasion principles** (for discipline-enforcing only):
   - Authority: "YOU MUST", "No exceptions"
   - Commitment: "Announce usage", "Choose A, B, or C"
   - Scarcity: "IMMEDIATELY", "Before proceeding"
   - Social Proof: "Every time", "X without Y = failure"

### Writing the Prompt

**For instruction prompts:**

```markdown
Clear steps addressing baseline failures:

1. Run git status to see modified files
2. Review changes, identify which should be committed
3. Run tests before committing
4. Write descriptive commit message following [convention]
5. Commit only reviewed files
```

**For discipline-enforcing prompts:**

```markdown
Add explicit counters for each rationalization:

## The Iron Law
Write code before test? Delete it. Start over.

**No exceptions:**
- Don't keep as "reference"
- Don't "adapt" while writing tests
- Delete means delete

| Excuse | Reality |
|--------|---------|
| "Already manually tested" | Ad-hoc ≠ systematic. No record, can't re-run. |
| "Tests after achieve same" | Tests-after = verifying. Tests-first = designing. |
```

**For guidance prompts:**

```markdown
Pattern with clear applicability:

## High-Throughput Event Processing

**When to use:** >1000 events/sec, async operations, resilience required

**Pattern:**
1. Queue-based ingestion (decouple receipt from processing)
2. Worker pools (parallel processing)
3. Dead letter queue (failed events)
4. Idempotency keys (safe retries)

**Trade-offs:** [complexity vs. reliability]
```

**For reference prompts:**

```markdown
Direct answers with examples:

## Authentication

All requests require bearer token:

\\`\\`\\`bash
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com
\\`\\`\\`

Tokens expire after 1 hour. Refresh using /auth/refresh endpoint.
```

### Testing with Prompt

Run same scenarios WITH prompt using subagent.

```markdown
Use Task tool with prompt included:

prompt: "You have access to [prompt-name]:

[Include prompt content]

Now handle this scenario:
[Scenario description]

Report back: actions taken, reasoning, which parts of prompt you used."

subagent_type: "general-purpose"
description: "Green test for [prompt-name]"
```

**Success criteria:**
- Agent follows prompt instructions
- Baseline failures no longer occur
- Agent cites prompt when relevant

**If agent still fails:** Prompt unclear or incomplete. Revise and re-test.

## REFACTOR Phase: Optimize Prompt (Stay Green)

After green, improve the prompt while keeping tests passing.

### Optimization Goals

1. **Close loopholes** - Agent found ways around rules?
2. **Improve clarity** - Agent misunderstood sections?
3. **Reduce tokens** - Can you say same thing more concisely?
4. **Enhance structure** - Is information easy to find?

### Closing Loopholes (Discipline-Enforcing)

Agent violated rule despite having the prompt? Add specific counters.

**Capture new rationalizations:**

```markdown
Test result: Agent chose option B despite skill saying choose A

Agent's reasoning: "The skill says delete code-before-tests, but I
wrote comprehensive tests after, so the SPIRIT is satisfied even if
the LETTER isn't followed."
```

**Close the loophole:**

```markdown
Add to prompt:

**Violating the letter of the rules is violating the spirit of the rules.**

"Tests after achieve the same goals" - No. Tests-after answer "what does
this do?" Tests-first answer "what should this do?"
```

**Re-test with updated prompt.**

### Improving Clarity

Agent misunderstood instructions? Use meta-testing.

**Ask the agent:**

```markdown
Launch subagent:

"You read the prompt and chose option C when A was correct.

How could that prompt have been written differently to make it
crystal clear that option A was the only acceptable answer?

Quote the current prompt and suggest specific changes."
```

**Three possible responses:**

1. **"The prompt WAS clear, I chose to ignore it"**
   - Not clarity problem - need stronger principle
   - Add foundational rule at top

2. **"The prompt should have said X"**
   - Clarity problem - add their suggestion verbatim

3. **"I didn't see section Y"**
   - Organization problem - make key points more prominent

### Reducing Tokens (All Prompts)

**From prompt-engineering skill:**

- Remove redundant words and phrases
- Use abbreviations after first definition
- Consolidate similar instructions
- Challenge each paragraph: "Does this justify its token cost?"

**Before:**

```markdown
## How to Submit Forms

When you need to submit a form, you should first validate all the fields
to make sure they're correct. After validation succeeds, you can proceed
to submit. If validation fails, show errors to the user.
```

**After (37% fewer tokens):**

```markdown
## Form Submission

1. Validate all fields
2. If valid: submit
3. If invalid: show errors
```

**Re-test to ensure behavior unchanged.**

### Re-verify After Refactoring

**Re-test same scenarios with updated prompt using fresh subagents.**

Agent should:
- Still follow instructions correctly
- Show improved understanding
- Reference updated sections when relevant

**If new failures appear:** Refactoring broke something. Revert and try different optimization.

## Subagent Testing Patterns

### Pattern 1: Parallel Baseline Testing

Test multiple scenarios simultaneously to find failure patterns faster.

```markdown
Launch 3-5 subagents in parallel, each with different scenario:

Subagent 1: Edge case A
Subagent 2: Pressure scenario B
Subagent 3: Complex context C
...

Compare results to identify consistent failures.
```

### Pattern 2: A/B Testing

Compare two prompt variations to choose better version.

```markdown
Launch 2 subagents with same scenario, different prompts:

Subagent A: Original prompt
Subagent B: Revised prompt

Compare: clarity, token usage, correct behavior
```

### Pattern 3: Regression Testing

After changing prompt, verify old scenarios still work.

```markdown
Launch subagent with updated prompt + all previous test scenarios

Verify: All previous passes still pass
```

### Pattern 4: Stress Testing

For critical prompts, test under extreme conditions.

```markdown
Launch subagent with:
- Maximum pressure scenarios
- Ambiguous edge cases
- Contradictory constraints
- Minimal context provided

Verify: Prompt provides adequate guidance even in worst case
```

## Testing Checklist (TDD for Prompts)

Before deploying prompt, verify you followed RED-GREEN-REFACTOR:

**RED Phase:**

- [ ] Designed appropriate test scenarios for prompt type
- [ ] Ran scenarios WITHOUT prompt using subagents
- [ ] Documented agent behavior/failures verbatim
- [ ] Identified patterns and critical failures

**GREEN Phase:**

- [ ] Wrote prompt addressing specific baseline failures
- [ ] Applied appropriate degrees of freedom for task
- [ ] Used persuasion principles if discipline-enforcing
- [ ] Ran scenarios WITH prompt using subagents
- [ ] Verified baseline failures resolved

**REFACTOR Phase:**

- [ ] Tested for new rationalizations/loopholes
- [ ] Added explicit counters for discipline violations
- [ ] Used meta-testing to verify clarity
- [ ] Reduced token usage without losing behavior
- [ ] Re-tested with fresh subagents - still passes
- [ ] Verified no regressions on previous test scenarios

## Common Mistakes (Same as Code TDD)

**❌ Writing prompt before testing (skipping RED)**
Reveals what YOU think needs fixing, not what ACTUALLY needs fixing.
✅ Fix: Always run baseline scenarios first.

**❌ Testing with conversation history**
Accumulated context affects behavior - can't isolate prom

---

Source: [Claudary](https://claudary.paisolsolutions.com/skills/skill-516) · https://claudary.paisolsolutions.com