What is DevOps Center Testing?

Testing in DevOps Center brings together Salesforce tools like Code Analyzer, Apex unit tests, and flow tests (with other Salesforce tools and partner tools from ACCELQ, Copado, Panaya, Provar, Quality Clouds, and Tricentis coming soon). You can run everything from static code analysis to full regression tests within a single workflow.

DevOps Center Testing is the single source of truth for test definitions and test results, where you can define your test strategy across multiple tools, run tests automatically, and enforce quality gates to keep only high-quality changes moving forward.

This means that your teams are empowered to find issues earlier in the development process and fix them well before any bugs make their way to production, where they are expensive to fix. You’ll be able to comprehensively test Apex and flow actions thanks to Code Analyzer v5 and integration with Apex unit tests and flow tests.

The cost of the late-stage testing bottleneck

“Shifting left” is the practice of moving testing, quality checks, and compliance validation as early in the development lifecycle as possible. Catching a bug in a developer sandbox takes minutes to fix. Catching that same bug in production can cost days of downtime and thousands of dollars in remediation.

Achieving a true shift-left workflow on Salesforce historically required complex CI/CD orchestration, external script maintenance, and heavy third-party syncing tools. DevOps Center eliminates this operational overhead by bringing automated quality frameworks natively on the platform where your metadata and code already live.

Quality gates: automated pipeline governance

Running tests automatically is only half the battle; the real magic happens when you use those tests to enforce governance. A quality gate is an automated checkpoint in a CI/CD pipeline that evaluates code against predefined criteria, blocking substandard software from advancing or deploying until it meets the required thresholds. Automated quality gates are now directly part of the pipeline workflow in DevOps Center. Instead of relying on manual checklists or human oversight to approve a pipeline promotion, you can define strict criteria for specific pipeline stages, such as on pull request creation or pre-promotion.

Imagine a developer attempting to promote a work item. Behind the scenes, DevOps Center automatically triggers the assigned Apex, Flow, and Code Analyzer test suites. If an Apex test fails, code coverage drops below your organization’s threshold, or Code Analyzer flags a critical security vulnerability, the pipeline automatically halts. The promotion is blocked, and the developer receives immediate, line-level feedback right inside their work item. The bug is isolated and fixed instantly, keeping the main release branch completely clean.

Test providers in native platform automation

DevOps Center Testing unifies execution and reporting for your most critical internal test providers right out of the box. From a single centralized hub, you can easily orchestrate a comprehensive testing matrix across programmatic and declarative elements.

• Apex tests: Automatically execute unit tests and track code coverage percentages to ensure backend programmatic logic is thoroughly vetted early.
• Flow tests: Natively execute declarative flow test cases to verify that your automated business logic behaves precisely as intended before promotion.
• Salesforce Code Analyzer: Catch security vulnerabilities, detect anti-patterns, and evaluate technical debt before code review even begins by running multi-engine static code analysis including PMD, ESLint, and Flow Scanner.

Agentic era: skills for DevOps Center Testing

While manual and programmatic gate configuration offers incredible safety, managing a matrix of dozens of test suites, mapping coverage gaps, and diagnosing complex failures can become a full-time task. To simplify this complexity, we have also released Skills for Testing within Agentforce Vibes.

Four new Agentforce skills bring AI-assisted test management directly into your DevOps Center workflow, from configuring providers and quality gates to running suites, analyzing failures, and tracking fixes.

These skills combine to act as an autonomous copilot for your release operations, allowing DevOps Center Testing managers to control the lifecycle through natural language interaction:

• dx-devops-test-pipeline-configure
  What it does: Configures test providers, syncs new suites into a pipeline, and assigns quality gates with pass-rate, severity, and essential-test rules to test suites on a pipeline stage. Instead of manually mapping criteria across complex tables, managers can instruct the agent to align the gate logic automatically.
• dx-devops-test-suite-assignments-configure
  What it does: Recommends and manages DevOps Center test suite assignments for pipeline stages. Use this skill to recommend suites for a commit, assign or map suites to stages, or add/remove tests in a suite.
• dx-devops-test-suite-run
  What it does: Triggers test suite execution on a specific pipeline stage, polls for results, and can automatically re-run a quality gate check after a developer resolves their code coverage gaps. This keeps the deployment train moving efficiently with automated validation loopbacks.
• dx-devops-test-failures-analyze
  What it does: Analyzes DevOps Center test failures and Code Analyzer violations in plain language, failure category, offending file/class/method/line, rule violated, fix direction, and prioritized improvement suggestions (test-code vs production-code), then optionally creates a tracked fix WorkItem on explicit request.

How to get started

You can bring automated quality to your release management workflow in a few quick steps:

1. Locate the Tests tab: The automated testing feature is available within the DevOps Center application. Admins can open their DevOps Center pipeline to find the new native Tests management interface.
2. Add test providers: Configure one or more of the available test providers: Apex, Flow, and Code Analyzer.
3. Configure your quality gates: Define your testing thresholds. Decide which pipeline stages require mandatory Apex test passes, flow validations, or Code Analyzer scans.
4. Automate and scale: Review the developer reference documentation to connect your CLI scripts, repository webhooks, or Agentforce toolsets to the Headless 360 API.

By automating your testing lifecycle natively within DevOps Center and pairing it with Agentforce, you eliminate release anxiety, secure your digital supply chain, and empower your teams to ship high-quality features faster and smarter than ever before.

Conclusion

DevOps Center Testing now enforces Apex, Flow, and Code Analyzer checks at each pipeline stage, and you can trigger the same gates from your existing CI tools via the CLI or REST API.

Resources

• Testing User Guide
• Release Notes
• Object References
• Code Analyzer 
• DevOps Center Trailblazer Group
• DX Inspector Documentation
• Salesforce CLI Reference
• Next Generation DevOps Center documentation

About the Author

Srikrishna Padmannagari is a Senior Product Manager at Salesforce, where he builds tools that simplify ALM for the global developer community. He leads product for Salesforce DX Inspector, Testing, Code Analyzer focusing on making the Salesforce DX ecosystem more efficient, reliable, and developer-friendly. Follow Srikrishna on LinkedIn.

The post Shift Left Natively: Testing and Quality Gates in DevOps Center appeared first on Salesforce Developers Blog.

※本記事は2026年5月14日に米国で公開された The New Agentforce Metadata and Development Lifecycleの抄訳です。本記事の正式言語は英語であり、その内容および解釈については英語が優先されます。

新しいAgentforce Builder（Spring ’26正式リリース）では、AIエージェントの作成とテストのエクスペリエンスが刷新されます。スピーディで「失敗しても安全」な環境が提供され、試行錯誤しながら複雑なロジックを改良できます。本番環境で稼働しているAIエージェントへの影響を心配する必要はありません。

Salesforce開発者の皆さんなら、構築エクスペリエンスが新しくなると、たいていは内部の仕組みも変わることをご存じでしょう。今回、このスピード感がある、安全な作業環境をサポートするために、基盤となるメタデータも進化させる必要がありました。この記事では、新しい開発者ワークフロー、メタデータが変更された理由、デプロイ用にパッケージを構成する方法について、順を追って説明します。

新しい開発ワークフロー – スクリプトからメタデータへ

メタデータの変更については、AIエージェント構築の新しい考え方を理解しておくとわかりやすくなるでしょう。新しいAgentforce Builderでは、開発者の「意図」（AIエージェントに実行させたいこと）と、エンジンの「実行」（有効なメタデータ）が明確に分離されます。

AIエージェントの作成から公開までは、次のような流れで進みます。

1. 記述と構築 – Agentforce BuilderのUIを使用するか、Agent Scriptを使って、AIエージェントを作成します。人間が読んで理解できるこのスクリプトは、AIエージェントの設定を示す単一の.agentファイルとして、新しいAiAuthoringBundleメタデータ型内に保存されます。この段階では、作業内容はドラフトの状態です。
2. 改良とプレビュー – プレビューモード（テストを組織のデータから安全に分離するシミュレーションモードなど）を使用して、ドラフトをテストします。
3. 公開 – ドラフトの内容で問題ないと判断したら、そのバージョンをコミットします。ここが非常に重要なポイントです。コミットの段階で初めて、プラットフォームは.agentスクリプトを、AIエージェントの実行に実際に使われる有効なBotメタデータとGenAiPlannerBundleメタデータに変換します。

メタデータ変更の理由 – ローカルアセットのバンドル化

新しいビルダーでGenAiPlannerBundleメタデータの構成を変更したのはなぜかというと、分離を確保し、デプロイの信頼性を高める必要があったからです。

これまで、Agentforceアセットはグローバルでした。あるAIエージェントのために共有サブエージェントを変更すると、それが全体に波及し、そのサブエージェントを使用しているすべてのエージェントに即座に影響していました。これを解決するために導入したのがローカルアセット（ローカルサブエージェントとローカルアクションを含む）です。ローカルアセットは、グローバルアセットを複製して作成され、特定のエージェントバージョンにひも付けられます。アセットがローカルになることで、他に影響を与えず安全に編集できます。

ローカルアセットは以前から利用可能でしたが、CI/CDパイプラインで完全にサポートするには、GenAiPlannerBundleメタデータを更新する必要がありました。これまで、エージェントメタデータは複数のメタデータ型に分散していました。新しいGenAiPlannerBundleで最も大きな変更は、「バンドル化」です。特定のバージョンに関連し、依存関係にあるすべてのエージェントアセットを、1つのフォルダー構造でデプロイして利用できるように、メタデータを再構成しました。これにより、デプロイエラーを防げるともに、エージェントがプレビュー時とまったく同じように動作するために必要なものを、すべて揃えられます。

内部の仕組み – 新しいメタデータ構造

従来のようにファイルが分散することなく、各エージェントバージョンに固有のすべての要素が、ディレクトリ構造の中にすっきりとまとめられています。

AiAuthoringBundleは、AIエージェントの設計時のアーティファクトをすべて含むディレクトリです。このバンドルでは、AgentName_1やAgentName_2のように複数のバージョン付きサブディレクトリを使用でき、それぞれが独自の.agentファイルと.bundle-meta.xml記述子を持ちます。これらのサブディレクトリは、AIエージェントのドラフトやコミット済みバージョンなど、異なるライフサイクル状態に対応します。各バージョンには、次のファイルが含まれます。

• .agentファイルには、Agent Scriptで記述されたAIエージェントの設定が保持されます。これには、名前、ラベル、説明、システム指示、サブエージェント定義、推論指示、変数、条件分岐、ツール/アクション参照が含まれます。
• メタデータ記述子（.bundle-meta.xml）は、bundleType（例：AGENT）と、その記述子が参照するエージェントバージョンを宣言します。

Botには、AIエージェントの種類や、プライベートデータをログに記録するかどうかといった設定など、AIエージェントのすべてのバージョンに共通する情報が含まれます。また、Botはエージェントレベルのコンテキスト変数も保持します。これは、各BotVersion内に存在する会話変数とは異なります。BotVersionの詳細には、会話変数、ウェルカムメッセージ、会話転送時のメッセージが含まれます。

GenAiPlannerBundleは、AIエージェントの公開済みバージョンごとに関連するデータをすべて保持します。各バージョンには、次の要素が含まれます。

• .genAiPlannerBundleは、AIエージェントの実行時設定（サブエージェント、指示、アクション、オーケストレーションロジック）を含む、中核となるメタデータファイルです。
• agentGraphは、サブエージェント間のすべての遷移と条件を記述した.jsonファイルです。
• agentScriptは、そのバージョンのAgent Scriptをエンコードしたコピーです。これは同期検出を目的として保持されるスナップショットです。このスナップショットにより、スクリプトが公開済みまたはコミット済みメタデータと同期していない場合に、Agentforce Builderがユーザーに通知できます。
• plannerActionsは、特定のサブエージェントにひも付かない、エージェントレベルのアクションです。
• localActionsは、サブエージェント単位でスコープが限定されたアクションで、それぞれのサブエージェントフォルダーの下にネストされます。input/schema.jsonファイルとoutput/schema.jsonファイルが、各アクションの型付きパラメーターを定義します。

注 – GenAiPlannerBundleのバージョンはコミットされた順に自動で番号が付けられるため、AiAuthoringBundleのバージョン番号と一致するとは限りません。

バージョンをコミットすると、BotメタデータとGenAiPlannerBundleメタデータはどちらも自動的に作成されます。また、AiAuthoringBundle、agentScript、agentGraphは、新しいAgentforce Builderで作成されたAIエージェントのメタデータにのみ含まれます。

GenAiPlannerBundle XMLの例

ローカル化されたサブエージェントとアクションをXMLの例で見てみましょう。

<GenAiPlannerBundle>
   <description>新しいAIエージェントの説明</description>
   <localTopicLinks>
       <genAiPluginName>Retrieve_data_from_the_Knowledge_Base_16jxx0000001234</genAiPluginName>
   </localTopicLinks>
   <localTopics>
       <fullName>Retrieve_data_from_the_Knowledge_Base_16jxx0000001234</fullName>
       <description>リトリーバーアクションを使用する</description>
       <pluginType>Topic</pluginType>
       <masterLabel>ナレッジベースからデータを取得</masterLabel>
       <genAiPluginInstructions>
           <description>あなたはAIエージェントです。</description>
           <sortOrder>1</sortOrder>
       </genAiPluginInstructions>
       <localActionLinks>
            <functionName>File_test_retriever_179xx0000001234</functionName>
       </localActionLinks>
       <localActions>
           <fullName>File_test_retriever_179xx0000001234</fullName>
           <invocationTarget>File_test_retriever_1234</invocationTarget>
           <invocationTargetType>apex:testRetriever</invocationTargetType>
           <source>File_test_retriever</source>
       </localActions>
   </localTopics>
   <plannerType>AiCopilot__ReAct</plannerType>
</GenAiPlannerBundle>

<localTopics>ブロックでは、サブエージェントのすべての設定を定義します。一意のAPI名、説明、プラグイン型、決定的な順序で並べられた指示、そのサブエージェントで利用可能なすべてのローカルアクションなどです。また、元のサブエージェントへのリファレンスが含まれる場合もあります。

<localActions>ブロックでは、アクション名、マスターラベル、呼び出し先とその種別を定義します。さらに、必要に応じて、クローン元のグローバルアクションへのsourceリファレンスを含める場合もあります。確認時の動作や読み込み中テキストの設定など、UX関連の追加設定が含まれる場合もあります。

新しいメタデータモデルに対応したpackage.xmlの例

新しいAgentforce Builderで構築したAIエージェントを正常に取得し、デプロイするには、package.xmlに新しいバンドル型を含める必要があります。以下は、Spring ’26のメタデータ構造を前提として作成されたマニフェストの例です。

<?xml version="1.0" encoding="UTF-8"?>
<Package xmlns="http://soap.sforce.com/2006/04/metadata">
    <types>
        <members>*</members>
        <name>GenAiFunction</name>
    </types>
    <types>
        <members>*</members>
        <name>Bot</name>
    </types>
    <types>
        <members>*</members>
        <name>GenAiPlannerBundle</name>
    </types>
    <types>
        <members>*</members>
        <name>GenAiPlugin</name>
    </types>
    <types>
        <members>*</members>
        <name>AiAuthoringBundle</name>
    </types>
    <version>66.0</version>
</Package>

注 – このマニフェストではAPIバージョン66.0を使用しています。この例のGenAiPlannerBundleと新しいエージェントメタデータ型をサポートするには、このバージョンが必要です。

新しいAgentforce Builderで開発するためのヒント

この新しいアーキテクチャーによって改善された開発ライフサイクルを活用する方法を、2つ紹介します。

• 人間が読めるスクリプトファイルを使って、コードレビューを効率化する。従来のAgentforce Builderでは、AIエージェントの変更をレビューするには、プルリクエスト内に分散した複雑なXMLファイルを見比べる必要がありました。新しいアーキテクチャーでは、人が読んで理解できる.agentスクリプトファイルを比較できます。これにより、ピアレビューが大幅にスピードアップし、内容も理解しやすくなります。
• AiAuthoringBundleを使用して、CI/CDをシンプルにする。ほとんどのパイプラインでは、ソース管理にAiAuthoringBundleを保持するだけで済みます。新しい組織でそのAIエージェントが必要になったら、デプロイし、バージョンをコミットして実行時メタデータを生成し、最後に有効化します。これは、次のコマンドを使用して自動的に実行できます。
  sf project deploy start --metadata AiAuthoringBundle --target-org my-org
sf agent publish authoring-bundle --api-name MyAuthoringBundle --target-org my-org

sf agent activate --api-name MyAuthoringBundle --version 2 --target-org my-org
  手動のステップを必要としない、完全に自動のパイプラインを構築したい場合は、AiAuthoringBundleとGenAiPlannerBundleの両方をソース管理に保持し、同時にデプロイすることで、コミット済みの状態にできます。システムは、デプロイされるスクリプトと事前に生成されたメタデータをあわせて認識します。手動のコミット手順がすべてにスキップされ、エージェントはデプロイ直後に稼働状態になります。
  sf project deploy start --metadata AiAuthoringBundle,GenAiPlannerBundle --target-org my-org

まとめ

新しいAgentforce Builderでは、メタデータ構造がバンドル化されたことで、影響範囲を分離し、バージョンを安全に維持しながらAIエージェントを作成できるようになりました。この構造により、メタデータが整理され、コードレビューが簡単になり、デプロイの信頼性も向上します。

さっそく、Agent Scriptと新しいAgentforce Builderを使ってみましょう。こちらのTrailheadモジュールでは、Agent Scriptを使用したエージェントの作成について学習できます。また、Agent Scriptの基本を解説したブログや、YouTubeのAgent Script Decodedシリーズ（英語）もご覧ください。Agentforce Builderのワークショップ（英語）も随時開催していますので、ぜひ参加してみてください。

関連情報

• リリースノート
  • エージェントのバージョン管理と編集
  • 改良されたエージェントバージョン機能を使用したエージェントのテストとカスタマイズ（英語）
• ヘルプドキュメント
  • 標準エージェントアクションの参照アクションの編集
