Generating Apex

Use this skill for production-grade Apex: new classes, selectors, services, async jobs, invocable methods, and triggers; and for evidence-based review of existing .cls OR .trigger.

Required Inputs

Gather or infer before authoring:

• Class type (service, selector, domain, batch, queueable, schedulable, invocable, trigger, trigger action, DTO, utility, interface, abstract, exception, REST resource)
• Target object(s) and business goal
• Class name (derive using the naming table below)
• Net-new vs refactor/fix; any org/API constraints
• Deployment targets (default to runSpecifiedTests and use generated tests where applicable)

Defaults unless specified:

• Sharing: with sharing (see sharing rules per type below)
• Access: public (use global only when required by managed packages or @RestResource)
• API version: 66.0 (minimum version)
• ApexDoc comments: yes

If the user provides a clear, complete request, generate immediately without unnecessary back-and-forth.

Workflow

All steps are sequential. Do not skip, merge, or reorder. If blocked, stop and ask for missing context. If not applicable, mark N/A with a one-line justification in the report.

Phase 1 — Author

1. Discover project conventions

   • Service-Selector-Domain layering, logging utilities
   • Existing classes/triggers and current trigger framework or handler pattern
   • Whether Trigger Actions Framework (TAF) is already in use
   • When refactoring or reviewing an existing .cls, call mcp__plugin_salesforce-development_salesforce-lsp__apex_documentSymbol with {filePath: "<absolute-path>"} to map the class's methods, properties, and inner types before editing, and call mcp__plugin_salesforce-development_salesforce-lsp__apex_hover with {filePath, line, character} (one-based line/character) to resolve the type or signature of a symbol you are unsure about. On error envelope or unavailable ({error: <code>} / tool not registered), fall back to reading the source directly.

2. Choose the smallest correct pattern (see Type-Specific Guidance below)

3. Review templates and assets

   • Read the matching template from assets/ before authoring (see Type-Specific Guidance for the file mapping)
   • When a references/ example exists for the type, read it as a concrete style guide
   • For any test class work, always read and use platform-apex-test-generate skill

4. Author with guardrails -- apply every rule in the Rules section below

   • Generate {ClassName}.cls with ApexDoc
   • Generate {ClassName}.cls-meta.xml

5. Generate test classes -- Load the skill platform-apex-test-generate to create {ClassName}Test.cls and {ClassName}Test.cls-meta.xml. Apex tests are always required to be generated to deploy. No test file creation or edits can occur without loading the platform-apex-test-generate skill to generate tests.

Phase 2 — Validate (required before reporting)

Writing files is the midpoint, not the finish line. Steps 6, 7, and 8 each require a tool invocation and produce output that must appear in the Step 9 report. Do not summarize or present the report until all three steps have run and their output is captured.

6. Compile-check every file (REQUIRED) — via the diagnostics tool when available, otherwise via the fallback. Running one of these is mandatory; which one depends on what your environment exposes.

   • Preferred: Invoke mcp__plugin_salesforce-development_salesforce-lsp__apex_diagnostics with {filePath: "<absolute-path>"} on every generated/updated .cls and .trigger file to compile-check and surface errors/warnings before deploy.
     • On success with diagnostics ({ok: true}, non-empty list), remediate all diagnostics with severity error or warning; re-run until clean.
     • Fail closed on an empty diagnostics result — always. The tool returns {ok: true, diagnostics: []} for BOTH a genuinely clean compile AND a swallowed timeout/internal error, so an empty list is not by itself proof the code compiled. Whenever diagnostics come back empty, you MUST corroborate with the Fallback (sf project deploy start --dry-run) before reporting the file as clean or deploy-ready. Do not treat any empty apex_diagnostics response as a passing compile on its own.
     • On error envelope ({error: <code>}), record apex_diagnostics=unavailable: <code> and use the Fallback.
     • On unavailable (tool not registered), record apex_diagnostics=unavailable: lsp_not_present and use the Fallback.
     • If the tool is not resolvable in this environment — e.g. it is a deferred tool and a ToolSearch for it returns no match, or the call otherwise cannot be made — do NOT stall or retry discovery. Record apex_diagnostics=unavailable: lsp_not_present and use the Fallback immediately.
     • If diagnostics report an unknown field or object that you just deployed, call mcp__plugin_salesforce-development_salesforce-lsp__refresh_org_schema to invalidate the cached org describe, then re-run apex_diagnostics before treating it as a real code error.
   • Fallback (fully satisfies this step): Compile-check via sf project deploy start --dry-run and read CLI errors. Remediate any errors and re-run until clean. A clean fallback result is a valid, complete outcome for this step — the diagnostics MCP tool is preferred, not required, when it is not available.
   • Compilation is this step's only concern. It does NOT cover PMD, CRUD/FLS, or complexity rules — those are static analysis, run as a separate required step below (Step 7).
   • NEVER report a class or trigger as valid or deploy-ready without running EITHER the diagnostics tool OR the fallback. "The tool wasn't available" is not a reason to skip validation — fall back and validate. Recording apex_diagnostics=unavailable: <reason> is only acceptable alongside a completed fallback.
   • Capture the final tool (or fallback) output verbatim for the report.

