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:
code
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