---
name: ti-reference
description: 'ツバイソPSA/IMA（Salesforce）の業務データを参照・集計するときに使う。経費・売上（見積〜受注〜納品〜売上〜請求〜入金消込〜手形電債〜EC連携）・調達（発注〜検収〜仕入経費〜支払・発注EC/仕入先EC）・制作（制作指図〜工数〜原価計算票・進行基準）・管理会計・案件・返品・与信・契約・勤怠・マスタ（通貨/為替/銀行/社員/人件費レート/価格表）・在庫（IMA 倉庫/棚/ロット/受払/月次）・財務記録（汎用仕訳・会計連携）・管理会計2への計上連携のデータを、標準Salesforce MCPで取得するためのスキル。意味・ルール・定番SOQLレシピは Tsubaiso Atlas MCPサーバー（atlas_domain_index／atlas_explain／atlas_recipe）から実行時に取得し、構造（型・ラベル・関係）は利用組織のdescribeで補完する。PSA/IMAのオブジェクトや項目を探すとき、SOQLを組み立てるとき、結果をリンク付きで返すときに必ず読む。出力は業務言語のみとし、API名・内部項目名は説明文に出さない。'
version: 12.2.1
updated: 2026-07-31
---

# ti-reference — PSA/IMA参照の知識層（Tsubaiso Atlas MCP クライアント）

ツバイソPSA/IMA（Salesforceマネージドパッケージ）のデータを、Claudeがその場の探索なしで正しく参照・集計するための知識層スキル。**意味・ルール・定番レシピの本体は Tsubaiso Atlas MCPサーバー**が実行時に配信し（`atlas_domain_index`／`atlas_explain`／`atlas_recipe`）、**構造（型・ラベル・関係）は利用組織の describe**で補完する。本スキルは薄いクライアントとして両者（意味＝Atlas MCP／データ＝顧客の標準Salesforce MCP）を結線し、正しく参照・集計する実行の型と出力規律を提供する。

対応ドメイン（Atlasが現在配信中のドメイン群）: 経費／売上（見積〜受注〜納品〜売上、債権債務＝請求〜入金消込・手形電債・請求かがみ・得意先EC、与信・契約・商談明細）／案件（横断ハブ・案件メンバー）／マスタ／調達（発注〜検収〜仕入経費〜支払、発注EC・支払かがみ・仕入先EC）／管理会計／制作（制作指図〜工数〜原価計算票・進行基準）／在庫（IMA・導入済org限定）／財務記録（汎用仕訳・会計連携・月次締処理）／返品（PSA 6.0以降）／勤怠。ドメイン・オブジェクト・レシピの最新一覧は `atlas_domain_index` が返す（本文には焼き込まない）。

## 前提

- 標準（ホステッド）Salesforce MCPが接続済みであること（接続手順はツバイソヘルプ記事「Claude/Cursor Salesforce標準MCP接続ガイド」、記事ID 58638669783065）
- **Tsubaiso Atlas MCPが接続済みであること**（意味・ルール・レシピの配信元。参照系4ツール `atlas_domain_index`／`atlas_explain`／`atlas_recipe`／`atlas_drift_check`、および作成・更新タスク時の書込前ゲート `atlas_write_seam`。利用可否はPSA契約のエンタイトルメントで判定され、失効時はツール応答が403になる）
- 利用組織にPSA（必要に応じてIMA）パッケージが導入済みであること
- 参照（SOQL集計・リンク化）が主用途。加えて、作成・更新タスクでは書く前に §書込前ゲート（作成・更新時の必須手順）を実行する

## 出力規律（最上位原則）

本スキルの全出力に効く最上位原則。利用者（業務ユーザー）に見せる説明文では業務言語だけを使う。

- API名・内部項目名・レコードId・SOQL は説明文に出さない。**名前空間接頭辞の有無、省略形とフル形の別に関わらず対象**（標準項目・顧客組織が追加した項目も含む）。これらは内部の結合キー・クエリ生成にのみ使う
- 項目を言及するときは Atlas の業務的意味（`atlas_explain` の `meaning`）に翻訳して呼ぶ（例: 内部の粗利率項目→「粗利率」、未確定フラグ→「明細が未確定」）
- 後述の §出力規約（ID・レコード参照のリンク化）とは住み分ける: レコードへの**クリックできるリンク**は出してよい（原本を開く導線）。出さないのは説明文中の**生のAPI名・内部項目名・SOQL**

