proffesor-for-testing__agentic-qe/docs/optimization/claude-4-5-patterns.md

Claude 4.5 Skill Optimization Patterns

Executive Summary

This guide defines best practices for optimizing Agentic QE skills for Claude 4.5, targeting 40-50% token reduction while improving agent coordination and maintaining quality.

Key Achievements:

• Token reduction: 40-50% target (e.g., 2,600 → 1,300-1,560 tokens)
• Improved agent coordination through structured hints
• Enhanced Claude 4.5 action-first directive patterns
• Standardized metadata and implementation tracking

---

Core Optimization Principles

1. Action-First Directive Pattern

Claude 4.5 excels with immediate, actionable directives at the top of skills.

❌ Before (Token-Heavy)

# Performance Testing

## Why Performance Testing Matters

Performance is a feature, not an afterthought. Modern users expect...

### User Impact
- 100ms delay = 1% drop in conversions
- 53% of mobile users abandon...

## Types of Performance Testing

### 1. Load Testing
What: System behavior under expected load...

✅ After (Action-First)

# Performance Testing

<default_to_action>
When performance testing is requested:
1. IDENTIFY critical paths (checkout, search, APIs)
2. DEFINE SLOs: p95 response time, throughput, error rate
3. SELECT test type: Load (typical usage) → Stress (breaking point) → Spike (sudden surge) → Endurance (24h+)
4. RUN k6/JMeter with realistic scenarios (user journeys, think time, varied data)
5. MONITOR: Response time percentiles, throughput, errors, CPU/memory/DB
6. ANALYZE bottlenecks: Database (indexes, N+1 queries), Sync ops, Memory leaks, Caching gaps
7. REPORT with baselines and trends

**Quick Decision Matrix:**
- Before release → Load + Stress tests
- Infrastructure change → Scalability test
- Major event → Spike test
- New features → Endurance test (24-72h)
</default_to_action>

## Performance Test Types

**Load Testing**: Expected traffic (e.g., 1K users, 10K req/min)
**Stress Testing**: Beyond capacity → find breaking point
**Spike Testing**: Sudden surge (Black Friday, viral posts)
**Endurance/Soak**: 24-72h → detect memory leaks
**Scalability**: Validate horizontal/vertical scaling

Benefits:

• Immediate actionable guidance (Claude starts working instantly)
• 60-70% token reduction in introductory content
• Critical decision points highlighted
• Clear workflow progression

---

2. Structured Output Templates

Use YAML frontmatter and structured sections for efficient parsing.

Metadata Block (YAML Frontmatter)

---
name: performance-testing
category: specialized-testing
priority: high
tokenEstimate: 1300
agents: [qe-performance-tester]
implementation_status: optimized
optimization_version: 1.0
last_optimized: 2025-12-02
dependencies: [agentic-quality-engineering]
quick_reference_card: true
---

Required Fields:

• name: Skill identifier (kebab-case)
• category: From skills-manifest.json
• priority: critical | high | medium | low
• tokenEstimate: Target after optimization
• agents: Array of associated QE agents
• implementation_status: draft | baseline | optimized | production
• optimization_version: Semantic version
• last_optimized: ISO date
• dependencies: Required skills
• quick_reference_card: Boolean (must be true for optimized skills)

---

3. Token Compression Techniques

A. Remove Verbose Explanations

❌ Before (256 tokens):
## Why Performance Testing Matters

### User Impact
Performance directly affects user experience and business metrics. Research shows that 100ms delay leads to 1% drop in conversions according to Amazon's studies. Google research indicates 53% of mobile users abandon sites taking more than 3 seconds to load. From a user's perspective, slow equals broken.

✅ After (64 tokens):
**Impact**: 100ms delay = 1% conversion drop (Amazon). 53% abandon sites >3s (Google). Slow = Broken.

Reduction: 75% token savings

B. Use Tables for Dense Information

❌ Before (180 tokens):
**k6**: Modern, developer-friendly, JavaScript-based load testing tool. Good for CI/CD integration and API testing. Has a low learning curve.

**JMeter**: Mature, feature-rich, GUI-based load testing tool. Good for complex scenarios and extensive protocol support. Has a medium learning curve.

✅ After (72 tokens):
| Tool | Best For | Learning Curve |
|------|----------|----------------|
| k6 | CI/CD, APIs, modern workflows | Low |
| JMeter | Complex scenarios, GUI | Medium |
| Gatling | High load, detailed metrics | Medium |

Reduction: 60% token savings

C. Consolidate Redundant Content

❌ Before (320 tokens):
### 1. Load Testing
What: System behavior under expected load
Goal: Verify the system handles typical usage
Example: E-commerce site handling 1,000 concurrent users
When: Before every major release

### 2. Stress Testing
What: System behavior under extreme load
Goal: Find breaking point, see how system fails
Example: Ramping up from 1,000 to 10,000 users
When: Before scaling infrastructure

