Platform Apex Generate

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

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 and 7 each require a tool invocation and produce output that must appear in the Step 8 report. Do not summarize or present the report until both steps have run and their output is captured.

6. Run code analyzer

   • Invoke MCP run_code_analyzer on all generated/updated .cls files.
   • Remediate all sev0, sev1, and sev2 violations; re-run until clean.
   • Capture the final tool output verbatim for the report.
   • Fallback: sf code-analyzer run --target <target>. If both are unavailable, record run_code_analyzer=unavailable: <error> in the report.

7. 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

8. Report -- use the output format at the bottom of this file.
   • The Analyzer line must contain the actual Step 6 tool output (or run_code_analyzer=unavailable: <reason> after attempting invocation).
   • The Testing line must contain the actual Step 7 results (or test_execution=unavailable: <reason> after attempting invocation).
   • A report missing either line is incomplete. Always attempt the tool invocation before recording unavailable.

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.)
• Queries executed in without sharing keyword classes with API versions 67.0 and up will throw when the running user does not have the proper field or object-level security. If API versions are being updated, ensure queries are safeguarded properly, and that tests are updated accordingly. Only explicitly justified usages of SYSTEM_MODE variants within queries should be allowed by default.

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 — these are the defaults for all Apex classes with API versions of 67.0 or higher
• 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)