EP04. "wp-acf-and-content-modeling ACF 与内容建模审查"

• 「先加个 flexible content 让编辑自己拼页面」听起来很方便，半年后变成没人敢动的怪物结构、查不动也迁不走——wp-acf-and-content-modeling 就是提前挡住这种坑
• 这是 jorgerosal/wordpress-skills 里专门审 Advanced Custom Fields 用法和内容架构设计的技能，跟只看插件骨架的 wp-plugin-development 不是一回事
• 核心判断标准：好的内容模型要「耐用、好查询、编辑好用、迁移可预期」，审查按七步走：先划模型边界，再看核心内容实体，然后是字段组架构、CRITICAL/WARNING/INFO 分级、最后按场景给权重
• 前置知识：先看过 Overview 系列「Claude Code 是什么与新手上手」「进阶功能：Skills、Plugins 与 Routines」，以及 EP01「wp-security-review 安全审查」了解这套 skill 包怎么调用

重点内容

这个 Skill 是做什么的

系统审查依赖 ACF 和自定义内容架构的 WordPress 项目：CPT/taxonomy 设计合不合理、字段组边界清不清楚、命名规范一不一致、数据存储策略、ACF JSON 环境同步、以及 meta-heavy 写法长期的性能代价。报告按文件/子系统分组，附 CRITICAL/WARNING/INFO 严重度和具体修法。

适合用在：

• 审查注册了 CPT、taxonomy 或 ACF 字段组的插件/主题
• Review acf_add_local_field_group() 或字段组 JSON 导出文件
• 判断 repeater / flexible content 是不是解决这个内容问题的对路方式
• 评估 options page、relationship 字段、clone 字段、block 字段组
• 排查后台页面变慢、内容量大时 meta_query 开销过高
• 给新项目（编辑型网站、目录站、落地页搭建器、headless 项目）规划内容模型
• Review ACF JSON 同步、字段 key 漂移、跨环境可移植性

不适合用在：

• 没有实质 ACF/内容建模工作的通用插件架构（交给 wp-plugin-development）
• 纯 REST 路由设计（交给 wp-rest-api-development）
• 跟字段建模无关的 Gutenberg block 实现细节（交给 wp-block-development）
• 跟内容 schema 无关的纯性能审查（交给 wp-performance-review）
• WooCommerce 领域建模（除非问题本身就是通用 ACF 建模问题）

触发方式

八个检查维度

实操示例

// ❌ CRITICAL：代码直接依赖字段 key，字段名改了代码全炸，字段名也毫无domain前缀
function get_hero_data( $post_id ) {
    return get_field( 'field_5f2a8b9c1234', $post_id ); // 硬编码字段 key
}

// ✅ GOOD：用稳定、带 domain 前缀的字段名，不依赖字段 key
function get_hero_data( $post_id ) {
    return get_field( 'hero_headline', $post_id ); // 字段名清楚表明属于 hero 组件
}

// ❌ CRITICAL：归档页靠好几层 meta_query 叠加做核心筛选，价格/地点/日期都是未建索引的 postmeta
$query = new WP_Query( array(
    'post_type'  => 'listing',
    'meta_query' => array(
        'relation' => 'AND',
        array( 'key' => 'location', 'value' => $location, 'compare' => 'LIKE' ),
        array( 'key' => 'price_band', 'value' => $price ),
        array( 'key' => 'event_date', 'value' => $date, 'compare' => '>=' ),
    ),
) );

// ✅ GOOD：把常用筛选维度提升成 taxonomy，可以用 tax_query 高效查询、还自带索引
$query = new WP_Query( array(
    'post_type' => 'listing',
    'tax_query' => array(
        array( 'taxonomy' => 'listing_location', 'field' => 'slug', 'terms' => $location ),
        array( 'taxonomy' => 'listing_price_band', 'field' => 'slug', 'terms' => $price ),
    ),
    // 日期这类原生排序需求，直接用核心的 date_query，而不是塞进 meta_query
    'date_query' => array( array( 'after' => $date ) ),
) );

// ❌ WARNING：字段组只在数据库里改过，没有导出 JSON，别人 pull 代码看不到这个改动
// （acf-json/ 目录缺这个字段组对应的文件）

// ✅ GOOD：开启 ACF JSON 自动同步并提交进版本控制
add_filter( 'acf/settings/save_json', function() {
    return get_stylesheet_directory() . '/acf-json';
} );
add_filter( 'acf/settings/load_json', function( $paths ) {
    unset( $paths[0] );
    $paths[] = get_stylesheet_directory() . '/acf-json';
    return $paths;
} );

怎么安装

这个 skill 是 wordpress-skills 这个开源仓库（jorgerosal/wordpress-skills）打包的 18 个技能之一，安装一次，18 个技能一起到位，不用逐个装：

Claude Code：

装完重启 Claude Code，进到一个 WordPress 项目里跑 /wordpress-skills:wp-acf-review 验证有没有装成功（用 marketplace/submodule 方式装的话，指令前面会带插件命名空间 wordpress-skills:；用「只装这一个 skill」的方式则不带命名空间，直接 /wp-acf-review）。

Claude Desktop / claude.ai： 走 Settings → Capabilities → Skills，上传技能文件夹（把 claude-skills/wp-acf-and-content-modeling 这个文件夹打包上传，里面要包含 SKILL.md）——跟 Claude Code 的 git submodule/marketplace 安装方式不同，Desktop 端是手动上传 UI，装好之后同样能用自然语言或 slash 指令触发。

常见错误

• ❌ 只要用了 ACF 后台好用就当成没问题——这个 skill 的判断标准是「网站的内容和编辑者、集成方翻倍之后还看得懂吗」，不是「后台填字段方不方便」
• ❌ 把「什么都是 flexible content 页面」当成灵活性的胜利——这恰恰是最常见的反模式（Final Reminder 原文强调的重点），长期查询、复用、迁移都会变得极其困难
• ❌ 把该用 taxonomy 或独立实体表达的关系硬塞进 post meta——「什么都是 post meta」是第二常见的反模式，日后既不好筛选也不好排序
• ❌ 审查时不区分网站类型直接套同一套优先级——编辑型网站看重治理与迁移安全，营销落地页搭建器更看重可维护性和编辑约束，headless 网站要优先看 schema 稳定性和 API 暴露形状，三种场景权重不一样
• 💡 发现查询行为是主要风险时，报告里建议顺手跑一下 /wp-perf-review；发现字段组主要在为自定义 block 供数据，建议顺手跑 /wp-block-review——这个 skill 本身不做性能或 block 审查的深挖

Sources

官方文档：

1. wordpress-skills（GitHub 仓库）— https://github.com/jorgerosal/wordpress-skills
2. wp-acf-and-content-modeling SKILL.md — https://github.com/jorgerosal/wordpress-skills/blob/main/claude-skills/wp-acf-and-content-modeling/SKILL.md