slashdev 1.1.0 → 1.3.0

package/claude-skills/salesforce-development/SKILL.md

@@ -0,0 +1,341 @@
+---
+name: salesforce-development
+description: >
+  Use this skill whenever you are working with Salesforce development — Apex classes, triggers,
+  Lightning Web Components (LWC), Flows, SOQL/SOSL queries, or Salesforce integrations. Trigger
+  this skill when you encounter ANY of the following: editing .cls, .trigger, or .apex files;
+  working inside LWC bundles (.js/.html/.css paired with .js-meta.xml); any code inside a
+  force-app/ directory or an sfdx-project.json workspace; mentions of Apex, Salesforce, SFDX,
+  SF CLI, Lightning Web Components, governor limits, SObject triggers, validation rules,
+  permission sets, sharing rules, Connected Apps, Named Credentials, Custom Metadata Types,
+  Platform Events, or Change Data Capture — even without the explicit words "Salesforce
+  development." Salesforce is a multi-tenant platform where code that looks correct by general
+  programming standards WILL fail in production without platform-specific patterns. Consult
+  this skill rather than relying on general programming instincts.
+version: "1.0"
+owner: michael@slashdev.io
+---
+
+# Salesforce Development
+
+Salesforce is a multi-tenant platform. Every line of Apex runs inside shared infrastructure
+with hard governor limits — CPU time, heap size, SOQL queries, DML statements, callouts — all
+capped per transaction. Code that works in a unit test with 1 record will blow up when a data
+loader pushes 200. These five rules are non-negotiable.
+
+---
+
+## Non-Negotiable Rules
+
+### 1. Bulkify everything
+
+Triggers fire on batches of up to 200 records. A single SOQL query or DML statement inside a
+loop means 200 queries or 200 DML operations — both exceed the 100-query / 150-DML governor
+limit and throw a runtime exception.
+
+```apex
+// WRONG — SOQL inside a loop
+trigger SetAccountRating on Contact (after insert) {
+    for (Contact c : Trigger.new) {
+        Account a = [SELECT Id, Rating FROM Account WHERE Id = :c.AccountId];
+        a.Rating = 'Hot';
+        update a;
+    }
+}
+
+// RIGHT — collect, query once, DML once
+trigger SetAccountRating on Contact (after insert) {
+    Set<Id> accountIds = new Set<Id>();
+    for (Contact c : Trigger.new) {
+        accountIds.add(c.AccountId);
+    }
+    List<Account> accounts = [SELECT Id, Rating FROM Account WHERE Id IN :accountIds];
+    for (Account a : accounts) {
+        a.Rating = 'Hot';
+    }
+    update accounts;
+}
+```
+
+### 2. Tests are not optional, and coverage is not the goal
+
+Salesforce enforces 75% code coverage for production deployment, but passing that bar with
+empty assertions is worthless. Every test must:
+
+- **Create its own data** — never use `@IsTest(SeeAllData=true)`.
+- **Test the bulk path** — insert 200+ records to prove bulkification.
+- **Use `Test.startTest()` / `Test.stopTest()`** — resets governor limits and forces async
+  jobs to complete synchronously.
+- **Assert on outcomes** — verify field values, record counts, error messages. A test
+  without assertions is not a test.
+
+```apex
+@IsTest
+private class SetAccountRatingTest {
+    @IsTest
+    static void shouldSetRatingForBulkContacts() {
+        List<Account> accounts = TestDataFactory.createAccounts(5, true);
+        List<Contact> contacts = new List<Contact>();
+        for (Account a : accounts) {
+            for (Integer i = 0; i < 50; i++) {
+                contacts.add(new Contact(FirstName = 'Test', LastName = 'Contact' + i, AccountId = a.Id));
+            }
+        }
+
+        Test.startTest();
+        insert contacts;  // 250 contacts — proves bulk handling
+        Test.stopTest();
+
+        List<Account> updated = [SELECT Rating FROM Account WHERE Id IN :accounts];
+        for (Account a : updated) {
+            Assert.areEqual('Hot', a.Rating, 'Account rating should be Hot after contact insert');
+        }
+    }
+}
+```
+
+### 3. Respect the security model
+
+Apex runs in **system mode** by default — it bypasses field-level security and sharing rules.
+This is a security risk in any context where user-supplied data or user-facing UI is involved.
+
+- **Default every class to `with sharing`**. This enforces the running user's record-level
+  access (sharing rules, org-wide defaults, role hierarchy).
+- **Use `without sharing` only with a documented reason** — e.g., a service class that must
+  aggregate data across all accounts for a rollup.
+- **Enforce FLS** on every SOQL query that surfaces data to users:
+  - `WITH SECURITY_ENFORCED` in the query (throws if user lacks field access)
+  - `Security.stripInaccessible(AccessType.READABLE, records)` after the query (silently
+    strips inaccessible fields)
+
+```apex
+// RIGHT — with sharing + FLS enforcement
+public with sharing class AccountService {
+    public List<Account> getVisibleAccounts() {
+        return [SELECT Id, Name, Industry FROM Account WITH SECURITY_ENFORCED];
+    }
+}
+```
+
+### 4. Never hardcode endpoints or credentials
+
+All HTTP callouts go through **Named Credentials**. Named Credentials manage the endpoint URL,
+authentication scheme (OAuth, certificate, password), and per-user or per-org identity — all
+configured in Setup, not in code.
+
+```apex
+// WRONG — hardcoded endpoint and bearer token
+HttpRequest req = new HttpRequest();
+req.setEndpoint('https://api.example.com/v1/accounts');
+req.setHeader('Authorization', 'Bearer ' + myToken);
+
+// RIGHT — Named Credential handles URL + auth
+HttpRequest req = new HttpRequest();
+req.setEndpoint('callout:ExampleAPI/v1/accounts');
+req.setMethod('GET');
+```
+
+### 5. Prefer declarative over code
+
+Before writing Apex, evaluate whether the requirement can be met with:
+
+- **Flow** — screen flows for user input, record-triggered flows for automation, scheduled
+  flows for batch-like processing
+- **Validation rules** — field-level constraints with error messages
+- **Formula fields** — derived values without storage cost
+- **Roll-up summary fields** — aggregations on master-detail relationships
+
+Apex is justified when you need: complex branching logic, HTTP callouts with custom error
+handling, Batch Apex for high-volume processing, or unit-testable mocking of dependencies.
+
+---
+
+## Apex Patterns
+
+### One trigger per object, handler class delegation
+
+Never put logic in a `.trigger` file. Delegate to a handler class so logic is testable,
+bypassable, and composable.
+
+```apex
+// AccountTrigger.trigger
+trigger AccountTrigger on Account (before insert, before update, after insert, after update) {
+    new AccountTriggerHandler().run();
+}
+```
+
+The handler extends a `TriggerHandler` base class with virtual methods for each context
+(`beforeInsert`, `afterUpdate`, etc.). See `references/apex-patterns.md` for the full base
+class with bypass and recursion control.
+
+### SOQL guidance
+
+- **Use indexed filters** — `Id`, `Name`, `CreatedDate`, `SystemModstamp`, `RecordTypeId`,
+  `foreign key fields`, and any field with a custom index.
+- **Use bind variables** — `WHERE Id IN :idSet` — never concatenate strings into queries.
+- **Be selective** — queries on large objects must return < 100K rows or use a selective filter
+  that narrows via an indexed field first.
+- **Never use `SELECT *`** — Apex doesn't support it, but don't emulate it with
+  `DescribeSObjectResult.getFields()` loops. Explicitly list fields.
+
+### Async flavor selection
+
+| Pattern | Use when | Key constraint |
+|---------|----------|----------------|
+| `@future` | Legacy — simple fire-and-forget | No chaining, no complex types, 50 calls/txn |
+| `Queueable` | **Default async choice** — callouts, chaining, complex types | 50 enqueued/txn, chain depth varies by edition |
+| `Batch Apex` | Processing > 50K records | 5 concurrent batches, scope of 200 default |
+| `Schedulable` | Cron-based execution | Enqueue a Queueable or start a Batch from `execute()` |
+
+**Triggers cannot make synchronous callouts.** From a trigger, enqueue a `Queueable` with
+`Database.AllowsCallouts` or call an `@future(callout=true)` method.
+
+---
+
+## Lightning Web Components
+
+### Bundle structure
+
+Every LWC lives in a directory under `force-app/main/default/lwc/`:
+
+```
+myComponent/
+├── myComponent.js          // Controller — class extending LightningElement
+├── myComponent.html        // Template — HTML with lwc directives
+├── myComponent.css         // Scoped styles (optional)
+└── myComponent.js-meta.xml // Metadata — API version, targets, visibility
+```
+
+The `.js-meta.xml` is required. Without it, the component won't deploy.
+
+### @wire vs imperative Apex
+
+- **`@wire`** — for **reads**. Cacheable, reactive, automatically re-fetches when reactive
+  parameters change. The Apex method must be annotated `@AuraEnabled(cacheable=true)`.
+- **Imperative** — for **writes** or when you need fine-grained control over timing. Call
+  the imported Apex method as a promise. The method needs `@AuraEnabled` but NOT `cacheable`.
+
+```javascript
+import getAccounts from '@salesforce/apex/AccountController.getAccounts';
+import saveAccount from '@salesforce/apex/AccountController.saveAccount';
+
+// Wire for reads
+@wire(getAccounts, { industry: '$selectedIndustry' })
+wiredAccounts;
+
+// Imperative for writes
+async handleSave() {
+    try {
+        await saveAccount({ account: this.record });
+        this.dispatchEvent(new ShowToastEvent({ title: 'Saved', variant: 'success' }));
+    } catch (error) {
+        this.dispatchEvent(new ShowToastEvent({ title: 'Error', message: reduceErrors(error).join(', '), variant: 'error' }));
+    }
+}
+```
+
+### Prefer SLDS base components
+
+Use `lightning-input`, `lightning-datatable`, `lightning-combobox`, `lightning-card`,
+`lightning-button`, and other base components over custom HTML. They handle accessibility,
+responsive layout, and Salesforce theming automatically.
+
+See `references/lwc-patterns.md` for parent-child communication, Lightning Message Service,
+`refreshApex`, navigation, and `@salesforce/*` imports.
+
+---
+
+## Flow vs Apex Decision Framework
+
+| Criteria | Use Flow | Use Apex |
+|----------|----------|----------|
+| Simple field updates on save | Yes | No |
+| Screen-based user input | Yes | No |
+| Complex branching (> 5 decision nodes) | No | Yes |
+| HTTP callouts with error handling | No | Yes |
+| Processing > 50K records | No | Yes (Batch Apex) |
+| Need unit-testable mocking | No | Yes |
+| Team has no Apex developers | Yes | No |
+
+Flows and Apex compose: expose Apex logic as `@InvocableMethod` for Flows to call, or invoke
+a Flow from Apex via `Flow.Interview`.
+
+---
+
+## Project Structure and Metadata
+
+Standard SFDX source format layout:
+
+```
+force-app/
+└── main/
+    └── default/
+        ├── classes/           // Apex classes (.cls + .cls-meta.xml)
+        ├── triggers/          // Apex triggers (.trigger + .trigger-meta.xml)
+        ├── lwc/               // LWC bundles (one directory per component)
+        ├── aura/              // Aura components (legacy — do not create new ones)
+        ├── objects/           // Custom objects and fields
+        ├── flows/             // Flow definitions (.flow-meta.xml)
+        ├── permissionsets/    // Permission sets
+        ├── namedCredentials/  // Named Credentials
+        ├── customMetadata/    // Custom Metadata Type records
+        ├── layouts/           // Page layouts
+        ├── flexipages/        // Lightning pages
+        └── staticresources/   // Static resources
+```
+
+Key conventions:
+- Every `.cls` and `.trigger` file requires a companion `-meta.xml` file
+- Custom objects end in `__c`, custom fields in `__c`, custom metadata types in `__mdt`
+- `sfdx-project.json` at the repo root defines package directories and API version
+- `.forceignore` works like `.gitignore` — controls what deploys
+
+---
+
+## Anti-Patterns to Reject
+
+- **SOQL or DML inside loops** — governor limit violation waiting to happen
+- **Logic in `.trigger` files** — untestable, unbypassable, unmaintainable
+- **`@IsTest(SeeAllData=true)`** — couples tests to org data, breaks in sandboxes
+- **Hardcoded credentials or endpoints** — use Named Credentials
+- **Undocumented `without sharing`** — security risk; always comment why
+- **New Aura components** — use LWC; Aura is legacy
+- **Process Builder or Workflow Rules** — use Flow; both are deprecated
+- **Tests with no assertions** — 75% coverage of nothing
+- **Tests that depend on execution order** — each test must be independent
+- **Catching and swallowing `DmlException`** — masks data integrity failures; catch, log/surface, then handle or rethrow
+- **`SELECT` with string concatenation** — SOQL injection risk; use bind variables
+- **Recursive triggers without recursion guards** — infinite loop potential
+
+---
+
+## When to Load Reference Files
+
+- **`references/apex-patterns.md`** — full TriggerHandler base class, Queueable with chaining,
+  Batch Apex, Schedulable, integration callout patterns, custom exceptions
+- **`references/lwc-patterns.md`** — parent-child communication, Lightning Message Service,
+  @wire with refreshApex, uiRecordApi vs Apex, error handling, NavigationMixin, @salesforce imports
+- **`references/testing-patterns.md`** — TestDataFactory class, bulk testing, HTTP callout
+  mocking, async testing, System.runAs, @testSetup, modern Assert patterns
+
+---
+
+## Deployment Checklist
+
+Before marking any Salesforce task as complete, verify:
+
+1. **Test coverage** — run tests for all modified classes. Minimum 75% overall, aim for 85%+
+   on new code. Every test has meaningful assertions.
+2. **Permission sets** — if you created new custom fields or objects, create or update a
+   permission set granting access. Do NOT modify profiles directly — profiles are org-specific
+   and cause deployment conflicts. Propose permission sets instead and flag profile changes as
+   risky.
+3. **`.forceignore`** — respect it. Do not deploy files listed there.
+4. **Meta.xml files** — every Apex class and trigger has a companion `-meta.xml` with the
+   correct API version.
+5. **Ask about deployment workflow** — do not assume. The team may use SF CLI (`sf project
+   deploy start`), Change Sets, unlocked packages, Gearset, Copado, or another tool. Ask
+   before suggesting deployment commands.
+6. **No hardcoded IDs** — record type IDs, user IDs, and org IDs vary between environments.
+   Use `Schema.SObjectType.Account.getRecordTypeInfosByDeveloperName()` or Custom Metadata
+   Types for environment-specific values.