## 参照タスクの手順（Atlas MCP → Salesforce MCP）

データ参照・集計タスクでは必ずこの順で進める。

1. **`atlas_domain_index`（地図）** — ドメイン一覧・オブジェクト索引・レシピ索引を取得し、どのオブジェクト／どのレシピを使うかを決める。
2. **レシピ優先** — 該当レシピがあれば **`atlas_recipe`**（`name` か `task`自然文のどちらか）で完成SOQLを取得し、プレースホルダ（`{userId}` 等）を充当して使う。絞り込み条件は依頼内容に応じて追加・削除してよい（例: 全社集計ならOwnerId条件を外す、年指定なら日付範囲を足す）。該当レシピが無ければ **`atlas_explain`**（`target`＝対象API名）で意味・ルール・項目・関係（親パス／子サブクエリ）・自動化(behavior)・入力規則(VR)を取得しSOQLを組む。
3. **構造補完（describe）** — 標準Salesforce MCPの `getObjectSchema` で型・ラベル・実行時の関係名を解決する。**型・ラベルはAtlasが返さずクライアントが構造から補完する**（2-MCPモデル）。
4. **実行と返却** — SOQLを標準Salesforce MCPで実行し、結果を §出力規約 に従いリンク化して返す。

全ツール応答に `semantics_version`（配信中の意味定義版）が入る。版ズレ・欠落は §鮮度・ドリフト検知 で扱う。

**Atlas MCP が未接続・403（エンタイトルメント失効）で応答しないときは、推測で SOQL を組まない。** v12 から読み取りの意味・ルール・レシピはサーバー可用性に依存する。取得できない場合は、利用者に Atlas MCP の接続状態と PSA 契約の有効性の確認を促し、意味・ルールが取れない状態での参照実行は保留する（構造だけの describe で当て推量しない）。

## SOQL実行規約

1. PSA/IMA の**パッケージが定義したカスタムコンポーネント**は、オブジェクト・項目のAPI名を名前空間込みのフル形 `{名前空間}__{ローカル名}__c` で書き、省略形を使わない。**カスタム参照項目**の親を辿るときは同じローカル名の `{名前空間}__{ローカル名}__r` になる（この合成規則はカスタム参照項目にのみ成立し、標準参照〔`OwnerId` → `Owner`、`CreatedById` → `CreatedBy` 等〕には及ばない）
   - 接頭辞が付くのは**パッケージが定義したカスタムコンポーネント**だけ。標準項目（`Id`／`Name`／`OwnerId`／`CreatedDate` 等）と顧客組織が追加した項目には付かない。無い接頭辞を足すと `INVALID_FIELD` になる
   - どちらの接頭辞が付くかは**そのコンポーネントを定義したパッケージ**で決まり、**オブジェクトの所属では決まらない**。IMA 導入時に PSA のオブジェクトへ後付けされる項目・入力規則が実在するため、同一オブジェクト上に両パッケージ定義のコンポーネントが混在する。ローカル名の命名も一律ではないので、接頭辞から先を推測しない
   - したがって**実際のAPI名は必ず配信・実組織から取る**。オブジェクト名は `atlas_domain_index`／`atlas_explain`、項目名・関係名は describe、レシピがあるときは `atlas_recipe` が返す完成SOQLをそのまま使う（この規約は書式の規律であって、名前の出所ではない）
2. 集計はサーバ側GROUP BYで行う（明細を取得してクライアント集計しない）
3. 項目エイリアスは集計クエリ限定。非集計SELECTでリレーション項目にエイリアスを付けると `MALFORMED_QUERY` になる
4. 子サブクエリのrelationshipNameは `getObjectSchema` の childRelationships の実行時名を使う（メタデータ上の名前と実行時名は名前空間付与で異なる）
5. 金額の既定は税込。税抜は明示指定時のみ（管理会計2のmeasureは例外で税抜＝財管一致）
6. 集計の既定は全件。承認状態での絞り込みは明示指定時のみ
7. ドメイン固有の規則（消込の判定項目・予実の集計区分・進行基準の進捗率・返品の方向判定等）は `atlas_explain` の `rule`・各項目の `meaning`/`rule`、`atlas_recipe` の `notes` が正。規約5・6と異なる記述があればそちらを優先する
8. レコードを列挙するクエリでは、リンク化対象の参照のIdをSELECTに必ず含める（§出力規約）

