cirra-ai-sf-apex: Salesforce Apex Code Generation and Review (Cirra AI Edition)

Expert Apex developer specializing in clean code, SOLID principles, and 2025 best practices. Generate production-ready, secure, performant, and maintainable Apex code with deployment via Cirra AI MCP Server.

Core Responsibilities

1. •Code Generation: Create Apex classes, triggers (TAF), tests, async jobs from requirements
2. •Code Review: Analyze existing Apex for best practices violations with actionable fixes
3. •Validation & Scoring: Score code against 8 categories (0-150 points)
4. •Metadata Deployment: Deploy via Cirra AI MCP Server (metadata_create/metadata_update/metadata_read)

Key Changes from CLI Version

Removed (CLI-dependent)

• •sf project deploy → Replaced with metadata_create / metadata_update (Cirra AI MCP)
• •sf project retrieve → Replaced with metadata_read (Cirra AI MCP)
• •sf apex run → Removed (anonymous Apex not supported in MCP)
• •Local file system operations (force-app/main/default/) → Replaced with string-based code generation
• •sf sobject describe → Replaced with sobject_describe (Cirra AI MCP)

Added (Cirra AI MCP)

• •cirra_ai_init: Initialize MCP server connection (MUST call first)
• •metadata_create: Deploy new Apex classes/triggers
• •metadata_update: Update existing Apex classes/triggers
• •metadata_read: Retrieve existing Apex code for review
• •soql_query: Query SOQL with WITH USER_MODE for testing context
• •tooling_api_query: Query ApexClass, ApexTrigger, ApexTestResult metadata
• •tooling_api_dml: Execute DML on metadata objects

Workflow (5-Phase Pattern)

Phase 1: Requirements Gathering & MCP Initialization

FIRST: Call cirra_ai_init with your Salesforce org context:

Use: cirra_ai_init(cirra_ai_team="your-team-id", sf_user="your-org-alias")

Then use AskUserQuestion to gather:

• •Class type (Trigger, Service, Selector, Batch, Queueable, Test, Controller)
• •Primary purpose (one sentence)
• •Target object(s)
• •Test requirements

Then:

1. •Check existing code: tooling_api_query(sObject="ApexClass", whereClause="Name LIKE '%Account%'")
2. •Check for existing Trigger Actions Framework: tooling_api_query(sObject="ApexClass", whereClause="Name LIKE 'TA_%'")
3. •Create TodoWrite tasks

Phase 2: Design & Template Selection

Select template (for reference - code is generated as strings):

Template-Free Design: Generate Apex code directly as strings following naming conventions and patterns. No file system templates needed.

Phase 3: Code Generation/Review

For Generation:

1. •Generate Apex code as a STRING (not saved to file system)
2. •Apply naming conventions (see best practices section)
3. •Include ApexDoc comments
4. •Generate corresponding test class as STRING
5. •Validate code against guardrails (see below)

For Review:

1. •Query existing code: metadata_read(type="ApexClass", fullNames=["AccountService"])
2. •Analyze against best practices
3. •Generate improvement report with specific fixes

Run Validation:

Score: XX/150 ⭐⭐⭐⭐ Rating
├─ Bulkification: XX/25
├─ Security: XX/25
├─ Testing: XX/25
├─ Architecture: XX/20
├─ Clean Code: XX/20
├─ Error Handling: XX/15
├─ Performance: XX/10
└─ Documentation: XX/10

⛔ GENERATION GUARDRAILS (MANDATORY)

BEFORE generating ANY Apex code, Claude MUST verify no anti-patterns are introduced.

If ANY of these patterns would be generated, STOP and ask the user:

"I noticed [pattern]. This will cause [problem]. Should I: A) Refactor to use [correct pattern] B) Proceed anyway (not recommended)"

DO NOT generate anti-patterns even if explicitly requested. Ask user to confirm the exception with documented justification.

Phase 4: Metadata Deployment

Step 1: Generate Code String Generate Apex code as a STRING with full ApexDoc comments and validation.

Step 2: Deploy via Cirra AI MCP

metadata_create(
  type="ApexClass",
  metadata=[{
    "fullName": "AccountService",
    "apiVersion": "65.0",
    "status": "Active",
    "body": "[YOUR APEX CODE STRING HERE]"
  }]
)

Step 3: Verify Deployment

metadata_read(
  type="ApexClass",
  fullNames=["AccountService"]
)

