wordpress-performance-best-practices

What this skill does

# WordPress Performance Best Practices

Comprehensive performance optimization guide for WordPress development, designed for AI agents and LLMs. Contains 34 rules across 8 categories, prioritized by impact to guide code review and generation.

## When to Apply

Reference these guidelines when:
- Writing WordPress plugins or themes
- Working with WP_Query or database operations
- Implementing caching (transients, object cache)
- Optimizing asset loading (scripts, styles)
- Reviewing WordPress code for performance issues
- Working with REST API or AJAX handlers

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Database Optimization | CRITICAL | `db-` |
| 2 | Caching Strategies | CRITICAL | `cache-` |
| 3 | Asset Management | HIGH | `asset-` |
| 4 | Theme Performance | HIGH | `theme-` |
| 5 | Plugin Architecture | MEDIUM-HIGH | `plugin-` |
| 6 | Media Optimization | MEDIUM | `media-` |
| 7 | API and AJAX | MEDIUM | `api-` |
| 8 | Advanced Patterns | LOW-MEDIUM | `advanced-` |

## Quick Reference

### 1. Database Optimization (CRITICAL)

- `db-prepared-statements` - Always use $wpdb->prepare() for queries
- `db-avoid-post-not-in` - Avoid post__not_in, filter in PHP instead
- `db-use-wp-query` - Use WP_Query/get_posts instead of direct DB queries
- `db-limit-query-results` - Never use posts_per_page => -1
- `db-meta-query-indexing` - Optimize meta queries, consider taxonomies
- `db-fields-optimization` - Use fields => 'ids' when only IDs needed

### 2. Caching Strategies (CRITICAL)

- `cache-transients-proper-use` - Use transients for external API calls
- `cache-object-cache` - Use wp_cache_* with cache groups
- `cache-remote-requests` - Always cache wp_remote_get responses
- `cache-invalidation` - Implement precise, event-driven invalidation
- `cache-fragment-caching` - Cache expensive template fragments

### 3. Asset Management (HIGH)

- `asset-proper-enqueue` - Use wp_enqueue_script/style, never hardcode
- `asset-conditional-loading` - Only load assets where needed
- `asset-defer-async` - Use defer/async for non-critical scripts
- `asset-dequeue-unused` - Remove unused plugin assets
- `asset-minification` - Minify assets, use critical CSS

### 4. Theme Performance (HIGH)

- `theme-avoid-queries-in-templates` - Keep queries out of template files
- `theme-template-parts` - Use get_template_part with data passing
- `theme-loop-optimization` - Optimize loops, use meta/term cache priming
- `theme-hooks-placement` - Use appropriate hook priorities

### 5. Plugin Architecture (MEDIUM-HIGH)

- `plugin-conditional-loading` - Load code only when needed
- `plugin-autoloading` - Use PSR-4 autoloading
- `plugin-activation-hooks` - Use activation hooks for setup tasks
- `plugin-hook-removal` - Remove hooks properly with matching priority

### 6. Media Optimization (MEDIUM)

- `media-responsive-images` - Use srcset and sizes attributes
- `media-lazy-loading` - Lazy load below-fold, eager load LCP
- `media-image-sizes` - Define appropriate custom image sizes

### 7. API and AJAX (MEDIUM)

- `api-rest-optimization` - Optimize REST endpoints, add caching headers
- `api-admin-ajax` - Use REST API for frontend, avoid admin-ajax
- `api-nonce-validation` - Implement proper nonce validation

### 8. Advanced Patterns (LOW-MEDIUM)

- `advanced-autoload-optimization` - Keep autoloaded options under 800KB
- `advanced-cron-optimization` - Use system cron, batch long tasks
- `advanced-memory-management` - Process in batches, clean up memory
- `advanced-query-monitor` - Profile before optimizing

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/db-prepared-statements.md
rules/cache-transients-proper-use.md
rules/_sections.md
```

Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references

## Full Compiled Document

For the complete guide with all rules expanded: `AGENTS.md`