Mitasu for Home — AI操作ガイド（AIエージェント向け仕様書）

バージョン 2026-08-24（アプリ実装と同期・自動テストで整合性を検証） 使い方: この文書全体を、Shopify Admin API に接続できるAIアシスタント （Claude + Shopifyコネクタ、Claude Code + Shopify MCP、カスタムエージェント等）に 貼り付けてから、商品情報の登録・割り当てを依頼してください。 English version: https://mitasu.tech/ai/home-agent-guide.en.md

このアプリのデータはすべてShopifyのメタフィールド／メタオブジェクトに保存されます （外部DBなし・namespace は全て home_info）。Admin GraphQL を使えるAIエージェントは、 アプリ管理画面を介さずにテンプレート作成と商品への割り当てを実行できます。

⛔ 最優先の禁止事項 — ストアの商品そのものには絶対に触らない

このガイドが許可する書き込みは、次の2種類だけです。

1. home_info メタオブジェクト（テンプレート）の作成・更新
2. 商品への home_info メタフィールドの書き込み（許可キーのみ・後述）

それ以外のストアデータは、読み取り専用として扱ってください。いかなる理由があっても 変更・作成・削除をしてはいけません。

メタフィールドの書き込みに productUpdate を使わないでください。 必ず metafieldsSet を使います。productUpdate は商品リソース本体を書き換えるミューテーション であり、指定しなかったフィールドを意図せず変更してしまう事故が起きます。

アプリ自身もこの規則で動いています。 Mitasu for Home のコードには productCreate / productUpdate / productDelete の呼び出しが1つも存在しません （書き込みは metafieldsSet と metaobject* のみ）。エージェントがそれを超えて操作すると、 アプリの想定外の状態になるだけでなく、ストアの売上に直結するデータを壊します。

迷ったら実行しないこと。 「寸法シートを整えるついでに商品説明も直す」「重複していそうな 商品を消す」「画像の順番を入れ替える」といった作業は、たとえ依頼されてもこのガイドの 範囲外です。ストアオーナーに Shopify 管理画面またはアプリの画面で行うよう案内してください。

最も安全なのは次章の CSV 経路です。 CSV 取り込みはアプリが処理するため、 商品本体を書き換える手段がそもそも存在しません。

最重要: 2つの安全な経路

1. 【最も安全・推奨】CSV経路 — アプリの「CSV書き出し」→ AIが列を埋める → 「CSV取り込み」（Pro）。名前参照・検証・上限クランプがアプリ側で全部かかる。 列: title, handle, dimension_sheet, material_profile, sets, room_scenes, faq, assembly_template, delivery_template, cleaning_code, rub_count, comfort_hint （参照はテンプレート名、Q&Aは質問文で指定。複数は | 区切り。 空欄の列は変更されない。cleaning_code / rub_count は割り当て済み 素材プロファイルへの商品ごと上書き、comfort_hint は firm / soft （硬め / 柔らかめ でも可）で商品ごとの座り心地の目安。いずれもアプリが 検証したうえで安全に反映する）。
2. 【上級】GraphQL直書き — 本書のスキーマに厳密に従うこと。テンプレート （メタオブジェクト）の作成 + 商品への参照割り当てのみ行い、それ以外のキーには 書かない。

絶対ルール（違反するとストア表示・アプリ管理画面が壊れます）

1. 寸法は cm のみで保存（inch は保存しない。表示時にアプリが換算）。重量は kg。
2. 書き込みは「テンプレート作成」と「参照(ref)の割り当て」だけ。 商品ごとの上書き・パッチキー — dimension_override / clearance_note_text / material_override / room_scene_overrides / set_overrides / faq_overrides / assembly_info / delivery_note / delivery_note_text — と、アプリ管理の集計・内部値 — comfort_feedback / return_stats / returns_baseline / review_pending / insights_cache / installed_at / plan / plan_kind / plan_cancel_at / plan_period_end — には絶対に書かない。*_override 系はオーナー自身の商品ごと微調整の置き場 なので、必要ならアプリの上書きUIを案内すること。 読み取りたい場合の置き場所（2026-08 に移設済み）: comfort_feedback は $app:votes、return_stats / returns_baseline / review_pending は $app:internal、plan は AppInstallation のアプリデータメタフィールドにあり、 home_info を探しても見つからない。 dimension_override には2つの形がある。 rows を持つものは寸法シート全体の スナップショット（＝その商品はもうシートを見ていない）。row_labels （[{from, to?}]）は行マップで、その商品が売っている行と呼び名だけを持ち、 数値はシートを見続ける。どちらも書き込み禁止だが、「この商品が売っているサイズ だけ表示したい」と頼まれたら、商品編集の「この商品で表示するサイズ」、または 「まとめて反映」の一括設定を案内すること。
3. Shopify標準属性をアプリ側namespaceに複製しない。 素材・色・柄などは Shopify標準のカテゴリーメタフィールド（商品ページで入力）をアプリが 特徴タブに自動表示する。アプリの素材・仕上げプロファイルは、標準属性で 表せないもの（部位別素材・お手入れ・かたさ・耐荷重）の置き場。
4. 割り当て上限: セット set_refs ≤ 4 / 部屋置き実例 room_scene_refs ≤ 4 / Q&A faq_items ≤ 10。セット1件内の商品 items ≤ 6。
5. 作成前に同名テンプレートの有無を必ず検索（重複作成しない）。 テンプレートの削除はアプリUIからのみ（直接deleteすると割り当て・上書きの 後始末が行われない）。
6. 破壊的変更（既存refの差し替え・大量更新）の前に現在値を読み、ユーザーに確認する。
7. metafieldsSet は1回 ≤ 25件。書き込み後は userErrors を必ず確認。

