KI-Regeldatei im Salesforce-Repository: wem gehört sie?

Eine KI-Regeldatei ist die Markdown-Datei, die ein Coding-Agent zu Beginn jeder Sitzung liest: CLAUDE.md bei Claude Code, AGENTS.md bei Codex und Copilot, .vibes/rules/ bei Agentforce Vibes. Ihr Salesforce-Repository braucht eine, sobald jemand intern oder beim Partner mit einem Agenten programmiert, sonst folgt jedes Werkzeug und jeder Partner eigenen Konventionen. Die Datei gehört dem Kunden und hat auf Ihrer Seite eine benannte verantwortliche Person, meist den Lead-Architekten. Sie leitet den Agenten an. Was jedes Mal gelten muss, gehört in Settings, Hooks und Pipeline.

Was ist eine KI-Regeldatei, und welches Werkzeug liest welche Datei?

Eine Regeldatei enthält dauerhafte Projektanweisungen in einfachem Markdown: Befehle, Konventionen, Fallstricke und was „fertig“ bedeutet. Der Agent lädt sie beim Start einer Sitzung in seinen Kontext und muss Ihr Projekt nicht jedes Mal neu erkunden. Jedes große Werkzeug kennt so eine Datei, nur unter anderem Namen:

Welches Werkzeug welche Datei liest

WerkzeugDatei im RepositoryWichtiges Detail

Claude CodeCLAUDE.md, dazu Pfadregeln in .claude/rules/Liest AGENTS.md nur, wenn es keine CLAUDE.md gibt

OpenAI CodexAGENTS.mdEine Datei näher am aktuellen Ordner gewinnt

GitHub Copilotcopilot-instructions.md, AGENTS.md oder eine CLAUDE.mdDie nächstgelegene AGENTS.md hat Vorrang

Agentforce Vibes.vibes/rules/Jede Regel gilt immer oder per Dateimuster

Quellen: Claude-Code-Doku zu Memory1, OpenAI Codex Best Practices2, GitHub Docs3, Agentforce Vibes Rules4.

Arbeitet Ihr Team mit mehreren Werkzeugen, entscheiden zwei Details, ob eine Datei reicht. Laut GitHub-Changelog vom 28. August 20255 liest der Copilot Coding Agent AGENTS.md neben GitHubs eigenen Formaten, außerdem CLAUDE.md und GEMINI.md. Claude Code liest AGENTS.md ab Version 2.1.277, aber nur, wenn im Arbeitsverzeichnis oder darüber keine CLAUDE.md oder CLAUDE.local.md liegt. Die Vibes-Dokumentation erwähnt AGENTS.md gar nicht, Vibes braucht also eine eigene kurze Regel in .vibes/rules/.

Die Regeldatei gehört dem Kunden

Partner bringen gern ihre eigene Vorlage mit. Das geht am Anfang schnell und wird später teuer, aus den Gründen in warum Kunden ihre DevOps-Tools selbst besitzen sollten: Wer die Regeln schreibt, setzt den Standard. Für Regeldateien sehe ich drei konkrete Gründe.

Die Datei hält Entscheidungen fest, die nur Sie treffen können. Welche API-Version neue Apex-Klassen nutzen, welcher Named Credential der einzige Weg zu SAP ist, welches von zwei Garantiedatumsfeldern gepflegt wird. Die Zeile zur API-Version ist keine Formalie: Ab API 67.0 läuft Apex laut Apex Developer Guide6 standardmäßig im Benutzerkontext, und Klassen ohne Sharing-Deklaration laufen im Kontext des aktuellen Benutzers. Ob eine alte Klasse auf 67.0 wechseln darf, ist eine Architekturentscheidung für Ihre Org, keine Gewohnheit des Partners.

Die Datei überdauert den Partner. Endet ein Auftrag, bleiben die Konventionen in Ihrem Repository.

Die Datei hält Partner vergleichbar. Eine Datei, eine Definition of Done für alle Teams. Mit zwei Partnern und zwei Vorlagen auf einer Org wird sonst still die lautere Vorlage zu Ihrem Standard.

Verantwortung heißt: Eine benannte Person auf Kundenseite gibt jede Änderung frei, typischerweise der Lead-Architekt oder der interne Tech Lead, mit Vertretung. Partner schlagen vor, sie mergen nicht. Das würde ich in die Anlage schreiben, die ich in was in den Vertrag gehört, wenn Partner mit KI programmieren beschreibe.

Was gehört in die Regeldatei, und was muss anderswo erzwungen werden?

