Rules - Spotify for Backstage

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:

---
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:

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.

​What makes a good rule

​Rule format

​Frontmatter fields

​Activation

​How rules are discovered

​Optional: catalog-info.yaml override