AI agents can write this code on behalf of the developer, but without deep Salesforce Connect context, AI agents hallucinate. They write Apex that looks correct but misses required columns, uses wrong field types, or returns a malformed TableResult. What promised speed becomes hours of debugging validate and sync failures.

That changes with the platform-salesforce-connect-adapter-generate skill.

Developers can now use a coding agent to carry out the entire end-to-end integration workflow and build a complete, working adapter, including Apex classes.

This blog post covers what the skill does, how it structures the generated code, and how it uses the Salesforce Headless 360 MCP Server to register your adapter, reducing the manual work required in Salesforce Setup to a single click

What is a custom Apex adapter in Salesforce Connect?

The Salesforce Connect custom Apex adapter type lets you build your external data source by connecting with any REST API as a first-class external object. External objects look and behave like native Salesforce records where they show up in related lists; work in SOQL, flows, reports; and support platform features like sharing and field-level security. The data is never stored in Salesforce. Every query fires a live callout.

To build one, you implement two Apex classes from the DataSource namespace:

• DataSource.Provider: This class declares what your adapter supports: which objects it exposes, which query capabilities it has, and which authentication method it uses.
• DataSource.Connection: This class handles the actual API calls. It receives a QueryContext, calls your external system, maps the response to Salesforce field types, and returns a TableResult.

The interface is well-defined and public. But writing it correctly requires knowing the right method signatures, valid field types, pagination contracts, and error handling patterns. All of that is knowledge that takes time to build.

Introducing platform-salesforce-connect-adapter-generate

Salesforce skills are specialized AI capabilities that ground Agentforce Vibes and other dev agents with deep, domain-specific knowledge. They’re open-source, available as sf-skills, preloaded in Agentforce Vibes, and installable in any third-party AI tool. You describe your API in plain language. The agent does the rest.

When the platform-salesforce-connect-adapter-generate skill is loaded, your dev agent knows:

• The exact method signatures for DataSource.Provider and DataSource.Connection
• Correct DataSource.DataType mappings for your API’s field types. The skill knows which enum value to use for text, numbers, URLs, and more
• That ExternalId and DisplayUrl columns are required on every table definition
• That every table needs a column designated as its “name” column or the validate and sync operation fails
• How to structure TableResult, QueryUtils, and SearchUtils
• Named credential patterns so no credentials end up hardcoded

Without this skill, any dev agent produces plausible Apex that fails on first sync. With it, the agent gets the contract right on the first try.

Real-world use case: iRail Belgian Rail API

A developer at a travel company needs live data from 714 Belgian train stations in Salesforce for their customer service agents. The iRail API has this data: a public REST endpoint, free to use, returning clean JSON. No built-in adapter covers this endpoint and a custom Apex adapter is the only path.

With the platform-salesforce-connect-adapter-generate skill loaded, the developer describes the API in plain language:

“I have a public REST API for Belgian train stations at GET https://api.irail.be/v1/stations. It returns 714 stations with id, name, locationX, and locationY fields. Create a custom Salesforce Connect Apex adapter.”

The agent generates both Apex classes DataSource.Provider and DataSource.Connection with correct field types, required columns, and named credential auth wired in:

public class TrainTravelDataSourceConnection extends DataSource.Connection {
    public override DataSource.TableResult query(DataSource.QueryContext context) {
        HttpRequest req = new HttpRequest();
        // context unused here — iRail returns all stations; use QueryUtils.filter/sort for filtered queries

req.setEndpoint('callout:iRail_Named_Credential/v1/stations?format=json&lang=en');
        req.setMethod('GET');
        HttpResponse res = new Http().send(req);
        Map<String, Object> body = (Map<String, Object>) JSON.deserializeUntyped(res.getBody());
        List<Object> stations = (List<Object>) body.get('station');
        List<Map<String, Object>> rows = new List<Map<String, Object>>();
        for (Object s : stations) {
            Map<String, Object> station = (Map<String, Object>) s;
            Map<String, Object> row = new Map<String, Object>();
            row.put('ExternalId', (String) station.get('@id'));
 row.put('DisplayUrl', 'https://api.irail.be/v1/stations?format=json&lang=en&id=' + (String) station.get('@id'));
            row.put('Name', (String) station.get('name'));
            row.put('LocationX', Double.valueOf((String) station.get('locationX')));
            row.put('LocationY', Double.valueOf((String) station.get('locationY')));
            rows.add(row);
        }
        return DataSource.TableResult.get(context, rows);
    }
}

The code above shows the Connection class, which handles query logic. The full adapter also includes a DataSource.Provider class that declares adapter capabilities and returns the connection instance. See the complete code at https://github.com/shra1904/dreamforce-demo.

Here’s an example of how to run such a prompt with Claude Code:

This skill gives your agent the edge

Some of the key things the skill gets right automatically:

• Every custom adapter must declare a DataSource.Column named ExternalId, and the skill enforces this
• Field types are deterministic and mapped accurately to avoid field type mismatches, which are the most common failure mode
• The callout uses named credentials via the callout: prefix so no hardcoded URLs, no secrets in code
• The return type is DataSource.TableResult, which is the exact contract Salesforce expects

When both classes are deployed to the org via sf project deploy start, the adapter code is live. The next step is registering it in Salesforce as an external data source, traditionally a multistep Setup wizard. With the Salesforce Headless 360 MCP Server connected to your coding agent, that step becomes an API call too.

Registering without going to Setup in Salesforce

The agent invokes the external-data-source-setup platform metadata operation directly thanks to an MCP tool:

# Coding agent generates and deploys the adapter, then calls:
# Headless 360 MCP → external-data-source-setup
# → External Data Source created without opening Setup

The MCP server exposes Salesforce configuration operations as structured tools an AI agent can call so the same operations you’d perform through the UI are accessible programmatically.

This is the direction the platform is heading. Every Setup operation becomes an API call that an agent can invoke. Salesforce Connect is one of the first areas where we’re making this real.

The final step is validate and sync, which creates the external object by querying the adapter for its schema. That is one click in Salesforce Setup. The result: live station data in Salesforce, queryable in SOQL and available across all platform features like flows, reports, and so on.

Getting started

