wp-acf-and-content-modeling

WordPress ACF とコンテンツモデリングのスキル

概要

Advanced Custom Fields とカスタムコンテンツアーキテクチャに依存する WordPress プロジェクトを、体系的にレビューするスキルです。**基本原則：**健全な WordPress のコンテンツモデルは、長期にわたって利用でき、クエリを考慮し、編集者が扱いやすく、予測可能な方法で移行できます。レビューでは、CPT とタクソノミーの設計、フィールドグループの境界、命名の一貫性、保存方式、ACF JSON の同期、メタデータに依存するパターンの長期的なコストに重点を置きます。ファイルまたはサブシステムごとに、重大度ラベル（CRITICAL、WARNING、INFO）、可能な場合は行番号、具体的な修正方法を添えて指摘事項を報告します。

使用する場合

次の場合に使用します：

• カスタム投稿タイプ、タクソノミー、または ACF フィールドグループを登録するプラグインやテーマを監査する場合
• acf_add_local_field_group() またはフィールドグループの JSON エクスポートをレビューする場合
• リピーターやフレキシブルコンテンツが、コンテンツの要件に適した選択肢かどうかを確認する場合
• オプションページ、リレーションフィールド、クローンフィールド、またはブロックフィールドグループを評価する場合
• コンテンツ量の多い構成で、遅い管理画面や高コストな meta_query の使用を調査する場合
• 編集者向けサイト、ディレクトリ、ランディングページビルダー、またはヘッドレス構成向けに新しいコンテンツモデルを計画する場合
• ACF JSON の同期、フィールドキーの不整合、または環境間の移植性をレビューする場合

次の場合には使用しないでください：

• ACF やコンテンツモデリングに実質的な関係がない一般的なプラグインアーキテクチャ（wp-plugin-development を使用してください）
• REST ルートの設計のみを扱う場合（wp-rest-api-development を使用してください）
• フィールドモデリングに関係しない Gutenberg ブロックの実装詳細（wp-block-development を使用してください）
• コンテンツスキーマやメタデータへのアクセスに関連しないパフォーマンス監査（wp-performance-review を使用してください）
• WooCommerce のドメインモデリング（問題が真に一般的な ACF モデリングに関するものでない限り、wp-woocommerce-dev を使用してください）

レビューワークフロー

以下の7段階のワークフローに従います。

1. モデルの境界を特定する

   • 実際のドメインは何ですか。記事、場所、スタッフ、製品、イベント、ランディングページ、設定、それとも再利用可能なコンテンツ断片ですか。
   • モデルが単一サイト向け、マルチサイト向け、ヘッドレス向けのいずれかを判断します。
   • 実装の品質を評価する前に、CPT、タクソノミー、オプションページ、フィールドグループを一覧にします。

2. まずコアとなるコンテンツエンティティを確認する

   • 各CPTに明確な目的があり、理由なく投稿や固定ページを単に複製していないことを検証します。
   • 追加のテキスト／メタフィールドよりもタクソノミーで分類や関係を適切にモデル化できないか確認します。
   • 無関係なコンテンツの受け皿として使われている、過度に多用途な投稿タイプを指摘します。

3. フィールドグループのアーキテクチャをレビューする

   • ロケーションルール、命名規則、説明、条件付きロジック、デフォルト値、必須フラグを調べます。
   • フィールドグループが巨大な一枚岩にならず、編集作業ごとに分割されているか確認します。
   • リピーターやフレキシブルコンテンツが、エンティティ設計の不足を補うためではなく、意図的に使われていることを確認します。

4. 重大なパターンを探す

   • 移行手段がないままフィールド名やデータ構造が変更されている。
   • 環境固有のフィールドキーにコードから直接依存している。
   • リレーショナルまたはタクソノミーとして扱うべきコンテンツが、単なるテキストの塊として保存されている。
   • 緩和策がないまま、主要なアーカイブ／検索の動作が大規模な meta_query への依存に偏っている。
   • 明らかに別個のエンティティが必要な箇所で、フレキシブルコンテンツやリピーターの構造が使われている。
   • オプションページの値を、キャッシュや無効化への配慮なくリクエスト固有のコンテンツとして扱っている。

5. 警告すべきパターンを確認する

   • ドメインの接頭辞や文脈がなく、意味が曖昧なフィールド名（title、image、link）。
   • 環境間で重複したフィールドグループや複製された定義に差異が生じている。
   • リレーションシップ／投稿オブジェクトフィールドで、返却形式に一貫性がない。
   • 説明やデフォルト値がなく、条件付きロジックも不明瞭なまま、編集者にフィールドが公開されている。
   • ACF JSONが一貫性なく有効化されている、または確実にコミットされていない。
   • リピーターを多用したランディングページが、クエリ、再利用、移行を困難にする可能性が高い。

