Ti Reference

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 が返す（本文には焼き込まない）。

前提

• そのセッションで最初に TI のスキルを使うときは、依頼の内容を問わず ti-core references/version-freshness.md を読み、同梱の版と公開されている最新版を照合する（1 セッション 1 回。古ければ本題の前に 1 行告げ、そのうえで本題は進める）
• 標準（ホステッド）Salesforce MCPが接続済みであること（接続手順はSalesforce標準MCPサーバー接続ガイド）
• Tsubaiso Atlas MCPが接続済みであること（意味・ルール・レシピの配信元。参照系4ツール atlas_domain_index／atlas_explain／atlas_recipe／atlas_drift_check、および作成・更新タスク時の書込前ゲート atlas_write_seam。利用可否はPSA契約のエンタイトルメントで判定され、失効時はツール応答が403になる）
• Tsubaiso Knowledge MCPが接続済みであること（製品の仕様・操作手順の配信元。Atlasと同じ組織公開コネクタの形で提供される）
• 利用組織にPSA（必要に応じてIMA）パッケージが導入済みであること
• 参照（SOQL集計・リンク化）が主用途。加えて、作成・更新タスクでは §書込タスクの手順（作成・更新）に従い、書込レシピと書込前ゲートの両方を引いてから書く

製品の仕様・操作手順に触れるとき [REQUIRED]

本スキルの守備範囲は「データが業務的に何を意味するか」までで、「どう操作するか・その挙動は仕様か」は入っていない。 次のどれかに手をかけた瞬間に、ti-core references/knowledge-lookup.md を読み、その作法でナレッジを引く。

1. 製品そのもの（Apexクラス・フロー・トリガ・項目ヘルプ・パッケージのメタデータ）を読もうとした
2. 可否・手順・理由を答える文を書こうとした（利用者へ出す選択肢・作業計画の前提に仕様を置こうとしたときを含む）
3. 実測した値が期待と違い、「不具合」「障害」「バグ」と書こうとした
4. 作業の対象範囲を自分で数え上げようとした

describe による構造の解決と atlas_explain が返す自動化・入力規則の読み取りは 1 に含まない（下記 §参照タスクの手順 の正規の経路）。含むのは、そこで取れたものを材料にして、ナレッジへ当たらないまま手順・可否・理由の文を書こうとしたときである。

not_found はナレッジへ移る合図ではない。 §業務プロセスの図・順番を描くとき のとおり「引き方を間違えた」の第一シグナルなので、まず指し先の名前で引き直す。

出力規律（最上位原則）

正本は ti-core references/output-discipline.md §業務言語だけで書く。本スキルへ書き写さない [REQUIRED]。 同じ規律を複数の場所に分けると、弱いほうが使われる。利用者へ見せる説明文を書く直前に同 reference を読む。要点だけ言えば、説明文には業務言語だけを使い、API名・内部項目名・レコードId・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（配信中の意味定義版）が入る。版ズレ・欠落は §鮮度・ドリフト検知 で扱う。

業務プロセスの図・順番を描くとき [REQUIRED]

上の手順は「値を引く」射程で、レコードができる順番（書込側のフロー）は入っていない。 業務プロセスフロー図・データのつながり図・業務モデル図を描く直前、および投入・移行の順序を組む直前は、次の手順で正準シーケンスを取る。本節がこの手順の正本で、他スキルからは参照で受ける。

1. atlas_domain_index のレシピ索引で、業務プロセス一巡の正準シーケンスにあたるレシピを特定する。索引から特定できないときは atlas_recipe の task（自然文）で「業務プロセス一巡の正準シーケンス」と引く。
2. 返ってきたシーケンスは、各工程の作り方を別のレシピ名で指している。必要な工程（制作原価の積み上げ・自動作成チェーン・在庫の変動 等）は、その指し先を name で引く。自分で自然文を組み立て直さない（近い言い回しでも not_found が返り、「無い」と誤って断定する経路になる）。
3. レシピ名を本文に焼き込まない。名前は索引と返り値から実行時に解決する。

順序を記憶や受領資料の日付順で振らない。 順番の誤りは図としても投入計画としても成立してしまい、落とした形跡が残らないため、提示先で指摘されるか投入が失敗するまで検知できない。引けなかったときは順番を断定せず、引けなかったことを明示して人に確かめる。

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・レコード参照のリンク化）