データモデル（テンプレート参照 + 商品ごと上書き）

テンプレート = メタオブジェクト（7種・再利用可能）

home_info_dimension_sheet（寸法シート — 主力機能）

カテゴリー別の寸法キー（これ以外は表示されない）:

home_info_material_profile（素材・仕上げ）

home_info_room_scene（部屋置き実例 — Pro）: name（必須）/ room_type （living / dining / bedroom / kids / office / outdoor …）/ room_size_m2 / photo（写真URL文字列）/ note

home_info_set（セット「部屋を完成させる」 — Pro）: name（必須）/ items （list.product_reference — 商品GID・≤ 6）/ note / image（file_reference — FilesのGID。無ければ省略）

home_info_faq（Q&A 1組）: question（必須）/ answer（必須）

home_info_assembly（組立情報）

home_info_delivery（配送情報 — 表示専用。アプリは注文・送料・配送APIには 一切触れない）

商品メタフィールド（割り当て — 書き込み可能なのはこの8つだけ）

バリアントメタフィールド（書き込み可）

dimension_sheet_ref / material_profile_ref のみ（例: 「ワイド」バリアントに 別シート、革/布バリアントに別プロファイル）。サイズ違いは通常1枚のシートの 行として持つ — そちらを優先。

ストア設定（SHOP所有）— 変更はオーナーにアプリの設定画面を案内

feature_flags（セクションON/OFF）/ section_order / section_titles / default_unit（cm|inch・編集画面のみ）/ week_start（mon|sun）。読み取りは可。

お手入れコード（home_info_material_profile.care 用）

推奨ワークフロー（商品分析 → テンプレート作成 → 割り当て）

1. 商品を読む — タイトル・説明・タイプ・タグ・標準カテゴリーから家具カテゴリー、 サイズ展開、素材を分類する。
2. 既存テンプレートを先に検索 — metaobjects(type: "...", first: 250) で 名前を確認。合うものは再利用する。
3. 足りないテンプレートだけ作成 — 上記スキーマに厳密に従う（特に cm 保存と packaged の梱包箱。梱包箱が無いと搬入チェックが点灯しない）。
4. 割り当て — metafieldsSet で ref を書く（リスト値は "[\"gid://...\"]" の ようなJSON文字列）。または CSVを生成してオーナーに取り込んでもらう （最も安全な経路）。
5. 確認 — アプリの「商品編集」画面の登録済みマークをオーナーに確認してもらう。

GraphQL 例

寸法シートの作成（梱包箱つき）

mutation {
  metaobjectCreate(metaobject: {
    type: "home_info_dimension_sheet",
    fields: [
      { key: "name", value: "ファブリックソファ 2/3人掛け" },
      { key: "category", value: "sofa" },
      { key: "rows", value: "[{\"size_label\":\"2人掛け\",\"measurements\":{\"width_cm\":150,\"depth_cm\":85,\"height_cm\":80,\"seat_height_cm\":42}},{\"size_label\":\"3人掛け\",\"measurements\":{\"width_cm\":190,\"depth_cm\":85,\"height_cm\":80,\"seat_height_cm\":42}}]" },
      { key: "packaged", value: "[{\"size_label\":\"2人掛け\",\"w_cm\":155,\"d_cm\":90,\"h_cm\":75,\"weight_kg\":38}]" },
      { key: "clearance_note", value: "脚は取り外し可能（高さ-11cm）。階段搬入時に有効。" }
    ]
  }) { metaobject { id } userErrors { field message } }
}

商品への割り当て（シート + 素材 + 組立 + Q&A）

mutation {
  metafieldsSet(metafields: [
    { ownerId: "gid://shopify/Product/123", namespace: "home_info", key: "dimension_sheet_ref",
      type: "metaobject_reference", value: "gid://shopify/Metaobject/456" },
    { ownerId: "gid://shopify/Product/123", namespace: "home_info", key: "material_profile_ref",
      type: "metaobject_reference", value: "gid://shopify/Metaobject/789" },
    { ownerId: "gid://shopify/Product/123", namespace: "home_info", key: "assembly_ref",
      type: "metaobject_reference", value: "gid://shopify/Metaobject/321" },
    { ownerId: "gid://shopify/Product/123", namespace: "home_info", key: "faq_items",
      type: "list.metaobject_reference", value: "[\"gid://shopify/Metaobject/111\",\"gid://shopify/Metaobject/222\"]" }
  ]) { metafields { key } userErrors { field message } }
}

既存テンプレートの一覧（重複チェック / 割り当て用GID取得）

{ metaobjects(type: "home_info_dimension_sheet", first: 250) {
    nodes { id field(key: "name") { value } }
    pageInfo { hasNextPage endCursor } } }

トラブルシューティング

• UNDEFINED_OBJECT_TYPE / 定義エラー → オーナーに「設定 → 再チェック」を実行 してもらう（定義は自己修復する）。
• 割り当てたのに店頭に出ない → 順に確認: ① Freeプランなのに Pro 機能 （部屋置き実例／セット／実感投票／実感まとめは Pro）ではないか ② 設定でセクションがOFFになっていないか ③ テーマにアプリブロックが 設置されているか。
• 搬入チェックが出ない → 割り当てたシートに packaged の梱包箱が無いか、 全箱が基準のドア幅を通るため安心の1行表示に切り替わっている（仕様）。基準幅は 設定で選べる（既定 70cm・ほかに 76 / 80 / 90cm）。
• 上限を超えた ref は表示されない — リストは上限内に収めること。