> ## Documentation Index
> Fetch the complete documentation index at: https://backstage.spotify.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rules

A **rule** is a short, focused guideline that an AI agent loads into its context. Rules enforce coding standards, architectural decisions, and best practices across your organization. When a developer installs a rule, their AI agent follows it automatically.

## What makes a good rule

Rules work best when they are:

* **Normative**: uses strong constraints like "must" or "must not", not suggestions
* **Verifiable**: a reviewer can objectively check whether code follows the rule
* **Focused**: covers one specific concern, not a broad topic
* **Durable**: expected to be relevant for 6–12 months or more

Good examples:

* "All React components must use design tokens from the theme for colors and spacing"
* "Database migrations must be backward-compatible with the previous schema version"
* "API endpoints must validate path parameters against expected formats before forwarding to services"

Poor candidates (better as documentation):

* General tutorials or onboarding guides
* Style preferences that change frequently
* Implementation details specific to one project

## Rule format

A rule is a single Markdown file with YAML frontmatter:

```markdown theme={"theme":{"light":"github-light","dark":"dracula"}}
---
title: Co-locate test files with source
discipline: web
category: testing
type: file-structure
id: web.testing.file-structure.test-placement.001
rationale: Co-located tests are easier to find and maintain
---

Test files MUST be placed alongside the source file they test.

For example, `Button.tsx` and `Button.test.tsx` must be in the same directory.
Do not place tests in a separate `__tests__` directory.
```

### Frontmatter fields

| Field        | Required | Description                                                                 |
| ------------ | -------- | --------------------------------------------------------------------------- |
| `title`      | Yes      | Human-readable title                                                        |
| `discipline` | Yes      | Area of expertise: `web`, `backend`, `android`, `ios`, `data`, `ml`, `core` |
| `category`   | Yes      | Topic area: `testing`, `architecture`, `style`, `security`, etc.            |
| `type`       | Yes      | Rule classification within the category                                     |
| `id`         | No       | Unique identifier (defaults to filename without extension)                  |
| `rationale`  | No       | Why this rule exists — helps agents explain their reasoning                 |
| `lifecycle`  | No       | `experimental`, `production`, or `deprecated` (defaults to `production`)    |
| `activation` | No       | Conditions for when the rule applies (see below)                            |

### Activation

Rules can optionally specify when they should activate:

```yaml theme={"theme":{"light":"github-light","dark":"dracula"}}
activation:
  strategy: intelligent
  languages:
    - typescript
    - javascript
  file_globs:
    - 'src/**/*.test.ts'
```

| Field        | Description                                     |
| ------------ | ----------------------------------------------- |
| `strategy`   | Activation strategy (defaults to `intelligent`) |
| `languages`  | Programming languages the rule applies to       |
| `file_globs` | File patterns that trigger the rule             |

## How rules are discovered

Rules are automatically discovered by AI Explorer's entity providers. The providers scan configured GitHub organizations for rule files in these locations:

* **`.claude/rules/*.md`** Markdown rules with YAML frontmatter
* **`rules/*.md`** Markdown rules with YAML frontmatter
* **`rules/*.yaml`** / **`rules/*.yml`** Pure YAML rule files (required fields: `id`, `title`, `discipline`, `category`, `type`)

Simply commit a rule file to one of these paths and AI Explorer will pick it up on its next scan. Metadata is extracted from the file's frontmatter, and ownership falls back to `CODEOWNERS` if not specified in the frontmatter.

### Optional: catalog-info.yaml override

If a repository also contains a `catalog-info.yaml` with `AiContext` rule entities, those hand-authored entities take precedence over any file-derived entity with the same `namespace/name`. This is an override mechanism, most cases will not require this.