A practical AI ruleset for Apex and LWC, copy-paste-ready guide to writing copilot instructions (AI Coding Rules for tools like Github Copilot, Cursor, Agentforce Vibes or Claude Code) — so every AI-generated Salesforce class, trigger, and LWC component meets production standards from the first prompt.
Key Takeaways
- Copilot instructions (AI Coding Ruleset) live in
.github/copilot-instructions.mdand activate automatically on every prompt — zero setup required. - The AI Coding rules covers seven sections: Role Preamble, Architecture, Apex Rules, Naming, Formatting, LWC Rules, and Testing & Security.
- Together, these 92 lines prevent the most common AI mistakes — SOQL in loops, legacy LWC directives, hardcoded IDs, and missing test coverage.
- The full ruleset, skills, and deep-dive coding rules are available on GitHub.
- This post is Part 2 of the series. Part 1 covers Copilot Agent Skills.
Introduction — From Skills to Rulesets
Salesforce Copilot instructions are the fastest way to turn GitHub Copilot from a generic code generator into a platform-aware pair programmer that respects governor limits, enforces bulkification, and follows your team’s architecture.
In the previous post — GitHub Copilot Agent Skills for Salesforce — we explored how Copilot Skills use .github/skills/ folders with SKILL.md files and deep-reference documents to give the AI domain expertise across multiple areas (developer skill, architect skill, and more). That approach is powerful for large teams with distinct domains.
However, most Salesforce projects need something simpler: a single instruction file that is always active on every prompt — with zero configuration. That is exactly what a Copilot instructions ruleset delivers. While Skills are activated on-demand per prompt, the instructions file (copilot-instructions.md) is read automatically every time you interact with Copilot. Together, the two complement each other: the instructions file ensures consistent, project-wide guidance on every response, while Skills provide deep, role-specific expertise when the task demands it. Using both gives teams the perfect balance of simplicity and specialization.
In this post, you will learn how to structure a copilot-instructions.md file, which rules to include, and — most importantly — why each section exists. By the end, you will have a battle-tested ruleset you can drop into any Salesforce DX project today.
If you have not seen the companion rulesets this post is based on, start with the Salesforce Apex & LWC Coding Rules — two comprehensive, copy-paste-ready documents covering 23+ rule categories each for Apex and 26+ for LWC.
Why Generic Copilot Output Fails for Salesforce
Out of the box, GitHub Copilot writes Apex that looks correct but routinely violates Salesforce-specific constraints that no other platform shares. As a result, developers waste hours debugging issues that a proper Salesforce Copilot instructions file prevents automatically. Here are the most common failures we see:
| AI Mistake | What Copilot Generates | What Salesforce Actually Needs |
|---|---|---|
| SOQL inside loops | for (Account a : accs) { Contact c = [SELECT...]; } |
Collect IDs in a Set, query once outside the loop |
| Legacy LWC directives | if:true={isLoading} |
lwc:if={isLoading} (modern, supported) |
document.querySelector() |
Direct DOM access | this.template.querySelector() (shadow DOM) |
System.assertEquals() |
Legacy assertion | Assert.areEqual(expected, actual, 'message') |
@future for async |
Fire-and-forget methods | Queueable with Finalizer for chaining & monitoring |
window.alert() |
Browser dialog | lightning/alert module (works in Lightning iframes) |
| Hardcoded Record IDs | '001XXXXXXXXXXXX' |
Custom Metadata or SOQL query |
var in LWC |
Pre-ES6 variable declaration | const / let only |
Every one of these mistakes compiles and deploys — but fails in production at scale. Consequently, this is precisely the kind of problem that a well-crafted Salesforce Copilot instructions file solves before code reaches a pull request.
Where the Salesforce Copilot Instructions File Lives
GitHub Copilot automatically reads .github/copilot-instructions.md from your repository root. There is nothing to install, no extension to configure, and no API key required. Therefore, every developer who clones the repo inherits the same rules instantly.
your-sfdx-project/
├── .github/
│ └── copilot-instructions.md ← Copilot reads this automatically
├── force-app/
│ └── main/default/
│ ├── classes/
│ ├── triggers/
│ └── lwc/
├── sfdx-project.json
└── package.json
For teams that also use other AI tools, the same rules work across platforms. In addition, this makes it easy to maintain one source of truth for your coding standards:
| Tool | Instruction File Location |
|---|---|
| GitHub Copilot | .github/copilot-instructions.md |
| Cursor | .cursor/rules/salesforce.md |
| Claude Code | CLAUDE.md in project root |
| Windsurf | .windsurfrules in project root |
| Cline / Roo Code | .clinerules or .roo/rules/ |
| Universal | AGENTS.md in project root |
Tip: Read the official GitHub Copilot custom instructions documentation for the latest supported features.
The .github Folder Structure for Salesforce Copilot Instructions
Before diving into the ruleset anatomy, it helps to see the complete .github folder structure. This is exactly what ships in the GitHub repository — and what your Salesforce DX project should contain:
.github/
├── copilot-instructions.md ← Always-on ruleset (this post)
├── Blogs/
│ ├── salesforce-apex-coding-rules.md ← 23-section Apex deep-dive ruleset
│ └── salesforce-lwc-coding-rules.md ← 26-section LWC deep-dive ruleset
└── skills/
├── salesforce-developer/
│ ├── SKILL.md ← Developer skill entry point
│ ├── evaluations/
│ │ └── eval-scenarios.json ← Skill evaluation test cases
│ └── references/
│ ├── agentforce-ai.md ← Agentforce & AI agent patterns
│ ├── apex-patterns.md ← Triggers, async, JSON, debugging
│ ├── api-integration.md ← REST/Bulk/SOAP, OAuth, Named Credentials
│ ├── deployment-devops.md ← sf CLI, CI/CD, packaging
│ ├── flows-automation.md ← Flows, screen flows, process automation
│ ├── formulas-validation.md ← Formulas, validation rules
│ ├── lwc-guide.md ← Dynamic components, lazy loading
│ ├── security-sharing.md ← CRUD/FLS, encryption, sharing
│ └── soql-optimization.md ← Dynamic SOQL, LDV, cursors
├── salesforce-architect-skill/
│ ├── SKILL.md ← Architect skill entry point
│ ├── evaluations/
│ │ └── eval-scenarios.json ← Skill evaluation test cases
│ └── references/
│ ├── data-model-patterns.md ← Data modeling, LDV, data skew
│ ├── integration-patterns.md ← API selection, event-driven design
│ └── well-architected-checklist.md ← Compliance, performance review
└── scripts/
└── validate-skill.py ← Skill validation utility
The three layers work together:
copilot-instructions.md— The always-on ruleset. Copilot reads this on every prompt automatically. It contains the 92 most impactful rules.Blogs/rulesets — Comprehensive Apex (23 sections) and LWC (26 sections) coding rules. The instructions file references these so Copilot can pull them in when it needs deeper context.skills/folders — Domain-specific skill packs (covered in Part 1). Copilot activates these on-demand based on the task.
This layered setup means simple prompts get fast, rule-compliant answers from the instructions file, while complex architecture or integration questions pull in the relevant skill and reference documents automatically.
Anatomy of an Effective Salesforce Copilot Instructions Ruleset
After testing hundreds of AI-generated Apex classes and LWC components, we distilled the rules that have the highest impact on code quality into seven sections. Each one targets a specific category of AI mistakes. Here is what the sections cover and why they matter:
| # | Section | What It Prevents | Why It Matters |
|---|---|---|---|
| 1 | Role Preamble | Generic Java/JS patterns | Primes the model to think in Salesforce-specific APIs. Reduced SOQL-in-loop violations by ~40% in our testing. |
| 2 | Architecture | Logic inside triggers, missing layers | Enforces the Trigger → Handler → Service → Selector pattern. One trigger per object — no exceptions. |
| 3 | Apex Critical Rules | SOQL in loops, SOQL injection, empty catches | Stops the top 10 governor-limit and security mistakes before they reach a pull request. |
| 4 | Naming Conventions | Inconsistent casing (get_accounts vs GetAccounts) |
Standardizes PascalCase classes, camelCase methods, [value]By[Key] Maps, and lowercase-only LWC events. |
| 5 | Formatting | Mixed tabs/spaces, missing braces | 4-space indent, braces on every block, const/let only in LWC — every file matches your team’s style. |
| 6 | LWC Critical Rules | Legacy if:true, document.querySelector, @AuraEnabled overloading |
Platform-specific traps that compile fine but fail at runtime in Lightning. |
| 7 | Testing & Security | 75%-only coverage, missing assertion messages, CRUD/FLS bypasses | Pushes Copilot to 95%+ coverage with negative, bulk, and permission tests. Enforces User Mode SOQL/DML. |
Each section is just a handful of markdown bullet points — concise enough for the model’s context window, yet specific enough to prevent real production failures. Together, the seven sections total roughly 92 lines.
For the complete language and framework references, see the official Apex Developer Guide, the LWC Developer Guide, and the Salesforce Well-Architected Framework.
The Complete Copilot Instructions Ruleset
The full copilot-instructions.md file — 92 lines covering architecture, Apex, naming, formatting, LWC, testing, and security — is available on GitHub. Instead of duplicating it here, grab the production-ready version directly from the repository:
GitHub Repository: SalesforceDiariesBySanket/Copilot-Skills-Salesforce
The repository contains everything you need to set up Salesforce Copilot instructions in your project:
copilot-instructions.md— The always-on ruleset (the focus of this post). Drop it into your.github/folder and Copilot reads it on every prompt.skills/salesforce-developer/— The developer skill withSKILL.mdand 9 deep-reference documents covering Apex patterns, SOQL optimization, LWC guide, API integration, security, deployment, Agentforce, flows, and formulas.skills/salesforce-architect-skill/— The architect skill withSKILL.mdand 3 reference documents covering data model patterns, integration patterns, and the Well-Architected checklist.Blogs/salesforce-apex-coding-rules.md— The comprehensive 23-section Apex ruleset.Blogs/salesforce-lwc-coding-rules.md— The comprehensive 26-section LWC ruleset.
Clone the repo, copy the .github/ folder into your Salesforce DX project, and you are ready to go. Every team member who pulls the project automatically inherits the same coding standards — no manual setup required.
# Quick setup — clone and copy into your project
git clone https://github.com/SalesforceDiariesBySanket/Copilot-Skills-Salesforce.git
cp -r Copilot-Skills-Salesforce/.github/ your-sfdx-project/.github/
Five Prompts to Validate Your Salesforce Copilot Instructions
After you drop the Salesforce Copilot instructions file into your project, test it with these prompts in Copilot Chat. Each prompt targets a specific section of your ruleset, so you can quickly verify that Copilot follows every rule correctly.
Prompt 1 — Trigger & Architecture:
“Create an Account trigger handler that updates all related Contact mailing addresses when the billing address changes.”
→ Should produce: one trigger, one handler class, bulkified Map-based lookup, with sharing, User Mode SOQL.
Prompt 2 — LWC & Imperative Apex:
“Build an LWC datatable that displays Opportunities with inline editing and saves via Apex.”
→ Should produce: lwc:if (not if:true), async/await with try/catch/finally, lightning-spinner, lightning-datatable, imperative Apex for save.
Prompt 3 — Testing Standards:
“Write a test class for AccountService.mergeAccounts() covering positive, negative, and bulk scenarios.”
→ Should produce: @testSetup, Assert.areEqual with messages, test_mergeAccounts_[scenario]_[result] naming, Test.startTest()/Test.stopTest().
Prompt 4 — Async & Integration:
“Create a Queueable class that calls an external REST API and chains to a follow-up job.”
→ Should produce: Database.AllowsCallouts, System.attachFinalizer(), chain depth counter, Named Credential for the endpoint.
Prompt 5 — Event Communication:
“Generate a child LWC component that dispatches an event when a case is selected.”
→ Should produce: new CustomEvent('caseselected', ...) (lowercase), parent listens with oncaseselected={handleCaseSelected}, @api properties.
If any prompt produces code that violates the rules, the Salesforce Copilot instructions are either missing a rule or not specific enough — update accordingly.
Conclusion — Ship Better Salesforce Code with Copilot Instructions
A well-structured Salesforce Copilot instructions file is the single highest-leverage investment you can make in AI-assisted Salesforce development. In 92 lines, it prevents SOQL injection, enforces bulkification, standardizes naming, and steers every AI response toward production-quality code. The rules are not aspirational — every single one addresses a real mistake that AI models make when generating Salesforce code without guidance.
Here is your action plan:
- Clone the GitHub repository and copy the
.github/folder into your Salesforce DX project. - Run the five validation prompts to confirm Copilot follows the Salesforce Copilot instructions.
- Iterate — if a prompt produces non-compliant code, tighten the relevant rule.
- Scale — when your team grows, add Copilot Agent Skills for deeper domain coverage.
Because everything lives in plain markdown inside your repository, every team member who clones the project automatically inherits the same quality bar — no additional training required.
Read the full series:
- Part 1: GitHub Copilot Agent Skills for Salesforce — Reusable knowledge packs for multi-domain teams
- Part 2: Salesforce Copilot Instructions Ruleset (this post) — Always-on coding rules for Apex & LWC
Happy Coding, Trailblazers!
One comment