> For the complete documentation index, see [llms.txt](https://docs.arnica.io/arnica-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.arnica.io/arnica-documentation/code-risks/agentic-rules-enforcer.md).

# Agentic Rules Enforcer

Use the Agentic Rules Enforcer to add your security coding rules to the instruction files that AI coding assistants read in every repository.

## Summary

AI coding assistants such as Cursor, GitHub Copilot, and Claude read instruction files in the repository to learn how to write code for it. The Agentic Rules Enforcer lets security teams write security coding rules once in Arnica and add them to those instruction files in every repository. AI assistants then follow your organization's security standards as they write code, instead of developers having to ask for them in every prompt.

The Agentic Rules Enforcer has three parts:

1. **AI coding rules** — rule sets that you create and manage in Arnica.
2. **Delivery** — Arnica adds the rules to repositories, either automatically on new pull requests through a policy action, or all at once through pull requests that Arnica opens.
3. **Annotations** — when an AI assistant applies one of Arnica's rules, it leaves a comment that cites the rule. Arnica detects these comments and shows them in the inventory, so you can see where the rules prevented a risk.

{% hint style="info" %}
The Agentic Rules Enforcer is an add-on. If your tenant doesn't have it, the **AI Coding Rules** tab shows an upgrade message. Contact your Arnica account team for details.
{% endhint %}

## Supported AI coding assistants

Arnica writes the rules to the following files, at the root of the repository:

| Platform                  | File                                    | How Arnica writes it |
| ------------------------- | --------------------------------------- | -------------------- |
| Coding Agents             | `AGENTS.md`                             | Create or update     |
| Cursor                    | `.cursor/rules/arnica-<rule alias>.mdc` | Create or replace    |
| GitHub Copilot            | `.github/copilot-instructions.md`       | Create or update     |
| Google Gemini Code Assist | `GEMINI.md`                             | Create or update     |
| Claude                    | `CLAUDE.md`                             | Create or update     |
| Augment                   | `.augment/rules/arnica-<rule alias>.md` | Create or replace    |

`AGENTS.md` is an open format read by many coding agents and tools. See [agents.md](https://agents.md/).

### How files are written

* **Create or update** — Arnica adds the rules to the file inside a managed block, marked by `ARNICA AI CODING RULES START` and `ARNICA AI CODING RULES END` comments. If the file already exists, Arnica changes only the managed block and leaves the rest of the file unchanged, so developers can keep their own instructions in the same file.
* **Create or replace** — the file belongs to Arnica. It is named after the rule alias, and Arnica rewrites it each time. Arnica adds the settings each assistant needs to always apply the rules.

Every file starts with a notice that its rules are managed by Arnica and links developers to [Adding AI Coding Rules](https://docs.arnica.io/arnica-documentation/developers/ai-coding-rules.md), which explains the change.

{% hint style="warning" %}
Don't edit the content inside the managed block, or a file that Arnica creates or replaces. Arnica overwrites those changes the next time it updates the rules. To change the rules, edit them in Arnica.
{% endhint %}

## Managing AI coding rules

Navigate to **Admin** → **AI Configurations** → **AI Coding Rules**. The **AI Coding Assistant Rules** table lists every rule with its alias, description, status, and whether a policy uses it. Select **Hide draft rules** to show only rules that are ready.

### Creating a rule

1. Click **Create Rule**.
2. Fill in the rule:
   * *Name:* a display name, at least 3 characters.
   * *Alias:* a unique identifier, at least 3 characters, using only letters, numbers, `-`, and `_`. Arnica uses the alias in file names and commit messages.
   * *Description:* at least 10 characters.
   * *Rule Content:* the instructions for AI assistants, in plain text or Markdown, at least 50 characters.
3. Select **Ready** when the rule is complete. Only ready rules can be used in policies or deployed. New rules are saved as drafts.
4. Click **Create**.

The **Rule Content** editor starts with Arnica's **Security Best Practices for AI Agents** rule set. It covers authentication, access control, session management, input validation, path traversal, SSRF, remote code execution, output encoding, secrets, cryptography, and more. You can use it as is, or edit it to match your organization's standards.

### Rule IDs and annotations

Each guideline in Arnica's rule set ends with a rule ID, such as `ARNIE_AUTH_PASSWORD_HASHING`. The rule set tells AI assistants to cite the rule ID in a code comment whenever they apply it:

```javascript
// Agentic Rule (ARNIE_AUTH_PASSWORD_HASHING): Using bcrypt with 12 rounds for secure password hashing
```

Arnica finds these comments and reports them as annotations. See [Viewing adoption](#viewing-adoption).

{% hint style="info" %}
Arnica counts annotations for rule IDs that start with `ARNIE_`. If you add your own guidelines, give them `ARNIE_` IDs to have their citations counted.
{% endhint %}

### Viewing a rule

Click a rule to expand it. The expanded rule has three tabs:

* **Details** — the rule's settings and content.
* **Pull Requests** — the pull requests Arnica opened to deploy the rule, with the repository, target branch, and status of each.
* **Deployment** — deploys the rule to repositories. See [Deploying rules to repositories](#deploying-rules-to-repositories).

## Adding rules on pull requests

Use a Code Risk policy rule to add the AI coding rules to a repository's source branch whenever a developer opens a pull request.

1. Navigate to **Admin** → **Policies** and open the **Code Risk** policy.
2. Add a rule with the **Pull request created** trigger.
3. Optionally, add conditions to limit the rule to specific repositories or products.
4. Add the **Inject AI Coding Rules** action.
5. In **AI Coding Rules**, select the rule to add. Only ready rules are listed. Click **Manage Rules** to create or edit rules.
6. Under **Platform Configuration**, turn on each AI assistant whose file Arnica should write. By default, only **Coding Agents** (`AGENTS.md`) is on.
7. Optionally, enter a **Custom Message**. Arnica adds it to the files as a message from the security team.
8. Save the policy.

When a pull request is created, Arnica commits the updated files directly to the pull request's source branch. The commit message has the format `chore(security): update AI coding rules [<alias>] for <platforms>`.

Arnica doesn't commit when:

* The files already have the current rules.
* The selected rule was deleted or is no longer ready.
* The event was caused by Arnica's own commit.
* Arnica can't push to the pull request's source branch.

{% hint style="info" %}
Developers who see this commit in their pull request can read [Adding AI Coding Rules](https://docs.arnica.io/arnica-documentation/developers/ai-coding-rules.md), which explains why the files were added and that they are safe to merge.
{% endhint %}

## Deploying rules to repositories

To add a rule to many repositories at once, without waiting for new pull requests, deploy it. Arnica opens a pull request in each repository.

1. Navigate to **Admin** → **AI Configurations** → **AI Coding Rules**.
2. Click the rule and open the **Deployment** tab.
3. Under **Deployment Scope**, select the repositories:
   * **Active Repositories** (default) — repositories that aren't archived and had activity in the last 90 days.
   * **Repositories without Arnica rules** — repositories where Arnica hasn't found any [annotations](#viewing-adoption) yet.
   * **All Repositories**
   * **Selected Repositories** — repositories you pick from the list.
4. Under **Platforms**, turn on each AI assistant whose file Arnica should write.
5. Optionally, enter a **Custom Message (optional)**.
6. Click **Deploy Rule**. If the deployment targets 10 or more repositories, confirm it.

For each repository, Arnica opens a pull request to each [SLA branch](https://docs.arnica.io/arnica-documentation/code-risks/code-risk-policy-settings/sla-branches.md), or to the default branch if the repository has no SLA branches. The pull request is titled `(<branch>) Deploy Arnica AI coding rules: <rule name>`, and Arnica tracks it on the rule's **Pull Requests** tab.

Arnica skips a repository when:

* It already has the current rules.
* An open Arnica pull request with the same content already exists.

If an older Arnica pull request for the rule is still open and its content is out of date, Arnica closes it and opens a new one.

Deployment pull requests are supported on GitHub, GitLab, Azure DevOps, and Bitbucket Cloud.

{% hint style="warning" %}
**Deploy Rule** is disabled for draft rules. Select **Ready** on the rule before you deploy it.
{% endhint %}

## Viewing adoption

Arnica's inventory scan reports which repositories have AI coding rules and how often AI assistants cite them. Navigate to **Inventory** → **Repositories**:

* The **Vibe Coding Rules** column shows the AI assistant instruction files found in each repository, including files that Arnica manages.
* The **Vibe Coding Annotations Count** column shows how many rule citations were found.

Expand a repository to see the details on the **Vibe Coding Rules** and **Vibe Coding Annotations** tabs. Each annotation shows the rule ID, file path, location, author, commit date, and commit. Arnica scans each repository's SLA branches for annotations. For more, see [Repositories](https://docs.arnica.io/arnica-documentation/inventory/repositories.md#vibe-coding-annotations).

## Related

* [Adding AI Coding Rules](https://docs.arnica.io/arnica-documentation/developers/ai-coding-rules.md)
* [Repositories](https://docs.arnica.io/arnica-documentation/inventory/repositories.md)
* [Code Risk Policy Settings](https://docs.arnica.io/arnica-documentation/code-risks/code-risk-policy-settings.md)
* [SLA Branches](https://docs.arnica.io/arnica-documentation/code-risks/code-risk-policy-settings/sla-branches.md)