正本は ti-core references/output-discipline.md §レコードのリンク化。対象・書式・組織のホスト名の解決手順・省いてよい場面は同 reference が持ち、本スキルへ書き写さない [REQUIRED]。 リンク化はクエリ結果の返却時だけでなく、承認待ちの点検結果・突合結果・調査報告などレコードを利用者へ示すあらゆる出力で効くため、規律の実体を参照系のスキルの中に置かない（置くと参照系が読み込まれない場面で規律に到達できない）。

本スキル側で守るのは、その規律を成立させるためのクエリ側の条件だけ＝レコードを列挙するクエリでは、リンク化する参照のIdをSELECTに必ず含める（規約8と対）。

書込タスクの手順（作成・更新）

作成・更新のタスクも、参照タスクと同じ順序を持つ。書込前ゲートだけを引いて判断しない。ゲートが返すのは「直接作ってよいか」で、「どこから作り始めるのが正規経路か」は書込レシピが持つ。片方だけを見ると、作れないと誤って断じるか、正規でない経路で作るかのどちらかに倒れる。

1. atlas_domain_index（地図） — 対象オブジェクトと、書込レシピがあるかを索引で確認する。
2. 書込レシピを引く — あれば atlas_recipe で取得し、経路を確定する（どの工程を直接作り、どこから先が自動生成か。上流のどのレコードから作り始めるか）。
3. 書込前ゲートを引く — 下記 §書込前ゲート に従い atlas_write_seam を引く。
4. 構造補完（describe） — 型・ラベル・実行時の関係名を解決する。項目API名はここで確定する。
5. 実行と突合 — 「フラグ→保存→読み戻し→差分UPDATE→突合」で書き、結果を入力元と突き合わせる。

レシピ名の読み方

レシピ名には用途を表すブロックが入る。索引から目的のレシピを引き当てるときに使う。

書込タスクで参照系だけを見て「作り方が無い」と判断しない。 索引には作り方を持つレシピが別の表記で並んでいる。

ゲートとレシピが食い違ったら、どちらも採らない [REQUIRED]

同じ操作について、ゲートが「機能経由でのみ作れる」と返し、レシピが「直接作るのが正規経路」と書いている（またはその逆）ことがある。このとき、もっともらしい方を選んで進めない。 どちらが誤っているかは応答からは判定できず、誤った側を採ると、画面経由と同等でないレコードを組織へ作り、下流の集計まで巻き込む。

1. その対象への書込を保留する（読み取りは続けてよい）。
2. 食い違いの内容（対象・操作・ゲートの返り・レシピの記述）を利用者へ伝える。
3. ti-core references/feedback.md でツバイソへ知らせる（意味定義側の是正は全接続先へクライアント無操作で反映される）。

「レシピ優先」と順位を固定しない。 レシピ側が誤っていることもあり、順位を決め打ちすると誤りをそのまま実行する経路になる。

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

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名>) を引く。ローカルに同梱していた意味定義・構造スナップショットは除去済みで、配布物の同梱はゼロ。atlas_write_seam 未接続・403 時は書込を保留する（references/write-index.md §可用性と保留規律）。

鮮度・ドリフト検知

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

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

authored/ の使い分け

• 組織固有の定番クエリ・注意書き・項目の意味補足は authored/ にMarkdownで追記する（ファイル名は自由）。データ参照タスクでは atlas_explain／atlas_recipe に加えて authored/ 配下も読む（READMEのみで追記がない場合はスキップしてよい）
• 意味定義の本体（意味・ルール・レシピ）はAtlas MCPが一元配信するため、本スキルは読み取り用の事前生成マップを同梱しない。書込前ゲートも Atlas MCP atlas_write_seam が判定するため、意味定義・構造スナップショットの同梱はゼロで、本スキルに同梱スクリプトは無い

変更履歴