✅ After (128 tokens):
**Test Types:**
- **Load**: Expected traffic (1K users) → Before releases
- **Stress**: Beyond capacity (1K→10K users) → Find breaking point
- **Spike**: Sudden surge (Black Friday) → Test auto-scaling
- **Endurance**: 24-72h at normal load → Memory leaks

Reduction: 60% token savings

---

4. Quick Reference Card Format

Every optimized skill must include a quick reference card for rapid agent coordination.

## Quick Reference Card

### When to Use
- Planning load testing strategy
- Investigating performance issues
- Setting performance baselines
- Optimizing system bottlenecks

### Key Actions
1. Define SLOs (p95 < 200ms, throughput > 10K req/min, error < 0.1%)
2. Identify critical paths (revenue flows, high-traffic pages)
3. Run appropriate test type (Load/Stress/Spike/Endurance)
4. Monitor: Response time percentiles, throughput, errors, resources
5. Analyze bottlenecks (DB, N+1, sync ops, memory, cache)
6. Report with baselines and trends

### Tools Selection
- **k6**: Modern CI/CD, APIs (Low learning curve)
- **JMeter**: Complex scenarios, GUI (Medium)
- **Gatling**: High load, reporting (Medium)

### Common Bottlenecks
- **Database**: Missing indexes, N+1 queries, connection pool exhaustion
- **Synchronous**: Blocking operations in request path (use queues)
- **Memory Leaks**: Event listeners, unbounded caches, circular refs
- **Caching**: Under-utilized or misconfigured

### Pass/Fail Criteria
✅ p95 < target, error rate < 0.1%, CPU < 70%, memory < 80%
❌ Response time > 2x target, error rate > 1%, resources maxed

### Agent Coordination
- `qe-performance-tester`: Orchestrates load testing and analysis
- `qe-quality-analyzer`: Interprets results and trends
- `qe-production-intelligence`: Compares to production baselines

Benefits:

• 200-400 token quick scan section
• Enables rapid agent decision-making
• Provides context for fleet coordination
• Clear pass/fail criteria

---

Agent Integration Patterns

Coordination Hints Section

## Agent Coordination Hints

### Memory Namespace
Store performance data in: `aqe/performance/{test-type}/{timestamp}`

**Schema:**
```json
{
  "testType": "load|stress|spike|endurance",
  "target": "https://api.example.com",
  "duration": "5m",
  "virtualUsers": 100,
  "results": {
    "p50": 120,
    "p95": 180,
    "p99": 250,
    "errorRate": 0.003,
    "throughput": 5420
  },
  "bottlenecks": ["database:slow-query:orders.user_id"],
  "recommendations": ["Add index on orders.user_id"]
}

Coordination Flow

1. qe-performance-tester → Run tests, store results in memory
2. qe-quality-analyzer → Retrieve results, analyze trends
3. qe-production-intelligence → Compare to production baselines
4. qe-deployment-readiness → Go/no-go decision based on thresholds

Blackboard Patterns

Post to: performance/test-completed with priority high Subscribe to: quality/gate-evaluation for deployment decisions

Cross-Agent Dependencies

• Requires: agentic-quality-engineering (foundational PACT principles)
• Complements: api-testing-patterns (for API performance testing)
• Informs: quality-metrics (for dashboard integration)

---

## Implementation Status Metadata

Track optimization progress with implementation status:

```yaml
implementation_status: optimized
optimization_details:
  baseline_tokens: 2600
  optimized_tokens: 1300
  reduction_percent: 50
  optimization_date: 2025-12-02
  optimizer: "claude-sonnet-4-5"
  validation_status: "passed"
  agent_tested: [qe-performance-tester]

Status Levels:

• draft: Initial creation, not production-ready
• baseline: Original version before optimization
• optimized: Underwent Claude 4.5 optimization
• production: Validated with real agents, battle-tested

---

Optimization Workflow

Phase 1: Baseline Analysis

# Count tokens in original skill
npm run count-tokens .claude/skills/performance-testing/SKILL.md

# Record baseline
Baseline: 2,600 tokens
Target: 1,300-1,560 tokens (40-50% reduction)

Phase 2: Apply Patterns

1. Add YAML frontmatter with metadata
2. Insert <default_to_action> block at top
3. Create quick reference card
4. Compress verbose sections:
   • Convert paragraphs to bullet lists
   • Use tables for comparisons
   • Remove redundant explanations
5. Add agent coordination section
6. Update implementation_status

Phase 3: Validation

# Validate structure
npm run validate-skill .claude/skills/performance-testing/SKILL.md

# Test with agent
Task("Performance test", "Run load test on staging API", "qe-performance-tester")

Phase 4: Metrics Collection

optimization_metrics:
  before: 2600 tokens
  after: 1300 tokens
  reduction: 50%
  validation_passed: true
  agent_feedback: "Excellent clarity, immediate action guidance"