Anthropic benennt die Grenze klar: Claude behandelt CLAUDE.md-Dateien „as context, not enforced configuration“. In den Claude Code Best Practices7 heißt es weiter: „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 ergänzt zur Länge: „A short, accurate AGENTS.md is more useful than a long file full of vague rules.“

Die Datei enthält also, was der Agent nicht im Code sieht. Anthropics Liste: die genauen Befehle, mit denen sich Arbeit prüfen lässt, Stellen, an denen der Code in die Irre führt, Entscheidungen, die nirgends im Repository stehen, und „anything you’ve had to correct twice already“. Die Memory-Doku nennt als Ziel unter 200 Zeilen pro Datei. Für das Repository eines Maschinenbauers könnten die Abschnitte so aussehen. Die Datei selbst halte ich englisch, damit Nearshore-Teams und Partner sie ohne Übersetzung lesen:

Alles, was ohne Ausnahme gelten muss, gehört an einen Ort, mit dem das Modell nicht verhandeln kann:

Wohin die harten Regeln gehören

RegelWohin sie gehörtWarum dort

Kein Zugriff auf Anmeldedateien und ProduktionDeny-Regeln in den eingecheckten Claude-SettingsGelten in jedem Berechtigungsmodus

Kein „fertig“ bei roten TestsEin Hook, der läuft, wenn der Agent aufhören willSchickt den Agenten zurück an die Arbeit

Codeanalyse, Tests, ValidierungsdeploymentPipeline als Merge-GateLäuft unabhängig vom Werkzeug

Kein Agent in ProduktionKeine Produktionszugänge auf Entwicklerrechnern; Vibes je Produktions-Org ausEine Textdatei entzieht keinen bestehenden Zugriff

Änderungen an Sharing, Datenmodell, RegeldateienBranch-Schutz mit Code OwnersEine Person auf Ihrer Seite gibt frei

Für Entwickler

Deny-Regeln und Hook für Claude Code