• v12.5.0: 書込タスクの手順を、参照タスクと同じ粒度で追加。従来は作成・更新の案内が書込前ゲートの1段落だけで、書込レシピを引く順序が無かったため、ゲートの返りだけを見て「直接は作れない」と断じ、同じ配信元が持つ作り方のレシピを引かないまま結論を出す経路が残っていた。あわせて (1) レシピ名の用途ブロックの読み方（参照系だけを見て作り方が無いと判断しない）(2) ゲートとレシピが同じ操作について反対のことを言ったときは、どちらも採らず書込を保留してツバイソへ知らせる規律を加えた。優先順位を固定しない理由は、レシピ側が誤っていることもあり、決め打ちすると誤りをそのまま実行する経路になるため。
• v12.4.0: 製品の仕様・操作手順に触れるときの発火点を §前提 に追加。本スキルの守備範囲は「データが業務的に何を意味するか」までで、「どう操作するか・その挙動は仕様か」は入っていない。境界を越える瞬間（製品そのものを読もうとした／可否・手順・理由を書こうとした／不具合と書こうとした／対象範囲を自分で数え上げようとした）を行動で判定できる4つに切り出し、ti-core references/knowledge-lookup.md へ渡す。describe と atlas_explain が返す自動化・入力規則の読み取りは除外（参照タスクの正規の経路であり、除外しないと参照タスクのたびに発火する）。あわせて not_found がナレッジへ移る合図ではないことを明示し、§業務プロセスの図・順番を描くとき の定義（引き方を間違えた第一シグナル）と食い違わないようにした。§前提 に Tsubaiso Knowledge MCP の接続を追加。
• v12.3.0: 業務プロセスの図・順番を描くときの手順を追加。参照タスクの手順は「値を引く」射程で書かれており、レコードができる順番（書込側のフロー）が入っていなかった。図を描く直前に正準シーケンスを引くことを [REQUIRED] にし、順序を記憶や受領資料の日付順で振らない規律を加えた。順番の誤りは図として成立してしまい落とした形跡も残らないため、提示先で指摘されるまで検知できないことを理由として明記した。
• v12.2.2: §出力規約 のリンクホスト解決手順を、実際に動く手順へ是正。旧記述は {instance} を「getUserInfo 等」で解決するとしていたが、getUserInfo はインスタンスURLも My Domain も返さないためホストが解決できず、必須であるリンク付与が実行できない状態だった。一次手段を Domain の照会に置き換え、Organization も代替にならないことを明示した。**採り方は「先頭ラベル」ではなく「末尾の既定形（.my.site.com / .my.salesforce-sites.com）だけを取り除いた残り全体」**とする。区画（sandbox・開発組織等）では既定形の手前に区画のラベルが入り、最初の . で切ると解決しないホストになるため。区画種別を列挙して分岐する形は将来増える区画に追従できないので採らない。あわせて Experience Cloud サイトのドメインが Lightning のホストとは別物である点、独自ブランドのCNAME行は My Domain 名を含まないため使えない点を注記し、解決不能時の退避規律（推測でホスト名を組み立てない／リンクを省いた旨を利用者に伝える）を加えた。
• v12.2.1: §SOQL実行規約 1 の限定を冒頭に移し、規約全体が「パッケージが定義したカスタムコンポーネント」に掛かることを最初の一文で明示した（直後の但し書きとセットで読まないと全項目に接頭辞が付くと読めてしまうため）。あわせて {名前空間}__{ローカル名}__r の合成規則がカスタム参照項目にのみ成立し、標準参照（OwnerId → Owner 等）には及ばないことを明記した。
• 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 の実行時判定へ切り替え。ローカルに同梱していた意味定義・構造スナップショットを除去し、配布物の同梱をゼロにした。ゲートは対象のAPI名を渡すと、作れない工程・自動作成シームの両方向・参照先の有効条件を返す。全件の一覧は提供しない。サーバー可用性に依存するため、未接続・権限失効時は書込を保留する規律を明記した（読み取りと同じ扱い）。
• v12.0.0: 読み取りの本体を Tsubaiso Atlas MCPサーバーへ移行。意味・ルール・定番レシピを atlas_domain_index／atlas_explain／atlas_recipe から実行時に取得する薄いクライアントへ再構成し、同梱していた意味定義への依存を廃止した。ドリフト検知を atlas_drift_check に一本化。書込前ゲートは構造由来のため本スキルに残置。Atlas MCP 未接続・権限失効時の参照保留規律を §参照タスクの手順 に明記した。
• v11系: 参照マップの網羅拡張（売上・調達・制作・在庫・マスタ・勤怠の各プロセスと入力規則）・書込前構造ゲートの整備・スキル名の ti-reference への整理。