The skill is available now in sf-skills as platform-salesforce-connect-adapter-generate. You’ll need a Salesforce Connect license, Salesforce CLI v2+, and a coding agent like Agentforce Vibes, Claude Code, or Cursor. If you use Agentforce Vibes, the skills are already loaded, but if you are working with a third-party agent, you’ll need to install the skill by running npx skills add forcedotcom/sf-skills in your project directory. Once the skills are available, describe your API to your agent in natural language.

The skill handles any REST API that returns a structured JSON response, whether the API is authenticated or public, and whether the response is paginated or returned as a single response. Tell the agent what fields you need, what types they are, and how authentication works. The generated code is a working first pass. Add error handling and a test class before deploying to production. Apex requires test coverage to deploy to a production org.

Conclusion

Custom Apex adapters have always been capable. The barrier was the knowledge required to write them correctly. The platform-salesforce-connect-adapter-generate skill removes that barrier because your coding agent now knows the full DataSource framework and can generate a working adapter from a plain-language description.

Combined with the Salesforce Headless 360 MCP server, virtually the entire workflow, including code generation, deployment, and org registration, can be completed without leaving your terminal. That’s the foundation we’re building toward: agentic Salesforce configuration, end to end.

In Winter ’27, we’re extending this further with full headless external data source lifecycle management and Salesforce Connect extensibility for standard adapters. (This represents current product direction and is subject to change. Please base purchasing decisions on currently available features.)

Have a data source you’d like to connect to Salesforce? Share your ideas and vote for related requests on IdeaExchange.

Resources

• Salesforce Connect Custom Apex Adapter documentation
• platform-salesforce-connect-adapter-generate skill on sf-skills
• DataSource Namespace reference
• Headless360 MCP documentation
• iRail API (demo target used in this post)

About the author

Shraddha Nakra is a Senior Product Manager at Salesforce on the Platform Connectivity Solutions team, where she owns Salesforce Connect and Private Connect. She focuses on making external data integration secure, faster, and developer-friendly from zero-copy connectivity to agentic configuration. Find her on LinkedIn.

The post Build Custom Salesforce Connect Adapters Smarter with Salesforce Skills appeared first on Salesforce Developers Blog.

You can package Python code as a script, deploy it into Data 360, and invoke it through a batch data transform. The transform remains the operational control point, while the script contains the customer’s processing logic.

The Northstar Outfitters customer scenario

Northstar Outfitters receives product data from several commerce systems. Brand names, currencies, units, required attributes, and product categories are represented differently across those systems. These inconsistencies affect product search and produce uneven analytics across channels.

Northstar needed one trusted product catalog in Data 360. The transformation had to:

• Standardize product names, brands, currencies, and units.
• Enrich products by mapping them to the approved category reference.
• Validate required attributes and identify invalid records.
• Calculate a product-completeness score using custom business rules.

Native batch data transforms support common operations through visual nodes and formulas. The complexity of Northstar’s transformation logic made a code-based approach more practical, so the team implemented it as modular, unit-tested, and source-controlled Python and PySpark with Code Extension.

A batch data transform remained the operational control point, providing execution, scheduling, status, and run history for the deployed script.

How Data 360 Code Extension fits the solution architecture

Northstar selected Code Extension so its production transformation could run on Salesforce-managed infrastructure within Data 360 using Spark for distributed processing. Developers used their local IDE only to validate the logic against sampled data. Full-scale processing began when the batch data transform invoked the deployed script.

This model provided:

• In-platform processing. Custom Python logic executes within Salesforce-managed infrastructure instead of a separate customer-managed processing pipeline.
• Distributed execution. Spark distributes PySpark DataFrame operations across Salesforce-managed compute resources.
• Isolated, temporary runtime. Tenant isolation, runtime sandboxing, network controls, and ephemeral compute help protect the platform and other workloads.
• Managed operations. Data 360 manages deployment, invocation, scheduling, execution status, logs, and run history.

The batch data transform starts the deployed Code Extension. The script uses the Data Custom Code SDK to read permitted DLOs as Spark DataFrames and write to the permitted target DLO. This scenario illustrates a DLO-to-DLO transform. Code Extension scripts also support DMO-to-DMO transforms, but a script must read from and write to the same object type—it can’t mix DLOs and DMOs.

For more about the architecture and security model, see How to Power Data 360 with Code Extension and Securely Running Python with Data Cloud’s Bring Your Own Code Architecture.

Northstar’s object map was:

The DLO names in the package constants matched this access model.

How to structure a Data 360 Code Extension package

The Code Extension script used the following structure:

my_package/
├── payload/
│   ├── config.json
│   └── entrypoint.py
├── requirements.txt
└── tests/
    ├── test_deploy_config.py
    └── test_entrypoint.py

Because my_package/ contains payload/, the team used it as the deployment root and passed --package-dir ./payload to the packaging and deployment commands.

The package access model

In config.json, Northstar identified the SDK version, entry point, data space, and DLOs that the package could read or write.

{
  "sdkVersion": "6.1.0",
  "entryPoint": "entrypoint.py",
  "dataspace": "default",
  "permissions": {
    "read": {
      "dlo": [
        "Product_Catalog_Raw__dll",
        "Product_Category_Reference__dll"
      ]
    },
    "write": {
      "dlo": [
        "Product_Catalog_Curated__dll"
      ]
    }
  }
}

The curated target remained write-only, keeping read and write responsibilities separate. The explicit permission list also gave reviewers a clear view of the package’s intended data access.

Before deployment, the team confirmed that each DLO existed in the configured data space and that the schemas contained every column used by the program. This caught naming and environment differences before transform creation.

What the Python and PySpark entrypoint script does

The entry point followed a simple read, transform, and write flow:

products_df = client.read_dlo(PRODUCT_SOURCE_DLO)
categories_df = client.read_dlo(CATEGORY_REFERENCE_DLO)

changes = transform_products(products_df, categories_df)

client.write_to_dlo(
    FINAL_DLO,
    changes,
    write_mode=WriteMode.MERGE)

Managed execution supplied the authenticated SDK context and enforced the permissions declared in config.json; the script did not hardcode credentials. The transformation function validated and standardized product data, matched approved categories, and calculated the required output. Spark distributed this processing across the managed execution environment.

