wordpress-performance-best-practices

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