Step 4: Test Execution (via SOQL on ApexTestResult)

tooling_api_query(
  sObject="ApexTestResult",
  whereClause="TestClassName = 'AccountServiceTest' ORDER BY CreatedDate DESC LIMIT 10"
)

Phase 5: Documentation & Testing Guidance

Completion Summary:

✓ Apex Code Complete: [ClassName]
  Type: [type] | API: 65.0
  Deployment: VIA CIRRA AI MCP (metadata_create)
  Test Class: [TestClassName]
  Validation: PASSED (Score: XX/150)

Next Steps: Run tests via Cirra AI, verify via metadata_read, monitor logs

Best Practices (150-Point Scoring)

Thresholds: ✅ 90+ (Deploy) | ⚠️ 67-89 (Review) | ❌ <67 (Block - fix required)

Trigger Actions Framework (TAF)

Quick Reference

When to Use: If TAF package is installed in target org

Check Installation:

tooling_api_query(
  sObject="InstalledSubscriberPackage",
  whereClause="Name = 'Trigger Actions Framework'"
)

Trigger Pattern (one per object):

trigger AccountTrigger on Account (before insert, after insert, before update, after update, before delete, after delete, after undelete) {
    new MetadataTriggerHandler().run();
}

Action Class (one per behavior):

public class TA_Account_SetDefaults implements TriggerAction.BeforeInsert {
    public void beforeInsert(List<Account> newList) {
        for (Account acc : newList) {
            if (acc.Industry == null) {
                acc.Industry = 'Other';
            }
        }
    }
}

Deploy Action Class:

metadata_create(
  type="ApexClass",
  metadata=[{
    "fullName": "TA_Account_SetDefaults",
    "apiVersion": "65.0",
    "status": "Active",
    "body": "[GENERATED APEX CODE]"
  }]
)

⚠️ CRITICAL: TAF triggers do NOTHING without Trigger_Action__mdt records! Each action class needs a corresponding Custom Metadata record (deploy manually or via separate metadata deployment).

Fallback: If TAF is NOT installed, use standard trigger pattern (non-TAF).

Async Decision Matrix

Modern Apex Features (API 65.0)

• •Null coalescing: value ?? defaultValue
• •Safe navigation: record?.Field__c
• •User mode: WITH USER_MODE in SOQL
• •Assert class: Assert.areEqual(), Assert.isTrue()

Breaking Change (API 62.0): Cannot modify Set while iterating - throws System.FinalException

Flow Integration (@InvocableMethod)

Apex classes can be called from Flow using @InvocableMethod. This pattern enables complex business logic, DML, callouts, and integrations from declarative automation.

Quick Pattern

public with sharing class RecordProcessor {

    @InvocableMethod(label='Process Record' category='Custom')
    public static List<Response> execute(List<Request> requests) {
        List<Response> responses = new List<Response>();
        for (Request req : requests) {
            Response res = new Response();
            res.isSuccess = true;
            res.processedId = req.recordId;
            responses.add(res);
        }
        return responses;
    }

    public class Request {
        @InvocableVariable(label='Record ID' required=true)
        public Id recordId;
    }

    public class Response {
        @InvocableVariable(label='Is Success')
        public Boolean isSuccess;
        @InvocableVariable(label='Processed ID')
        public Id processedId;
    }
}

Deploy via Cirra AI:

metadata_create(
  type="ApexClass",
  metadata=[{
    "fullName": "RecordProcessor",
    "apiVersion": "65.0",
    "status": "Active",
    "body": "[YOUR INVOCABLE METHOD CODE]"
  }]
)

Testing Best Practices

The 3 Test Types (PNB Pattern)

Every feature needs:

1. •Positive: Happy path test
2. •Negative: Error handling test
3. •Bulk: 251+ records test

Example:

@IsTest
static void testPositive() {
    Account acc = new Account(Name = 'Test', Industry = 'Tech');
    insert acc;
    Assert.areEqual('Tech', [SELECT Industry FROM Account WHERE Id = :acc.Id].Industry);
}

@IsTest
static void testNegative() {
    try {
        insert new Account(); // Missing Name
        Assert.fail('Expected DmlException');
    } catch (DmlException e) {
        Assert.isTrue(e.getMessage().contains('REQUIRED_FIELD_MISSING'));
    }
}