The script logged failures with their processing context and rethrew exceptions so the data transform could report the run as failed.

How to validate a Code Extension script locally

Before deployment, Northstar ran the script locally against a Data 360 sandbox. Local execution read a sample of up to 1,000 records and sent output to the console without modifying Data 360 objects.

The team used this for functional validation. They measured performance and scale after deploying the script to the managed Data 360 runtime.

Local setup

The local toolchain included Salesforce CLI, Python 3.11, the SDK version declared in config.json, and the Salesforce CLI Code Extension plugin.

sf update
sf plugins install @salesforce/plugin-data-code-extension
python3.11 -m pip install salesforce-data-customcode==6.1.0

sf org login web \
  --alias myorg \
  --instance-url https://test.salesforce.com

sf org display --target-org myorg

With the sandbox authenticated as myorg, the team ran the entry point from the repository root:

sf data-code-extension script run \
  --entrypoint ./my_package/payload/entrypoint.py \
  --config-file ./my_package/payload/config.json \
  --target-org myorg

They ran the unit tests separately:

cd my_package
python3.11 -m pytest tests -q

Northstar’s test suite covered schema handling, normalization, category enrichment, quality-score calculation, invalid and empty inputs, write behavior, structured logging, and disjoint read/write permissions.

The team used the Code Extension quick start as its reference for prerequisites and sandbox setup.

How to deploy a Code Extension with Setup or Salesforce CLI

Deploying through Setup

In Setup, Northstar entered Code Extension in Quick Find and opened Code Extension. The page displayed existing deployments, including their code type, owner, deployment time, and current status.

After selecting New, the team uploaded the ZIP package and selected Python, Script, Batch Transform, and the required compute size before submitting the Code Extension.

Deploying with Salesforce CLI

For its repeatable developer workflow, Northstar used the Code Extension plugin to package and deploy the script:

cd my_package

sf data-code-extension script zip \
  --package-dir ./payload

sf data-code-extension script deploy \
  --name Northstar_Product_Catalog_V1 \
  --package-version 1.0.0 \
  --description "Product catalog standardization and enrichment" \
  --package-dir ./payload \
  --target-org myorg \
  --cpu-size CPU_2XL

The available CPU flags were CPU_L, CPU_XL, CPU_2XL, and CPU_4XL. Northstar began with CPU_2XL, measured the managed run, and used its timing logs to decide whether a different size was justified.

The deployment name was metadata supplied by the command, not a value that had to appear in entrypoint.py. Northstar later used that same name to select the Code Extension for its transform and filter execution logs.

The team also accounted for the documented CLI limitation for DMO-to-DMO transforms, where the UI deployment path is required. The current behavior is described in Deploy a Custom Script to Data 360 Sandbox by Using CLI.

After upload, the package passed through platform security validation before execution. Managed runs used isolated, temporary compute resources, and Northstar planned to migrate the validated Code Extension and dependencies through a DevOps data kit for its production release.

How to connect a Code Extension to a batch data transform

Deployment made Northstar’s script available, but did not execute it. The team connected the deployed Code Extension to a batch data transform, which became the invocation and scheduling layer.

Creating the transform in the UI

In Data 360, Northstar opened Data Transforms, selected Create from Code Extension, entered a unique label and API name, and selected the deployed Code Extension. It saved the transform and used Run Now for the first managed validation.

The team kept the API name within the documented character, length, and uniqueness rules described in Invoke Code Extension by Creating a Batch Data Transform.

Automating transform creation with the Connect API

To automate transform creation, Northstar captured the Connect API request as transform-request.json. The following abridged excerpt highlights the relationship between the target DLO, input DLOs, data space, and deployed Code Extension:

{
  "definition": {
    "type": "DCSQL",
    "manifest": {
      "nodes": {
        "node1": {
          "relation_name": "Product_Catalog_Curated__dll",
          "config": { "materialized": "table" },
          "compiled_code": ""
        }
      },
      "sources": {
        "source1": {
          "relation_name": "Product_Catalog_Raw__dll"
        },
        "source2": {
          "relation_name": "Product_Category_Reference__dll"
        }
      },
      "macros": {
        "macro.byoc": {
          "arguments": [
            {
              "name": "Northstar_Product_Catalog_V1",
              "type": "BYOC_SCRIPT"
            }
          ]
        }
      }
    },
    "version": "56.0"
  },
  "label": "Northstar Product Catalog Transform V1",
  "name": "Northstar_Product_Transform_V1",
  "description": "Invokes the Northstar custom Code Extension",
  "type": "BATCH",
  "dataSpaceName": "default"
}

The team submitted the payload with Salesforce CLI’s REST client:

sf api request rest \
  /services/data/v67.0/ssot/data-transforms \
  --method POST \
  --header "Content-Type: application/json" \
  --body @transform-request.json \
  --target-org myorg

Because the excerpt is intentionally abbreviated, Northstar used the complete manifest required by the current Data 360 Connect REST API reference in transform-request.json.

During testing, transform creation sometimes outlived the UI or CLI wait window. Instead of immediately resubmitting, the team queried MktDataTransform and checked the Data Transforms UI to determine whether backend creation was still progressing.

How to run and monitor a batch data transform

For its on-demand validation, Northstar invoked the transform through the API:

sf api request rest \
  /services/data/v67.0/ssot/data-transforms/Northstar_Product_Transform_V1/actions/run \
  --method POST \
  --body '{}' \
  --target-org myorg

The operations team retrieved transform details and run history with the companion endpoints:

sf api request rest \
  /services/data/v67.0/ssot/data-transforms/Northstar_Product_Transform_V1 \
  --method GET \
  --target-org myorg

sf api request rest \
  /services/data/v67.0/ssot/data-transforms/Northstar_Product_Transform_V1/run-history \
  --method GET \
  --target-org myorg

Northstar waited to schedule recurring production runs until it had measured duration, verified input and output counts, and understood billing for the selected compute size.

How to troubleshoot a failed Code Extension run

Northstar checked three separate signals: Code Extension deployment in DataCustomCode, data transform status in MktDataTransform, and Python execution messages in DataCustomCodeLogs__dll.

