Update-safe WordPress features

WordPress Development

Never edit what updates overwrite

• Never modify WordPress core (wp-admin, wp-includes) or third-party plugins and themes in place; updates erase the change.
• Customize a third-party theme through a child theme; customize plugins through their hooks or a small custom plugin or mu-plugin.
• Site functionality (post types, integrations) belongs in a plugin, not the theme, so it survives a theme switch.

Hooks over template edits

• Prefer actions and filters to copying templates. Find the hook in the source before overriding a file.
• Hook at the right time: init for post types and taxonomies, wp_enqueue_scripts / admin_enqueue_scripts for assets, rest_api_init for routes, plugins_loaded for plugin bootstrap.
• Filters always return a value. Set priority and accepted args deliberately.
• Override templates only through the child theme or a plugin's documented override path, and keep them minimal.

Assets

• wp_register_script / wp_enqueue_script and wp_enqueue_style with dependencies, a version (plugin version or filemtime) and a footer or defer strategy. Never hardcode script or link tags.
• Enqueue only where needed. Pass data to JS with wp_add_inline_script or wp_localize_script.
• Blocks: block.json plus register_block_type, built with the repo's @wordpress/scripts setup.

Standards

• Follow the WordPress Coding Standards; run PHPCS with the repo's phpcs.xml (WordPress ruleset) when present.
• Prefix every global function, class, constant, option, hook, script handle and meta key with the project prefix, or use a namespace. Reuse the existing prefix.
• Respect the minimum PHP and WordPress versions in the plugin or theme header.

Internationalization

• Wrap user-facing strings in _(), e(), esc_html(), _x() or _n() with the project's text domain.
• Use sprintf/printf placeholders, never concatenated sentence fragments.

Data

• Options: prefixed names; autoload off for large or rarely used options.
• Transients for expensive results, with an expiry; always handle a missing transient.
• register_post_meta for meta used by REST or blocks.
• Custom tables only when needed: dbDelta on activation, with a schema version option.

Custom post types and REST

• register_post_type and register_taxonomy on init with labels, supports, show_in_rest and rewrite slug. Flush rewrite rules only on activation, never per request.
• register_rest_route with a versioned namespace, an args schema with validate and sanitize callbacks, and a real permission_callback.

Query performance

• WP_Query with bounded posts_per_page (never -1 on large sites), fields => ids when only IDs are needed, no_found_rows when not paginating.
• Avoid unindexed meta_query in hot paths; cache results in the object cache or transients.
• Never use query_posts; call wp_reset_postdata after custom loops. No queries inside loops.

WP-CLI

• Use WP-CLI for local inspection and tasks (wp option get, wp post list, wp cron event list). Never run destructive commands like search-replace or db reset outside a local environment.

Before you finish

• No core or third-party code edited; child theme or plugin used.
• Assets enqueued properly and only where needed.
• Everything prefixed; strings translatable with the right text domain.
• Queries bounded, expensive results cached.
• PHPCS with the WordPress ruleset passes on changed files if configured.