Claude Code reads a file called CLAUDE.md at the start of every session. In a Salesforce DX project that file is where you write down the rules a new person would need on day one: which org is safe, which commands are fine, and what to never do without asking.
This page gives you a working CLAUDE.md, a skills folder layout, and a settings file. Copy them, edit the bracketed parts, commit them. The file also helps Cursor, Codex and VS Code users: those tools read their own instruction files, and the same text can go in them. Claude Code is the one this page is written for.
The project layout it assumes
A standard Salesforce DX project:
my-salesforce-project/
├── sfdx-project.json # package directories, source API version
├── force-app/ # your source (main/default/classes, flows, objects, ...)
├── config/ # scratch org definition files
├── CLAUDE.md # the file below
└── .claude/
├── settings.json # permissions: what is allowed, asked, denied
└── skills/
├── org-discovery/
│ └── SKILL.md # how to learn an org before changing it
└── safe-deploy/
└── SKILL.md # how to validate and deploy to a sandbox
If your sfdx-project.json lists more than one package directory, say so in CLAUDE.md. The agent will otherwise assume force-app holds everything.
The CLAUDE.md template
# [PROJECT NAME]: Salesforce DX project
## What this is
Salesforce DX source for [CLIENT / TEAM]. Source lives in `force-app/` as defined in `sfdx-project.json`. Keep the source API version already in that file unless I ask for a change.
## Orgs
- Default work org: sandbox alias `[SANDBOX_ALIAS]`. Use `--target-org [SANDBOX_ALIAS]` on every `sf` command. Never rely on the default target org.
- Production alias: `[PROD_ALIAS]`. Treat it as off limits (see Hard rules).
- Run `sf org list` before any task and tell me which org you are about to use.
## Hard rules
1. Sandbox first. Every change is written, validated and tested in `[SANDBOX_ALIAS]` before anything else.
2. Never deploy to production without my written sign-off in this conversation. A dry run to production counts as a deploy: ask first.
3. Never run a command that deletes data or metadata (`sf data delete`, `sf project delete`, destructive changes) without asking, even in a sandbox.
4. Before you change a field, object, Flow or permission, find what depends on it and show me the list. If you cannot prove a thing is unused, say "unknown", not "unused".
5. Do not read or write record data unless the task needs it. Query only the fields you need. Never copy record contents into files, commits or chat.
6. Never print, store or commit access tokens, auth URLs or secrets. `sf org display` can show a token: do not run it with `--verbose` and do not paste its output.
## Commands you may use
- Read: `sf org list`, `sf project retrieve start`, `sf sobject describe`, `sf data query` (SOQL and Tooling API).
- Check: `sf project deploy start --dry-run`, `sf apex run test`, `sf project deploy preview`.
- Change (sandbox only, ask first): `sf project deploy start`.
Anything not on this list: ask.
## How we work
- Small changes. One concern per commit. Describe the why in the message.
- Retrieve before you edit: run `sf project retrieve start` for the component so you start from the org's current version, then show me the diff.
- Apex: bulk-safe, no SOQL or DML in loops, a test class for every class and trigger.
- Flows: edit the Flow, never replace it wholesale. Name new elements clearly and add a description.
- After a deploy to the sandbox, run the relevant tests and report pass or fail with the test names.
## Org map
org map: Clientell MCP (hosted, connected to [SANDBOX_ALIAS]). Use it for questions about the org's structure: what uses a field, which Flows touch an object, who has access. Install: https://www.getclientell.com/salesforce-mcp/install
If the org map and the files in this repo disagree, say so and show both. Do not pick one silently.
## Skills
`.claude/skills/org-discovery`: use before changing anything in an org you have not worked in.
`.claude/skills/safe-deploy`: use for any deploy.
What each part does
| Section | Why it is there |
|---|---|
| Orgs | A named sandbox on every command stops the most common mistake: running against whichever org happens to be the default. |
| Hard rules | Short, numbered, absolute. The agent follows a rule it can check against a command more reliably than a paragraph of advice. |
| Rule 2 (dry run counts) | A validation-only deploy to production still connects to it and can create load and noise. Make it a decision, not a habit. |
| Rule 4 (say "unknown") | Agents tend to answer "nothing else uses this" when they only searched the repo. The wording forces the honest answer. |
| Rule 6 | The Salesforce CLI can print session details. Keep them out of the transcript. |
| Commands you may use | A whitelist is clearer than a blacklist. The settings file below enforces it. |
| Org map | One line tells the agent where to look for what the repo cannot show. |
The settings file
CLAUDE.md is guidance. .claude/settings.json is enforcement. Put this in .claude/settings.json:
{
"permissions": {
"allow": [
"Bash(sf org list:*)",
"Bash(sf sobject describe:*)",
"Bash(sf data query:*)",
"Bash(sf project retrieve start:*)",
"Bash(sf apex run test:*)"
],
"ask": [
"Bash(sf project deploy start:*)"
],
"deny": [
"Bash(sf data delete:*)",
"Bash(sf project delete:*)",
"Bash(sf org login:*)"
]
}
}
With this file, Claude Code runs the read and test commands without asking, stops and asks before any deploy, and refuses the delete commands. Logging in to an org is left to you. Check the current permissions documentation for the exact rule syntax in your version, because it has changed over time.
The skills folder
A skill is a folder with a SKILL.md file. The file starts with a short header (a name and a description) and then plain instructions. Claude Code loads the skill when your request matches the description.
.claude/skills/org-discovery/SKILL.md
---
name: org-discovery
description: Learn a Salesforce org before changing it. Use when starting work in an org you have not worked in, or before changing a field, object, Flow or permission.
---
# Org discovery
1. Run `sf org list` and confirm the sandbox alias with me.
2. Read `sfdx-project.json` and list the package directories.
3. Count the metadata in `force-app`: objects, fields, Flows, Apex classes, triggers, LWCs, permission sets.
4. For the thing I am about to change, list everything that references it. Say what you searched and what you did not.
5. Return: what you found, what is unknown, and the three questions to ask the client before we change anything.
Do not edit any file in this skill. Discovery only.
.claude/skills/safe-deploy/SKILL.md
---
name: safe-deploy
description: Validate and deploy changes to the sandbox. Use whenever a deploy is requested.
---
# Safe deploy
1. Confirm the target is the sandbox alias in CLAUDE.md. If the target is anything else, stop and ask.
2. Run `sf project deploy start --dry-run --target-org [SANDBOX_ALIAS]` with the tests this change needs.
3. Show me the result: components, test pass or fail, any warnings.
4. Wait for my yes. Then run the real deploy to the sandbox.
5. Run the tests again and report. Never deploy to production from this skill.
Edit the bracketed alias to match your project. Keep skills this short. A skill that runs to pages is hard to review and easy to ignore.
Salesforce's own skills
Salesforce publishes a curated collection of agent skills at forcedotcom/sf-skills. Its README lists skills for Flow, Apex, SOQL, Lightning Web Components, objects and fields, and permission sets, among others. They are a good source of patterns for writing your own. They are not an org map: a skill tells the agent how to do a task, and it does not tell it what is in your client's org. If you still have the Salesforce DX MCP server in a config file, read what its end of life means before you carry it into a new project.
Common mistakes
- Writing the production alias into the default target. Set the sandbox as default in your own terminal if you must. The file should still name it on every command.
- A long CLAUDE.md. Keep it to what the agent must know on every task. Move task-specific steps into skills.
- Rules with no check. "Be careful with production" does nothing. "Never run a command with
--target-org [PROD_ALIAS]" can be checked. - Letting the agent answer from the repo alone. A retrieved project is a snapshot of what you pulled. Automations, permissions and anything you did not retrieve are not in it.
- Committing secrets. Add
.sfdx/and.sf/to.gitignoreif they are not already there.
Add an org map
The Org map section of the template is one line. It points the agent at a source for the parts of the org that are not in the repo. Clientell MCP is a hosted server that works in Claude Code, Cursor, Codex and VS Code. It reads records live under the user's own Salesforce permissions and does not store record data. Nothing changes in the org without your approval.
To see the difference on your own project, use the field-usage prompts with and without it.
Start the 14-day trial (no card) and connect a client sandbox
Setup steps are on the install page.
Keep going
- Where is this Salesforce field used? Prompts: eight prompts that rely on the rules in this file.
- Salesforce Org Discovery Kit: a first-hour checklist, queries and a client-org
CLAUDE.mdfor an org you did not build.