Verifying the Code Extension record

sf data query \
  --target-org myorg \
  --query "SELECT Id, Name, CodeType, DeploymentStatus, Status, DeploymentFailureCode, DeploymentFailureReason, CreatedDate, LastModifiedDate FROM DataCustomCode WHERE Name = 'Northstar_Product_Catalog_V1' ORDER BY CreatedDate DESC"

The team treated Status = Active and DeploymentStatus = Deployed as separate signals. DeploymentStatus showed whether package deployment had completed successfully.

Verifying the data transform record

This query confirms the transform exists and shows its current status and most recent execution details.

sf data query \
  --target-org myorg \
  --query "SELECT Id, Name, DataTransformStatus, LastRunStatus, LastRunTime, CreationSource, Type, CreatedDate, LastModifiedDate FROM MktDataTransform WHERE Name = 'Northstar_Product_Transform_V1' ORDER BY CreatedDate DESC"

Inspecting execution logs

Application logs are stored in the DataCustomCodeLogs__dll DLO, so Northstar queried them in Data Explorer using Data 360 SQL. Because log ingestion is asynchronous, messages may appear shortly after an execution completes.

The latest execution messages

Run this query to review the latest execution messages and correlate them with a specific Code Extension run.

SELECT
    "Timestamp__c",
    "Message__c",
    "CorrelationId__c",
    "ExecutionId__c",
    "ProcessDefinitionName__c",
    "DataCustomCodeName__c"
FROM "DataCustomCodeLogs__dll"
WHERE "DataCustomCodeName__c" =
      'Northstar_Product_Catalog_V1'
ORDER BY "Timestamp__c" DESC
LIMIT 200;

How the script produced application logs

Northstar used Python’s standard logging module inside entrypoint.py:

import logging

log = logging.getLogger(__name__)
log.info(
    "PRODUCT_PIPELINE | phase=PROCESS | status=SUCCESS | records_written=%s",
    records_written,
)

During managed execution, Data 360 captured this application message and ingested it into DataCustomCodeLogs__dll. The script did not call a separate API or write directly to the log DLO.

Conclusion

Data 360 Code Extension brings the flexibility of Bring Your Own Code to complex data transformations. Teams can use Python and PySpark for modular and testable logic, multiple data inputs, custom validation, specialized libraries, and distributed processing within a governed Data 360 environment. Combined with batch data transforms for execution, scheduling, monitoring, and run history, it provides a scalable way to operationalize sophisticated data processing without managing a separate external processing platform.

Resources

• • YouTube series: Extend Data 360 with Code Extension
  • How to Power Data 360 with Code Extension
  • Securely Running Python with Data Cloud’s Bring Your Own Code Architecture
  • Code Extension in Data 360
  • Code Extension quick start
  • Deploy a custom script using Salesforce CLI
  • Create a batch Data Transform from Code Extension
  • Data 360 Connect REST API reference
  • Salesforce Data Custom Code SDK on PyPI
  • Salesforce CLI Code Extension plugin

About the authors

Ravindra Varshney is a Senior Director, Software Engineering at Salesforce. You can find him on LinkedIn.   

Gaurav Tewari is a Senior Product Manager at Salesforce. You can find him on LinkedIn.

Chandan Agarwal is a Principal Member of Technical Staff at Salesforce. You can find him on  LinkedIn.

The post Run Complex Data Transformations in Data 360 with Code Extension appeared first on Salesforce Developers Blog.

What is Web Console?

Web Console is a modern, browser-based IDE designed to help developers work faster inside the platform they already know, without switching tools just to inspect code, run queries, debug an issue, or make a quick fix. It’s built on a proven foundation of VS Code for the Web with our existing Salesforce Extensions for Visual Studio Code, delivering a seamless in-browser experience for Salesforce developers. This provides the robustness of a modern IDE in a fast, easy-to-access experience like you had with Developer Console. Yes, this is your modern alternative to Developer Console!

You may also be wondering about how Web Console differs from Agentforce Vibes IDE, since they are both dev environments accessible from the browser. In short, Web Console is a lightweight environment optimized for quick file editing and development tasks within a single org, while Agentforce Vibes IDE is a full development environment backed by a virtual machine (VM), providing additional compute, AI, integration capabilities, and multi-org connections. They really serve two different needs, and depending on what you’re looking to do you can select the appropriate tool for the job.

Web Console provides the same trusted functionality you’ve become accustomed to in Developer Console, but through a more modern experience. Additionally, Web Console provides new capabilities that have not been available in Developer Console, including support for Lightning Web Components (LWC). 

Below is a table highlighting key capabilities of Web Console, with Quick Start instructions for using them in Web Console (and links to full documentation for each). A star indicates features you have access to in Web Console that you didn’t have access to in Developer Console.

Feature/Capability	Quick Start – How to Access Web Console
Quick, in-context Apex viewing/editing	Click Edit on any Apex Class, Trigger, or Scheduled Job from within the org Edit as desired, then Save
View/edit Lightning Web Component (LWC) files	Open Org Browser (cloud icon) in the left-side Activity Bar Navigate the Metadata tree, then click Retrieve Metadata Edit as desired, then Save Learn More
Run Anonymous Apex	From Command Palette (Ctrl+Shift+P on Windows or Cmd+Shift+P on macOS), run SFDX: Create Anonymous Apex Script Edit the script, then right-click in the script file -> SFDX: Execute Anonymous Apex Learn More
Generate/run SOQL queries, optionally with declarative SOQL Builder , and optimize performance by generating a query plan	From Command Palette*, run SFDX: Create Query in SOQL Builder (or Create SOQL Query) Edit the query, then select Run Query Learn More
Run Apex tests and view test results	Open Testing (beaker icon) from the left-side Activity Bar Select a test method, test class, or all Apex tests.  Run test(s) Learn More
Debug Apex with trace flags and log levels	View Logs: Command Palette* -> SFDX: Get Apex Debug Logs Trace/Log Levels Command Palette* -> SFDX: Create Trace Flag for Current User Adjust Log Levels as desired Learn More
Browse all metadata in the org , and optionally retrieve for editing/redeploy with the Org Browser	Open Org Browser (cloud icon) in left-side Activity Bar Browse metadata in the org Optionally Retrieve, Edit, Save Optionally open Explorer (files icon) in left-side Activity Bar to browse/edit/deploy retrieved metadata Learn More
Log Analysis	Coming soon via Certinia Apex Log Analyzer!

