description: "Primary Apex authoring skill for class generation, refactoring, and review. ALWAYS ACTIVATE when the user mentions Apex, .cls, triggers, or asks to create/refactor a class (service, selector, domain, batch, queueable, schedulable, invocable, DTO, utility, interface, abstract, exception, REST resource). Use this skill for requests involving SObject CRUD, mapping collections, fetching related records, scheduled jobs, batch jobs, trigger design, @AuraEnabled controllers, @RestResource endpoints, custom REST APIs, or code review of existing 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.
- 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:
| Constraint | Rationale |
|---|---|
| Place all SOQL outside loops | Avoid query governor limits (100 queries) |
| Place all DML outside loops | Avoid DML governor limits (150 statements) |
| Declare a sharing keyword on every class | Prevent unintended `without sharing` defaults and data exposure |
| Use Custom Metadata/Labels/describe calls instead of hardcoded IDs | Ensure portability across orgs |
| Use bind variables for all dynamic SOQL with user input | Prevent SOQL injection |
| Use Apex-native collections (`List`, `Map`, `Set`) rather than Java types | Prevent compile errors |
| Verify methods exist in Apex before use | Prevent reliance on non-existent APIs |
| Avoid `System.debug()` in main code paths | Debug statements evaluate even when loggign is not active and consume CPU. Use a logging framework if required on main code paths |
| Never use `@future` methods | Use Queueable with `System.Finalizer`; `@future` cannot chain, cannot be called from Batch, and cannot accept non-primitive types |
### 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
| Type | Pattern | Example |
|---|---|---|
| Service | `{SObject}Service` | `AccountService` |
| Data/Integration | SOQL, DML, HTTP | Business decisions |
- 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
| Scenario | Default | Key Traits |
|---|---|---|
| Standard async work | **Queueable** | Job ID, chaining, non-primitive types, configurable delay (up to 10 min via `AsyncOptions`), dedup signatures |
| Very large datasets | **Batch Apex** | Chunked processing, max 5 concurrent; use `QueryLocator` for large scopes |
| Modern batch alternative | **CursorStep** (`Database.Cursor`) | 2000-record chunks, higher throughput, no 5-job limit |
| Recurring schedule | **Scheduled Flow** (preferred) or **Schedulable** | Schedulable has 100-job limit; use only when chaining to Batch or needing complex Apex logic |
-`@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`
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`.