6. 改善案を記録する

   • タクソノミーを使うと、絞り込み、SEO、編集の一貫性が向上する可能性がある。
   • オプションページを使うと、ページごとに重複した設定を置き換えられる可能性がある。
   • 大量の構造化データには、カスタムテーブルが適切な場合がある。
   • 共有コンポーネントには、クローンフィールドや再利用可能なブロック戦略が有効な場合がある。
   • フィールドの説明、タブ、グループを使うと、編集者のエラー率を下げられる可能性がある。

7. 状況に応じた重大度で報告する

   • エンタープライズ／編集サイト：ガバナンス、移行の安全性、クエリの動作、コンテンツ作成の使いやすさを優先します。
   • マーケティング／ランディングページビルダー：抽象的な純粋さより、保守性と編集上の制約を優先します。
   • ヘッドレスサイト：スキーマの安定性、APIへの公開形式、リレーションシップのモデル化を優先します。
   • 指摘事項への対応後に wp-rest-api-development、wp-performance-review、wp-block-development を実施すべき場合は、関連スキルについての注記を追加します。

モデルレベルのチェック

コンテンツタイプの設計（ACF-01）

重大

• type、layout、kind などのフラグですべてを処理し、複数の無関係なビジネス概念を1つのCPTに押し込んでいる
• 既存のコンテンツタイプに属するフィールドをグループ化するためだけにCPTが存在している
• 重要なリレーショナルコンテンツが、構造化されたエンティティではなく、シリアライズされた配列や長いテキストフィールドに保存されている

警告

• CPTのラベル、サポート対象、またはアーカイブの動作が編集上の意図に合っていない
• コアのタイトル／スラッグが担うべき役割を、投稿タイプが主要なタイトルやスラッグ用のカスタムフィールドに依存している
• コンテンツの見つけやすさが、タクソノミーや日付の意味付けではなく、カスタムソート／メタに完全に依存している

情報

• 別の真偽値／選択フィールドを追加するより、タクソノミーのほうが適切な場合がある
• 小規模な再利用可能投稿タイプを使うと、繰り返し使うセクションのコンテンツや共有ランディングページの断片を簡素化できる場合がある

タクソノミーの設計（ACF-02）

重大

• タクソノミーに適した分類を自由入力フィールドとしてモデル化しているため、表記ゆれが重複し、フィルターが正しく機能しません
• 関係性の意味をタームやリレーションシップフィールドではなく、繰り返し使用されるテキストフィールドや選択フィールドに押し込んでいます

警告

• オーディエンス、トピック、場所、ワークフローの状態を1つの構造に混在させるなど、タクソノミーの範囲が広すぎます
• フラットなタグ付けのほうがシンプルな場面で階層型タクソノミーを使用している、またはその逆です
• 独立したエンティティにすべきと思われる中核的なエンティティのコンテンツに、タームメタデータを追加しています

情報

• タクソノミーを使うことで、エディターが入力する不安定なラベルを置き換え、クエリのしやすさを改善できる場合がよくあります

フィールドの命名とスキーマの安定性（ACF-03）

重大

• 必要がないのに、コードが安定したフィールド名ではなく field_123abc のようなフィールドキーに依存しています
• 移行や後方互換性への対応なしに、フィールド名を変更しています
• コンテキストの異なる無関係な2つのフィールドに、ほぼ同じ名前を付けているため、テンプレートが混乱します

警告

• 名前が汎用的すぎる（title、cta、copy、image など）ため、1つのテンプレート以外では意味が伝わりません
• ドメイン間でプレフィックスの付け方が一貫していません（hero_、event_、team_ が予測不能に混在しています）
• 同じ概念のフィールドでも、フィールドグループ間で戻り値の形式が気付かないうちに異なっています

情報

• 関連するフィールドにドメインまたはコンポーネントごとのプレフィックスを付けると、grep での検索が容易になり、将来の移行にも役立ちます

リピーターとフレキシブルコンテンツの使用（ACF-04）

重大

• ガバナンスなしに、テスト不可能なコンテンツの組み合わせを生み出す完全なサイトビルダーとして、フレキシブルコンテンツを使用しています
• 独立した URL、再利用、所有権、またはフィルタリングが必要なデータをリピーターに格納しています
• 巨大な入れ子のリピーターを、リレーショナルテーブルのようにクエリまたは変換しています

警告

• リピーターの行に最小数・最大数の制限や、編集者向けのガイダンスがありません
• フレキシブルコンテンツのレイアウトが大きく重複しており、デザインシステムの規律が不足しています
• 入れ子が深いため、移行、プレビュー、テンプレートの保守が脆弱になっています

情報

• 再利用可能な構造には、専用エンティティ、同期パターン、またはブロックベースの構成を検討してください

リレーションシップフィールドと戻り値の形式（ACF-05）

重大

• 安定した想定戻り値の形式をコードで定めずに、リレーションシップ／投稿オブジェクトフィールドを使用しています
• 双方向リレーションシップが維持されていないにもかかわらず、維持されているものと仮定しています

警告