* To open Command Palette use Ctrl+Shift+P on Windows or Cmd+Shift+P on macOS.

Connected workflow example: Debugging an Apex job failure

Apex job failures are a good example of where Web Console can make an immediate difference. A developer can begin in the Apex Jobs page, where a failed or long-running Apex job is already visible. From there, they can open the related Apex class in Web Console, enable logging, rerun the scenario, inspect the execution path, jump from the stack trace to the problematic line of code, make the fix, run tests, and validate that the job now completes successfully. They can do all of that without leaving Salesforce or bouncing between disconnected tools.

This streamlined flow is more efficient because it mirrors how real troubleshooting actually happens. The work does not begin in a file tree. It begins with a problem. Web Console is designed so the IDE meets the developer at that point of failure, then stays with them through diagnosis, code change, and validation.

This is one of the clearest ways Web Console improves usability. Instead of forcing the developer to reconstruct the situation across separate tools, it keeps runtime evidence, source code, and validation steps close together, shortening the distance between “What just happened?” and “Did my fix resolve the issue?”

Production versus non-production: Web Console guardrails

Web Console is built with the realities of Salesforce development in mind. In production orgs, Apex editing is read-only, letting developers inspect and understand code safely without any risk to live orgs. In sandboxes and other non-production environments, developers can make inline edits and save changes as part of a faster path-to-fix workflow.

That balance is important. A modern experience should make developers faster, but not by weakening platform guardrails. Web Console keeps the guardrails intact while still streamlining inspection, debugging, and validation.

How to launch Web Console

Web Console is now enabled by default for users with admin permissions. Getting started with Web Console requires no local command-line setup or extension installation. Once it is enabled, you can simply launch it directly from the Setup (gear) menu within your Salesforce org or refer to the official guide on How to launch Web Console. Global access can be disabled or enabled through Setup -> Development -> Web Console.

What about Developer Console?

While we believe that Web Console will provide you with the functionality that you need and an improved experience, if you still prefer to use Developer Console you can easily re-enable it through Setup -> Development -> Web Console, then toggle Enable Developer Console. 

If you or your team find yourselves needing to revert to the legacy Developer Console, we would love to know why! Please share your feedback so we can ensure Web Console continues to satisfy all your development needs.

Conclusion

We’re excited to bring Web Console to general availability, providing a quick, easy, and streamlined experience for your everyday development needs. Whether it’s making a quick edit to an Apex class, modifying an LWC component, testing and debugging your code, querying data in your org, running an Apex script, or just browsing your org’s metadata, Web Console makes it easy. 

And it’s only a click away: try Web Console today at Setup Menu (gear icon) -> Web Console!

Resources

• Web Console documentation
• Feedback/Issues repository on GitHub
• AMA: Oct 28, 2026 at 9 a.m. PT

About the author

Karen Fidelak is a Sr. Director Product Management at Salesforce, focused on bringing robust developer tooling and experiences to our developer community. She leads product teams responsible for our IDEs, VS Code extensions, CLI, Agentforce Vibes, DevOps Center, DX Inspector, and Code Analyzer. You can follow her on LinkedIn.

The post Announcing General Availability: Web Console – Your Modern In-Browser IDE appeared first on Salesforce Developers Blog.

If AI agents are returning confident but wrong answers from enterprise documents, the problem probably isn’t your LLM. It’s your RAG pipeline, and you can fix it without writing code.

We validated the approach described in this post on four public, reproducible benchmarks. Three configuration changes in Data 360 improved accuracy from 62.5% to 92.5% on knowledge-base question answering. On complex enterprise PDFs with tables, charts, and formulas, the same pipeline achieved 86.8% accuracy end to end.

In this post, we’ll cover where your pipeline is breaking, three configuration steps to fix it, how to validate improvements, and what’s coming next.

The four stages where RAG pipelines fail

RAG failures compound silently across four stages. Before tuning anything, identify your bottleneck:

1. Content processing: Charts, diagrams, and tables lose structure during extraction. A pricing matrix becomes garbled text; a wiring diagram disappears entirely.
2. Content splitting: A 15-step procedure gets split at an arbitrary token boundary. Your agent returns steps 1–7 and misses the safety warning on step 12.
3. Search: The right content exists but the wrong content surfaces. Your user asks about “firmware reset” but the document says “factory restore procedure.”
4. Generation: The retrieved context is correct but the LLM produces a wrong or incomplete answer anyway.

Fixing one stage doesn’t help if another is the actual bottleneck. On our benchmarks, the remaining errors after full optimization break down as follows: 

• 40% generation
• 26% content processing
• 18% search
• 16% content splitting

Your distribution will vary by document type.

Here’s what fixing these stages looks like in practice across different industries and for your business:

• Insurance and financial services: Multipage policy tables become queryable with correct cell-level extraction. Finance-domain accuracy improved by over 27.9 percentage points, the largest increase of any domain tested.
• Manufacturing and field service: Schematics, wiring diagrams, and safety documentation become searchable by meaning, not just filename. Technical/product manual-domain accuracy: from 77% to 88.7%.
• Customer support and service: Optimized configuration delivers 92.5% accuracy on knowledge-base question answering. Your agents get complete procedures, not fragments that leave customers waiting.
• Enterprise-wide search: 82.1% accuracy with confluence documents. Your agents find information regardless of where it lives.

Optimize your RAG pipeline

Enable intelligent parsing for rich documents

The first thing you can do to increase accuracy is to enable intelligent parsing (expected November 2026) for rich documents. Intelligent parsing analyzes each page and routes it to the right extraction method. Text-heavy pages get fast, structure-preserving parsing. Pages with charts, diagrams, or schematics get vision-model interpretation that converts visual content into searchable text.

This matters because standard parsing skips images entirely and breaks tables across rows. Intelligent parsing keeps tables intact, preserves section hierarchy during chunking, and makes visual content retrievable.

To enable it, select Intelligent Parsing as the document processing method in your Data 360 intelligent context. No additional setup is required; page-level routing happens automatically.