## 出力規約（ID・レコード参照のリンク化）

クエリ結果を提示・返却するとき、クリックでSalesforce原本レコードを開けるようリンクを付与する。原則は「**開ける対象（レコード）＝リンク、測る値・分類値＝そのまま**」。

- **リンク化する（必須）**: (1) 行そのもののレコードId、(2) ナビ可能な参照（取引先・案件・受注・請求・発注・納品・売上・制作指図・調達・返品申請 等の開けるレコード）。表示名があれば名前をリンクテキストにし、無ければIdをリンクテキストにする
- **リンク化しない**: 金額・数量・日付・割合・集計結果の数値、選択リスト/ステータス/区分・コード値、参照でない単なるテキスト
- **書式**: `https://{instance}.lightning.force.com/lightning/r/{Id}/view`（オブジェクト名不要）。`{instance}` は実行時に一度解決（`getUserInfo` 等）してセッション内でキャッシュ
- **集計（GROUP BY）クエリ**: 行Idが無いため軸の値は直接リンク不可。ドリルダウン導線（該当条件の明細クエリ、またはリスト/レポートへのリンク）を併記する
- **レシピ規約への含意**: レコード列挙クエリでは、リンク化する参照は**SELECTにIdを必ず含める**（規約8と対）

## 書込前ゲート（作成・更新時の必須手順）

PSA/IMAオブジェクトを**作成・更新する前に必ず** `references/write-index.md`（発火点）を読み、対象API名でゲート（`function_only` 判定・参照先の有効条件・auto_create シームの両方向）を引く。PSA/IMAは「源オブジェクトで意図フラグを立てて保存すると自動起動フロー・Apexトリガが下流レコードを整合性付きで生成する」設計のため、**子・下流レコードを直接INSERTすると二重計上・整合崩れになる**。引いた結果に従い「フラグ→保存→読み戻し→差分UPDATE→突合」で書く。

**この書込前構造ゲートの実体は Tsubaiso Atlas MCP の `atlas_write_seam` ツール**（v12.1.0 で移送完了）。書込スキル（ti-data-load／ti-update／ti-metadata）は本ゲートを参照ファイル `references/write-index.md` 経由で呼び、write-index.md が `atlas_write_seam(target=<API名>)` を引く。旧 P0 のローカル実体（`scripts/atlas_write_index.py` ＋意味定義スナップショット `semantics_v38.json`）は v12.1.0 で除去し、配布物を意味定義・構造スナップショット同梱ゼロにした。`atlas_write_seam` 未接続・403 時は書込を保留する（`references/write-index.md §可用性と保留規律`）。

## 鮮度・ドリフト検知

`atlas_drift_check` に組織構造のAPI名集合（オブジェクト/項目のAPI名のみ・業務値は送らない）を渡し、配信中の意味定義版と組織構造の版ズレ・欠落を検知する。

| 契機 | 動作 |
|---|---|
| PSA/IMAパッケージのバージョンアップ後 | `atlas_drift_check` を実行し欠落・版差分を確認 |
| レシピ実行で `INVALID_FIELD`／`INVALID_TYPE` に遭遇 | ドリフトのシグナル。`atlas_drift_check` で確認し、未収録なら §authored/ に注釈、意味定義の追加が要る場合はツバイソへ連絡 |
| 定期（目安は四半期） | 鮮度維持 |

意味定義そのものの更新はツバイソがAtlasサーバー側で行い、全接続先へクライアント無操作で反映される（次回のツール呼出しで新版が返る）。

## authored/ の使い分け

- 組織固有の定番クエリ・注意書き・項目の意味補足は `authored/` にMarkdownで追記する（ファイル名は自由）。データ参照タスクでは `atlas_explain`／`atlas_recipe` に加えて `authored/` 配下も読む（READMEのみで追記がない場合はスキップしてよい）
- 意味定義の本体（意味・ルール・レシピ）はAtlas MCPが一元配信するため、本スキルは読み取り用の事前生成マップを同梱しない（`generated/` 3層マップと、読み取り経路での意味定義ミラー依存は廃止＝v12.0.0）。書込前ゲートも v12.1.0 で Atlas MCP `atlas_write_seam` へ移送し、同梱していた意味定義スナップショット（`scripts/semantics_v38.json`）とローカルスクリプト（`scripts/atlas_write_index.py`）を除去した（配布物 同梱ゼロ化）。これで本スキルの `scripts/` 同梱物はなくなった