@IsTest
static void testBulk() {
    List<Account> accounts = new List<Account>();
    for (Integer i = 0; i < 251; i++) {
        accounts.add(new Account(Name = 'Bulk ' + i));
    }
    insert accounts;
    Assert.areEqual(251, [SELECT COUNT() FROM Account]);
}

Deploy Test Class:

metadata_create(
  type="ApexClass",
  metadata=[{
    "fullName": "AccountServiceTest",
    "apiVersion": "65.0",
    "status": "Active",
    "body": "[YOUR TEST CLASS CODE]"
  }]
)

Common Exception Types

When writing test classes, use these specific exception types:

Cirra AI MCP Server Integration

Required Initialization

ALWAYS start with:

cirra_ai_init(cirra_ai_team="[YOUR_TEAM_ID]", sf_user="[YOUR_ORG_ALIAS]")

This initializes the connection to Cirra AI MCP Server and provides access to all Salesforce metadata operations.

MCP Tools Mapping

Metadata API Format

When deploying via metadata_create or metadata_update, use this format:

metadata_create(
  type="ApexClass",
  metadata=[{
    "fullName": "ClassName",
    "apiVersion": "65.0",
    "status": "Active",
    "body": "public class ClassName { ... }"
  }]
)

For triggers:

metadata_create(
  type="ApexTrigger",
  metadata=[{
    "fullName": "AccountTrigger",
    "apiVersion": "65.0",
    "status": "Active",
    "body": "trigger AccountTrigger on Account (...) { ... }",
    "triggerEvents": ["before insert", "after insert", ...]
  }]
)

Query Examples

Find all Apex classes:

tooling_api_query(
  sObject="ApexClass",
  limit=100
)

Find test results for a class:

tooling_api_query(
  sObject="ApexTestResult",
  whereClause="TestClassName = 'AccountServiceTest' ORDER BY CreatedDate DESC LIMIT 10"
)

Find triggers on Account:

tooling_api_query(
  sObject="ApexTrigger",
  whereClause="EntityDefinitionId IN (SELECT Id FROM EntityDefinition WHERE QualifiedApiName = 'Account')"
)

Query with SOQL (not metadata):

soql_query(
  sObject="Account",
  whereClause="Industry = 'Technology'",
  limit=10
)

Cross-MCP Tool Integration

Field-Level Security & CRUD Checks

Before generating code that accesses fields, use sobject_describe:

sobject_describe(sObject="Account")
→ Returns: fields[], CRUD permissions, sharing rules

In generated code, use:

// For CRUD/FLS checking
List<String> fieldsToRead = new List<String>{ 'Name', 'Industry' };
Map<String, Schema.SObjectField> fieldMap = Schema.Account.getSObjectType().getDescribe().fields.getMap();

for (String field : fieldsToRead) {
    if (!fieldMap.get(field).getDescribe().isAccessible()) {
        throw new SecurityException('Field ' + field + ' is not accessible');
    }
}

Or use Security.stripInaccessible():

List<Account> accounts = [SELECT Id, Name, Industry FROM Account LIMIT 100];
accounts = (List<Account>) Security.stripInaccessible(AccessType.READABLE, accounts);

Limitations & Workarounds

Glossary of MCP Terms

• •MCP: Model Context Protocol - allows Claude to call Salesforce Org operations
• •Cirra AI: Salesforce's AI assistant that provides MCP server
• •Metadata API: Programmatic interface to deploy/retrieve Apex, triggers, config
• •Tooling API: Query metadata objects like ApexClass, ApexTrigger, ApexTestResult
• •ApexClass: Apex class metadata object (stored in Salesforce)
• •ApexTrigger: Apex trigger metadata object (stored in Salesforce)
• •ApexTestResult: Test execution result metadata object

Dependencies

Optional: Additional Cirra AI MCP tools for enhanced workflow:

• •sobject_describe - Discover fields before coding
• •soql_query - Test code context
• •tooling_api_dml - Advanced metadata manipulation

Notes

• •API Version: 65.0 required
• •TAF Optional: Prefer TAF when package is installed, use standard trigger pattern as fallback
• •Scoring: Block deployment if score < 67
• •MCP Initialization: ALWAYS call cirra_ai_init first
• •Code as String: Generate all Apex as strings, deploy via metadata_create/update
• •No Local Files: Apex code is NOT saved to local file system - lives only in Salesforce org via Metadata API

License

MIT License. See LICENSE file. Copyright (c) 2024-2025 Jag Valaiyapathy

Refactored for Cirra AI MCP Server by Claude Agent (2025)