The following table shows the measured impact of intelligent parsing on OHR-Bench (Office-domain Hybrid Retrieval Benchmark) v2 (International Conference on Computer Vision [ICCV] 2025, enterprise PDF questions):

Turn on enriched indexing

Another way to improve accuracy is to enable enriched indexing. For every chunk in your index, enriched indexing generates two additional representations automatically:

• Rich metadata: titles, keywords, entities, summaries, and topic labels extracted from the content
• Question chunks: the natural-language questions this content is likely to answer, phrased the way your users actually search

At retrieval time, a query matches against all three surfaces simultaneously: raw content, metadata, and anticipated questions.

This matters because your users search with different vocabulary than your documents use. A service agent asks “How do I reset the configuration after a firmware update?” but the document says “Restore factory settings post-upgrade.” Enriched indexing bridges that gap without manual tagging.

To enable it, toggle Enriched Indexing on in Search Index Setup. The enrichment runs during indexing;  no changes are needed at query time.

The measured impact of enriched indexing was +2.4 percentage points on top of intelligent parsing by itself (84.4% to 86.8% on OHR-Bench v2). No manual content curation is required.

Tune chunk size, search depth, and generation prompts

This is likely where you will see the largest single improvement. On WixQA (arXiv 2025, real help articles with expert-written questions), configuration tuning alone delivered a 30 percentage-point improvement, with no code changes and no custom models.

The three levers are:

Adjust these configurations in your search index and RAG pipeline settings. If your documents contain multistep procedures or tables, start with the chunk size, increasing it to 512 or higher.

The measured impact of this tuning was 62.5% to 92.5% accuracy on the same benchmark, same platform, and same data, with configuration changes only.

What’s next: Knowledge Graph

Some questions can’t be answered from a single page or even a single document. “What safety certifications apply to this component given recent regulatory changes?” requires connecting information across multiple sources.

Knowledge Graph (Generally Available November 2026) builds entity-relationship connections across your entire document corpus. Instead of retrieving isolated content, the system traverses relationships. It follows a policy clause to its definitions. It connects a financial line item to its footnoted methodology. It links a product specification to safety constraints in a separate document.

This is our path to 90%+ accuracy on multipage reasoning (the same level we’ve achieved on single-document benchmarks).

Your action plan

Validating your improvements

You don’t need to trust our benchmark numbers; you can measure the pipeline against your dataset:

1. Build your own evaluation dataset of 20-50 questions paired with correct answers from your documents. You can evaluate the answers to each of these questions in Intelligent Context now. In the next version of Intelligent Context (expected November 2026), you will be able to get an aggregate accuracy assessment on your dataset out of the box. 
2. Through our benchmarking exercise, we mapped every failure pattern to the specific pipeline configuration that fixes it. We’re now packaging that into auto-tuning, which is expected to launch in November 2026. It runs accuracy assessments against a set of golden question-answer pairs, diagnoses where answers fail, and automatically applies the right configuration, with no manual experimentation and no RAG expertise required. In early testing, auto-tuning found the optimal configuration in three iterations, replacing months of manual work.

Conclusion

Enterprise RAG accuracy is a configuration problem, not a model problem. Three changes (Intelligent Parsing, Enriched Indexing, and tuned pipeline settings) improved accuracy from 62.5% to 92.5% on public benchmarks without custom code or model training.

For practitioners who want hands-on control, start with the Action Plan table above to identify your highest-impact fix. Then, use the validation steps to measure your own pipeline. For everyone else, we’re introducing auto-tuning and automated accuracy assessments built from the same diagnostic logic our benchmarking uncovered so that any practitioner can reach optimal accuracy without needing to understand the details of the RAG system. 

If you have questions or want to share your results, join the conversation on the Trailblazer Community.

Ready to get started? Set up a Data 360 search index today and run your first evaluation.

Resources

• Data 360 Documentation –  Platform setup and configuration guides
• Benchmarks:
  • OHR-Bench v2 (ICCV 2025) –  Complex enterprise PDF benchmark
  • MMLongBench-Doc (NeurIPS 2024) –  Long-document reasoning benchmark
  • WixQA (arXiv 2505.08643) –  Knowledge-base QA benchmark
  • Enterprise RAG Bench – Multisource enterprise retrieval benchmark
• Data 360 on Trailhead –  Learning paths for Data 360 developers
• Salesforce AI Blog – Related posts on enterprise AI architecture

About the Authors

Barnali Patnaik is a Senior Product Manager at Salesforce, focused on enterprise search accuracy and RAG pipeline optimization in Data 360. She leads benchmarking and evaluation strategy for the Data 360 retrieval stack. LinkedIn

Aanchal Varma is a Senior Member of Technical Staff (SMTS) in Data Science at Salesforce, specializing in retrieval evaluation and accuracy measurement for enterprise search systems in Data 360. LinkedIn

Kartik Muktinutalapati, Senior Director of Product Management at Salesforce, leads the Data 360 product vision and strategy for unstructured data processing and retrieval to give AI agents access to enterprise knowledge.

The post Improve Enterprise RAG Accuracy in Data 360 appeared first on Salesforce Developers Blog.

みなさん、こんにちは。株式会社セールスフォース・ジャパンの Trailblazer リレーションズチームで、Developer Advocate をしている odasho です。

2026 年 6 月に開催された TDX Tokyo 2026 (Agentforce World Tour Tokyo) の会場で、Salesforce の実装スピードと正確性を競う「Lightning MiniHack Live」が初開催されました。予選を勝ち抜いた 4 名のファイナリストが 1 vs 1 のトーナメント形式で対決し、初代チャンピオンが誕生しています。

ファイナリストのご紹介

Madani Abdullah さん(サークレイス株式会社) — 初代チャンピオン シリア出身。日本のアニメや文化に惹かれて 2019 年に来日し、2025 年 4 月にサークレイス株式会社へ新卒入社。Salesforce デベロッパーとして活動中です。

Yuki Hasegawa さん (東京都市大学 メディア情報学部 社会メディア学科 3 年) 昨年の Agentforce Hackathon Tokyo で優勝した企業でインターン中の学生。本ハッカソンが Salesforce にほぼ初めて触れる挑戦でした。