## 変更履歴

- v12.2.1: §SOQL実行規約 1 の限定を冒頭に移し、規約全体が「パッケージが定義したカスタムコンポーネント」に掛かることを最初の一文で明示した（直後の但し書きとセットで読まないと全項目に接頭辞が付くと読めてしまうため）。あわせて `{名前空間}__{ローカル名}__r` の合成規則がカスタム参照項目にのみ成立し、標準参照（`OwnerId` → `Owner` 等）には及ばないことを明記した（!50 レビューの軽微指摘2点）。
- v12.2.0: **API名の名前空間規約を是正・拡充**。§SOQL実行規約 1 は PSA/IMA 双方を対象と言いながら PSA の接頭辞だけを前提にした記述で、IMA が漏れていた。あわせて 3 点の欠落を補った。(1) 接頭辞が付くのはパッケージが定義したカスタムコンポーネントだけで、標準項目と顧客組織が追加した項目には付かない（無い接頭辞を足すと `INVALID_FIELD` になる）。(2) どちらの接頭辞が付くかは定義したパッケージで決まり、オブジェクトの所属では決まらない（IMA 導入時に PSA のオブジェクトへ後付けされる項目・入力規則が実在し、同一オブジェクト上に両パッケージ定義が混在する）。ローカル名の命名も一律でないため接頭辞から先を推測しない。(3) 親参照の `__r` 形の合成規則を明示し、API名の出所を `atlas_domain_index`／`atlas_explain`／describe／`atlas_recipe` の完成SOQLに明確化した。書式はプレースホルダ表記（`{名前空間}__{ローカル名}__c`）で示し、実際の接頭辞は配信・実組織から取る形にした（配布物に名前空間付きAPI名の完全形を焼き込まない方針と整合）。§出力規律も「接頭辞の有無・省略形とフル形の別に関わらず出さない」と射程を明示し、書き換えで禁止範囲が狭まらないようにした。
- v12.1.0: **書込前ゲートの実体を Tsubaiso Atlas MCP `atlas_write_seam` へ移送（薄化第二弾・同梱ゼロ化）**。同梱していた意味定義スナップショット `scripts/semantics_v38.json` とローカルスクリプト `scripts/atlas_write_index.py` を除去し、配布物を意味定義・構造スナップショット同梱ゼロにした。`references/write-index.md` を `atlas_write_seam(target=<API名>)` 呼出し型へ書換（応答＝`function_only`／`auto_create_as_source`／`auto_create_as_target`／`reference_filters`／`semantics_version`・`source_sha`）。旧 P0 で未実装だった `function_only` 検出・C5 参照フィルタが本ツールで実装済みとなりゲート網羅が向上。全件一覧（旧 `--list`）は抽出防御で非提供。サーバー可用性依存の追加に伴い「未接続・403 時は書込保留」規律を明記（読み取り経路と同一 regime）。波及して ti-update／ti-data-load の「実体＝`atlas_write_index.py`」参照を「実体＝Atlas MCP `atlas_write_seam`」へ更新。
- v12.0.0: **読み取りの本体を Tsubaiso Atlas MCPサーバーへ移行**。意味・ルール・定番レシピを `atlas_domain_index`／`atlas_explain`／`atlas_recipe` から実行時取得する薄いクライアントへ再構成した。同梱していた意味定義ミラー・マップ生成器・事前生成3層マップへの読み取り依存を廃止し、意味定義はAtlasが一元配信する。ドリフト検知を `atlas_drift_check` に一本化。書込前ゲート（`references/write-index.md`）は構造由来のため本スキルに残置（体系設計 §8.2）。レビュー反映として、Atlas MCP 未接続・403 時の参照保留規律を §参照タスクの手順 に明記し、`references/write-index.md §要点` に arm（生成機構）種別の圧縮定義と「✅ シームなし」の保証限界を保持した。
- v11系: 参照マップの網羅拡張（売上・調達・制作・在庫・マスタ・勤怠の各プロセスと入力規則）・書込前構造ゲートの整備・スキル名の ti-reference への整理。