AI rules file for Salesforce repos: who owns it?
An AI rules file is the Markdown file a coding agent reads at the start of every session: CLAUDE.md for Claude Code, AGENTS.md for Codex and Copilot, .vibes/rules/ for Agentforce Vibes. Your Salesforce repository needs one as soon as anyone, internal or partner, codes with an agent, because otherwise every tool and every partner follows its own conventions. The file belongs to the client and has a named owner on your side, usually the lead architect. It guides the agent. Whatever must happen every time goes into settings, hooks and the pipeline.
What is an AI rules file, and which tool reads which file?
A rules file holds standing project instructions in plain Markdown: commands, conventions, pitfalls and what “done” means. The agent loads it into its context when a session starts, so it does not have to rediscover your project each time. Every major tool has one, under different names:
Which tool reads which file
Sources: Claude Code memory docs1, OpenAI Codex best practices2, GitHub Docs3, Agentforce Vibes rules4.
For a team with several tools, two details decide whether one file is enough. According to the GitHub changelog of 28 August 20255, the Copilot coding agent reads AGENTS.md next to GitHub’s own formats, plus CLAUDE.md and GEMINI.md. Claude Code reads AGENTS.md from version 2.1.277, but only if no CLAUDE.md or CLAUDE.local.md exists in the working directory or above. The Vibes documentation does not mention AGENTS.md at all, so Vibes needs its own short rule in .vibes/rules/.
The rules file belongs to the client
Partners like to bring their own template. That is quick at the start and expensive later, for the reasons in why clients should own their DevOps tools: whoever writes the rules sets the standard. For rules files I see three specific reasons.
The file records decisions only you can make. Which API version new Apex classes use, which Named Credential is the only route to SAP, which of two warranty date fields is the maintained one. The API version line is no formality: from API 67.0, Apex runs in user context by default and classes without a sharing declaration run in the current user’s context, according to the Apex Developer Guide6. Whether an old class may move to 67.0 is an architecture decision for your org, not a partner’s habit.
The file outlives the partner. When an engagement ends, the conventions stay in your repository.
The file keeps partners comparable. One file, one definition of done for every team. With two partners and two templates on one org, the louder template quietly becomes your standard.
Ownership means a named person on the client side approves every change, typically the lead architect or the internal tech lead, with a deputy. Partners propose, they do not merge. I would write that into the annex described in what belongs in the contract when partners code with AI.
What goes into the rules file, and what must be enforced elsewhere?
Anthropic’s documentation is plain about the limit: Claude treats CLAUDE.md files “as context, not enforced configuration”. The Claude Code best practices7 add: “If something has to happen every time, make it a hook, a deny rule, or a managed setting. CLAUDE.md is for guidelines, and Claude is allowed to decide a guideline doesn’t apply.” OpenAI makes the length point: “A short, accurate AGENTS.md is more useful than a long file full of vague rules.”
So the file holds what the agent cannot see in the code. Anthropic’s list: the exact commands to confirm work, places where the code is misleading, decisions written down nowhere in the repository, and “anything you’ve had to correct twice already”. The memory docs target under 200 lines per file. For a machine builder’s repository, the sections could look like this:
AGENTS.mdEntry
- Owner
- Lead architect; changes only via pull request
- Orgs
- Scratch orgs or the development sandbox, never UAT or production
- Commands
- The exact commands for one test class, static analysis and a validation deploy
- Apex
- New classes on API 67.0 with an explicit sharing declaration; no version change on existing classes unless the task says so
- SAP
- Calls only through the stored connection to S/4, never addresses in code
- Data model
- Which warranty date field the SAP interface maintains and which one is a read-only migration leftover
About 90 lines in the worked example below. "Done" means real tests and the test output in the pull request.
Everything that must hold without exception goes somewhere the model cannot argue with:
Where the hard rules belong
For developers
Deny rules and hook for Claude Code
- Deny rules in the committed
.claude/settings.json:Read(~/.sf/),Read(~/.sfdx/), `Bash(sf - -o mb-prod*)
andBash(sf - --target-org mb-prod*)
. They hold in every permission mode, including auto andbypassPermissions`. - Stop hook: a script that runs the tests and Code Analyzer and exits with code 2 while either is red; Claude then keeps working.
- Pointer file: a
CLAUDE.mdwith the single line@AGENTS.md, and a Vibes rule with the file pattern**/*.cls. - Commands for the rules file:
sf apex run test -n MyClassTest -o mb-dev,sf code-analyzer run --target force-app,sf project deploy validate -o mb-int --test-level RunLocalTests.
Deny rules have limits too. Anthropic’s permissions docs8 say a Bash rule matches the command text the agent writes and “isn’t a security boundary around the program”: the same command wrapped in another shell call is not caught. The real boundary is that production credentials never reach a developer laptop and only the pipeline deploys to production. Salesforce lets you disable Agentforce Vibes for a production org9 under Setup, Agentforce Vibes Extensions. If you provide the Claude licences yourself, managed settings apply, which according to Anthropic no personal settings file can override.
Worked example: three tools, two partners, one file
Assume a machine builder with Service Cloud, Field Service, a dealer portal on Experience Cloud and SAP S/4 as ERP. Partner A builds the portal and service processes with six nearshore developers and Claude Code. Partner B builds the SAP integration with three developers and Copilot. Two internal developers use Agentforce Vibes. All figures are assumptions to show the method.
The repository holds partner A’s CLAUDE.md from an earlier project, about 300 lines, which sets API 62.0 for all classes. Partner B’s copilot-instructions.md says nothing about API versions and allows direct HTTP callouts “for quick tests”. Vibes runs with its built-in rules only. The internal architect writes the same review comment about sharing declarations several times per sprint.
The client then sets this up:
- One AGENTS.md of about 90 lines, owned by the internal architect, built from the old coding standard and the review findings of the last sprints.
- A two-line CLAUDE.md that points to AGENTS.md, and a Vibes rule for Apex files that repeats the Apex section.
- Committed deny rules for the production alias, and Code Analyzer, tests and a validation deploy as merge gates in the client’s pipeline.
- CODEOWNERS for all rules and settings files.
Partner A’s template becomes a proposal pull request; a handful of lines survive. Assume two days for the first version and half an hour per sprint afterwards. The reviewer still reviews, but stops repeating the same comments.
Changes go through pull requests with CODEOWNERS
Rules files are part of your controls. GitHub’s documentation notes that Copilot code review reads custom instructions from the pull request’s head branch. A pull request that edits copilot-instructions.md therefore changes the instructions its own AI review runs with. In the same way, a committed deny rule can be deleted in a pull request like any other line.
That is why I would put every rules and settings file under CODEOWNERS10: AGENTS.md, CLAUDE.md, .claude/, .vibes/ and .github/copilot-instructions.md. With “Require review from Code Owners” in the branch protection, the owner’s approval becomes mandatory. GitHub requires code owners to have write permission, which only works if the repository sits in your organisation. The same logic applies to shared objects, as described in the object ownership matrix.
The file grows from evidence, not from wish lists. OpenAI recommends adding rules after repeated mistakes, Anthropic after the second correction. In practice, the input is the review findings counted by category, as described in reviewing AI-generated Salesforce code. Lines move out again once a pipeline gate covers them. After each Salesforce release, the owner checks the API version line first.
Take stock of the rules files in your repository
- 01
Take stock
Search the repository for CLAUDE.md, AGENTS.md, .github/copilot-instructions.md and .vibes/rules/, and ask every partner which tools it uses.
- 02
Name the owner
One person and a deputy on your side.
- 03
Write the first version
Under 200 lines, from your coding standard and the last review findings.
- 04
Add the pointers
A short CLAUDE.md that points to AGENTS.md, and one Vibes rule.
- 05
Move the hard rules out
Deny rules, a hook that stops the agent while tests are red, and the gates from quality gates for AI code, with Vibes disabled in production.
- 06
Protect the files
With CODEOWNERS and branch protection.
Setting this up is part of my work in DevOps and release management and in partner governance. For the first version I plan a few days.
Sources10
- 1Claude Code memory docs (opens in a new tab)code.claude.com
- 2OpenAI Codex best practices (opens in a new tab)developers.openai.com
- 3GitHub Docs (opens in a new tab)docs.github.com
- 4Agentforce Vibes rules (opens in a new tab)developer.salesforce.com
- 5GitHub changelog of 28 August 2025 (opens in a new tab)github.blog
- 6Apex Developer Guide (opens in a new tab)developer.salesforce.com
- 7Claude Code best practices (opens in a new tab)code.claude.com
- 8permissions docs (opens in a new tab)code.claude.com
- 9disable Agentforce Vibes for a production org (opens in a new tab)developer.salesforce.com
- 10CODEOWNERS (opens in a new tab)docs.github.com
Frequently asked questions
Do I need a separate AI rules file for every coding tool?
Mostly not. One AGENTS.md serves Codex and Copilot, and Claude Code through a short CLAUDE.md that imports it. Agentforce Vibes reads .vibes/rules/ and its docs do not mention AGENTS.md, so keep a short Vibes rule and update it in the same pull request.
Who should own the AI rules file in a partner project?
A named person on the client side, usually the lead architect or the internal tech lead, plus a deputy. Partners propose changes through pull requests, and a CODEOWNERS entry with branch protection makes the owner's approval mandatory.
Does a rules file stop an agent from deploying to production?
No. The model may decide a guideline does not apply. Keep production credentials off developer machines, deploy only through the pipeline, add deny rules for production aliases and disable Agentforce Vibes for production orgs in Setup.
How long should an AI rules file be?
Anthropic targets under 200 lines per CLAUDE.md, and OpenAI says a short, accurate AGENTS.md beats a long file of vague rules. Add a line when a review finding repeats, and delete lines that the pipeline already enforces.