Tomoki Omuro さん (東京都市大学 メディア情報学部 社会メディア学科 3年) Hasegawa さんと同じ企業 (株式会社 Tekuru) でインターン中。日頃から社長や先輩たちが挑戦する姿を間近で見て、自身も初の大会参加を決意しました。

Tatsuro Suzuki さん (アクセンチュア株式会社) Salesforce 歴 14 年のベテラン。近年はマネジメント側に軸足を移しつつも、現場の第一線であり続けるために挑戦を決めました。当日はオンラインでご参加いただきました。

聞き手は Salesforce の Kimura と odasho です。

なぜ Lightning MiniHack Live に挑んだのか

Madani さんは、昨年のハッカソンにも応募した経験があり、挑戦することそのものに強い哲学を持っています。

「挑戦しなかったら、あとに残るのは『挑戦しなかった』という結果だけです。生きている間に挑戦できる機会があるなら挑戦したい。それに、コミュニティには技術や実装に長けた方が多いので、そうした方々と競える機会は楽しいんじゃないかと思ったんです」

Hasegawa さんのきっかけは、同じインターン先の Omuro さんからの誘いでした。

「私は現在大学 3 年生で、就職活動が始まったばかりです。クラウド業界やソフトウェア業界を志望しており、その中でも Salesforce の技術やエコシステムに魅力を感じていました。学生のうちに実践的な技術力を磨き、自分の力を試したいと思っていた中で、この Lightning MiniHack Live の開催を知りました。ひとりだけでは挑戦しなかったかもしれませんが、Omuro さんも挑戦したいということを教えてもらい、挑戦への勇気をもらいました」

Omuro さんは、インターン先の社長の背中を見て、挑戦を決意したそうです。

「社長が 2025 年に Agentforce Hackathon など様々なイベントや事業に挑戦している姿を日々見ていて、自分もそのような経験がしてみたいと思って応募しました」

そして Suzuki さん。14 年のキャリアを持つベテランならではの、少し意外な動機でした。

「徐々にマネジメント側に移りつつあって、最近は Apex を組む機会も減ってきていたんです。プロジェクトのメンバーには『最新のリリースノートを読み込もう』『最新情報をキャッチアップしよう』と言っている手前、私自身もちゃんとキャッチアップして『我々もいけるんだぞ』というところを見せたい。そんな気持ちで応募しました」

「最速」はこうして作られた 〜予選・本選への準備〜

予選・本選で問われたのは、スピードと正確性の両立。ファイナリストたちはそれぞれのやり方で「最速」を作り込んでいました。

Madani さんの練習法は、アスリートさながらの動画分析です。

「自分の実装を動画に撮って、時間を確認する。『この部分はもっと速くできる』『ここは AI に任せられる』と分析してもう一度練習する。その繰り返しで毎回タイムを縮めて、最速の手順を作り込んでいきました。ベストの動画は残しておいて、AWTT (Agentforce World Tour Tokyo) に向かう移動中もスマホで見返していましたね」

学生のお二人は、インターン先のメンバーを巻き込んだチーム戦でした。

「オンラインで社員のみなさんと勉強会をしたり、空いている時間にタイムを計って『何分何秒だった』と社内で共有して競い合ったり励まし合ったりしていました」(Hasegawa さん)

「『インターンシップの業務時間を使って練習していいよ』と言ってもらえたことが、まず大きかったです。さらに、実装方針を一緒に考えてもらったり、操作方法の練習を見てもらったりと、社長自らサポートしてくれました。ここまで挑戦できたのは、会社全体で背中を押してもらえる環境があったからだと思います」(Omuro さん)

Suzuki さんは、要件の「見切り」から入る戦略派です。

「ひととおり試してみて、3 シナリオのうち 2 つは制限時間に収まらないと判断しました。だったら他の方もハマらないはずだと前提を置いて、いかに業務が回る形に要件を絞るかを考える。制限時間内で実現できる最大限のアプリケーションを設計して、あとはひたすら練習。1 分のバッファを残して収まるまで作り込み、その 1 分で加点要件を取りにいくアプローチです」

ちなみに運営側では、皆さんから提出された予選のプレイを全部絶叫しながら見ていました。予選通過タイム 1 位は Madani さんで、なんと 2 位に約 1 分半の差をつけてのトップ通過でした。

四者四様の実装選択 〜入力規則？ フロー？ Apex トリガー？〜

本選の課題は、入力規則・フロー・Apex トリガーのいずれでも実装できるバリデーション要件。「緊急フラグがオンなら予算超過チェックをスキップする」という例外ロジックの扱いが勝負どころでした。ここでファイナリストたちの選択が分かれます。

Suzuki さんの選択は Apex トリガーでした。

「フローでもいけると思うんですが、ドラッグ & ドロップやダブルクリックで設定画面を開く操作には、1〜2 秒ずつの積み重ねがあります。一方トリガーなら、最後に一発セーブすればそこでしか PC とサーバー間の通信が発生しない。そこに賭けました」

Omuro さんはフローを選択。理由は「安定性」です。

「ほかの手段を試したときに読み込みに時間がかかることがあって、録画するタイミングによってタイムがまちまちだったんです。安定しないなと思って、フローだけに絞りました」

Hasegawa さんは、初心者として「確実性」を最優先しました。

「カスタムエラーを使いました。奇をてらったやり方だと自分が混乱してしまうと思ったので、速さには欠けても確実にできるものを選びました。とにかく間違えないように、です」

そして優勝した Madani さんの選択は、フロー。ただしその使い方が徹底されていました。

「Apex とフロー、どちらも試したうえで、私はフローを構築するほうが速かったんです。ホットキーで速度を上げられますし、数式も使える。そして読み込み時間の間には必ず別の作業をする。フローの弱みを、作業のパラレル化でカバーしていました」

得意なものを選ぶのではなく、検証したうえで「自分にとっての最速」を選ぶ。全員に共通していたのは、この姿勢でした。

AI 時代における「実装力」とは何か

今回の運営側のこだわりは、AI で何でもできるようになった時代における「人による実装力」でした。そこで、AI ツールと人が手を動かす力の関係をどう捉えているか、全員に聞いてみました。

