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 queriesdb-avoid-post-not-in- Avoid post__not_in, filter in PHP insteaddb-use-wp-query- Use WP_Query/get_posts instead of direct DB queriesdb-limit-query-results- Never use posts_per_page => -1db-meta-query-indexing- Optimize meta queries, consider taxonomiesdb-fields-optimization- Use fields => 'ids' when only IDs needed
2. Caching Strategies (CRITICAL)
cache-transients-proper-use- Use transients for external API callscache-object-cache- Use wp_cache_* with cache groupscache-remote-requests- Always cache wp_remote_get responsescache-invalidation- Implement precise, event-driven invalidationcache-fragment-caching- Cache expensive template fragments
3. Asset Management (HIGH)
asset-proper-enqueue- Use wp_enqueue_script/style, never hardcodeasset-conditional-loading- Only load assets where neededasset-defer-async- Use defer/async for non-critical scriptsasset-dequeue-unused- Remove unused plugin assetsasset-minification- Minify assets, use critical CSS
4. Theme Performance (HIGH)
theme-avoid-queries-in-templates- Keep queries out of template filestheme-template-parts- Use get_template_part with data passingtheme-loop-optimization- Optimize loops, use meta/term cache primingtheme-hooks-placement- Use appropriate hook priorities
5. Plugin Architecture (MEDIUM-HIGH)
plugin-conditional-loading- Load code only when neededplugin-autoloading- Use PSR-4 autoloadingplugin-activation-hooks- Use activation hooks for setup tasksplugin-hook-removal- Remove hooks properly with matching priority
6. Media Optimization (MEDIUM)
media-responsive-images- Use srcset and sizes attributesmedia-lazy-loading- Lazy load below-fold, eager load LCPmedia-image-sizes- Define appropriate custom image sizes
7. API and AJAX (MEDIUM)
api-rest-optimization- Optimize REST endpoints, add caching headersapi-admin-ajax- Use REST API for frontend, avoid admin-ajaxapi-nonce-validation- Implement proper nonce validation
8. Advanced Patterns (LOW-MEDIUM)
advanced-autoload-optimization- Keep autoloaded options under 800KBadvanced-cron-optimization- Use system cron, batch long tasksadvanced-memory-management- Process in batches, clean up memoryadvanced-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