• 値を一度正規化できる場面で、テンプレートがループ内で get_field() を繰り返し呼び出しています
• リレーションシップフィールドのクエリが制約されていないため、編集者による選択が煩雑で、エラーも起きやすくなっています
• コードパスごとに ID、オブジェクト、配列を無造作に混在させています

情報

• テンプレートの繰り返しが増えてきたら、ビューモデルヘルパーや DTO に似たマッパーを通じてフィールドへのアクセスを正規化してください

オプションページとグローバル設定（ACF-06）

重大

• 頻繁に変更されるリクエスト単位のコンテンツをグローバルに保存し、ページ、ユーザー、コンテキストごとに変わることが期待されています
• 重要な実行時設定を、検証やデプロイの規律なしに ACF オプションから編集しています

警告

• サイト全体で使用するコンテンツをオプション／グローバルエンティティに集約せず、ページごとに重複させています
• オプションページの1画面に、マーケティング用コピー、連携用シークレット、編集者向け設定が混在しています
• コードがオプションは常に存在すると仮定し、空の場合のデフォルト値を処理していません

情報

• オプションページを責務ごとに分割し、堅牢性を高めるデフォルト値や説明を追加してください

ACF JSON と環境間の同期（ACF-07）

重大

• コミット済み JSON やエクスポート手段がなく、フィールドグループの変更がデータベース内にしか存在しません
• 同期の方向が不明確なため、チームのワークフローでフィールド定義が頻繁に上書きされます

警告

• acf-json のコミットに一貫性がない、または一部しかコミットされていません
• フィールドグループを本番環境で編集しているものの、変更を反映する手順がありません
• ローカル JSON のパス設定が環境間で異なりますが、ドキュメントに記載されていません

情報

• acf-json をバージョン管理下に置き、データベースのみでの編集はエクスポートするまで一時的なものとして扱ってください

メタクエリとストレージのパフォーマンス（ACF-08）

重大

• 大規模サイトでは、主要なアーカイブ／検索の動作が、インデックス未設定の複数の meta_query 句に依存しています
• ビジネス上重要なビューでは、リピーター／フレキシブルコンテンツの値を LIKE クエリで検索しています
• 数値／日付の絞り込みに、文字列比較のセマンティクスや一貫性のない保存形式が使われています

警告

• コンテンツモデリングにより、リクエストごとに postmeta への多数の結合が発生しています
• ネストされた ACF データから派生値／集計値がページ読み込みのたびに再計算されています
• 管理画面の UI が便利だからという理由で、ACF フィールドへのクエリが低コストだと想定しています

情報

• 必要に応じて、高頻度でクエリされるキーをタクソノミー、専用のルックアップテーブル、または事前計算済みインデックスに移行します

レビューのヒューリスティクス

ACF の優れた兆候

• フィールドグループが明確な編集作業やコンポーネントに沿っています
• CPT とタクソノミーが実際のビジネスエンティティを表しています
• 名前が安定しており、内容が明確で、ドメインの接頭辞が付いています
• ACF JSON がコミットされ、環境間の同期が意図的に行われています
• リレーションシップフィールドと返却形式がコード内で正規化されています
• メタの使用方法が、サイトの規模とクエリパターンに対応しています

よくあるアンチパターン

• 「あらゆるものを、いつまでもフレキシブルコンテンツ付きのページにする」
• 「タクソノミーや専用エンティティにすべきものも含め、すべてを投稿メタにする」
• 制約や安全なデフォルトを設けずに「編集者が何でも作れる」ようにする
• 「リピーターの内部データを直接クエリする」
• 「フィールド名を変更しても、テンプレートはそのまま動くだろうと期待する」

出力形式

次の構造を使用してください。

# ACF / Content Modeling Review

## Summary
- Scope: plugin/theme/app reviewed
- Modeling maturity: strong / mixed / fragile
- Primary risks: 2-5 bullets

## Critical Findings
- [ACF-XX] Title — file:line or subsystem
  Why it matters
  Recommended fix

## Warning Findings
- [ACF-XX] Title — file:line or subsystem
  Why it matters
  Recommended fix

## Info / Improvement Opportunities
- [ACF-XX] Title — file:line or subsystem
  Suggested improvement

## Modeling Notes
- Entity design observations
- Taxonomy vs meta observations
- Query/storage implications

## Cross-Skill Follow-Up
- Run `/wp-perf-review` if query behavior is the main risk
- Run `/wp-rest-review` if schema exposure or API contracts need review
- Run `/wp-block-review` if field groups power custom blocks heavily

参照ファイル

必要に応じて、以下のファイルのみを読み込みます。

• references/content-modeling-guide.md
• references/acf-json-and-field-group-guide.md
• references/meta-query-and-performance.md

最後に

このスキルでは、管理画面で動作するというだけで ACF の使用を高く評価しないでください。サイトのコンテンツ、編集者、連携先が倍増しても、理解しやすさを保てるモデルを優先してください。