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