• Deny-Regeln in der eingecheckten .claude/settings.json: Read(~/.sf/), Read(~/.sfdx/), `Bash(sf
• -o mb-prod*) und Bash(sf
• --target-org mb-prod*). Sie gelten in jedem Berechtigungsmodus, auch in Auto und bypassPermissions`.
• Stop-Hook: ein Skript, das Tests und Code Analyzer ausführt und mit Exit-Code 2 endet, solange etwas rot ist; Claude arbeitet dann weiter.
• Verweisdatei: eine CLAUDE.md mit der einzigen Zeile @AGENTS.md und eine Vibes-Regel mit dem Dateimuster **/*.cls.
• Befehle für die Regeldatei: 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.

Auch Deny-Regeln haben Grenzen. Laut Berechtigungsdoku von Anthropic8 prüft eine Bash-Regel den Befehlstext, den der Agent schreibt, und sie „isn’t a security boundary around the program“: Derselbe Befehl in einen weiteren Shell-Aufruf verpackt fällt durch. Die eigentliche Grenze ist, dass Produktionszugänge nie auf einem Entwicklerrechner landen und nur die Pipeline nach Produktion deployt. Agentforce Vibes lässt sich laut Salesforce im Setup unter Agentforce Vibes Extensions für eine Produktions-Org deaktivieren9. Stellen Sie die Claude-Lizenzen selbst, greifen Managed Settings, die laut Anthropic keine persönliche Settings-Datei überschreiben kann.

Beispiel: drei Werkzeuge, zwei Partner, eine Datei

Nehmen wir einen Maschinenbauer mit Service Cloud, Field Service für den Außendienst, einem Händlerportal auf Experience Cloud und SAP S/4 als ERP. Partner A baut Portal und Serviceprozesse mit sechs Nearshore-Entwicklern und Claude Code. Partner B baut die SAP-Schnittstelle mit drei Entwicklern und Copilot. Zwei interne Entwickler nutzen Agentforce Vibes. Alle Zahlen sind Annahmen, die das Vorgehen zeigen sollen.

Im Repository liegt die CLAUDE.md von Partner A aus einem früheren Projekt, rund 300 Zeilen, die API 62.0 für alle Klassen vorgibt. Die copilot-instructions.md von Partner B sagt nichts zu API-Versionen und erlaubt direkte HTTP-Callouts „für schnelle Tests“. Vibes läuft nur mit seinen eingebauten Regeln. Der interne Architekt schreibt mehrmals pro Sprint denselben Review-Kommentar zu fehlenden Sharing-Deklarationen.

Der Kunde richtet daraufhin ein:

• Eine AGENTS.md mit rund 90 Zeilen, verantwortet vom internen Architekten, aufgebaut aus dem alten Coding-Standard und den Review-Funden der letzten Sprints.
• Eine zweizeilige CLAUDE.md, die auf AGENTS.md verweist, und eine Vibes-Regel für Apex-Dateien, die den Apex-Abschnitt wiederholt.
• Eingecheckte Deny-Regeln für den Produktions-Alias sowie Code Analyzer, Tests und Validierungs-Deployment als Merge-Gates in der Pipeline des Kunden.
• CODEOWNERS für alle Regel- und Settings-Dateien.

Die Vorlage von Partner A wird zum Vorschlags-Pull-Request; eine Handvoll Zeilen bleibt. Angenommen sind zwei Tage für die erste Fassung und danach eine halbe Stunde pro Sprint. Der Reviewer prüft weiter, schreibt aber nicht mehr dieselben Kommentare.

Änderungen laufen per Pull Request mit CODEOWNERS

Regeldateien sind Teil Ihrer Kontrollen. Laut GitHub-Dokumentation liest Copilot Code Review die Anweisungen aus dem Head-Branch des Pull Requests. Ein Pull Request, der copilot-instructions.md ändert, ändert also die Anweisungen, mit denen sein eigenes KI-Review läuft. Genauso lässt sich eine eingecheckte Deny-Regel per Pull Request löschen wie jede andere Zeile.

Deshalb würde ich jede Regel- und Settings-Datei unter CODEOWNERS10 stellen: AGENTS.md, CLAUDE.md, .claude/, .vibes/ und .github/copilot-instructions.md. Mit „Require review from Code Owners“ in der Branch Protection wird die Freigabe der verantwortlichen Person zur Pflicht. GitHub verlangt Schreibrechte für Code Owner, das funktioniert also nur, wenn das Repository in Ihrer Organisation liegt. Dieselbe Logik gilt für gemeinsam genutzte Objekte, wie in der Object Ownership Matrix beschrieben.

Die Datei wächst aus Belegen, nicht aus Wunschlisten. OpenAI empfiehlt, Regeln nach wiederholten Fehlern zu ergänzen, Anthropic nach der zweiten Korrektur. In der Praxis sind die Review-Funde nach Kategorie die Grundlage, wie in KI-generierten Salesforce-Code prüfen beschrieben. Zeilen fliegen wieder raus, sobald ein Pipeline-Gate sie abdeckt. Nach jedem Salesforce-Release prüft die verantwortliche Person zuerst die Zeile zur API-Version.

Vorhandene Regeldateien im Repository aufnehmen

1. 01

   Bestand aufnehmen

   Suchen Sie im Repository nach CLAUDE.md, AGENTS.md, .github/copilot-instructions.md und .vibes/rules/, und fragen Sie jeden Partner, welche Werkzeuge er nutzt.

2. 02

   Verantwortliche benennen

   Eine Person mit Vertretung auf Ihrer Seite.

3. 03

   Erste Fassung schreiben

   Unter 200 Zeilen, aus Ihrem Coding-Standard und den letzten Review-Funden.

4. 04

   Verweise anlegen

   Eine kurze CLAUDE.md, die auf AGENTS.md verweist, und eine Vibes-Regel.

5. 05

   Harte Regeln auslagern

   Deny-Regeln, ein Hook, der den Agenten bei roten Tests nicht aufhören lässt, und die Gates aus Quality Gates für KI-Code, Vibes in Produktion deaktiviert.

6. 06

   Dateien schützen

   Mit CODEOWNERS und Branch Protection.

Das Einrichten gehört zu meiner Arbeit in DevOps und Release-Management und in der Partnersteuerung. Für die erste Fassung rechne ich mit wenigen Tagen.

Quellen10

1. 1Claude-Code-Doku zu Memory (öffnet in einem neuen Tab)code.claude.com
2. 2OpenAI Codex Best Practices (öffnet in einem neuen Tab)developers.openai.com
3. 3GitHub Docs (öffnet in einem neuen Tab)docs.github.com
4. 4Agentforce Vibes Rules (öffnet in einem neuen Tab)developer.salesforce.com
5. 5GitHub-Changelog vom 28. August 2025 (öffnet in einem neuen Tab)github.blog
6. 6Apex Developer Guide (öffnet in einem neuen Tab)developer.salesforce.com
7. 7Claude Code Best Practices (öffnet in einem neuen Tab)code.claude.com
8. 8Berechtigungsdoku von Anthropic (öffnet in einem neuen Tab)code.claude.com
9. 9für eine Produktions-Org deaktivieren (öffnet in einem neuen Tab)developer.salesforce.com
10. 10CODEOWNERS (öffnet in einem neuen Tab)docs.github.com