开发或扩展 WordPress 主题、插件…

适用于需要构建或扩展 WordPress 站点功能，并确保安全、性能、可维护性的开发场景。

适用场景

解决思路

1. 分析需求：理解 WordPress 上下文、现有设置和目标。
2. 设计架构：规划主题/插件结构、钩子和数据流。
3. 实现：使用 WordPress 编码标准和安全最佳实践构建。
4. 验证：运行 `phpcs --standard=WordPress` 捕获 WPCS 违规；手动验证 nonce 处理和 capability 检查。
5. 优化：应用 transient/对象缓存、查询优化和资源入队。
6. 测试与加固：确认所有 I/O 的清理/转义，测试目标 WordPress 版本，并运行安全检查清单。
7. 按任务领域加载参考文档：主题开发读 `references/theme-development.md`（模板、层级、子主题、FSE）；插件架构读 `references/plugin-architecture.md`（结构、激活、设置 API、更新）；Gutenberg 区块读 `references/gutenberg-blocks.md`（区块开发、模式、FSE、动态区块）；Hooks 与 Filters 读 `references/hooks-filters.md`（actions、filters、自定义 hooks、优先级）；性能与安全读 `references/performance-security.md`（缓存、优化、加固、备份）。
8. 表单 nonce 验证：用 `wp_nonce_field( 'my_action', 'my_nonce' );` 输出 nonce 字段；提交时检查 `$_POST['my_nonce']` 存在并用 `wp_verify_nonce( sanitize_text_field( wp_unslash( $_POST['my_nonce'] ) ), 'my_action' )` 验证，失败用 `wp_die( esc_html__( 'Security check failed.', 'my-textdomain' ) );` 提前退出。
9. 输入清理：用 `sanitize_text_field( wp_unslash( $_POST['title'] ?? '' ) )` 处理标题；用 `wp_kses_post( wp_unslash( $_POST['content'] ?? '' ) )` 处理内容；用 `esc_url_raw( wp_unslash( $_POST['url'] ?? '' ) )` 处理 URL。
10. 输出转义：用 `echo esc_html( $title );`、`echo wp_kses_post( $content );`；链接示例用 `echo '<a href="' . esc_url( $url ) . '">' . esc_html__( 'Link', 'my-textdomain' ) . '</a>';`。
11. 资源入队：添加 `add_action( 'wp_enqueue_scripts', 'my_theme_assets' );`；在 `my_theme_assets()` 中用 `wp_enqueue_style( 'my-theme-style', get_stylesheet_uri(), [], wp_get_theme()->get( 'Version' ) );`；用 `wp_enqueue_script( 'my-theme-script', get_template_directory_uri() . '/assets/js/main.js', [ 'jquery' ], '1.0.0', true );` 在页脚加载；用 `wp_localize_script( 'my-theme-script', 'MyTheme', [ 'ajaxUrl' => admin_url( 'admin-ajax.php' ), 'nonce' => wp_create_nonce( 'my_ajax_nonce' ), ] );` 安全传递服务器数据到 JS。
12. 预处理数据库查询：`global $wpdb;` 后用 `$wpdb->get_results( $wpdb->prepare( "SELECT * FROM {$wpdb->prefix}my_table WHERE user_id = %d AND status = %s", absint( $user_id ), sanitize_text_field( $status ) ) );`。
13. 能力检查：敏感操作前用 `if ( ! current_user_can( 'manage_options' ) ) { wp_die( esc_html__( 'You do not have permission to do this.', 'my-textdomain' ) ); }`。
14. MUST DO：遵循 WordPress Coding Standards (WPCS)，用 `phpcs --standard=WordPress` 验证。
15. MUST DO：所有表单提交和 AJAX 请求都使用 nonces。
16. MUST DO：所有用户输入都用适当函数清理（`sanitize_text_field`、`wp_kses_post` 等）。
17. MUST DO：所有输出都转义（`esc_html`、`esc_url`、`esc_attr`、`wp_kses_post`）。
18. MUST DO：所有数据库查询都使用 prepared statements（`$wpdb->prepare`）。
19. MUST DO：在特权操作前实现正确的 capability 检查。
20. MUST DO：通过 `wp_enqueue_scripts` / `admin_enqueue_scripts` 钩子入队脚本/样式。
21. MUST DO：使用 WordPress hooks，而不是修改核心。
22. MUST DO：用 text domains 编写可翻译字符串（`__()`、`esc_html__()` 等）。
23. MUST DO：在目标 WordPress 版本上测试。
24. MUST NOT DO：不要修改 WordPress 核心文件。
25. MUST NOT DO：不要使用 PHP 短标签或已弃用函数。
26. MUST NOT DO：不要信任未清理的用户输入。
27. MUST NOT DO：不要输出未转义的数据。
28. MUST NOT DO：不要硬编码数据库表名（使用 `$wpdb->prefix`）。
29. MUST NOT DO：不要在管理功能中跳过 capability 检查。
30. MUST NOT DO：不要忽略 SQL 注入向量。
31. MUST NOT DO：当 WordPress API 足够时，不要捆绑不必要的库。
32. MUST NOT DO：不要允许不安全的文件上传处理。
33. MUST NOT DO：不要跳过国际化（i18n）。
34. 输出模板：实现 WordPress 功能时提供：1) 带正确 headers 的主插件/主题文件；2) 相关模板文件或区块代码；3) 带正确 WordPress hooks 的函数；4) 安全实现（nonces、sanitization、escaping）；5) 简要说明所用的 WordPress 特定模式。
35. 知识参考：使用 WordPress 6.4+、PHP 8.1+、Gutenberg、WooCommerce、ACF、REST API、WP-CLI、区块开发、主题定制器、小工具 API、短代码 API、transients、对象缓存、查询优化、安全加固、WPCS。

适用边界 · 注意事项

• 非 WordPress 项目、纯 PHP/其他 CMS/静态站点，且不需要 WordPress 主题、插件、Gutenberg、WooCommerce 或 REST API 时。
• 如果目标必须修改 WordPress 核心文件才能实现，不适用；应改用 hooks/filters 或插件。
• 没有 WordPress 运行环境或无法按目标版本测试时，安全与性能优化结论不可靠。