• パッケージ
  • Agentforceメタデータコンポーネントのパッケージ化（英語）
  • スクラッチ組織を使用したAIエージェントテンプレートの開発とパッケージ化（英語）
• メタデータの更新
  • GenAiPlannerBundle
  • GenAiFunction
  • GenAiPlugin
  • GenAiPluginInstructionDef

Shreyasは、サンフランシスコのSalesforce AIでリードソフトウェアエンジニアを務めており、Institute of Analyticsのフェロー（FIoA）でもあります。Agentforce Core Platformチームの中心メンバーとして、AgentforceにエンタープライズレベルのALMを導入するため、Agentforceのバージョン管理システムとローカルアセット構成の変更を共同で設計し、主導しました。LinkedInのプロフィールはこちら。

Alba Rivasは、Salesforceのプリンシパルデベロッパーアドボケイトです。LinkedInのプロフィールはこちら。

The post 新しいAgentforceメタデータと開発ライフサイクル appeared first on Salesforce Developers Blog.

※本記事は2026年5月29日に米国で公開された Build a Salesforce Agent Skill with Claude Codeの抄訳です。本記事の正式言語は英語であり、その内容および解釈については英語が優先されます。

AIにコードを書かせるのは簡単です。とはいえ、セキュリティレビューに合格し、ガバナ制限を守り、指定したフレームワークに従い、静的解析でも高い評価を得られるコードを安定して生成させるとなると、そう簡単にはいきません。エージェントスキル（英語）を使えば、この問題を解決できます。エージェントスキルとは、開発チームが定義する「本番品質」を、エージェントが従い、検証ツールが強制できる形に落とし込んだ、構造化されたプロンプトパッケージです。LLMの出力には確率的なばらつきがあるため、どうしても例外的な結果が生じます。それを想定して検出するのが、このアーキテクチャーです。

この記事では、Apexを例に、Salesforceエージェントスキルの構造を詳しく見ていきます。わかりやすいように、Claude Codeを使って具体的な例を紹介しますが、ここで取り上げる原則はどのAIエージェントにも適用できます。エージェントスキルとは何か、プロジェクトの構造、最初のスキルの作成方法について、順を追って説明していきます。

エージェントスキルとは

エージェントスキルとは、Claudeを汎用的なアシスタントではなく、スペシャリストとして使えるようにするために構造化されたプロンプトパッケージです。スキルでは、モデルの学習データだけに頼るのではなく、明確に定義されたワークフロー、リファレンス、コードテンプレート、自動検証ツールを用意します。スキルが有効化されると、これらがコンテキストに読み込まれます。

Claudeの基盤である大規模言語モデル（LLM）は、Apex、LWC、SOQLといったSalesforceエコシステムのプログラミング言語をすでに習得しています。しかし、プログラミング言語を理解しているからといって、必ずしもベストプラクティスに沿った高品質なコードを安定して生成できるわけではありません。スキルは、これを可能にします。

各スキルは、次のような一定の構造を持つフォルダー内に配置されます。

skills/authoring-apex/
├── SKILL.md              # 実行ルール
├── references/           # デシジョンツリー、パターン、ガードレール
├── assets/               # サンプルコード
└── hooks/scripts/        # Python検証ツール

最低限必要なのは、SKILL.mdです。これは、スキルの有効化時にClaudeが最初に参照するファイルです。その他の要素は、スキルの成長に応じて追加する足場となります。まずはSKILL.mdと参照ドキュメントを1つずつ用意し、指示だけではなく、仕組みによってルールを徹底したい段階でフックを追加するとよいでしょう。

スキルは、フロントマターにもとづいて有効化されます。フロントマターは、Markdownファイルの先頭で区切り記号「---」の間に記述されるYAML形式のメタデータブロックです。フロントマターはコンテンツとして表示されず、機械が読み取れる設定情報として使用されます。フロントマターは、どのような場合にそのスキルを有効にするかをエージェントに示します。nameフィールドでスキルを識別し、descriptionフィールドには、現在のタスクにこのスキルが適しているかどうかを判断するためのトリガールールを記述します。

以下の例では、descriptionでTRIGGER when / DO NOT TRIGGER whenという構造を使用して、スキルを有効にする条件と有効にしない条件の両方をエージェントに示しています。有効化の条件だけをモデルに伝えると、「このSOQLはApexコードの作成作業としてApexスキルで扱うのか、それともSOQLスキルで扱うのか」といったあいまいさが生じ、誤ったスキルが有効化されることがあります。この形式を使えば、そうしたあいまいさを排除できます。

---
name: authoring-apex
description: >
  TRIGGER when: ユーザーがSalesforce Apexコードを作成、編集、またはレビューする場合 — 
  対象は、サービスクラス、セレクタークラス、
  トリガーハンドラー、テストクラス、バッチジョブ、Queueableクラス、
  呼び出し可能メソッド、Apex RESTエンドポイントを含む.clsファイルまたは.triggerファイル。
  DO NOT TRIGGER when: ユーザーがLWC JavaScript、Flow XML、
  単独のSOQLクエリーを扱う場合、または既存のテストを実行する場合。
---

この例は簡略化されたもので、実際には、descriptionにはもっと包括的な情報を記述します。すべてのクラス種別（Schedulable、AuraEnabled、HttpCalloutMock）を列挙し、除外するケースごとに、どのスキルが処理するかを明記します（LWC JavaScriptには「authoring-lwcを使用」など）。境界を具体的に定義するほど、誤ったスキルの有効化を減らせます。

条件に一致するタスクが検出されると、ClaudeはSKILL.mdを読み込み、ワークフローに従います。プロンプトで/skill-nameを指定して、スキルを手動で有効化することもできます。どちらの場合も、ワークフロー、リファレンス、テンプレートを含むスキルのコンテキスト全体が自動的に組み込まれます。SKILL.mdの内容を会話に貼り付ける必要はありません。

スキルの形式自体（フロントマターを含むSKILL.md、リファレンス、アセット）は、AnthropicがApache 2.0の下で管理しているオープン仕様（英語）で、コミュニティも開発に参加できます。作成したSKILL.md、リファレンス、テンプレートは、別の環境でも利用できます。フックの仕組み（PostToolUseライフサイクルイベントを含むhooks.yaml）はClaude Code固有のものです。別のエージェントランタイムを使用する場合は、検証を別の方法で組み込むことになりますが、スキルの内容はそのまま移行できます。そのため、スキルは特定の実行環境に依存しない、いわばヘッドレスなものになります。Agentforce Vibes、Claude Code、Cursor、Visual Studio Code、Gemini CLI、OpenAI Codex、Windsurf、Roo Code、Gooseのほか、このオープン仕様をサポートする30以上のエージェントで使用できます。

エージェントスキルの構造

SKILL.md – 実行ルール

スキルを使用する際に従う重要なワークフローです。手順は変更できず、各フェーズには厳格な終了条件が設定されています。以下に、その構造を示す簡略化した例を紹介します。実際のSKILL.md（英語）では各フェーズをさらに詳しく記述しますが、終了条件を伴うフェーズを順番に並べるという構造は同じです。

このワークフローを順番どおりに実行してください。ステップの省略、結合、順序変更は禁止します。
行き詰まった場合は停止し、不足しているコンテキストを確認してください。該当なしの場合は、
レポートで「N/A」と記載し、その理由を1行で示してください。

## 必須の入力

作成に入る前に、以下を収集または推測する：

- クラス種別（サービス、セレクター、バッチ、Queueable、Invocable、トリガーハンドラー）
- 対象となるオブジェクトとビジネス目標
- デフォルトの共有設定（理由がある場合を除き`with sharing`）
- すでに使用中のトリガーフレームワーク（または明示的に選択されたもの）

フェーズの構成:

### フェーズ1 — 作成
1. **プロジェクト規約を確認する** — 既存のパターン、トリガー
     フレームワーク、命名スタイルを調べる
2. **要件を満たす最小のパターンを選択する**:

  | 要件                  | パターン                              |
  | ------------------ | -------------------------------------- |
  | ビジネスロジック       | サービスクラス                          |
  | データアクセス         | セレクタークラス                        |
  | トリガーロジック        | トリガーハンドラー（フレームワークが必要）　|
  | Flowとの連携        | @InvocableMethod                       |
  | 一括処理             | Batch Apex                            |
  | 非同期処理          | Queueable                               |

3. 作成に入る前に、`assets/`内の**対応するテンプレートを確認する**
4. **ガードレールに従って作成する** — 以下の「ルール」セクションにあるすべてのルールを適用する
5. **テストクラスを生成する** — テストスキルに委任する

### フェーズ2 — 検証

6. **Code Analyzerを実行する** — すべてのブロッキング違反を修正し、クリーンになるまで再実行する
7. **テストを実行する** — 合否とコードカバー率を記録する

### フェーズ3 — レポート

8. **報告する** — ファイル、設計上の判断、アナライザー出力、テスト結果、デプロイメモ

フェーズが適用されない場合、ClaudeはそのフェーズをN/Aとして記録し、理由を記す必要があります。これは、「順序や完全性が重要な場合は、番号付きリストを使って、指示を連続したステップとして示す」というAnthropicのベストプラクティスに対応しています。

references/: ナレッジライブラリ

referencesは、一般的な学習では一貫した対処ができない、特定の失敗モードに対処するための参照ドキュメントです。つい情報を詰め込んでしまいがちなので、以下にAnthropicのベストプラクティスをいくつか示します。

authoring-apexスキルでは、どのような参照ファイルを含めるとよいかを見てみましょう。

このようなリファレンスの構成は、Anthropicが言う「指示の背景にある文脈と動機を提供する」という方法を活用したものです。単に「何をすべきか」だけを示すのではなく、「なぜそうするのか」も説明することで、Claudeが機械的にパターンマッチングするのではなく、未知の状況にも正しく応用できるようにします。

anti-patterns.mdの例を見てみましょう。この構造は、繰り返し問題が起きやすいプラクティスを対象に設計されています。すべてのセクションで同じBAD/GOOD形式を使用しています。Claudeが個別のミスを認識し、回避できるようにするためです。アンチパターンの詳細については、こちらのドキュメントをご覧ください。

# Apexのアンチパターン

## 目次