7. Run static analysis (REQUIRED) — compilation does not check PMD, CRUD/FLS, complexity, and related rules; this step does.

   • Invoke sf code-analyzer run --target <target> on all generated/updated .cls and .trigger files. Remediate all sev0, sev1, and sev2 violations; re-run until clean.
   • This is a distinct gate from Step 6 — a clean compile does not satisfy it, and running it does not substitute for the compile-check.
   • If Code Analyzer cannot run in this environment, record run_code_analyzer=unavailable: <reason> in the report. That explicit outcome is the only acceptable way to skip it.
   • Capture the final tool output verbatim for the report.

8. Execute Apex tests

   • Run org tests including {ClassName}Test via sf apex run test or MCP.
   • Delegate all test generation/fixes/coverage work to platform-apex-test-generate; iterate until the tests pass.
   • Capture pass/fail counts and coverage percentage for the report.
   • If unavailable, record test_execution=unavailable: <error> in the report.

Phase 3 — Report

9. Report -- use the output format at the bottom of this file.
   • The Compile line must contain the actual Step 6 output — either the diagnostics tool result, or the fallback (sf project deploy start --dry-run) result prefixed with apex_diagnostics=unavailable: <reason>. Code Analyzer does NOT belong on this line — it cannot establish that Apex compiles.
   • The Analyzer line must contain the actual Step 7 sf code-analyzer run output (or run_code_analyzer=unavailable: <reason> after attempting invocation).
   • The Testing line must contain the actual Step 8 results (or test_execution=unavailable: <reason> after attempting invocation).
   • A report missing any of these lines is incomplete. Always run each step or record its explicit unavailable outcome before reporting.

Rules

Hard-Stop Constraints (Must Enforce)

If any constraint would be violated in generated code, stop and explain the problem before proceeding:

Bulkification & Governor Limits

• All public APIs accept and process collections; single-record overloads delegate to the bulk method
• In batch/bulk flows, prefer partial-success DML (Database.update(records, false)) and process SaveResult for errors
• Use Map<Id, SObject> constructor for efficient ID-based lookups from query results
• Use Map<Id, List<SObject>> to group child records by parent; build the map in a single loop before processing
• Use Set<Id> for deduplication and membership checks; prefer Set.contains() over List.contains()
• Use relationship subqueries to fetch parent + child records in a single SOQL when both are needed
• Use AggregateResult with GROUP BY for rollup calculations instead of querying and counting in Apex
• Only DML records that actually changed — compare against Trigger.oldMap or prior state before adding to the update list
• Use Limits.getQueries(), Limits.getDmlStatements(), Limits.getCpuTime() to monitor consumption in complex transactions

SOQL Optimization

• Use selective queries with proper WHERE clauses; use indexed fields (Id, Name, OwnerId, lookup/master-detail fields, ExternalId fields, custom indexes) in filters when possible
• SELECT * does not exist in SOQL -- always specify the exact fields needed
• Apply LIMIT clauses to bound result sets; use ORDER BY for deterministic results
• When querying Custom Metadata Types (objects ending with __mdt), do NOT use SOQL — use the built-in methods ({CustomMdt__mdt}.getAll().values(), getInstance(), etc.)

Caching

• Use Platform Cache (Cache.Org / Cache.Session) for frequently accessed, rarely changed data; set a TTL and always handle cache misses — cache can be evicted at any time
• Use private static Map fields as transaction-scoped caches to prevent duplicate queries within the same execution context; lazy-initialize on first access

Security

• Default to with sharing; document justification for without sharing or inherited sharing
• WITH USER_MODE in SOQL and AccessLevel.USER_MODE for Database DML for CRUD/FLS enforcement
• Validate dynamic field/operator names via allowlist or Schema.describe
• Named Credentials for all external credentials/API keys
• AuraHandledException for @AuraEnabled user-facing errors (no internal details)
• without sharing requires a Custom Permission check
• Isolate without sharing logic in dedicated helper classes; call from with sharing entry points to limit elevated-access scope
• Encrypt PII/sensitive data at rest via Platform Encryption; never expose PII in debug statements, error messages, or API responses

Security Verification

Before finalizing, verify: CRUD/FLS enforced (SOQL + DML) · explicit sharing keyword on every class · no hardcoded secrets or Record IDs · PII excluded from logs and error messages · error messages sanitized for end users.