---

Token Reduction Strategies by Section

Introduction (Target: 80% reduction)

Before: 400 tokens of philosophy and context After: 50-80 tokens in <default_to_action> block

Core Content (Target: 40% reduction)

Before: 1,800 tokens with verbose explanations After: 1,080 tokens with tables, lists, and structured formats

Examples (Target: 30% reduction)

Before: 300 tokens with full code blocks After: 210 tokens with minimal, essential examples

Agent Integration (NEW: +150 tokens)

Added: Agent coordination hints, memory schemas, fleet patterns

Net Result: 2,600 → 1,300 tokens (50% reduction)

---

Quality Assurance Checklist

Before marking a skill as optimized, verify:

• YAML frontmatter present with all required fields
• <default_to_action> block at top (100-200 tokens)
• Quick reference card section included
• Agent coordination hints section present
• Token estimate ≤ baseline × 0.6 (40%+ reduction)
• All agents from manifest referenced
• Dependencies listed correctly
• Implementation status updated
• Tested with at least one agent
• Cross-references to related skills updated

---

Anti-Patterns to Avoid

❌ Over-Compression

**Bad:** Load test: sys behavior @ expected load. Run b4 release.

Issue: Loses clarity, becomes cryptic

Better: Load Testing: System behavior under expected traffic (1K users). Run before releases.

❌ Removing Critical Context

**Bad:** p95 < 200ms

Issue: No explanation of why or when

Better: SLO: p95 response time < 200ms (95% of requests complete in under 200ms)

❌ Eliminating Examples

**Bad:** Use k6 for load testing.

Issue: No guidance on how

Better:

// k6 load test example
export const options = {
  stages: [{ duration: '1m', target: 50 }],
  thresholds: { http_req_duration: ['p(95)<200'] }
};

---

Template Usage Guidelines

Selecting the Right Template

New Skill (from scratch):

cp docs/templates/optimized-skill-template.md .claude/skills/my-new-skill/SKILL.md
# Fill in all sections

Optimizing Existing Skill:

# 1. Read original skill
# 2. Extract core content
# 3. Apply optimization patterns from this guide
# 4. Validate with script
npm run validate-skill .claude/skills/my-skill/SKILL.md

---

Metrics Dashboard

Track optimization progress:

fleet_optimization_status:
  total_skills: 41
  optimized: 0
  in_progress: 0
  baseline: 41

  target_reduction: 45%  # (40-50% range midpoint)

  token_savings:
    estimated_before: 90000  # 41 skills × ~2200 avg
    estimated_after: 49500   # 45% reduction
    savings: 40500 tokens

  priority_order:
    critical: [agentic-quality-engineering, holistic-testing-pact]
    high: [tdd-london-chicago, api-testing-patterns, cicd-pipeline-qe-orchestrator, ...]
    medium: [security-testing, performance-testing, ...]
    low: [consultancy-practices, technical-writing]

---

Advanced Patterns

Conditional Content Loading

<default_to_action>
**Quick Start:**
For rapid testing → See [Quick Reference Card](#quick-reference-card)
For comprehensive strategy → See [Detailed Methodology](#detailed-methodology)
For troubleshooting → See [Common Issues](#common-issues)
</default_to_action>

Cross-Skill References

## Related Skills
**Prerequisites:** [agentic-quality-engineering](../agentic-quality-engineering/) (PACT principles)
**Complements:** [api-testing-patterns](../api-testing-patterns/) (API performance)
**Informs:** [quality-metrics](../quality-metrics/) (dashboard integration)

Versioned Optimization

optimization_history:
  - version: 1.0
    date: 2025-12-02
    tokens: 1300
    reduction: 50%
    notes: "Initial Claude 4.5 optimization"
  - version: 0.9
    date: 2025-11-15
    tokens: 2600
    notes: "Baseline before optimization"

---

Success Metrics

Target Achievement:

• ✅ 40-50% token reduction across all 41 skills
• ✅ <300ms agent skill loading time
• ✅ 100% skills have quick reference cards
• ✅ Zero quality regression in agent effectiveness
• ✅ Improved coordination through structured hints

Validation Methods:

1. Token Counting: Automated script validation
2. Agent Testing: Real agent execution with optimized skills
3. Coordination Flow: Multi-agent workflows with memory sharing
4. User Feedback: Manual review of optimization quality

---

References

• Claude 4.5 Best Practices: Action-first directives, structured output
• Skills Manifest: /workspaces/agentic-qe-cf/.claude/skills/skills-manifest.json
• Validation Script: /workspaces/agentic-qe-cf/scripts/validate-skill-optimization.ts
• Template: /workspaces/agentic-qe-cf/docs/templates/optimized-skill-template.md

---

Document Version: 1.0 Last Updated: 2025-12-02 Maintained By: Agentic QE Fleet Architecture Team