- [ループ内SOQL](#soql-in-loops)
- 

---

## ループ内SOQL
**アンチパターン:** `for`ループまたは`while`ループ内でSOQLクエリーを実行すること。

**失敗する理由:** Salesforceには、1つの同期トランザクションで実行できるSOQLクエリーは
100件までという厳格な制限があります。トリガーは最大200件のレコードをまとめて処理するため、
ループ内でSOQLを1回実行すると、100件を処理しただけで上限に達します。

```apex
// BAD: 1回の反復につきSOQLを1回実行。レコード101件目で100クエリー制限を超過する。
for (Account acc : accounts) {
    List contacts = [SELECT Id FROM Contact WHERE AccountId = :acc.Id];
}

修正方法: クエリーは一括で1回だけ実行し、取得した結果を反復処理します。

// GOOD: SOQLの実行は全体で1回。
Map contactsByAccount = new Map();
for (Contact c : [SELECT Id, AccountId FROM Contact WHERE AccountId IN :accountIds]) {
    ...
}
// Salesforce Well-Architectedのアンチパターンに合わせて、他の項目を追加します。

トランザクションセキュリティポリシーのような特殊なケースでは、この構造に沿ってMarkdownを作成し、通常のルールがどれも当てはまらない特定のApex機能を1つ扱うことができます。このMarkdownでは、通常のルールが当てはまらないのはどのような場合か、代わりに何をすべきか、なぜそうするのかをClaudeに教える必要があります。BAD/GOODのペアはありません。この文脈では、「悪い」コード（例：global without sharing）が実際には正しいコードだからです。この例では、assetsフォルダーにある実例を参照していることに注意してください。

# トランザクションセキュリティポリシー（Apex条件）

## 目次

- [概要](#overview)
- [クラスの形式](#class-shape)
- [共有設定](#sharing)
- [ガードレール](#guardrails)
- [例](#example)

---

## 概要

条件ビルダーでは不十分な場合、拡張トランザクションセキュリティポリシーはApexを呼び出します。
`TxnSecurity.EventCondition`を実装し、単一の
`evaluate(SObject event)`メソッドを定義します。

## クラスの形式

- クラスは**`global`**として宣言する（［設定］で選択できるようにするために必須）
- `TxnSecurity.EventCondition`を実装する
- シグネチャ: `global Boolean evaluate(SObject event)`

## 共有設定

これらのクラスは、ユーザー向けのコントローラーでは**ありません**。`without sharing`を使用します。
`with sharing`をデフォルトとする通常のルールはここでは適用されません。
適用すると、エラーが明示されないまま、ポリシーが正しく機能しなくなります。

## ガードレール

- 一括SOQLクエリーは最大1つとする（ループ内でSOQLは実行しない。ガバナ制限は引き続き適用される）
- トランザクションをブロックする場合は`true`、許可する場合は`false`を返す

## 例

`assets/transaction-security-policy.cls`を参照してください。

assets/：具体例によるfew-shot

Anthropicは、Claudeの出力形式、トーン、構造を方向づける最も信頼性の高い方法の1つに、few-shotとして機能する例の使用を挙げています。few-shotとは、テンプレートとして使える良い例をいくつか提示するといった意味です。各テンプレートには、必須要件として、ApexDocコメント、バルク対応のロジック、明示的なsharing宣言、CRUD/FLSの適用、テストを容易にするための依存性の注入が組み込まれています。Claudeはテンプレートをもとにコードを作成する際に、テンプレートの構造からこれらの要件を引き継ぎます。学習済みの知識から引き出す必要はありません。

Apexには幅広い可能性がありますが、ここでは有効なユースケースをいくつか掘り下げてみましょう。

各テンプレートは、単に「特定のクラスをどう書くか」を示すものではありません。必須要件を構造に組み込んだ、事前に用意されたfew-shot例です。

hooks.yamlと検証スクリプト：セーフティネット

フックは、ライフサイクルの特定のタイミングでClaude Codeが自動実行するシェルコマンドです。フックはhooks.yamlで設定します。スクリプトは、そのコマンドが実行するものです。一般的には、ツールの入出力を検査して構造化されたフィードバックを返す、Pythonの検証スクリプトです。

フックによって、人が介入しなくてもフィードバックループが完結します。Claudeがコードなどを生成すると、フックがすぐにそれを評価し、その結果をClaudeが同じ会話ターンの中で受け取ります。Claudeが問題全体を把握している状態のまま、その文脈内で修正が行われます。

hooksファイルは、検証スクリプトが適切なタイミングで実行されるように設定します。たとえば、ユーザーがプロンプトを送信したタイミングで、事前チェックが実行されます。

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 ${CLAUDE_SKILL_DIR}/hooks/scripts/preflight-apex-check.py",
            "timeout": 10000
          }
        ]
      }
    ]
  }
}

また、ファイルの書き込みまたは編集が行われるたびに、PostToolUseフックが実行されます。

---
name: authoring-apex
description: ...
hooks:
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "python3 ${CLAUDE_SKILL_DIR}/hooks/scripts/preflight-apex-check.py"
          timeout: 90000
---

Claude Codeは、フックのコンテキストをJSON形式で標準入力（stdin）に渡します。ペイロードの構造はライフサイクルイベントによって異なります。PostToolUseにはツール名、入力パラメーター、出力が含まれ、UserPromptSubmitにはユーザーのプロンプトテキストが含まれます。

開発チーム向けの事前チェックを例に考えてみましょう。SKILL.mdのワークフローでは、検証フェーズで「Code Analyzerを実行する」と指示しています。しかし、Code Analyzerがインストールされていなかったり、バージョンが誤っていたりすると、どうなるでしょうか。フックがない場合、Claudeはワークフローの途中でコマンドを実行しようとしてエラーを受け取ります。開発者はエラーの原因がプラグインの不足にあることを突き止めなければなりません。フックを設定しておけば、Apex関連の作業が始まった時点でチェックが実行されます。

import json, subprocess, sys

MINIMUM_VERSION = "5.5.0"

def parse_version(v):
    """バージョン文字列を比較可能なタプルに変換します。"""
    return tuple(int(x) for x in v.split(".")[:3])

def main():
    hook_input = json.load(sys.stdin)
    prompt = hook_input.get("prompt", "").lower()

    # Apex関連の作業である可能性が高い場合のみチェックする
    apex_keywords = ["apex", ".cls", "class", "trigger", "service", "selector", "batch"]
    if not any(kw in prompt for kw in apex_keywords):
        sys.exit(0)

    try:
        result = subprocess.run(
            ["sf", "plugins", "--json"],
            capture_output=True, text=True, timeout=15
        )
        if result.returncode == 0:
            plugins = json.loads(result.stdout)
            for plugin in plugins:
                if plugin.get("name") == "@salesforce/plugin-code-analyzer":
                    version = plugin.get("version", "0.0.0")
                    if parse_version(version) >= parse_version(MINIMUM_VERSION):
                        sys.exit(0)
                    else:
                        print("=== 事前チェック ===")
                        print(f"  [警告] Code Analyzer {version} は、最低対応バージョンである {MINIMUM_VERSION} を満たしていません。")
                        print(f"  インストール: sf plugins install @salesforce/plugin-code-analyzer@latest")
                        sys.exit(0)
    except (FileNotFoundError, subprocess.TimeoutExpired, json.JSONDecodeError):
        pass

    print("=== 事前チェック ===")
    print("  [警告] Salesforce Code Analyzerがインストールされていません。")
    print("  authoring-apex skillでは、検証のためにSalesforce Code Analyzerが必要です。")
    print("  インストール: sf plugins install @salesforce/plugin-code-analyzer")
    sys.exit(0)

if __name__ == "__main__":
    main()

開発者は、ツールチェーンに不足があることを事前に発見できるので、ワークフローの途中で検証フェーズが失敗してから気づくという事態を避けられます。

指示とフックの違いはここにあります。SKILL.mdには、「検証フェーズでCode Analyzerを実行する」と書かれています。フックは、ワークフローが始まる前にCode Analyzerを実行できることを確認します。指示は望ましい動作を示すものであり、フックは機械的に実行されるものです。この両方が必要です。

エージェントスキルには、なぜ人間と機械の両方による検証が必要になるのか

スキルはすべてを解決する切り札ではありません。スキルによってClaudeの出力のばらつきはかなり小さくできますが、それでもClaudeは本質的に非決定論的なシステムです。ここで問題になるのは、次の2点です。

動作を完全に指定することはできない。SKILL.mdがどれほど正確であっても、実際の要件にはテンプレートやリファレンスではカバーしきれない、新しい組み合わせが含まれます。それでもClaudeは判断を下さなければなりません。新しいモデルほどプロンプトを文字どおりに解釈するため、記述が少し足りないだけでも結果にばらつきが出ます。SKILL.mdでパターンを指定せずに「エラー処理を追加する」とだけ書くと、毎回異なるアプローチが使われることになります。

出力は確率に左右される。プロンプトを構造化し、役割を割り当て、例を提示し、検証フックを使っても、結局は正答率を最適化しているにすぎません。正答率が60%から95%に向上すれば、もちろん大きな改善ではありますが、残りの5%に対応するために検証ツールが必要です。このアーキテクチャーには、予防的対策（構造化されたプロンプト、リファレンス、テンプレート）と検出的対策（自動検証ツール、採点ルーブリック、エラー時のブロック）の両方が含まれます。このスキルは、Claudeが間違えることもあるという前提に立っています。完全な出力が可能であるかのように見なすのではなく、修正プロセスをワークフローに組み込んでいるのです。

さっそく始めてみましょう

Anthropicは、プロンプトの作成についてこう述べています。「背景情報をほとんど知らない同僚にプロンプトを見せて、それに沿って作業してもらってみてください。その同僚が戸惑うようなら、Claudeも戸惑います」。適切に作成されたエージェントスキルには、人間にとってもモデルにとっても、あいまいな点がありません。

スキルをゼロから構築する必要はありません。Anthropicが提供するskill-creatorスキル（英語）を使うと、意図の整理、SKILL.mdの記述、テストケースの作成、evalの実行、そして出力が求める基準に達するまで反復するという一連のプロセスを進められます。skill-creatorスキルをインストールし、作成したいスキルをClaudeに伝えてみてください。skill-creatorスキルが土台を作成し、エッジケースについて聞き取り、実際に動作し、調整可能なドラフトを生成してくれます。

Salesforceに特化したサンプルを使って始めてみたい場合は、Agentforce Vibesスキルライブラリ（英語）で、Apex、LWC、Flowなどの本番品質のスキルを利用できます。こうしたスキルをインストールして使い、どのように構成されているかを確認してみてください。この記事で説明したものと同様のパターンに従っています。Agentforce Vibesスキルライブラリでは、ルールと理由をSKILL.mdにインラインで記述し、Markdown形式の参照ドキュメントの代わりに、完全なApexソースファイルをテンプレートとして使っています。これにより、少ないファイル数でスキルを自己完結させることができますが、モジュール性は損なわれます。1つのルールを更新するには、メインのワークフローファイルを編集する必要があります。

スキルは、ニーズに合わせて成長していきます。まずはskill-creatorまたは既存のスキルから始めてみましょう。プロジェクトに合わない部分をカスタマイズし、既存のスキルでは埋められないギャップが出てきたら、新しいスキルを構築してみるとよいでしょう。

関連情報

• GitHub：Salesforceのエージェントスキル集（英語）
• Trailhead：プロンプトの基本事項
• Trailhead：プロンプトエンジニアリングのテクニック
• GitHub：Anthropic Skill Creator（英語）
• ドキュメント：Claude Code

執筆者について

Dave Norrisは、Salesforceのデベロッパーアドボケイトです。技術的なテーマを、多様な読者に広くわかりやすく説明することに情熱を注いでいます。Salesforceで10年以上勤務し、現在、SalesforceとMuleSoftの認定資格を40以上保有。2013年に、Salesforce認定テクニカルアーキテクトの資格を取得しています。

The post Claude CodeでSalesforceエージェントスキルを構築する appeared first on Salesforce Developers Blog.

TDX 2026 で発表された HXL（Headless Experience Layer） ですが、2026年8月後半よりベータ公開となりました。Salesforce のデータを Slackbot、ChatGPT や Claude といった外部の AI エージェントアプリに、リッチなカスタム UI（ウィジェット）として表示できます。しかも表示するのは静的なサンプルではなく、組織の実データです。

本記事では、その HXL ウィジェットを MCP（Model Context Protocol）サーバー経由で公開し、AI エージェントアプリに「取引先の商談サマリ」を表示するまでをの流れを解説します。完成すると、AI エージェントアプリで「株式会社アストロエンタープライズの商談状況サマリを教えて」などと話しかけるだけで、次のようなカードが返ってくるようになります。

HXL の仕様や API の詳細は、公式の Headless Experience Layer Developer Guide (Beta) に詳しくまとまっています。ただし内容は英語で、サンプルもオブジェクトのデータにはアクセスしないものでした。そこで本記事では、実際に Salesforce 組織のデータを扱いながら、日本語で一連の流れを解説することを目的に作成しました。公式ガイドとあわせて読むことで、より理解が深まるはずです。

対象読者は Salesforce 開発の経験がある方です。Apex、メタデータ、VS Code + Salesforce&Agentforce 関連の拡張機能、sf コマンドの基礎は前提とし、HXL・MCP まわりの新しい概念を重点的に解説します。

※注意

• この記事は 2026 年 8 月時点の情報で作成しています。HXL / MCP まわりは進化が速いため、最新の仕様は公式ドキュメントもあわせてご確認ください。
• 本番組織ではなく Sandbox / Developer Editio/ Scratch Org での検証をおすすめします。
• 本記事の内容を試すには、組織のインスタンスが Summer ’26 Patch 14.4 以降である必要があります。パッチバージョンは Salesforce Status で自組織のインスタンスを検索すると確認できます。
• 本手順は Developer Edition での動作を確認しています。

全体の流れ

作るファイルはやや多いですが、役割ごとに整理すると次の 7 ステップになります。

1. Apex クラスで取引先の商談サマリーを取得する（データ取得ロジック）
2. LightningType で戻り値の型とレンダラー（描画マッピング）を定義する
3. UiWidgetBundle でウィジェットの見た目（UI）を作る
4. GenAiFunction（Agent Action） で Apex を API カタログに登録する
5. McpServerDefinition で MCP サーバーとして公開する
6. デプロイする
7. MCP サーバーを有効化し、AI エージェントアプリから接続して動作確認する

登場人物を図にすると、データの流れは次のようになります。

ポイントは、「データを取得する経路（tools）」と「見た目を定義する経路（resources）」が別々で、それを McpServerDefinition が束ねているところです。ここを押さえると、以降のファイル構成がすっきり理解できます。

事前準備

• Salesforce 組織（検証には Developer Edition または Sandbox を推奨）
• Salesforce CLI（sf）& VS Code + Salesforce & Agentforce の拡張機能

本記事では API バージョン 67.0 を前提にしています。

HXL を有効化する

まず、組織で HXL の機能を有効化しておきます。設定 のクイック検索で「ヘッドレスエクスペリエンスレイヤー」を検索し、設定ページを開いて有効化スイッチをオンにします。

※ この設定が表示されない場合は、組織のインスタンスが Summer ’26 Patch 14.4 以降になっているかを確認してください（パッチバージョンの確認方法は冒頭の注意を参照）。

本記事で作成するコード一式は、GitHub リポジトリ hinabasfdc/hxl-mcp-widget-sample に公開しています。手を動かしながら読む場合は、あわせて参照してください。

ステップ 1：Apex で商談サマリーを取得する

まずはデータ取得の心臓部となる Apex クラスです。取引先名を受け取り、次の 3 つを返します。

• 商談の総数
• フェーズ（StageName）別の商談件数
• 未クローズ（IsClosed = false）商談の合計金額

MCP のツールとして呼び出せるように、@InvocableMethod / @InvocableVariable で入出力を定義するのがポイントです。クラス全体は次のとおりです。

global without sharing class AccountOpportunitySummary {

    @InvocableMethod(label='取引先の商談サマリーを取得' description='取引先名から、商談件数・フェーズ別件数・未クローズ商談の合計金額を取得します。')
    global static List<SummaryResponse> getAccountOpportunitySummary(List<SummaryRequest> requests) {
        List<SummaryResponse> responses = new List<SummaryResponse>();

        for (SummaryRequest req : requests) {
            SummaryResponse res = new SummaryResponse();
            res.summary = buildSummary(req.accountName);
            responses.add(res);
        }

        return responses;
    }

    private static Summary buildSummary(String accountName) {
        Summary summary = new Summary();
        summary.accountName = accountName;
        summary.accountInitials = toInitials(accountName);
        summary.totalOpportunityCount = 0;
        summary.stageSummaryText = '';
        summary.openOpportunityAmount = 0;

        List<Account> accounts = [
            SELECT Id, Name
            FROM Account
            WHERE Name LIKE :('%' + accountName + '%')
            ORDER BY Name
            LIMIT 1
        ];

        if (accounts.isEmpty()) {
            return summary;
        }

        Account acc = accounts[0];
        summary.accountName = acc.Name;
        summary.accountInitials = toInitials(acc.Name);

        List<String> stageSummaryParts = new List<String>();
        for (AggregateResult ar : [
            SELECT StageName, COUNT(Id) opportunityCount
            FROM Opportunity
            WHERE AccountId = :acc.Id
            GROUP BY StageName
            ORDER BY StageName
        ]) {
            String stageName = (String) ar.get('StageName');
            Integer count = (Integer) ar.get('opportunityCount');

            summary.totalOpportunityCount += count;
            stageSummaryParts.add(stageName + ': ' + count + '件');
        }
        summary.stageSummaryText = String.join(stageSummaryParts, ' / ');

        AggregateResult openTotal = [
            SELECT SUM(Amount) totalAmount
            FROM Opportunity
            WHERE AccountId = :acc.Id AND IsClosed = false
        ];
        Decimal openAmount = (Decimal) openTotal.get('totalAmount');
        summary.openOpportunityAmount = (openAmount != null) ? openAmount : 0;

        summary.totalOpportunityCountText = summary.totalOpportunityCount + '件';
        summary.openOpportunityAmountFormatted = formatCurrency(summary.openOpportunityAmount);

        return summary;
    }

    // ウィジェット表示用に3桁区切りの「¥」表記へ整形する(Decimal.format()はロケール依存のため使わない)
    private static String formatCurrency(Decimal amount) {
        Long rounded = amount.round();
        String sign = (rounded < 0) ? '-' : '';
        String digits = String.valueOf(Math.abs(rounded));

        List<String> groups = new List<String>();
        Integer len = digits.length();
        Integer head = Math.mod(len, 3);
        if (head > 0) {
            groups.add(digits.substring(0, head));
        }
        for (Integer i = head; i < len; i += 3) {
            groups.add(digits.substring(i, i + 3));
        }

        return sign + '¥' + String.join(groups, ',');
    }

    // アバター表示用に、法人格の接頭辞を除いた先頭1文字を取り出す
    private static String toInitials(String name) {
        if (String.isBlank(name)) {
            return '?';
        }
        String bareName = name.replace('株式会社', '').replace('有限会社', '').trim();
        return String.isBlank(bareName) ? name.substring(0, 1) : bareName.substring(0, 1);
    }

    global class SummaryRequest {
        @InvocableVariable(label='取引先名' description='検索対象の取引先名(部分一致)' required=true)
        public String accountName;
    }

    global class SummaryResponse {
        @InvocableVariable(label='商談サマリー')
        public Summary summary;
    }

    global class Summary {
        @InvocableVariable public String accountName;
        @InvocableVariable public String accountInitials;
        @InvocableVariable public Integer totalOpportunityCount;
        @InvocableVariable public String stageSummaryText;
        @InvocableVariable public Decimal openOpportunityAmount;
        @InvocableVariable public String totalOpportunityCountText;
        @InvocableVariable public String openOpportunityAmountFormatted;
    }
}

ステップ 2：LightningType で型とレンダラーを定義する

ここが HXL の肝です。Apex の戻り値を、そのままウィジェットに流し込めるわけではありません。LightningType が「どの Apex 型を、どのウィジェットの、どの属性にマッピングするか」を仲介します。

MCP のレスポンスは 3 層の入れ子（エンベロープ）になっています。

accountOpportunitySummaryResult        ← 一番外側（actionName / isSuccess / outputValues）
  └─ accountOpportunitySummaryOutputValues  ← 中間（summary を保持）
       └─ AccountOpportunitySummary$Summary  ← Apex の Summary クラス（実データ）

この 3 層に対応する LightningType をそれぞれ用意します。

2-1. 一番内側：Apex 型のラッパー

lightningTypes/accountOpportunitySummary/schema.json は、Apex の Summary クラスを LightningType として参照するだけのシンプルなものです。

{
  "title": "Account Opportunity Summary",
  "description": "Apex から返される取引先の商談サマリー情報",
  "lightning:type": "@apexClassType/c__AccountOpportunitySummary$Summary"
}

@apexClassType/c__<クラス名>$<内部クラス名> という記法で、Apex の内部クラスを直接参照できます。

2-2. 中間層：OutputValues

lightningTypes/accountOpportunitySummaryOutputValues/schema.json は、Apex アクションのレスポンス payload（summary を持つ）を表します。lightning:tags に mcp を付けるのがポイントです。

{
  "title": "Account Opportunity Summary Output Values",
  "type": "object",
  "lightning:type": "lightning__objectType",
  "unevaluatedProperties": false,
  "lightning:tags": [ "mcp" ],
  "properties": {
    "summary": {
      "title": "Summary",
      "lightning:type": "@apexClassType/c__AccountOpportunitySummary$Summary"
    }
  }
}

2-3. 一番外側：Result エンベロープ

lightningTypes/accountOpportunitySummaryResult/schema.json が MCP に公開される最上位の型です。actionName / isSuccess / outputValues を持ちます。

{
  "title": "Account Opportunity Summary Result",
  "type": "object",
  "lightning:type": "lightning__objectType",
  "unevaluatedProperties": false,
  "lightning:tags": [ "mcp" ],
  "properties": {
    "actionName": { "title": "Action Name", "lightning:type": "lightning__textType" },
    "isSuccess":  { "title": "Is Success",  "lightning:type": "lightning__booleanType" },
    "outputValues": {
      "title": "Output Values",
      "lightning:type": "c__accountOpportunitySummaryOutputValues"
    }
  }
}

2-4. レンダラー：属性のマッピング

そして最も重要なのが renderer.json です。これが 「入れ子になったデータのどこを、ウィジェットのどの属性に流し込むか」 を定義します。Result 型のレンダラーは、3 層をたどって値を取り出します。

{
  "renderer": {
    "componentOverrides": {
      "$": {
        "definition": "@widget/c/accountSummaryCard",
        "attributes": {
          "accountName": "{!$attrs.outputValues.summary.accountName}",
          "accountInitials": "{!$attrs.outputValues.summary.accountInitials}",
          "totalOpportunityCountText": "{!$attrs.outputValues.summary.totalOpportunityCountText}",
          "stageSummaryText": "{!$attrs.outputValues.summary.stageSummaryText}",
          "openOpportunityAmountFormatted": "{!$attrs.outputValues.summary.openOpportunityAmountFormatted}"
        }
      }
    }
  }
}

• "definition": "@widget/c/accountSummaryCard" で、次のステップで作るウィジェットを指定します。
• {!$attrs.outputValues.summary.xxx} という式で、エンベロープの奥にある実データを取り出してウィジェットの属性に渡します。この階層（outputValues.summary.）を間違えると値が表示されないので注意してください。

ステップ 3：UiWidgetBundle でウィジェットの UI を作る

いよいよ見た目です。HXL のウィジェットは tile/* というコンポーネントを JSON でツリー状に組み合わせて作ります。

3-1. スキーマ（受け取る属性の宣言）

uiWidgets/accountSummaryCard/schema.json で、ウィジェットが受け取る属性を宣言します。

{
  "title": "Account Opportunity Summary Widget",
  "type": "object",
  "properties": {
    "attributes": {
      "lightning:type": "lightning__objectType",
      "properties": {
        "accountName":                     { "title": "取引先名", "lightning:type": "lightning__textType" },
        "accountInitials":                 { "title": "取引先名イニシャル", "lightning:type": "lightning__textType" },
        "stageSummaryText":                { "title": "フェーズ別商談数", "lightning:type": "lightning__textType" },
        "totalOpportunityCountText":       { "title": "商談数(表示用)", "lightning:type": "lightning__textType" },
        "openOpportunityAmountFormatted":  { "title": "未クローズ商談合計金額(表示用)", "lightning:type": "lightning__textType" }
      }
    }
  }
}

フェーズ別件数は、Apex 側で フェーズA: 3件 / フェーズB: 2件 のような 1 本のテキスト（stageSummaryText）に整形して渡しています。

3-2. ウィジェット本体（tile ツリー）

uiWidgets/accountSummaryCard/accountSummaryCard.json がレイアウト定義です。全体は長いので、構造を先に示します。

tile/widget
└─ tile/container
   └─ tile/column (gap: lg)
      ├─ [ヘッダー行] tile/row (justify: between)
      │   ├─ tile/row → tile/avatar（イニシャル） + tile/column（取引先名 + キャプション）
      │   └─ tile/badge（商談数）
      ├─ [統計行] tile/row (align: stretch, isWrapped)
      │   ├─ tile/container → icon(briefcase) + 「商談数」 + 大きな数値
      │   └─ tile/container → icon(dollar-sign) + 「未クローズ商談合計金額」 + 大きな金額
      ├─ tile/separator
      └─ [フェーズ別] tile/column → 見出し + stageSummaryText

ヘッダー部分（アバター＋取引先名＋商談数バッジ）の JSON は次のようになります。

{
  "definition": "tile/row",
  "attributes": { "gap": "md", "align": "center", "justify": "between", "isWrapped": true },
  "children": [
    {
      "definition": "tile/row",
      "attributes": { "gap": "sm", "align": "center" },
      "children": [
        {
          "definition": "tile/avatar",
          "attributes": {
            "initials": "{!$attrs.accountInitials}",
            "alt": "{!$attrs.accountName}",
            "size": "md",
            "shape": "circle"
          }
        },
        {
          "definition": "tile/column",
          "attributes": { "gap": "xs" },
          "children": [
            { "definition": "tile/text", "attributes": { "text": "{!$attrs.accountName}", "variant": "h3", "weight": "semibold" } },
            { "definition": "tile/text", "attributes": { "text": "取引先の商談サマリー", "variant": "caption", "color": "muted" } }
          ]
        }
      ]
    },
    {
      "definition": "tile/badge",
      "attributes": { "label": "{!$attrs.totalOpportunityCountText}", "variant": "primary" }
    }
  ]
}

未クローズ商談合計金額を強調して表示する統計カード部分はこうです。アイコンと大きな数値を組み合わせます。

{
  "definition": "tile/container",
  "children": [
    {
      "definition": "tile/column",
      "attributes": { "gap": "xs" },
      "children": [
        {
          "definition": "tile/row",
          "attributes": { "gap": "sm", "align": "center" },
          "children": [
            { "definition": "tile/icon", "attributes": { "name": "dollar-sign", "size": "sm", "color": "success" } },
            { "definition": "tile/text", "attributes": { "text": "未クローズ商談合計金額", "variant": "caption", "color": "muted" } }
          ]
        },
        {
          "definition": "tile/text",
          "attributes": { "text": "{!$attrs.openOpportunityAmountFormatted}", "variant": "h2", "weight": "bold", "color": "success" }
        }
      ]
    }
  ]
}

現時点でのハマりどころ：tile/icon の name は実在する値のみ
tile/icon の name に存在しないアイコン名（例：currency）を指定すると、ウィジェット全体が NullPointerException でクラッシュします。エラーメッセージが「An unexpected error occurred」としか出ないため、原因の特定に時間がかかりました。briefcase や dollar-sign など、実在するアイコン名を使ってください。

UiWidgetBundle のメタデータ（accountSummaryCard.uiwidget-meta.xml）は widgetType を JSON にしておきます。

<?xml version="1.0" encoding="UTF-8"?>
<UiWidgetBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <masterLabel>Account Summary Card</masterLabel>
    <description>取引先名、商談数、フェーズ別商談数、未クローズ商談の合計金額を表示します。</description>
    <widgetType>JSON</widgetType>
</UiWidgetBundle>

ステップ 4：GenAiFunction（Agent Action）で Apex を登録する

ここは見落としがちですが必須です。Apex クラスを MCP サーバーから呼び出せるようにするために、Agent アクションとして登録する必要があります。

genAiFunctions/Get_Account_Opportunity_Summary/Get_Account_Opportunity_Summary.genAiFunction-meta.xml:

<?xml version="1.0" encoding="UTF-8"?>
<GenAiFunction xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>取引先名から、商談件数・フェーズ別件数・未クローズ商談の合計金額を取得します。</description>
    <developerName>Get_Account_Opportunity_Summary</developerName>
    <invocationTarget>AccountOpportunitySummary</invocationTarget>
    <invocationTargetType>apex</invocationTargetType>
    <isConfirmationRequired>false</isConfirmationRequired>
    <masterLabel>取引先の商談サマリーを取得</masterLabel>
</GenAiFunction>

入力スキーマ（input/schema.json）では、accountName をユーザー入力として受け取ることを宣言します。

{
  "required": [ "accountName" ],
  "properties": {
    "accountName": {
      "title": "取引先名",
      "lightning:type": "lightning__textType",
      "copilotAction:isUserInput": true
    }
  },
  "lightning:type": "lightning__objectType"
}

出力スキーマ（output/schema.json）では、summary を 表示可能（isDisplayable） として宣言します。これがウィジェット表示につながる重要なフラグです。

{
  "properties": {
    "summary": {
      "title": "商談サマリー",
      "lightning:type": "@apexClassType/c__AccountOpportunitySummary$Summary",
      "copilotAction:isDisplayable": true,
      "copilotAction:isUsedByPlanner": true
    }
  },
  "lightning:type": "lightning__objectType"
}

ステップ 5：McpServerDefinition で MCP サーバーとして公開する

最後に、これまでの部品を束ねる McpServerDefinition です。ここが「データ取得（tools）」と「見た目（resources）」を接続する結節点になります。

<?xml version="1.0" encoding="UTF-8"?>
<McpServerDefinition xmlns="http://soap.sforce.com/2006/04/metadata">
    <description>取引先の商談サマリー(商談数、フェーズ別件数、未クローズ商談合計金額)を検索して返します。</description>
    <masterLabel>account-opportunity-summary-server</masterLabel>
    <tools>
        <apiDefinition>
            <apiIdentifier>aa:apex-AccountOpportunitySummary</apiIdentifier>
            <apiSource>API_CATALOG</apiSource>
            <operation>AccountOpportunitySummary</operation>
        </apiDefinition>
        <descriptionOverride>取引先名から、商談件数・フェーズ別件数・未クローズ商談の合計金額を取得します。</descriptionOverride>
        <destructive>false</destructive>
        <idempotent>true</idempotent>
        <openWorld>false</openWorld>
        <readOnly>true</readOnly>
        <returnDirect>false</returnDirect>
        <toolName>AccountOpportunitySummaryapex_AccountOpportunitySummary</toolName>
        <toolTitle>AccountOpportunitySummary</toolTitle>
        <uiResource>accountSummary</uiResource>
    </tools>
    <resources>
        <resourceName>accountSummary</resourceName>
        <resourceUri>ui://widget/lightningType/c__accountOpportunitySummaryResult</resourceUri>
        <resourceTitle>Account Opportunity Summary</resourceTitle>
        <description>取引先名、商談数、フェーズ別商談数、未クローズ商談合計金額を表示するウィジェット。</description>
    </resources>
</McpServerDefinition>

読み解きのポイント

• <tools> は データ取得の経路です。apiIdentifier の aa:apex-<クラス名> と apiSource の API_CATALOG が、ステップ 4 で登録した Agent Action を指しています。
• <resources> は 見た目の経路です。resourceUri は ui://widget/lightningType/c__<LightningTypeBundleのAPI名> という形式で、ステップ 2 で作った Result 型を指します。
• <uiResource> と <resourceName> の値（accountSummary）を一致させることで、ツールとリソース（＝データと見た目）が紐づきます。

現時点の仕様: CSP（connectDomains など）や _meta.ui.domain といった MCP プロトコルの内部設定は、Salesforce プラットフォームが自動生成します。開発者がメタデータで設定する項目ではありません。

ステップ 6：デプロイする

ソースを組織にデプロイします。依存関係の順（Apex → LightningType & UiWidget → GenAiFunction → McpServerDefinition）を意識するとエラーが減りますが、まとめてデプロイしても解決してくれることが多いです。

sf project deploy start \
  --source-dir force-app/main/default \
  --target-org <your-org-alias> \
  --wait 15 --json

現時点の仕様: UiWidgetBundle のスキーマは「プロパティ削除」で失敗する
一度デプロイしたウィジェットの schema.json から既存プロパティを削除すると、Schema update contains breaking changes: ... プロパティは削除できません というエラーになります。属性を作り直したいときは、古いプロパティを残したまま新しいものを追加するのが安全です。

ステップ 7：MCP サーバーを有効化し、AI エージェントアプリから接続する

デプロイが終わったら、MCP サーバーを有効化します。これは現状 設定画面からの手動操作のみです。

有効化したら、外部クライアントアプリケーションを作成し、AI エージェントアプリ側でコネクタ（プラグイン）として登録します。この OAuth まわりの手順は、別記事「Salesforce Hosted MCP Server 使い始め」で詳しく解説されているので、そちらもあわせてご覧ください。

ChatGPT と Claude で試してみる

公開した MCP サーバーは、MCP に対応した AI エージェントアプリから接続できます。コネクタとして登録したうえで「SalesforceDev で United Oil の商談サマリを見せて」と話しかけると、AccountOpportunitySummary ツールが呼び出され、次のように同じカードが表示されます。

Claude の場合

ChatGPT の場合

SUM(Amount) も GROUP BY StageName も、すべて組織の実データが反映されています。フィールドレベルセキュリティ（FLS）や共有ルールも尊重されるため、安心して社内データを扱えます。同じ MCP サーバーを Claude と ChatGPT のどちらから呼び出しても、同一のウィジェットが同じ見た目で表示される点にも注目してください。

要考慮事項：ウィジェットの変更が反映されない

ところで、ウィジェットの定義を更新後、デプロイは成功しているのに、AI エージェントアプリ側では古いレイアウトのままという現象に悩まされました。組織側のメタデータを取得して確認しても、ローカルと内容は一致しています。それでも新しい見た目にならないのです。

原因は、AI エージェントアプリ（クライアント）側が、ウィジェットのテンプレートを resourceUri の文字列をキーにキャッシュしているからのようです。AI エージェントアプリの内部仕様で詳細は不明ですがresourceUri が同じままだと、中身をいくら変えても古いテンプレートが使われ続けるように見えました。

実際、クライアント側のコネクタ設定を見ると、ui://widget/lightningType/c__accountOpportunitySummary... という resourceUri をキーに、ウィジェットのテンプレート内容が保持されているのが確認できます。

ひとまずの対策は resourceUri のバージョニングです。

1. LightningTypeBundle を新しい API 名でコピーする（例：accountOpportunitySummaryResult → accountOpportunitySummaryResultV2）
2. McpServerDefinition の <resourceUri> と <uiResource> を新しいものに更新する
3. デプロイ後、AI エージェントアプリ側でコネクタ／プラグインを更新（再登録）する

<!-- 変更前 -->
<resourceUri>ui://widget/lightningType/c__accountOpportunitySummaryResult</resourceUri>

<!-- 変更後（V2 に）-->
<resourceUri>ui://widget/lightningType/c__accountOpportunitySummaryResultV2</resourceUri>

なお、バージョニングが必要なのは resourceUri が指す LightningTypeBundle と McpServerDefinition だけです。UiWidgetBundle は同じ名前のまま上書きデプロイで問題ありません（クライアントは URI をキーにキャッシュしているため、URI が変われば中身も取り直されます）。Apex や GenAiFunction も影響を受けません。

ただし、この対策はあまり美しいものとは言えません。今後の AI エージェントアプリ側でのキャッシュクリアなどよりスマートな解決策が出てくることを願っています。

おわりに

本記事では、Apex・LightningType・UiWidgetBundle・GenAiFunction・McpServerDefinition を組み合わせて、組織の実データ（取引先の商談サマリー）を AI エージェントアプリにリッチなカードとして表示する HXL カスタムウィジェットを作りました。

従来、AI エージェントアプリに返せるのはテキストや静的なサンプルが中心でした。HXL と MCP を使うことで、Salesforce の実データを、意味のある UI として、外部の AI 体験に直接埋め込めるようになります。FLS や共有ルールも尊重されるため、セキュリティ面でも安心です。

一度この 7 ステップの型を押さえてしまえば、Apex のクエリとウィジェットの tile ツリーを差し替えるだけで、ケース一覧・在庫状況・売上ダッシュボードなど、さまざまなカスタムウィジェットに応用できます。ぜひ Developer Edition で試してみてください。

参考資料

• Headless Experience Layer Developer Guide (Beta)
• Salesforce Hosted MCP Server 使い始め（OAuth 接続手順）
• Salesforce Status（インスタンスのパッチバージョン確認）
• 本記事のサンプルコード一式（GitHub: hinabasfdc/hxl-mcp-widget-sample）

The post Headless Experience Layer によるカスタムウィジェット：MCP 経由で取引先の商談サマリーを AI エージェントアプリに表示する appeared first on Salesforce Developers Blog.

This is the second post in our series on LWC anti-patterns. The first post covered security and platform compatibility — how to write components that work within Lightning Web Security. In this post, you’ll learn the most common mistakes in three areas: the @wire service, public properties (@api), and event handling. Fixing these patterns is one of the highest-leverage things you can do to make your components more reliable.

Wire service anti-patterns

The wire service is how components reactively fetch Salesforce data, but its subscription model trips up developers who treat it like a one-time fetch. The patterns below cover the mistakes that lead to stale data, infinite loops, and updates that never arrive.

@wire is a subscription, not a fetch

Before diving into specific anti-patterns, there’s one mental model shift that explains most wire service bugs: @wire is not a fetch wrapper. It’s a subscription.

When you wire a property to getRecord (see docs), you’re not making a one-time request. You’re subscribing to a stream. The adapter can emit multiple times — once from cache, again when the network responds, and again when any component on the page modifies that record. Your wire handler should be safe to call multiple times with the most recent value.

This distinction matters for every pattern below.

Don’t mutate @wire results directly

Wire data is immutable. Assigning directly to a wired property, or to a nested field on that property, violates the contract with the wire service. The result is unpredictable: you may see stale data, missed reactive updates, or a render that doesn’t reflect your change.

@wire(getContacts)
contacts;

handleDelete(event) {
    // This won't work reliably — wire data is immutable
    this.contacts.data = this.contacts.data.filter(c => c.Id !== event.detail.id);
}

Copy the data into a local property instead, and mutate that.

contacts = [];

@wire(getContacts)
wiredContacts({ data, error }) {
    if (data) {
        this.contacts = [...data];
    }
}

handleDelete(event) {
    this.contacts = this.contacts.filter(c => c.Id !== event.detail.id);
}

Don’t update wire config in renderedCallback()

renderedCallback() (see docs) runs after every render. If you change a reactive wire config property inside it, that change triggers a new render, which calls renderedCallback() again. You’ve created an infinite loop.

renderedCallback() {
    // This causes an infinite render loop
    this.recordId = this.template.querySelector('input').value;
}

Update wire config properties in response to user events, not in rendering callbacks.

handleIdChange(event) {
    this.recordId = event.detail.value; // wire re-evaluates automatically
}

Don’t assume wire adapters fire in order

Multiple wire adapters on the same component are independent subscriptions. The order they deliver data is not guaranteed, and neither is the number of times each fires. Code that reads from one wire result inside another wire’s handler, or reads wire data inside connectedCallback(), will fail silently when the Lightning Data Service (LDS) cache is cold.

connectedCallback() {
    // items.data is undefined on first load — this throws
    this.total = this.items.data.reduce((sum, item) => sum + item.UnitPrice__c, 0);
}

Drive derived state from inside the wire handler itself, and guard against undefined at every access.

@wire(getOrderItems, { orderId: '$recordId' })
wiredItems({ data }) {
    if (data) {
        this.items = data;
        this.total = data.reduce((sum, item) => sum + item.UnitPrice__c, 0);
    }
}

If derived state depends on two adapters, compute it once both have delivered.

updateTotal() {
    if (this.order && this.items.length > 0) {
        this.total = this.items.reduce((sum, item) => sum + item.UnitPrice__c, 0);
    }
}

@wire(getOrder, { recordId: '$recordId' })
wiredOrder({ data }) {
    if (data) {
        this.order = data;
        this.updateTotal();
   }
}

@wire(getOrderItems, { orderId: '$recordId' })
wiredItems({ data }) {
    if (data) {
        this.items = data;
        this.updateTotal();
    }
}

Use schema imports for object and field references

Hard-coding SObject or field names as strings bypasses Salesforce’s ability to validate references, prevent accidental deletion, and cascade renames. A renamed field silently breaks the component at runtime.

// String literals — not validated at deploy time
@wire(getRecord, { recordId: '$recordId', fields: ['Account.Name', 'Account.Industry'] })
account;

Import field tokens from @salesforce/schema instead. The platform validates these at build time.

import ACCOUNT_OBJECT from '@salesforce/schema/Account';
import NAME_FIELD from '@salesforce/schema/Account.Name';
import INDUSTRY_FIELD from '@salesforce/schema/Account.Industry';

@wire(getRecord, { recordId: '$recordId', fields: [NAME_FIELD, INDUSTRY_FIELD] })
account;

Use the correct field path in getRecord

Every field in a getRecord fields array must be reachable from the record’s own object type. Specifying a top-level field from a different object — like including Account.Name in a call for a Case record — produces a malformed config. The component receives incomplete data. Because Aura components share the same Lightning Data Service (LDS) cache, a malformed config can affect those Aura components too.

// Wrong — Account.Name is not a field on Case
@wire(getRecord, { recordId: '$recordId', fields: [CASE_SUBJECT, ACCOUNT_NAME] })
record;

To access a related record’s field, use the full relationship path starting from the base object.

import CASE_ACCOUNT_NAME from '@salesforce/schema/Case.Account.Name';

// Correct — traversal expressed from Case
@wire(getRecord, { recordId: '$recordId', fields: [CASE_SUBJECT, CASE_ACCOUNT_NAME] })
record;

Don’t use @wire for write operations

@wire is for read operations only. Using it to invoke an Apex method that performs DML gives you unpredictable invocation timing and no way to handle errors in the UI.

// Don't wire a method that performs DML
@wire(saveRecord, { record: '$record' })
savedResult;

Use imperative Apex calls for any operation that writes data.

async handleSave() {
    try {
        await saveRecord({ record: this.record });
        this.dispatchEvent(new CustomEvent('saved'));
    } catch (error) {
        // show error in UI
    }
}

Don’t mix Apex and LDS for the same record

Apex and Lightning Data Service (LDS) maintain separate, independent caches. When you fetch the same record through both at the same time, the two copies can diverge — one reflecting a recent server change, the other serving a stale value. The result is inconsistent UI state that’s hard to reproduce.

Pick one data source per record and use it consistently. Use LDS wire adapters when they support your use case. Use Apex only when LDS doesn’t (unsupported objects, complex queries, transactional operations).

Don’t use refreshApex() on LDS wire adapters

refreshApex()(see docs) is designed for wired Apex methods only. Calling it on an LDS adapter like getRecord is deprecated and has no reliable effect. LDS manages its own cache automatically when records change through LDS-aware operations.

handleRefresh() {
    refreshApex(this.record); // deprecated for LDS adapters
}

To signal that a record’s cached data is stale after an out-of-band write, use notifyRecordUpdateAvailable() (see docs).

import { notifyRecordUpdateAvailable } from 'lightning/uiRecordApi';

async handleRefresh() {
    await notifyRecordUpdateAvailable([{ recordId: this.recordId }]);
    // LDS now has fresh data for all subscribed adapters
}

All active wire adapters subscribed to that record will automatically receive fresh data.

Call notifyRecordUpdateAvailable() after imperative Apex writes

When an imperative Apex method modifies a record, LDS doesn’t know about it. Every LDS wire adapter on the page — including those in sibling and parent components — continues to serve its cached, pre-mutation value. The UI shows stale data with no error.

async handleSave() {
    await updateAccount({ recordId: this.recordId, name: this.name });
    // LDS still has the old value — nothing updates here
}

After the write completes, notify LDS that the record is stale.

import { notifyRecordUpdateAvailable } from 'lightning/uiRecordApi';

async handleSave() {
    await updateAccount({ recordId: this.recordId, name: this.name });
    await notifyRecordUpdateAvailable([{ recordId: this.recordId }]);
    // LDS now has fresh data
}

This keeps all LDS wire adapters across the page consistent with the server state.

Use config gating for dependent data, not promise chains

When loading data that depends on the result of another fetch — like fetching an Account after you have its ID from a Case — developers often reach for nested imperative Apex calls or Promise.then() (see docs) chains. This is fragile, doesn’t participate in LDS caching, and doesn’t recover automatically when upstream data changes.

The wire service handles this natively: a wire adapter won’t evaluate until all of its required config properties are truthy. Keep a reactive config property undefined until upstream data arrives, and the second adapter gates automatically.

@api recordId;   // Case record ID
accountId;       // undefined until first wire delivers

@wire(getRecord, { recordId: '$recordId', fields: [CASE_ACCOUNT_ID] })
wiredCase({ data }) {
    if (data) {
        this.accountId = data.fields.AccountId.value; // triggers second wire
    }
}

// Does not evaluate until accountId is truthy
@wire(getRecord, { recordId: '$accountId', fields: [ACCOUNT_NAME] })
accountRecord;

Both records now participate in the LDS cache. If the Case’s AccountId changes, the second wire re-fetches the new Account automatically.

Don’t swap the config object to “re-fetch”

The @wire reactive system tracks individual top-level class properties, not nested object contents or the config object reference. Replacing the entire config object doesn’t trigger re-evaluation.

currentConfig = { recordId: '001000000000001', fields: [NAME_FIELD] };

@wire(getRecord, '$currentConfig')
record;

handleSelectRecord(event) {
    // Swapping the object doesn't trigger re-evaluation
    this.currentConfig = { recordId: event.detail.recordId, fields: [NAME_FIELD] };
}

Declare reactive config values as individual top-level properties and reference them with $.

recordId;

@wire(getRecord, { recordId: '$recordId', fields: [NAME_FIELD] })
record;

handleSelectRecord(event) {
    this.recordId = event.detail.recordId; // wire re-evaluates automatically
}

Don’t add dummy optionalField to bust the LDS cache

Some developers add irrelevant fields to optionalFields hoping to force a cache miss. This doesn’t work. optionalFields are fetched opportunistically when already in the cache and silently omitted when not. They don’t invalidate cache entries for required fields.

Use notifyRecordUpdateAvailable() after any out-of-band write to signal LDS that the record is stale. See the pattern above.

Design wire handlers to be idempotent

Because @wire is a subscription stream that can emit multiple times, wire handlers must be safe to call with a fresh value at any time. A handler that performs one-time initialization side effects will leave the component in a stale state after subsequent emissions.

@wire(getRecord, { recordId: '$recordId', fields: [NAME_FIELD] })
wiredRecord({ data }) {
    if (data) {
        this.record = data;
        this.initializeChart(data); // breaks on second emission
    }
}

Derive all displayed state from the most recent emission. For side effects that genuinely run once, guard them with a flag and keep them separate from the data-update logic:

_chartInitialized = false;

wiredRecord({ data }) {
    if (data) {
        this.record = data;
        if (!this._chartInitialized) {
            this._chartInitialized = true;
            this.initializeChart(data);
        }
        this.updateChart(data); // idempotent update path

    }
}

Public property anti-patterns

Public properties (@api) define the contract between a component and its parent. Data flows down through them, and the patterns below cover the mistakes that break that one-way flow or leak your component’s internal state to the outside.

Don’t reassign @api properties internally

@api properties are owned by the parent component. They flow data downward. If you reassign an @api property from within your own component, you break the unidirectional data flow contract, which can cause infinite update cycles and runtime warnings from the LWC engine.

@api value = '';

handleInput(event) {
    this.value = event.target.value; // reassigning an @api property
}

Store the working value in a private property and expose a getter for the public interface.

_value = '';

@api
get value() { return this._value; }
set value(v) { this._value = v; }

handleInput(event) {
    this._value = event.target.value;
    this.dispatchEvent(new CustomEvent('change', { detail: { value: this._value } }));
}

Don’t pass objects by reference in event detail

JavaScript passes objects by reference. When you put an object directly into a CustomEvent detail (see docs), any listener can mutate the original. This creates hidden coupling and hard-to-debug state corruption.

handleSave() {
    this.dispatchEvent(new CustomEvent('save', { detail: this.record })); // mutable reference
}

Pass a shallow copy so listeners can’t affect your component’s state.

handleSave() {
    this.dispatchEvent(new CustomEvent('save', { detail: { ...this.record } }));
}

Event handling anti-patterns

Events carry data upward, from a component to its ancestors. The patterns below cover the mistakes that make events hard to listen for, leak mutable state between listeners, or quietly break component encapsulation.

Use CustomEvent, not Event

Unlike CustomEvent, the base Event constructor doesn’t support a detail property. Using it forces you to attach data through non-standard properties, which is fragile and inconsistent with platform conventions.

this.dispatchEvent(new Event('recordselected'));

this.dispatchEvent(new CustomEvent('recordselected', {
    detail: { recordId: this.selectedId }
}));

Don’t prefix event names with “on”

HTML attribute syntax uses on as a prefix for event handlers. If you name your custom event onstatuschange, a parent component must listen for it as ononstatuschange — which is confusing and risks conflicts with reserved event names.

this.dispatchEvent(new CustomEvent('statuschange', { detail: { status } }));

<c-child onstatuschange={handleStatusChange}></c-child>

Don’t mutate event.detail

event.detail is a shared object reference. Mutating it inside your handler modifies the object that other listeners in the same bubbling chain will read.

handleStatusChange(event) {
    event.detail.status = 'processed'; // affects other listeners
    this.currentStatus = event.detail.status;
}

Read from event.detail and store the value locally — never write back to it.

handleStatusChange(event) {
    this.currentStatus = event.detail.status;
}

If you need to enrich event data for upstream listeners, stop the original event and re-dispatch a new one with the updated payload. This makes the transformation explicit.

handleStatusChange(event) {
    event.stopPropagation();
    this.dispatchEvent(new CustomEvent('statuschange', {
        bubbles: true,
        detail: { ...event.detail, status: 'processed', processedAt: Date.now() }
    }));
}

Always remove event listeners you add imperatively

Listeners added via addEventListener (see docs) to elements outside your component’s template — like window (see docs) or document (see docs) — will hold a reference to your component after it disconnects. This prevents garbage collection and can fire callbacks on a disconnected component.

connectedCallback() {
    window.addEventListener('resize', this.handleResize.bind(this)); // never removed
}

The cleanest fix is to declare the event handler as an arrow function class field, which is bound at class definition time and always has the same reference. Then, remove the event handler by calling removeEventListener() (see docs).

handleResize = () => {
    this.width = window.innerWidth;
};

connectedCallback() {
    window.addEventListener('resize', this.handleResize);
}

disconnectedCallback() {
    window.removeEventListener('resize', this.handleResize);
}

Don’t call .bind() inline with addEventListener

.bind() (see docs) returns a new function object every time it’s called. If you pass this.handler.bind(this) to addEventListener and then pass this.handler.bind(this) again to removeEventListener, you’re passing two different functions. The listener is never removed.

connectedCallback() {
    window.addEventListener('scroll', this.handleScroll.bind(this));
}

disconnectedCallback() {
    window.removeEventListener('scroll', this.handleScroll.bind(this)); // different function — does nothing
}

Use an arrow function class field (same reference always) or store a single .bind() result in a property and reuse it.

// Arrow field — preferred
handleScroll = () => { this.scrollTop = window.scrollY; };

// Or stored bind reference
connectedCallback() { this._scrollHandler = this.handleScroll.bind(this); }

Don’t use bubbles: true, composed: true unneccessarily

Setting both bubbles (see docs) and composed (see docs) event properties to true causes the event to propagate through every shadow boundary all the way to the document root. This breaks encapsulation, creates implicit dependencies on ancestor components, and risks event name collisions higher in the tree. The LWC documentation is explicit: “Lightning web components don’t use this configuration.”

Use the default (bubbles: false, composed: false) for events handled by a direct parent. Use bubbles: true, composed: false only when a grandparent within the same shadow tree needs to hear the event. Reserve composed: true for rare cases where crossing a shadow boundary is genuinely necessary, and stop propagation at the first component that handles it.

Replace pubsub with Lightning Message Service

The community pubsub module is deprecated and no longer actively maintained. It only works within a single page, can’t cross namespace boundaries, and requires manual unregistration — a step that’s easy to forget and causes memory leaks.

Use Lightning Message Service — lightning/messageService — (see docs) instead. It works across LWC, Aura, and Visualforce components, spans multiple pages and namespaces, and manages subscription lifecycle cleanly.

import { subscribe, unsubscribe, MessageContext } from 'lightning/messageService';
import RECORD_SELECTED_CHANNEL from '@salesforce/messageChannel/RecordSelected__c';

export default class RecordConsumer extends LightningElement {
    @wire(MessageContext) messageContext;
    _subscription;

    connectedCallback() {
        this._subscription = subscribe(
            this.messageContext,
            RECORD_SELECTED_CHANNEL,
            (message) => this.handleRecordSelected(message)
        );
    }

    disconnectedCallback() {
        unsubscribe(this._subscription);
        this._subscription = null;
    }
}

Don’t register capture-phase listeners

LWC doesn’t support the capture (see docs) phase of DOM event propagation. Passing { capture: true } to addEventListener has no effect — the listener won’t fire on the way down the tree. There’s no runtime error; the code just behaves as if the option wasn’t set.

Design event handling around the bubbling phase. If you need to intercept an event before child components handle it, restructure the component tree so the intercepting component is a direct parent, or use a declarative handler on the child element in the template.

Conclusion

The patterns in this post share a common root: misunderstanding how data flows through LWC. The wire service is a subscription stream — not a fetch call. @api properties flow down from the parent — they’re not yours to reassign. Events carry immutable snapshots — don’t mutate their payloads or attach shared object references to them.

Correcting your mental model on these three surfaces prevents the large majority of data and communication bugs in LWC development.

In the next and final post in this series, we’ll cover runtime behavior — DOM access, component lifecycle, async patterns, performance, and base component usage.

Resources

• Wire Service documentation
• LDS — getRecord
• notifyRecordUpdateAvailable()
• Lightning Message Service
• LWC Events documentation
• @lwc/eslint-plugin-lwc rules

About the author

Tim Dionne is a Principal Member of Technical Staff (PMTS) on the Customer Centric Engineering team. He’s worked on many UI features of Salesforce over the years, starting with VisualForce, Aura Components, and Lightning Web Components with an emphasis on Lightning Web Security and Lightning Data Service.

The post Data and Communication Anti-Patterns in Lightning Web Components appeared first on Salesforce Developers Blog.

Whether you’re joining us in San Francisco or tuning in on Salesforce+, we’ve curated our top Dreamforce recommendations for developers to help you make the most of your experience. 

Ready to plan your perfect three days? With My Agenda now live, it’s time to start building your schedule. See the sessions you’ve added alongside personalized, AI-powered recommendations based on your interests, so you can quickly add sessions that interest you or hide them anytime. Explore the must-attend experiences for developers, from practical training and deep technical dives to hands-on agent-building sessions designed to give you the skills and confidence needed to put what you learn into production right away.

Prepare for Dreamforce 2026

Road to Dreamforce Quest

Before arriving at Dreamforce, dive into hands-on learning, must-see sessions, and curated resources to help you build your Agentic Enterprise. Complete the Road to Dreamforce Quest by September 14, 2026, and you’ll be entered for a chance to win* 1 of 100 prize boxes. *No purchase necessary. Void where prohibited. Country of residence and other restrictions apply. See the Trailblazer Quests page for full details and restrictions.

Developer Trail Map

The Dreamforce Developer Trail Map is your guide to Dreamforce for developers. We’ve curated the experiences, sessions, and connections most relevant to you so you can explore what to prioritize and make every moment at Dreamforce count.

Dreamforce keynotes for developers

Dreamforce is jam-packed with must-see sessions for developers. If you’re attending in person, be sure to add these sessions to your agenda. Can’t join us in San Francisco? Register for the livestream on Salesforce+ to tune in remotely.

Main Keynote

Join Salesforce Chair and CEO Marc Benioff, along with special guests, to explore what it means to become an Agentic Enterprise, where humans, agents, and platforms together promote customer success.
Add to your agenda
Watch on Salesforce+

Developer Keynote: Build the Agentic Enterprise

Join Christophe Coenraets and Salesforce Developer Advocates for a keynote built by developers, for developers. See Headless 360 and the latest AI-powered innovations in action through live demos, and discover how AI is transforming your developer workflows.
Add to your agenda
Watch on Salesforce+

True to the Core 

Join Co-Founder Parker Harris and other Salesforce product leaders as they answer your questions in this fan-favorite, unscripted keynote. This is a unique opportunity to ask your questions and get answers directly from the experts.
Add to your agenda
Watch on Salesforce+

Build the Agentic Enterprise in Trailblazer Forest

Once you’ve secured your badge, head to Trailblazer Forest to see the Agentic Enterprise in action. Created for admins, developers, and architects, this core hub brings Agentforce, Headless 360, Slack, and Data 360 to life through hands-on experiences, technical demos, and expert-led sessions. Gain the foundational expertise and confidence to build and deploy trusted agents in production at scale.

Attend introductory sessions at Headless 360 Theater

Headless 360 Theater features six repeating 20-minute sessions that break down the core innovations of the Agentic Enterprise. Whether you’re an admin, developer, architect, or new to the Salesforce ecosystem, these expert-led introductory sessions provide the essential foundation you need before diving into deeper demos and workshops at Dreamforce. Sessions include:

• Introduction to Headless 360
• Introduction to Agentforce
• Introduction to Agentic Experiences in Slack
• Introduction to Salesforce Vibe Coding Agents
• Introduction to Data 360
• Introduction to Platform

See Headless 360 in action through live demos

Visit the Headless 360 zone to see how unified context and flexible deployment coexist. Through live demos, discover how Headless 360, Hosted MCP Servers, Multi-Framework, and HXL empower you to ground coding agents in real org metadata. Learn how to deploy across various frameworks and render rich UIs natively on React and Slack, all with built-in governance.

Get hands-on at Headless 360 Basecamp

Headless 360 Basecamp is where you’ll get firsthand experience building with any coding agent and deploying on any surface with Salesforce Headless 360. Start at the Welcome Desk to learn how to complete this stop of the Developer Quest by participating in the area’s activity, and earn an exclusive Agent Codey backpack. Then, get hands-on in a guided, 15-minute activity where you’ll learn how to configure Salesforce MCPs within a third-party AI system. Technical experts will be available in the area to help as you go through the exercise.

Dive deeper with product demos at Platform Park

Platform Park features 20 expert-led demos, including 18 platform demos and 2 customer success demos, designed to turn inspiration into implementation. Whether you’re a developer, admin, architect, or partner, go beyond keynotes and sessions to learn how to securely connect data, applications, and AI at scale. Gain practical insights, engage in discussions, and access guided builds that equip you to turn Salesforce innovation into real business outcomes.

Hear from the experts in Developer Grove

This is your #1 stop for developer-focused sessions in Trailblazer Forest. Catch sessions and demos from Salesforce experts throughout Dreamforce, covering everything from Agentforce Vibes and Agent Script to Headless Data 360 and Apex best practices. It’s the perfect spot to sit back, recharge, and soak up technical content between your other activities and experiences in Trailblazer Forest.

Test your skills at Camp Mini Hack

Start building the Agentic Enterprise at Camp Mini Hack. Get hands-on with Agentforce, Headless 360, vibe coding, Apex & Flow, and Data 360 through 30-minute challenges designed for every skill level. Build and deploy working agents with on-demand expert help and real-time automated validation, while earning prizes along the way.

Master the full agent lifecycle in the Agentforce Zone

Explore the full lifecycle of autonomous AI agents at the Agentforce Zone. Through interactive, expert-led demos, developers will see how to create, deploy, and scale production-ready agents. Discover how Agentforce Studio, Agentforce Builder, Agentforce Operations (formerly known as Regrello), Agentforce Voice, Multi-Agent Orchestration, and Agentforce Observability bring AI-first workflows to life.

Skill up at Camp Trailhead

Get hands-on with Salesforce in 30 minutes at Camp Trailhead. Whether you’re brand new to the platform or an experienced pro, complete hands-on Trailhead badges covering key innovations like Headless 360, Agentforce Coworker, Help Agent, Salesforce Flow, and more. Work on provided laptops or bring your own, receive real-time support from on-site experts, and when you complete one of the highlighted badges, be sure to stop by the prize desk to collect your reward.

Get a peek into the future at Sneak Peeks

Sneak Peeks is back at Dreamforce to give admins, developers, and architects an exclusive look at what’s next for the platform. Catch sessions covering unreleased features across Agentforce, Headless, Flow, and User Access Management. Afterward, stick around for live Q&A to get your burning technical questions answered directly by the product experts.

Connect people, data, and agents in Slack

Slack is the work operating system for the Agentic Enterprise, a multiplayer workspace where Salesforce data, agents, and teams seamlessly collaborate. Step into a real Salesforce org to experience headless automation brought to life. Get hands-on working a sales cycle, service retro, or campaign using interactive Slackbot skills. Explore live demos of Code Channels, end-to-end Slack-to-Salesforce automation (using Workflow Builder, Flow, Apex, and Block Kit), and stop by the live vibe coding station where you’ll prompt Vercel’s v0 agent to build a web app on the fly based on your real-time suggestions.

Skill up with developer sessions

Developer sessions are your opportunity to learn directly from product experts, Salesforce Developer Advocates, and experts from the community building the Agentic Enterprise. These sessions cover technical deep dives, real-world implementations, and innovative solutions across the Headless 360 platform. Join us to sharpen your skills and deliver production-ready solutions at scale. 

To find developer-focused sessions in the Dreamforce session catalog, select “Role” in the left navigation and then select “Developer”.

Agentforce and AI integration sessions

Master Agentforce Vibes, Agent Script, Agentforce Voice, and Mobile SDK Skills to build, test, and deploy trusted agents across any surface.

Develop Apps with Metadata Grounding MCP and Skills

What to expect: Learn how to use the Metadata Grounding MCP and the Salesforce Skills Library to ground AI coding agents. Build with Agentforce Vibes and Claude Code using prebuilt skills and trusted context.
Featured speakers: Gonzalo Gambino, Sally ElGhoul
Add this session to your agenda

Build Deterministic Agents with Agent Script

What to expect: Write reliable, testable, and deterministic agents using Agent Script in your IDE. Learn how to control agent behavior precisely, eliminate unpredictability, and ship with confidence.
Featured speakers: Tulsi Patel, Ismaen Aboubakare, Kevin Wang
Add this session to your agenda

Headless 360 sessions

Explore the Headless Experience Layer (HXL), Headless Data 360, and Hosted MCP Servers to bring intelligence into every surface and render rich interfaces anywhere.

Build Document AI Automation with Headless Data 360

What to expect: ​​Build end-to-end document automation with Agentforce Vibes and Document AI. Create extraction schemas and integrate with Flows, LWC, and Apex using headless patterns for document workflows.
Featured speakers: Ananth Anto, Nishan Naseer
Add this session to your agenda

Query Data 360 from Apex in Five Lines, Not 100

What to expect: Discover the Data 360 Apex query experience. Learn about synchronous and asynchronous SQL query patterns that replace complex Connect API integrations with minimal code and built-in test mocks.
Featured speakers: Geoff Rothman, Manuel Then
Add this session to your agenda

Roadmap sessions

Join Salesforce product leaders for exclusive insights into upcoming developer tools, MCP, Apex limits, and Agentforce 360 platform innovations.

Explore the Agentic App Dev Roadmap

What to expect: Get an overview of the new agentic app dev and governance tools on the Headless 360 Platform. See how to plan, build, test, deploy, and observe using the coding agents of your choice.
Featured speakers: Dan Fernandez, Karishma Lalwani
Add this session to your agenda

Explore the Data 360 Roadmap for Developers

What to expect: Preview upcoming Data 360 capabilities, including Catalog APIs and Python Code Extension enhancements. Learn how these investments will impact your architecture and development strategy.
Featured speakers: William Yeh, Rohit Dar
Add this session to your agenda

More product sessions

Explore more technical deep dives, real-world implementations, and platform best practices curated to sharpen your developer skills.

Accelerate Mobile App Development with Skills

What to expect: Use prebuilt Salesforce Mobile SDK skills with any coding agent. Quickly add authentication, offline sync, push notifications, and camera access to your mobile apps.
Featured speaker: Shalini Jain
Add this session to your agenda

Discover Apex Best Practices for Apps and Agents

What to expect: Explore asynchronous patterns, concurrency scaling, exception logging, trigger architecture, and other advanced Apex techniques for building production-ready agents and apps.
Featured speakers: Daniel Ballinger, Szandor Knapp
Add this session to your agenda

More things to check out at Dreamforce 2026

Explore opportunities for admins and architects

Looking to expand your perspective? Check out sessions on the admin and architect tracks to see how the Agentic Enterprise is being built, governed, and scaled in production. Explore the Admin and Architect Guides to Dreamforce 2026 for more can’t-miss experiences tailored to each role.

Grow your network at Community Cove

Community Cove is the destination for all Trailblazers to connect, learn, and celebrate 20 years of the Trailblazer Community. Catch career growth and thought leadership sessions in Trailblazer Theater, and dive into interest-based networking sessions. Be sure to design your custom Trailblazer card before you continue exploring everything else Dreamforce has to offer.

Get certified at Trailblazer Bootcamp

Go deeper at Dreamforce with Trailblazer Bootcamp. This is your opportunity to gain hands-on product expertise, elevate your skills, and build lasting connections with peers. It’s all happening from Saturday, September 12, to Monday, September 14, 2026. Learn more about this pre-Dreamforce bootcamp and jumpstart your certification goals.

Experience Dreamfest at Oracle Park

Dreamfest, the ultimate Dreamforce celebration and Concert for Kids, will be on Wednesday, September 16, 2026 from 6:00 p.m. – 10:00 p.m. at Oracle Park to benefit UCSF Benioff Children’s Hospitals. Dreamfest is included with your in-person Dreamforce registration. All you need to attend is your Dreamforce conference badge and a government-issued ID. Stay tuned for performance announcements.

Quick Dreamforce tips

Watching from home? Join on Salesforce+

Can’t make it to Dreamforce in person? Select keynotes and sessions will be live-streamed on Salesforce+ during the entirety of the event. In addition to the live experience, a selection of on-demand episodes will be available for viewing once Dreamforce concludes.

Register for Salesforce+ for free to get access to featured content.

Accessible Guide to Dreamforce 2026

Explore what to expect throughout Dreamforce this year from a first-person explanation of the event, discover accessibility services and accommodations, and find resources to help you plan the experience that’s right for you.

Your Dreamforce 2026 checklist

Dreamforce 2026 will be here before you know it. Take these steps now to prepare for the big event.

• Register to attend Dreamforce if you haven’t already. 
• Start building your perfect Dreamforce agenda now with My Agenda. Refer to the sessions in this post to guide you. 
• Download the Salesforce Events app in the App Store or Google Play Store to keep track of everything on your agenda in one easy-to-access place.
• If you’re not attending in person, be sure to register and watch on Salesforce+. 
• Follow Salesforce Developers on X and LinkedIn for more Dreamforce updates.

About the author

Sarah Welker is a Developer Marketing Manager at Salesforce. She balances her love for sustainable shopping and Sunday league soccer with a mission to visit every MLB ballpark, while maintaining her status as her kids’ #1 fan on the sidelines. Find her on LinkedIn.

The post The Salesforce Developer’s Guide to Dreamforce 2026 appeared first on Salesforce Developers Blog.

In this post, we’ll present the key components of headless development and explore how Salesforce enables this approach at scale. We’ll also introduce a Claude Code plugin that streamlines the practice before sharing what’s on the roadmap.

The components of headless development

Headless development relies on a few main components: agent skills, MCP servers, and agent plugins.

Agent skills

Agent skills are reusable, validated instructions that teach AI agents how to perform specific tasks. A skill is a folder that contains a SKILL.md markdown file. The file has a header with a set of standard attributes (name and description at a minimum) followed by free-text instructions. Skills can also include subfolders and files such as templates or scripts.

Thanks to a detailed specification, skills are interoperable across agents. Skills work with a lazy-loading mechanism: only skill names and descriptions are initially loaded in the agent context. When running a prompt, the agent determines which skills it needs to activate, and then loads them in context.

MCP servers

The Model Context Protocol (MCP) is an open-source standard that provides a standardized way to connect AI applications to external systems. MCP helps by decoupling AI agents from API clients for those external systems. Agents embed a standard MCP client that can connect to any MCP server. Service providers ship MCP servers that interact with their systems’ APIs and expose MCP tools, prompts, and resources to agents. Thanks to this standard, connecting agents to external systems becomes plug and play just like using USB-C.

Agent plugins

Setting up a headless development environment requires that you retrieve skills and configure MCP servers. This can be time-consuming during initial setup and a bother to keep up to date. Agent plugins are precisely designed to address these pain points.

Plugins package skills, MCP servers, and other utilities into a single installable unit for a specific AI platform. This simplifies setup and eases maintenance over time as there’s generally an update mechanism for plugins. A key limitation of plugins at the time of writing is that they remain AI vendor-specific, unlike skills and MCP servers, which are standard.

How Salesforce is scaling headless development

Salesforce skills are evolving

Salesforce ships a collection of over a hundred skills for development across its clouds and products in the open-source Salesforce skills library (sf-skills) GitHub repository.

Each skill focuses on a narrow capability such as generating Apex classes, running Data 360 queries, designing mobile apps, generating OmniScript, and more. Each skill includes context about the platform, best practices, and error handling.

The Salesforce skills library comes pre-installed in Agentforce Vibes. You can install some or all of its skills in the agentic environment of your choice (for example, OpenCode, Claude Code, Codex, or Cursor) by running this interactive command (requires Node.js):

npx skills add forcedotcom/sf-skills

With Salesforce driving headless development across products, the number of available skills has skyrocketed since the launch of the skills library. And, with multiple teams contributing, it became clear that strict governance is needed to manage skills at scale to ensure discoverability and distribution.

Improved discoverability

Developers and agents can’t predict skill names (should a skill be named “generate-X”, “build-X”, or “create-X”?). The problem becomes ever more visible as coverage for multiple products and features is added to the mix. Without a structured and defined taxonomy, skills fall out of step with how Salesforce officially names and groups features. This leads to developer frustration and agents that can’t execute tasks effectively or consistently.

To prevent this, skills have been renamed in accordance with a well-defined taxonomy. For example, the dx-devops-test-failures-analyze skill belongs to the following classification path: DX > DevOps > Test > Failures Analyze.

To prevent context dilution and structural drift as multiple teams and individuals contribute to the library over time, an automated, gated verification pipeline ensures skills are checked for taxonomy alignment, accuracy, and expected outcomes before they are cleared for distribution.

Robust distribution

In initial releases of the skills library, skills were not individually versioned (only the library was versioned) and dependencies weren’t expressed in a standardized manner. As skill instructions and dependencies were updated, these changes could occasionally introduce undocumented behavior changes in dev workflows.

To provide more visibility and control over skills, we’ve used skill metadata to define individual skill versions and dependencies. For example, below is the header of the dx-org-manage skill. Note the metadata section that includes the skill version, minimum required Salesforce API version, related skills, and dependencies.

Introducing the Salesforce development plugin for Claude Code

The Salesforce development plugin is our first official plugin, built for Claude Code, Anthropic’s AI-powered command-line development tool. This plugin transforms Claude from a general-purpose coding assistant into a Salesforce development expert.

Here are the details of what’s included in the Salesforce development plugin for Claude Code: a collection of Salesforce development skills, MCP servers, specialized agents, hooks, and commands.

Salesforce development skills

The plugin bundles a subset of about 40 skills from the Salesforce skills library. This collection of skills covers core Salesforce development. Skills for other clouds and features (including Data 360, Commerce, and mobile development) are not included in this plugin. We plan to collect feedback on this initial plugin before shipping dedicated plugins for these domains.

Specialized agents

The plugin includes specialized Claude agents that automatically activate based on context:

• salesforce-dev: The primary development agent that auto-detects Salesforce projects and routes requests through skills → Salesforce CLI → Salesforce APIs in that priority order.
• architecture-review: A read-only agent that grades your project against the Well-Architected pillars (Trusted, Easy, Adaptable) and provides a governance checklist.
• Agentforce Development Lifecycle (ADLC) agents: A set of specialized agents for authoring, engineering, and testing Agentforce agents.

Salesforce MCP servers

The plugin exposes three MCP servers that provide Claude with deep platform integration without requiring that you configure them manually one by one:

• salesforce-api-context: Offers API and metadata guidance.
• salesforce-metadata-experts: Provides expert knowledge about Salesforce metadata types.
• salesforce-lsp: Hosts local Apex and SOQL language servers, exposing semantic capabilities (diagnostics, completions, and code actions) as MCP tools. This means that Claude can perform real-time Apex syntax validation, suggest code fixes, and provide intelligent completions just like the Salesforce Extensions for VS Code, but from the terminal.

Hooks

The plugin ships with custom Claude Code hooks. A hook is a shell command that automatically runs in response to specific events, like before/after tool calls or when certain actions occur. They let you extend Claude Code’s behavior without changing the core tool.

Here are some examples of hooks that ship with the plugin:

• Automated context discovery: When Claude Code starts or changes directories, a hook runs to detect whether the folder is a Salesforce DX project and, if so, loads information such as the default org.
• Agent Script syntax validation: When a .agent file is edited, a hook runs an Agent Script syntax validation command.
• Deployment validation: When a metadata deployment command runs, a hook validates the deployment result and analyzes potential errors.

Commands

The plugin ships with a set of convenient commands that let you run operations from the Claude Code interface such as:

• A /setup command for validating the state of the plugin and the org.
• A /discovery command for exploring available skills.
• A set of utility commands that act as shortcuts for common CLI commands such as getting the status of the default org (/org), logging into an org (/login), or logging out of an org (/logout). These are convenient as you can’t directly run Salesforce CLI commands from within the Claude Code interface and calling the related MCP tools for simple tasks like these is overkill.

Getting started with the Salesforce development plugin

Setting up the plugin is straightforward:

1. Install the prerequisites:
   • Claude Code
   • Node.js LTS (v22 or v24 at time of writing)
   • Salesforce CLI
   • Python 3.8 or above. This is only required for some internal hooks related to org detection and deployment safety. The Python requirement may go away in future versions. Check the official setup instructions for the latest information.
2. Open any Salesforce DX project and authenticate to an org with the Salesforce CLI:
   

   sf org login web --alias my-org --set-default
   

3. In Claude Code, add the Salesforce Claude Plugin Marketplace and install the plugin:
   

   /plugin marketplace add forcedotcom/sf-skills
   /plugin install salesforce-development@salesforce
   

4. Validate your environment in Claude Code (optional but recommended):
   

   /salesforce-development:setup
   

That’s it. Claude will automatically detect your org context from your project and activate the salesforce-dev agent. You can now use natural language prompts like:

• “Create an Apex service class to handle Account territory assignments”
• “Generate a Project__c custom object with fields for Status, Due Date, and Priority”
• “Deploy the project to my org”
• “Write a test class for AccountTerritoryService and run it”

What’s next

We’re expanding development plugins across the AI agent ecosystem. Upcoming work (subject to change) includes:

• Claude Cowork plugin: Bringing skills to Anthropic’s collaborative agentic workspace
• Open-source plugin architecture: Community-contributed plugins for domain-specific use cases (Agentforce Service, Agentforce Sales, Agentforce Commerce)
• Coding Agent Platform Governance (CAP-G): Integration with governance tools for session tracking, policy enforcement, and compliance reporting

Expanding development plugins is the first step in shipping plugins for broader use cases. We are considering options and frameworks to ship plugins for knowledge workers. For instance, you could see an Agentforce 360 for Automotive plugin with a set of business skills, custom, hosted MCP servers preconfigured with access to business processes, and more.

Conclusion

This concludes our tour of how Salesforce is scaling headless development from expanding skills and MCP servers to the adoption of plugins. You learned about governance applied to skills, the launch of our first Salesforce development plugin for Claude Code, and our plans for additional plugins.

Try the Salesforce development plugin today and remember that Salesforce skills and plugins are open-source initiatives. You can participate by exploring the skills and plugins repository and sharing your feedback on GitHub.

Resources

• Plugin homepage
• Salesforce skills library repository
• Claude Code documentation
• Salesforce Hosted MCP Servers
• Plugin development guide

About the author

Philippe Ozil is a Principal Developer Advocate at Salesforce, where he focuses on the Salesforce Platform. He writes technical content and speaks frequently at conferences. He is a full-stack developer and enjoys working with APIs, DevOps, robotics, and VR projects. Follow him on X, LinkedIn, and Bluesky, and check out his GitHub projects.

The post Headless Development with Skills and a Claude Code Plugin appeared first on Salesforce Developers Blog.

Nevertheless, the Omnistudio standard runtime is the future, offering new innovations and faster performance. Whether you’re migrating from a Vlocity Industries managed package or the Omnistudio Foundation package, the standard runtime removes the need for managed package installations. And now you can simplify this process. The Omnistudio Migration Assistant (OMA) tool is specifically designed to automate the heavy lifting, making your move to the standard runtime fast and simple.

Note: Package uninstallation is not recommended as existing org workflows and custom components may still rely on package schema or underlying metadata.

Omnistudio evolution: From managed packages to the standard runtime 

Before we dive into the “how,” let’s review a brief history of where Omnistudio started, where it’s going, and where you might fit in:

Before the acquisition: Initially, customers were dependent on Vlocity Industries managed packages, such as Communications, Media, and Energy (CME), Insurance, and Public Sector, to use Omnistudio components on the Vlocity Industries managed package runtime.

After the acquisition: Following the acquisition, these Vlocity Industries managed packages remained, but the Omnistudio Foundation package was created for customers using solutions like Financial Services Cloud (now Agentforce Financial Services) or Health Cloud (now Agentforce Health). Now, some customers are on the managed package runtimes and some are on the standard runtime.

The future: Our goal is to bid goodbye to the managed packages and their runtimes and move toward a package-free Omnistudio experience by transitioning all customers to the Omnistudio standard runtime.

Benefits of migrating to the standard runtime

Here are the benefits of making the switch to the Omnistudio standard runtime:

Massive performance gains

Who doesn’t want a faster system? Moving to the Omnistudio standard runtime delivers incredible runtime performance gains for your end-users on the Salesforce platform. Depending on your configuration, your runtime architecture will execute 2x to 5x faster, with Flexcards delivering up to 5x better performance, Integration Procedures processing data up to 4x faster, Data Mappers providing up to 3x faster data mapping and transformation, and Omniscripts delivering up to 2x faster interactive guided experiences.

Note: All data presented above is derived from internal testing, which showed that execution averaged 2112 ms on the standard runtime versus 5061 ms on a managed package runtime.

Zero functionality loss

The standard runtime completely supports all critical business functions, providing a faster experience with no compromise on capability.

Access to the latest innovations

Business logic and components can transition directly to the standard runtime, which offers a more native experience within the Salesforce platform, reducing the overhead typically associated with managed packages.

Staying on a managed package runtime means you risk missing out on the new product innovations, including Agentforce integration for your Integration Procedures, design assistance, and Lightning Web Runtime (LWR) support for your Experience Cloud implementations.

Simplified deployment

Deploying changes is significantly easier. Standardized Salesforce CLI-based deployments replace the older, complex Vlocity build tools. This reduces the time and complexity of your deployments, ensuring that future patches, bug fixes, and upgrades are smooth.

Find your transition path

Every business has a slightly different setup. Use the following table to identify the transition path for your specific setup:

Note: Beginning with Summer ’25, Omnistudio is package-free for new customers. Designers and runtime are available natively with supported cloud licenses.

Managed package runtime versus standard runtime

Let’s briefly review the core differences between the managed package runtime and the standard runtime. The runtime describes the look and feel of your configured Omnistudio components:

• Managed package runtime: This legacy environment is highly flexible but relies on an older architecture. It supports both the custom data model (which uses custom objects provided by Industries managed packages) and the standard data model.
• Standard runtime: This is the native, modernized environment on the Salesforce platform. It operates strictly on the standard data model (using standard Salesforce objects) and does not support custom objects from the legacy managed packages.

What is the Omnistudio Migration Assistant (OMA)?

The OMA is a handy Salesforce command-line interface (CLI) plugin built specifically to help you automatically move your Omnistudio components from a custom data model (industry-specific or package-based data structures, such as those from managed packages, where objects and relationships are predefined within the package) to the standard data model (the native Salesforce data structure, using standard objects and custom objects built directly on the platform). It takes the components you’ve already built, such as Flexcards, Omniscripts, Data Mappers, and Integration Procedures, and smoothly shifts them to the standard runtime.

No one wants to manually update hundreds of components piece by piece. Luckily, the OMA tool automates most of the migration effort. It handles the tedious, repetitive tasks for you, such as automatically updating namespace references and managing complex dependencies. This enables a much faster migration process and significantly reduces the chance of human error.

Using the OMA tool can reduce your team’s manual efforts in migration by 95%. While it handles much of the migration, a few unique items (such as rebuilding older Angular-based components or mapping industry-specific objects) will still need manual attention.

How the migration process works

Migrating your entire system might sound like a massive undertaking, but the process is highly structured and controlled. To make the transition as smooth as possible, let’s understand it in three manageable phases: development, testing, and production.

First things first. Before jumping into the first phase, install the plugin. Open your terminal and install the recommended OMA plugin version: sf plugins install @salesforce/plugin-omnistudio-migration-tool@2.0.0-rc.57

Next, assess exactly where you currently stand and plan how you will migrate. You should never run a migration directly on your live system. Instead, start by creating and refreshing a sandbox from your production org to provide a safe environment for the migration. In this environment, you will set up your detailed test flows and outline all of your critical business workflows to prepare for the move.

Note: Upgrade to the Vlocity Industries managed package version Winter ’26 or later before starting the migration process, regardless of your transition path.

Phase 1: Development (with Assess and Migrate modes)

This is the phase where the OMA really gets to work. It has four steps.

1. Run your baseline tests: Before you even touch the OMA tool, you should run your full automation suite, including sanity checks, business workflows, smoke tests, and regressions, and carefully record the results. This gives you a reliable baseline to compare against later.
2. Run Assess mode: Next, run the OMA tool in Assess mode. It generates a highly detailed report of your Omnistudio configuration, flagging exactly what needs your attention, such as namespace issues or older Angular-based components. Analyze your components for potential migration blockers without modifying any data. Use the -a flag to assess all component versions: sf omnistudio:migration:assess -u dev_sandbox_username@domain.com -a
   Tip: You can isolate the analysis by appending –only=dm,ip to target specific components.
   
3. Fix issues: Now it is time for a little manual intervention. Your team will manually fix the specific issues identified in the assessment report. Once fixed, simply rerun Assess mode until the report comes back completely “green” and error-free.
4. Run Migrate mode: With a green light, you can now run the tool in Migrate mode to actually move your components over to the standard runtime. What gets moved depends on your current setup: if your Omnistudio Metadata setting is enabled, the tool will only migrate your package dependencies. If your setting is disabled, the tool will migrate both your Omnistudio assets and the package dependencies. Once your assessment report is green, use the following command to execute the actual metadata migration: sf omnistudio:migration:migrate -u dev_sandbox_username@domain.com -a

Phase 2: Validation

This phase is all about testing. Once the migration steps are complete in your development sandbox, you’ll deploy those freshly migrated components over to a new, clean test sandbox. In this environment, you need to perform thorough regression testing, running all of the automation test suites you recorded back in Phase 1. This ensures that every single business flow works flawlessly before your users ever see the changes.

Phase 3: Production 

You’ve made it to the finish line! After your sandbox and test-environment validations are complete, it’s time to deploy those tested changes into your production environment. Once deployed, you’ll perform a few final readiness checks, like assigning the proper permission sets to your users, and perform post-deployment validation. Congratulations, you’re now officially running on the Omnistudio standard runtime!

Scenario-specific migration process variations

The three-phase migration process described above applies across scenarios, but some steps differ depending on your current managed package and data model configuration. 

For customers using Vlocity Industries managed packages with the standard data model, the process looks like:

• Development phase: After upgrading your sandboxes to the latest release and migrating any older calculation logic to the Business Rules Engine (BRE), run the OMA tool in Assess mode. Then, after you have manually resolved any flagged issues, run the tool in Migrate mode to convert your components. Finally, turn off the “Managed Package Runtime” and “Managed Package Designer” settings.
• Validation phase: Here’s the key difference in the validation phase: you only run the OMA tool to move your Omni Global Auto Numbers. For everything else (like Flexcards and Omniscripts), you’ll manually switch your settings to the standard runtime and use standard deployment tools (like VS Code) to push the migrated components over from your development sandbox. Test everything thoroughly.
• Production phase: Prepare your production org by enabling Omnistudio Metadata API support. Just like in the Validation phase, you only run the OMA tool to migrate your Global Auto Numbers. Then, deploy your fully tested components from the test sandbox, switch off the “Managed Package Runtime” and “Managed Package Designer” settings, and validate your live workflows.

For customers using the Omnistudio Foundation package with the standard data model, the migration is a bit more streamlined.

• Development phase: Start by upgrading your Foundation package and moving calculation logic to the BRE. Run OMA in Assess mode, fix any flagged issues manually, and run it again in Migrate mode. The tool will automatically update references and strip away package dependencies for you.
• Validation phase: There’s a notable difference here: Omni Global Auto Numbers aren’t supported in this use case because they don’t exist in the Omnistudio namespace. Because of this, you don’t run the OMA tool at all in this phase. Simply switch your sandbox settings to the standard runtime and use standard deployment tools (like VS Code) to bring your migrated components over from the development sandbox. Run your full suite of regression tests.
• Production phase: In your production org, enable Omnistudio Metadata API support. Switch your settings to the standard runtime, deploy your successfully tested components from the test sandbox, validate your workflows, and you’re officially live on the standard runtime.

Migrate to all-new Omnistudio today

Migrating your Omnistudio components from the managed package runtime to the Omnistudio standard runtime is no longer the daunting, manual chore it used to be. OMA does most of the heavy lifting. Moving to the standard runtime means you can enjoy up to 5x better runtime performance, vastly simplified deployments, and immediate access to cutting-edge features like Agentforce integration.

Don’t let a managed package runtime hold you back from the platform’s latest innovations. Download the OMA tool via the Salesforce CLI and migrate to standard Omnistudio to future-proof your business workflows today.

Resources

• Trailhead: Omnistudio Development Essentials 
• Trailhead: Omnistudio Omniscript Fundamentals
• External site: YouTube: Build Low-Code Digital Experiences with All-New OmniStudio  | TDX Bengaluru
• Documentation: Migrate Omnistudio Components from Vlocity Industries Managed Packages and Custom Data Model to Omnistudio Standard Runtime

About the author

Kishore Kumar Kurri is a Principal Member of Technical Staff (PMTS) at Salesforce with nearly 20 years of software engineering experience. He’s part of the Industries Common Services – OmniStudio team, specializing in cloud performance, AI-driven features, and developer tooling at platform scale. Kishore has led key initiatives, including Omnistudio’s Connect API modernization, the OmniStudio Migration Assessment (OMA) tool, and Command Center Live Cards for OmniSupervisor. His work focuses on scalability, customer trust, and engineering excellence across Salesforce’s intelligent cloud experiences. Connect with him on LinkedIn.

Krishna Kruthiventi is a Senior Product Manager at Salesforce, specializing in Industries Cloud solutions. His primary focus is on the Omnistudio product suite on simplifying complex enterprise workflows and elevating Omnistudio to deliver best-in-class, consumer-grade digital experiences for both administrators and end users. Follow him on LinkedIn.

Payal Verma is a Content Marketing Analyst at Salesforce with over 4 years of professional experience in product, brand, and content marketing. She’s worked across both B2B and B2C markets, developing and executing content strategies for a wide range of formats, including blogs, social media, scripts, e-books, guides, etc. Follow her on LinkedIn.

The post Migrate From Managed Package Runtime to the Omnistudio Standard Runtime appeared first on Salesforce Developers Blog.

※本記事は2026年7月22日に米国で公開された Build Production-Ready Apps in Claude Code with Salesforce Skillsの抄訳です。本記事の正式言語は英語であり、その内容および解釈については英語が優先されます。

Claude CodeのSalesforceスキルを使うと、自然言語で指示するだけで、本番品質のApexコード、Lightning Webコンポーネント（LWC）、テストクラスを生成できます。生成されたコードはSalesforce Code Analyzer（英語）のチェックに自動的に合格し、テストのコードカバー率も75%以上を達成します。つまり、必要なものを簡単な言葉で説明するだけで、あとはClaudeがSalesforceのベストプラクティスに従った、そのままデプロイできるコードを生成してくれるのです。

この記事では、LWC、Apexコントローラー、テストクラスを組み合わせて、完全な取引先作成フォームを構築する流れを見ていきます。その後で、スキルシステム内部の仕組みを説明し、バッチジョブ、サービスレイヤー、デバッグワークフローなどの高度なパターンを取り上げます。

Salesforceスキルとは

Salesforceスキルは、Salesforceのアーキテクチャー、ガバナ制限、セキュリティパターン、デプロイ要件を理解している、Salesforceに特化したAI機能です。いわば、開発ワークフローに熟練の開発者が直接組み込まれているようなものと考えてください。

Claude Codeに「取引先作成フォームを作成して」と指示すると、生成されるのは、単なる汎用的なコードではありません。generating-apexスキルがプロジェクトの規則やパターンを理解し、適切なエラー処理とガバナ制限を考慮したクエリーを含む、本番品質のコードを生成します。また、ループ内でのSOQLの実行を防ぐといったガードレールを適用し、一括処理化のパターンを検証します。続いて、TestDataFactoryパターンを使用し、75%以上のコードカバー率を達成するテストクラスを作成します。タスクを完了する前に、Salesforce Code Analyzerを実行し、テストスイートも自動的に実行します。

スキルの仕組み

Claude Codeに指示を出すと、システムは4つの段階からなるワークフローに沿って動作します。まず、Claudeがプロンプトの内容を分析し、適切なスキルに対応付けます。たとえば、「Lightning Webコンポーネント」というキーワードがあればgenerating-lwc-componentsが有効になります。プロンプトに「Apexクラス」が入っていればgenerating-apexが、「テストクラス」ならgenerating-apex-testが起動します。

該当するスキルが特定されると、それぞれのスキルがワークフローを実行します。generating-apexは、命名パターンや既存のクラスなど、プロジェクトの決まりを把握します。サービス、コントローラー、バッチ、その他のアーキテクチャーから適切なパターンを選択し、assetsディレクトリ内のテンプレートを確認します。続いて、共有ルールを適用し、ループ内でのSOQLの実行を防ぐガードレールを組み込んだクラスを生成します。次に、generating-apex-testスキルを呼び出し、網羅的なテストを作成して十分なコードカバー率を確保します。

このプロセス全体を通じて、スキルがガードレールを自動的に適用します。スキルは、ループ内でクエリーを実行するコードを拒否し、すべてのクラスに共有ルールを強制し、テストクラスを生成するまで処理を完了しません。Lightning Webコンポーネントについては、クライアント側とサーバー側の両方が所定のパターンに従っているかどうかを検証します。各スキルは.cls-meta.xmlなど、必要となるメタデータファイルも自動で生成します。

最後に、スキルはタスクの正常完了を報告する前に、生成したコードを検証します。sf code-analyzerを実行してセキュリティ上の問題を検出し、sf apex run testを実行してコードが正しく動作することを確認し、75%以上のコードカバー率を確保します。その結果、単なる定型コードではなく、本番運用を想定したコードが生成されるのです。

チュートリアル – 取引先作成フォームの作成

では、実際に機能を作成してみましょう。このチュートリアルでは、検証、エラー処理、テストまで含めた、取引先レコード作成用のLightning Webコンポーネントフォームを構築します。

概要

ここでは、3つの要素で構成される完全なソリューションを作成します。3つの要素とは、取引先名と電話番号を入力項目として持つLightning Webコンポーネント、@AuraEnabledメソッドとエラー処理を備えたApexコントローラー、75%以上のコードカバー率を確保し、251件以上のレコードで一括処理をテストするテストクラスです。フォームにはインライン検証とトースト通知を実装し、アプリケーションビルダーに追加してホームページに配置できる状態にします。

事前準備

構築に取りかかる前に、Claude Code（個人開発者は無料）と、Node.js（スキルのインストールに使用）がインストールされていることを確認してください。また、組織に対して、Salesforce CLIの認証を済ませておいてください。この例では開発者向けエディションの組織、Sandbox組織、またはスクラッチ組織のいずれかが必要です。まだ認証していない場合は、sf org login webを実行してください。

Salesforceスキルをインストールする

Salesforceスキルのセットアップは、コマンドを1つ実行するだけで完了します。Salesforceプロジェクトのディレクトリに移動し、次のコマンドを実行してください。

npx skills add forcedotcom/sf-skills

これで、GitHubからSalesforceスキルの公式ライブラリが取得されます。

スペースキーを使って、インストールするスキルを選択します。このチュートリアルでは、以下のスキルを選択してください。

• generating-apex：Apexクラスを生成
• generating-apex-test：Apexテストクラスを生成
• generating-lwc-components：Lightning Webコンポーネントを生成
• debugging-apex-logs：Apexクラスをデバッグ

Enterキーを押してインストールします。

インストールの範囲は、次のいずれかを選択できます。

• Project：現在のディレクトリにインストール（プロジェクトと一緒にコミット）
• Global：ホームディレクトリにインストール（すべてのプロジェクトで利用可能）

これで、Salesforceプロジェクトでスキルを利用できるようになります。インストール済みのスキルは、プロジェクト内のskills-lock.jsonに記録されます。

skills-lock.jsonファイルを開くと、インストール済みのすべてのスキルを確認できます。

現在、forcedotcom/sf-skillsライブラリには60以上のスキルがあり、その数は増え続けています。スキルの一覧は、公式のsf-skillsリポジトリ（英語）で確認できます。

利用可能なすべてのスキルをインストールするには、--allフラグを追加してください。

npx skills add forcedotcom/sf-skills --all

注 – Salesforceスキルは、npmパッケージとしては提供されていません。また、「skills」npmパッケージ（英語）は、Salesforceが所有しているものではありません。Salesforceは、このパッケージをGitHubリポジトリにあるスキルを簡単にインストールするために利用しています。

ステップ1：Claude Codeを起動する

プロジェクトディレクトリでClaude Codeを起動します。

claude

Claude Codeの対話型プロンプトが表示されます。ここから、Claude Codeが威力を発揮します。

ステップ2：指示を入力する

以下のプロンプトを入力するか、コピーして貼り付けます。

以下の要素で構成される、完全なSalesforceソリューションを作成してください。

1. Lightning Webコンポーネント（LWC）
accountCreationFormという名前で、次の2つの入力項目を持つフォームコンポーネントを作成してください。
- 取引先名（必須）
- 電話（必須、10～15桁の数字）
- 両方の項目の入力値が有効になるまで、［保存］ボタンを無効にする
- 入力検証のエラーメッセージをインラインで表示する
- 保存に成功した場合は成功のトースト通知を、失敗した場合はエラーのトースト通知を表示する
- 読み込み中はスピナーを表示する

2. Apexコントローラー
- AccountCreationControllerクラスを作成する
- メソッド：@AuraEnabled(cacheable=false) saveAccount(String accountName, String phone)
- 標準の電話項目を使用する（取引先には標準のメール項目がありません）
- AuraHandledExceptionを使用して、適切なエラー処理を実装する
- コードカバー率が85%以上になるテストクラスを作成する

3. アプリケーションビルダーとの統合
- アプリケーションページとホームページで使用できるよう、*.js-meta.xmlを設定する
- デプロイ手順を示す

制約：
- DML処理であるため、@wireではなくApexメソッドを命令として呼び出してください
- SalesforceのLWCベストプラクティスに従ってください
- 標準オブジェクトと標準項目のみを使用してください

上記の要件をすべて含む、取引先作成フォームのプロンプトをターミナルに入力すると、次のように表示されます。

ステップ3：スキルの動作を確認する

プロンプトを入力すると、Claude Codeは適切なスキルを自動的に有効にします。UIにはgenerating-lwc-components、コントローラーにはgenerating-apex、テストにはgenerating-apex-testが使用されます。

Claude Codeは、既存の命名規則やアーキテクチャーレイヤーを含む、プロジェクトのパターンを検出します。続いて、必要なファイルをすべて生成します。

• accountCreationForm.html: Lightning Webコンポーネントのテンプレート
• accountCreationForm.js: Apexメソッドを命令としてコールするコンポーネントロジック
• accountCreationForm.js-meta.xml: アプリケーションページとホームページに公開するためのメタデータ
• AccountCreationController.cls: エラー処理を実装したApexコントローラー
• AccountCreationController.cls-meta.xml: Apexメタデータファイル
• AccountCreationControllerTest.cls: テストメソッドを含むテストクラス
• AccountCreationControllerTest.cls-meta.xml: テストメタデータファイル

ステップ4：生成されたコードとテストクラスをレビューする

生成されたコードとテストクラスの内容を確認します。Salesforceスキルによって、本番運用を想定したコードとテストクラスが生成されていることを確認できます。Apexクラスのコードカバー率も100%に達しています。

ステップ5：ソリューションをデプロイしてテストする

Claudeを使用しているため、ソリューションのデプロイとテストもClaudeが手伝ってくれます。または、Salesforce CLIコマンドを使用することもできます。

ステップ6：組織のホームページにコンポーネントを追加する

［設定］→［Lightningアプリケーションビルダー］に移動し、［新規］をクリックして［ホームページ］を選択します。［2つの範囲］などのテンプレートを選択します。［カスタム］コンポーネントセクションから［AccountCreationForm］をページ上にドラッグします。［保存］、［有効化］、［組織のデフォルトとして割り当て］の順にクリックします。

以下のスクリーンショットでは、Lightningアプリケーションビルダーで、［カスタム］コンポーネントパネルにaccountCreationFormコンポーネントが表示され、ホームページのレイアウトに配置されています。

ステップ7：Salesforce UIでテストする

Salesforce組織のホームページに移動し、コンポーネントをテストしてみましょう。［取引先名］を空欄にすると、エラーメッセージが表示されます。9桁の無効な電話番号を入力しても、エラーメッセージが表示されます。有効なデータを入力すると、［保存］ボタンが有効になります。

このチュートリアルでは、1つのLWCとApexコントローラーを組み合わせたパターンを取り上げましたが、スキルは、Database.Statefulを使用するバッチジョブ、サービス、セレクター、ドメインの各レイヤーで構成されるアーキテクチャー、条件分岐を含む画面フロー、デバッグログの分析など、さらに複雑なシナリオにも対応できます。

Salesforceスキルを使って構築できる4つのパターンを紹介します。

1. データを処理するバッチジョブの生成

Claudeへの指示：「2年よりも前のケースをアーカイブする、CaseArchivalBatchという名前のバッチApexクラスを作成してください。ClosedDate < LAST_N_YEARS:2に該当するケースを検索し、Status__cを’Archived’に更新してください。また、適切なエラー処理とログ記録を組み込んでください。75%以上のコードカバー率を確保するテストクラスを生成してください」

Claudeはgenerating-apexを起動し、CaseArchivalBatch.clsを生成します。このクラスは、エラーを追跡するためにDatabase.Statefulを実装し、適切なstart、execute、finishメソッドと、ループ内でSOQLを実行せず、ガバナ制限を考慮したクエリーを備えています。また、251件以上のレコードを使った一括処理テストを含むCaseArchivalBatchTest.clsも生成されます。

2. サービスレイヤークラスの構築

Claudeへの指示：「サービス-セレクター-ドメインパターンを使用し、取引先の請求先住所を一括更新するメソッドを備えたAccountServiceクラスを作成してください。メソッドのシグネチャは、updateBillingAddresses(Map<Id, Address> addressByAccountId)としてください。適切なエラー処理を組み込み、90%以上のコードカバー率を確保するテストクラスも作成してください」

Claudeは、with sharingキーワードを指定し、DMLを一括処理化したAccountService.clsを生成します。このクラスは、クエリーをAccountSelector.clsに委譲し、一部のレコードだけが成功した場合にも対応できるようにList<Database.SaveResult>を返します。ClaudeはTestDataFactoryパターンを使用したテストクラスも作成します。

3. 画面フローの作成

Claudeへの指示：「Lead_Qualificationという名前で、リード評価用の画面フローを作成してください。会社名、業種、年間売上の各項目に対応する画面を追加してください。売上に応じて適切なキューに振り分ける決定要素を追加してください。売上が100万ドルを超える場合はEnterprise Queueに、それ以外の場合はSMB Queueに割り当ててください」

Claudeはgenerating-flowを有効化し、Salesforceのベストプラクティスに従ったフローメタデータを生成します。

4. Apexログの分析

Claudeへの指示：「debug.log内のApexログを分析し、バッチジョブがガバナ制限に達している原因を特定してください」

Claudeはdebugging-apex-logsスキルを使用してログファイルを解析し、SOQL文とDML文を検出します。また、ループ内でSOQLを実行している箇所を特定し、CPU時間とヒープ使用量を報告して、最適化を提案します。

スキルを活用するためのベストプラクティス

プロンプトに具体的な情報を含めるほど、出力の質が高まります。「Apexクラスを作成して」ではなく、「名前と電話番号を検証して取引先レコードを保存する、AccountForm LWC用のApexコントローラーを作成して」といった指示にしてみましょう。項目のAPI参照名、オブジェクト間のリレーション、ビジネスロジックの具体的な要件も含めるとよいでしょう。

Claude Codeは対話形式のツールですので、最初の出力が期待どおりでなければ、変更を依頼できます。「そのコントローラーに一括処理時のエラー処理を追加して」、「テストクラスでTestDataFactoryパターンを使用するように変更して」と指示するだけです。スキルが対話全体のコンテキストを保持しながら、指示に応じてコードを更新します。

スキルは本番品質のコードを生成しますが、本番環境にデプロイする前に、必ず出力内容をレビューしてください。項目のAPI参照名が組織のスキーマと一致していることを確かめ、カスタムオブジェクトとカスタム項目がデプロイ先の組織に存在することも確認してください。共有ルールや項目レベルセキュリティを含む、セキュリティ設定のチェックも必要です。本番環境へのデプロイの前に、まずSandboxでテストし、さらに安全性を再確認するため、Salesforce Code Analyzerを手動で実行しましょう。

経験豊富な開発者であっても、スキルから新たに学べることがあります。ぜひスキルを使ってみてください。見逃していたベストプラクティスを発見できるかもしれません。またGiven/When/Thenパターンを使ったテストクラスの構成方法を理解し、セキュリティとパフォーマンスにとって重要なCode Analyzerのフラグを知ることもできます。スキルは自動化ツールであると同時に、開発を学ぶためのツールでもあります。

スキルをさらに活用する

ここまでスキルの実際の動作を見てきました。スキルライブラリ（英語）には60以上の利用可能なスキルが公開されています。こうしたスキルを使えば、FlexCardとIntegration Procedureを使用したOmniStudioソリューションの構築、Data 360データソースへの接続、B2Bコマースストアの作成、オーケストレーションと連携する画面フローの生成など、さまざまなことが可能になります。

さらに高度なパターンも試してみましょう。Trigger Actions Framework（TAF）を使って Trigger Frameworksを構築したり、Queueable with Finalizersを組み合わせて後処理ロジックを伴う非同期処理を実装したりすることもできます。また、Custom REST Resourcesを使って、適切なエラー処理を備えたバージョン付きのAPIを構築することもできます。

スキルはオープンソースです。そのため、リポジトリをフォークしてパターンをカスタマイズし、チームの命名規則をテンプレートに追加できます。組織固有のスキルを作成することも可能です。コントリビューションガイド（英語）を参考にして開発を始めてみましょう。

最後に、スキルを既存のワークフローと統合しましょう。スキルは、Claude CodeのVS Code拡張機能（英語）や、自動化ワークフローでコードを生成するCI/CDパイプラインとスムーズに連携します。また、プルリクエストを提出する前の一次レビュアーとして、コードレビュープロセスにも組み込めます。

まとめ

Claude CodeのSalesforceスキルによって、AIは単なるコード生成ツールから開発のエキスパートへと進化します。定型コードの記述や、ガバナ制限を考慮した実装を手作業で行わなくても、やりたいことを説明するだけで、Claudeが本番品質のパターンを使って形にします。

ApexやLWCの生成からログのデバッグまで、スキルはベストプラクティスを実践しながら、ワークフローを加速させます。そのため、開発者は実装作業の繰り返しに時間を費やすのではなく、ビジネス課題の解決に注力できます。

さっそく始めてみませんか？Claude Codeを無料でダウンロードし、Salesforceプロジェクトでnpx skillsを実行してforcedotcom/sf-skillsを追加しましょう。数分後には、自然言語で指示するだけで、本番環境に対応したコードを生成できるようになります。

質問がある方やスキルで構築したものを共有したい方は、Salesforceの開発者コミュニティに参加してください。LinkedInとX（旧Twitter）でつながることもできます。スキルを使った感想や体験を、ぜひお聞かせください。

関連情報

• Salesforceスキルライブラリ（英語）
• Claude Codeドキュメント
• Claude Code入門ガイド
• Agent Skillsの仕様（英語）
• Salesforce CLIリファレンス
• Trailhead：Lightning Web コンポーネントの基本
• Trailhead：Apexテスト

執筆者について

Akshata Sawantは、Salesforceのシニアデベロッパーアドボケート。Packt Publishingから出版された『MuleSoft for Salesforce Developers』の共著者です。詳しい経歴や実績については、LinkedInプロフィールをご覧ください。

The post Salesforceのスキルを活用して、Claude Codeで本番運用可能なアプリを構築する appeared first on Salesforce Developers Blog.

This provides your agents with the capacity to execute external computational logic, access third-party data repositories, or trigger microservices hosted on disparate platforms. The integration bypasses traditional Apex callouts or intricate middleware, utilizing a standardized protocol to link your agent with any remote MCP-compatible tool.

In this post, we will demonstrate how to deploy a timezone MCP server utilizing MuleSoft CloudHub, register the service within your Salesforce environment, and empower an Agentforce agent to leverage these tools through the robust MCP architecture.

Why MCP matters for developers

When Agentforce agents can call MCP-compliant tools, you gain:

• Standardized tool discovery: MCP servers advertise capabilities via tools/list. Salesforce automatically discovers available tools during registration.
• Zero custom Apex: MCP tool calls are JSON-RPC over HTTP. The platform handles serialization, authentication, and error handling.
• Secure external context: MCP servers can be secured with OAuth 2.0. Salesforce manages token acquisition and refresh automatically.
• Reusable infrastructure: One MCP server can serve multiple agents, orgs, or non-Salesforce AI systems.

Your tools become platform-agnostic services.

Why MuleSoft for hosting MCP servers

MuleSoft Anypoint Platform provides the exact primitives MCP requires out of the box:

• HTTP Listener: Mounts the /mcp endpoint with method routing. No framework boilerplate.
• DataWeave 2.0: Pure functional transformations handle JSON-RPC parsing, tool logic, and response formatting in a single expression.
• CloudHub: One-click deploy with auto-scaling, monitoring, and zero infrastructure management.
• Connected Apps: Client credentials grant for machine-to-machine auth. Salesforce consumes these natively.

The result: a production-grade MCP server with no external dependencies beyond the Mule runtime.

Example: Timezone MuleSoft MCP server

Our example server brings world clock and timezone conversion capabilities to Agentforce agents. It exposes four tools that handle the most common timezone queries.

All timezone logic uses DataWeave 2.0 with built-in timezone support — no external API calls. The server maps 50+ common cities (NYC, London, Tokyo, Dubai) to IANA timezone IDs (America/New_York, Europe/London, Asia/Tokyo). DataWeave handles offset arithmetic, date formatting, and timezone conversion in pure functional expressions.

MCP protocol methods

The MCP server implements three core methods: initialize (handshake), tools/list (catalog), and tools/call (invocation).

When Salesforce calls the server, requests flow through these stages:

1. Bearer token validation: Returns JSON-RPC error code -32000 (Unauthorized) if the Authorization header is missing or invalid
2. Method routing: Dispatches to the appropriate flow based on method field (initialize, tools/list, or tools/call)
3. Tool execution: For tools/call, extracts the tool name and arguments, then routes to timezone-specific logic
4. Response formatting: Wraps results in MCP content arrays: {“type”:”text”,”text”:”…”}

Production features

The server is deployed to CloudHub as a single JAR (0.1 vCores, Micro worker) with HTTPS auto-provisioned. OAuth 2.0 secures the endpoint via an Anypoint Connected App (client credentials grant) and an API Manager policy. The stateless design requires no session storage — it is fully horizontally scalable. CORS headers allow browser-based clients.

Ready to configure the MCP server on your MuleSoft (Anypoint Platform) instance? 

Grab the full source from our GitHub repo. Clone the repo, build the deployable JAR with ./build.sh, and upload it to CloudHub via Runtime Manager. The README.md walks you through the prerequisites, deployment steps, and how to verify the server.

Registering the MCP server in Salesforce

With the MCP server deployed and secured, we can now register it in Salesforce.

Pre-requisites:

• MuleSoft Anypoint subscription tier 
• Agentforce/Einstein enablement 
• Connected App with client-credentials grant 
• Agent Studio access
• CloudHub application

Import external MCP server

1. Open Setup → Quick Find → API Catalog → “MCP Server”.
2. Click Add MCP Server → Import External MCP Server.
3. Configure:
   • Label: TimezoneMCP
   • MCP server URL: Your CloudHub application URL (e.g., https://timezone-mcp-server.us-e2.cloudhub.io/mcp)
   • Authentication: OAuth 2.0
   • Identity provider URL: https://anypoint.mulesoft.com/accounts/api/v2/oauth2/token
   • Client ID: (from Connected App)
   • Client secret: (from Connected App)
4. Click Create and Continue.

What happens during registration

Salesforce performs these steps automatically:

1. Token acquisition: Calls the Identity provider URL with client credentials to obtain a Bearer token
2. MCP initialize: Calls the MCP server’s /mcp endpoint with method “initialize” to negotiate protocol version (2024-11-05)
3. Tool discovery: Calls method: “tools/list” to fetch the tool catalog
4. GenAiFunction creation: Creates Salesforce metadata records for each discovered tool

Add tools to allowlist

After discovery, Salesforce displays the four timezone tools. Select all four and click Add to Allowlist. This makes them available for use in Agent Script.

Agentforce integration: Invoking MCP tools via JSON-RPC

With tools registered, we can now configure an Agentforce agent to call them. This happens in Agent Script, the YAML-based DSL that defines agent behavior.

Incorporating MCP actions into Agent Script

Once imported, your MCP agents become available within the Asset library, allowing you to select the tool and add it directly to the subagent’s action.

1. Navigate to Agent Studio.
2. Click New Agent and select Agentforce Employee Agent.
3. Name your agent “Time Zone Assistant” and keep the default developer name.
4. Switch to Canvas View.
5. In the subagent section, click the + button to create a new subagent named “Time Zone Expert”.
   
6. Configure the subagent:
   1. Description: “Help users with Time Zone conversions and related questions.”
   2. Reasoning Instructions: “Leverage available tools to assist users with timezone conversions and related inquiries.”
7. Click Select Action and choose Add from Asset Library to import your registered Timezone tools.
   
8. Select the Time Zone MCP tools and click Add to Agent.
   
   
9. Choose Review and Validate: verify that the subagent properly displays the new actions in its configuration panel.
   
   
10. Click Save, then click Commit Version & Activate.
11. Navigate to Preview and test the setup by asking: “What is the current time in New Delhi?”

How RPC calls flow from agent to MCP server

When a user asks “What time is it in Tokyo?”, here’s the execution flow:

1. User input parsing: The agent’s reasoning model extracts city = “Tokyo” from natural language
2. Action selection: The @subagent.Timezone reasoning determines the get_current_time_action should be called
3. Target resolution: Salesforce looks up the GenAiFunction with DeveloperName
4. Token acquisition: Salesforce calls the MCP server’s token endpoint to get a Bearer token (cached for subsequent calls)
5. JSON-RPC invocation: Salesforce constructs and sends the following:
   

   {
     "jsonrpc": "2.0",
     "id": 1,
     "method": "tools/call",
     "params": {
       "name": "get_current_time",
       "arguments": {
         "city": "Tokyo"
       }
     }
   }
   

6. MCP server processing: The Mule flow validates the token, routes to the timezone logic flow, and returns the following:
   

   {
     "jsonrpc": "2.0",
     "id": 1,
     "result": {
       "content": [
         {
           "type": "text",
           "text": "Wednesday, July 3, 2026 12:40:30 AM JST (Asia/Tokyo)"
         }
       ]
     }
   }
   

7. Agent response: The agent receives the formatted time and responds: “The current time in Tokyo is Friday, July 3, 2026, 12:40 AM JST (Japan Standard Time).”
   

The entire exchange happens over HTTP — no Apex, no custom callouts, no manual credential management. Salesforce handles token refresh, retries, and error handling automatically.

Conclusion

By implementing MCP over MuleSoft and connecting it to Agentforce, you’ve created a reusable, OAuth-secured tool server that any MCP-compatible agent can call. This same pattern applies to real-time inventory queries, shipping label generation, knowledge base retrieval, and multi-step external workflows.

Resources

• Documentation: Model Context Protocol (MCP)
• Documentation: MCP for Agentforce

About the authors

Parvinder Singh is a Senior Forward Deployed Engineer at Salesforce with deep expertise in Salesforce and Agentforce, specializing in building intelligent, customized agent experiences for enterprise customers. He is passionate about sharing developer insights with the community and bringing practical, field-tested patterns to life through hands-on content.

Alex Martinez was part of the MuleSoft Community before joining MuleSoft as a Developer Advocate. She founded ProstDev to help other professionals learn more about content creation. In her free time, you’ll find Alex playing Nintendo or PlayStation games and writing reviews about them. Follow Alex on LinkedIn or in the Trailblazer Community.

The post Extending Agentforce with External MCP Tools via MuleSoft appeared first on Salesforce Developers Blog.