Error Handling

• Catch specific exceptions before generic Exception; include context in messages
• Use try/catch only around code that can throw (DML, callouts, JSON parsing, casts); avoid defensive wrapping of simple assignments/collection ops/arithmetic
• Preserve exception cause chains: new CustomException('message', cause) (do not replace stack trace with concatenated messages)
• Provide a custom exception class per service domain when meaningful
• In @AuraEnabled methods, catch exceptions and rethrow as AuraHandledException
• Fallback option: when no meaningful domain exception exists, catch generic Exception and either rethrow it or wrap it in a minimal custom exception that preserves the original cause.

Null Safety

• Add guard clauses for null/empty inputs at the top of every public method; match style to context: return early in private/trigger-handler methods, throw exceptions in public APIs, record.addError() in validation services
• Return empty collections instead of null
• Use safe navigation (?.) for chained property access
• Never dereference map.get(key) inline unless presence is guaranteed; use containsKey, assignment+null check, or safe navigation first
• Use null coalescing (??) for default values
• Prefer String.isBlank(value) over manual checks like value == null || value.trim().isEmpty()

Constants & Literals

• Use enums over string constants whenever possible; enum values follow UPPER_SNAKE_CASE
• Extract repeated literal strings/numbers into private static final constants or a constants class
• Use Label. custom labels for user-facing strings
• Use Custom Metadata for configurable values (thresholds, mappings, feature flags)
• Never output HTML-escaped entities in code (e.g., '); use literal single quotes ' in Apex string literals

Naming Conventions

Additional naming rules:

• Classes: PascalCase
• Methods: camelCase, start with a verb (get, create, process, validate, is, has, can)
• Variables: camelCase, descriptive nouns; Lists as plural nouns (e.g., accounts, relatedContacts); Maps as {value}By{key} (e.g., accountsById); Sets as {noun}Ids
• Constants: UPPER_SNAKE_CASE
• Use full descriptive names instead of abbreviations (acc, tks, rec)

ApexDoc

• Required on the class header and every public/global method
• Include: brief description, @param, @return, @throws, @example where helpful

Class-level format:

/**
 * Provides services for geolocation and address conversion.
 */
public with sharing class GeolocationService { }

Method-level format:

/**
 * @param paramName Description of the parameter
 * @return Description of the return value
 * @example
 * List<Account> results = AccountService.deduplicateAccounts(accountIds);
 */

Code Structure & Architecture

• Single responsibility per class; max 500 lines -- split when exceeded
• Return Early: validate preconditions at method top, return/throw immediately
• Extract private helpers for methods over ~40 lines
• Use Dependency Injection (constructor/method params) for testability
• Prefer composition and narrow interfaces over deep inheritance; extend via new implementations, not modifications
• Enforce single-level abstraction per method across layer boundaries:

• Disallowed: methods mixing orchestration with inline SOQL/DML/HTTP; business rules mixed with parsing internals; validation + persistence + cross-system plumbing in one method

Async Decision Matrix

Type-Specific Guidance

Service

• Template: assets/service.cls · Reference: references/AccountService.cls
• with sharing; stateless — no public fields or mutable instance state; keep public APIs focused and static where reasonable
• Delegate all SOQL to Selectors and SObject behavior to Domains
• Wrap business errors in a custom exception (e.g., AccountServiceException)

Selector

• Template: assets/selector.cls · Reference: references/AccountSelector.cls
• inherited sharing; one per SObject or query domain
• Return List<SObject> or Map<Id, SObject>; use a shared base field list constant (no inline duplication)
• Accept filter parameters; always include WITH USER_MODE

Domain

• Template: assets/domain.cls
• with sharing; encapsulate field defaults, derivations, and validations
• Operate on in-memory lists only; no SOQL/DML (belongs in Services/Selectors)

Batch

• Template: assets/batch.cls · Reference: references/AccountDeduplicationBatch.cls
• with sharing; implement Database.Batchable<SObject> (add Database.Stateful when tracking across chunks)
• start() = query definition; execute() = business logic; finish() = logging/notification
• Use QueryLocator for large datasets; handle partial failures via Database.SaveResult
• Accept filter parameters via constructor for reusability

Queueable

• Template: assets/queueable.cls
• with sharing; implement Queueable and optionally Database.AllowsCallouts when HTTP callouts are needed
• Accept data via constructor
• Add chain-depth guards to prevent infinite chains
• Optionally implement Finalizer for recovery/cleanup
• Use AsyncOptions for configurable delay (up to 10 min) and dedup signatures

Schedulable

• Template: assets/schedulable.cls
• with sharing; execute() delegates to Queueable or Batch
• Provide CRON constants and a convenience scheduleDaily() helper

DTO / Wrapper

• Template: assets/dto.cls
• No sharing keyword needed (pure data containers)
• Simple public properties; no-arg + parameterized constructors; Comparable when ordering matters
• Use @JsonAccess on private/protected inner DTOs that are serialized/deserialized

Utility

• Template: assets/utility.cls
• No sharing keyword needed; all methods public static; private constructor
• Pure, side-effect-free; no SOQL/DML

Interface

• Template: assets/interface.cls
• Define clear contracts with ApexDoc on each method signature

Abstract

• Template: assets/abstract.cls
• with sharing; offer default behavior via virtual methods
• Mark extension points protected virtual or protected abstract
• Include a concrete example in the ApexDoc showing how to extend the class

Custom Exception

• Template: assets/exception.cls
• No sharing keyword; extend Exception with descriptive names
• Supported constructors: (), ('msg'), (cause), ('msg', cause)

Trigger

• Template: assets/trigger.cls
• One trigger per object; delegate all logic to handler/TAF action classes
• Include all relevant DML contexts; if TAF: new MetadataTriggerHandler().run();

Trigger Action (TAF)

• One class per concern per context; implement TriggerAction.{Context}
• Register via Trigger_Action__mdt (actions are inactive without registration)
• Name: TA_{SObject}_{ActionName}; prefer field-value comparison over static booleans for recursion

Invocable Method (@InvocableMethod)

• Template: assets/invocable.cls
• with sharing; inner Request/Response with @InvocableVariable
• Method must be public static; non-static or single-object signatures will not compile
• Accept List<Request>, return List<Response>; bulkify (SOQL/DML outside loops)
• Decorator parameters: label (required — Flow Builder display name), description, category (groups actions in Builder), callout=true (required when method makes HTTP callouts)
• @InvocableVariable parameters: label (required), description, required=true/false
• @InvocableVariable supports: primitives, Id, SObject, List<T> only (no Map/Set/Blob); use List<Id> or List<SObject> fields for Flow collection I/O
• Always include isSuccess, errorMessage, and errorType (e.getTypeName()) in Response
• Return errors in Response (recommended); throwing an exception triggers the Flow Fault path — reserve for unrecoverable failures only

REST Resource (@RestResource)

• Template: assets/rest-resource.cls
• global with sharing; both class and methods must be global
• Versioned URL: @RestResource(urlMapping='/{resource}/v1/*')
• Use proper HTTP status codes per branch (200/201/400/404/422/500); never default all errors to 500
• Validate inputs (Id format: Pattern.matches('[a-zA-Z0-9]{15,18}', value)); bind all user input in SOQL
• Include LIMIT/ORDER BY in queries; implement pagination (pageSize/offset)
• Standardized ApiResponse wrapper (success, message, data/records); inner request/response DTOs
• Thin controller: delegate business logic to Service classes

@AuraEnabled Controller

• with sharing; use WITH USER_MODE in all SOQL
• Use @AuraEnabled(cacheable=true) only for read-only queries; leave cacheable unset for DML operations
• Catch exceptions and rethrow as AuraHandledException with user-friendly messages

Output Expectations

Deliverables per class:

• {ClassName}.cls
• {ClassName}.cls-meta.xml (default API version 66.0 or higher unless specified)
• {ClassName}Test.cls (generated via platform-apex-test-generate skill)
• {ClassName}Test.cls-meta.xml (generated via platform-apex-test-generate skill)

Deliverables per trigger:

• {TriggerName}.trigger
• {TriggerName}.trigger-meta.xml (default API version 66.0 or higher unless specified)

Meta XML template:

<?xml version="1.0" encoding="UTF-8"?>
<ApexClass xmlns="http://soap.sforce.com/2006/04/metadata">
    <apiVersion>{API_VERSION}</apiVersion>
    <status>Active</status>
</ApexClass>

Report in this order:

Apex work: <summary>
Files: <paths>
Design: <pattern / framework choices>
Workflow: all steps completed (1-9); any N/A justified
Risks: <security, bulkification, async, dependency notes>
Compile: <REQUIRED -- paste actual apex_diagnostics output, or the "sf project deploy start --dry-run" fallback result prefixed with "apex_diagnostics=unavailable: <reason>">
Analyzer: <REQUIRED -- paste actual "sf code-analyzer run" output or state "run_code_analyzer=unavailable: <reason>">
Testing: <REQUIRED -- paste actual test execution results (pass/fail, coverage) or state "test_execution=unavailable: <reason>">
Deploy: <dry-run or next step>

Cross-Skill Integration

Troubleshooting Boundary

This skill handles production .cls/.trigger/.apex issues only: compile/parse failures, deployment dependency errors, runtime governor-limit failures. For test execution, assertions, coverage, or sf apex run test failures, delegate to platform-apex-test-generate.