Madani さんの判断基準は明快です。

「まず自分に問いかけるのは『AI にプロンプトを書くより、自分の手を動かしたほうが速いか？』です。自分の手のほうが速いならプロンプトを書く時間がもったいないし、プロンプトの結果が必ずしも欲しいものになるとは限らない。逆に AI に任せると決めたら、指示をしている間に自分は別のことをする。これからの実装力は『誰が最も正しく AI に説明し、正しい出力を引き出せるか』になっていくと思います」

Suzuki さんは「対話力」というキーワードを挙げました。

「これからの実装力は、対話力とニアリーイコールになっていくと思っています。明確な要件があってあとは作るだけ、という領域は AI が担っていく。一方で、コンタクトセンターやフィールドサービス、営業といった現場で汗をかいて、お客様と話しながら『あ、これはこの画面に欲しかったんだ』とサクッと作って当てられる力は、どうしても人間が必要です。Salesforce は画面をドラッグ & ドロップで実装できるので、対話ツールとしても優秀なんですよ」

学生のお二人は、AI との日々の付き合いから実感を語ってくれました。

「出てきた成果物を評価して、さらによく改善していくのは人間の楽しみだと思います。曖昧な指示だと想定と全然違う動きになってしまうので、『自分がやりたいことは何か』を自分の中で明確にすることが大事だと感じています」(Omuro さん)

「私も日常会話くらいの感覚で AI を使うんですが、けっこう間違いが多くて。『ここ違くない？』と言うと『すみません』って、平気で嘘をついてくるんですよ(笑)。だからこそ、AI が生成したものを精査する力が実装力において大切なんじゃないかと思います」(Hasegawa さん)

初代チャンピオンの勝ち筋 〜ウィナーズインタビュー〜

優勝した Madani さんに、勝因を自己分析してもらいました。

「横の画面で AI に指示を出して、AI が作っている間に、私は AI にできないことを別の画面で進める。Agentforce Grid など Salesforce の最新機能を使おうという意識もありました。完全に AI に任せるのではなく、指示して、待っている間に他の作業をして、戻ってきて AI の生成物を編集する。このやり方が優勝に導いてくれたと思っています。こうした、要件に応じて最適な実装方法を見極め、AIと自身の技術を使い分けながら素早く形にする力は、実際のお客様のプロジェクトでも生かされています。お客様のご要望に対して、スピードと品質を両立させながら設計やコーディングを進める推進力につながっています」

「優勝できると思っていましたか？」という質問には、迷いなく「はい」。

「私は自分が勝つと思って挑戦していました。たとえ勝てなかったとしても『全力を尽くした』と言えるくらいの努力はしたつもりです」

優勝が決まった瞬間については、こう振り返ります。

「言葉にできないくらい幸せでした。頑張ったことの価値を感じられる瞬間が、一番幸せなんだと思います。Salesforce の知識が少ないところから増やしながら、それでも『勝ちます』という自信を持って頑張れたことは、次の挑戦への自信にもなります。この結果は自分の努力だけではなく、職場のみなさん、そして妻をはじめ、多くの支えてくれた方々のおかげです。……ただ同時に、練習では時間内に終わらせられたのに、本戦では収めきれなかった悔しさもあるんですけどね」

チャンピオンはすでに次を見据えていました。

挑戦を終えて 〜これから参加するあなたへ〜

最後に、この挑戦で得たものを聞きました。

「Salesforce は名前を聞いたことがある程度の認識だったので、ノーコードでアプリを作れる世界があることをまず知れました。就活の面でも『こういう進路もあるんだ』と視野が広がったのは大きなメリットです。私はもともと人前に出るのがすごく苦手で、予選に通ったときも『みんなの前でやるのか……』と危惧していたくらいなんです。1 vs 1 の対戦では敗れて決勝には進めず悔しかったのですが、足も手も子鹿のように震わせながら(笑)、それでも実力を発揮できた。自分の中で本当にいい経験になりました」(Hasegawa さん)

「Salesforce は知っていましたが、企業が業務で使うものという格式高いイメージがあって、自分に触れるのかなという気持ちがありました。でも触ってみると、どういうものか分かればできるものなんだなと。知らないから勝手に難しいと思い込んでいただけで、自分の中のハードルがすごく下がりました。今回自信がなくて挑戦しなかった方がいらっしゃれば、難しくとらえすぎず、次回挑戦していただけたらと思います」(Omuro さん)

「一番よかったのは、新しい知識を得られたことです。普段使っているとはいえ、自分のプロジェクトで触る機能は本当に一部なんですよね。聞いたことはあっても自分の手で作ったことのない機能に触れられましたし、他のみなさんのプレイから『こんな方法があったのか、これならもっと速くなる』と学べたのも、すごく面白い経験でした」(Suzuki さん)

おわりに

運営としてこの企画には、「AI 時代でも、やろうと思えば人はキャッチアップできる」ということを証明したいという思いがありました。Salesforce にほぼ初めて触れる学生から 14 年のベテランまでが同じ土俵で本気の勝負を見せてくれたことで、それが証明されたと感じています。

一方で作り手としては、クリアされると難易度を上げたくなってしまうのも正直なところ(笑)。せっかく初代チャンピオンが誕生したので、次回はレギュレーションや名称が変わるかもしれませんが、挑戦してくれたみなさんに報いるような、そして初めての方がもっと参加しやすいような形を用意していきます。

この記事を読んで「自分もやってみたい」と思った方は、まずは Trailhead で Salesforce に触れてみてください。次はあなたの挑戦をお待ちしています！

The post 【TDX Tokyo 2026】Lightning MiniHack Live ファイナリスト座談会: 初代チャンピオンと挑戦者たちが語る「最速」の舞台裏と AI 時代の実装力 appeared first on Salesforce Developers Blog.

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 をキーに、ウィジェットのテンプレートに関する情報が保持されているのが確認できます。

(2026/8/28更新)

まずは、クライアント側での「ツールの更新」をお試しください。これでテンプレート情報が新しいものに更新されることが多いです。

それでも上手くいかない場合のひとまずの対策は 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 も影響を受けません。

おわりに

本記事では、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.