Skip to content

Rules

Rules encode durable guidance (style, testing, domain constraints). Declare them under rules, then run capa install. capa writes Cursor-style rule files where the provider has a rules directory, and folds content into the provider’s instructions file elsewhere.

Types

Type	Fields
`inline`	`content`
`remote`	`url`
`github` / `gitlab`	`def.repo` (`@basename` or `::exact/path`, with optional `:tag` / `#sha`)

Common fields

Field	Purpose
`id`	Filename stem and capa marker id
`providers`	Optional allow-list of provider ids; omit for all active providers
`appliesTo`	Glob patterns (maps to Cursor `globs`)
`alwaysApply`	When `true`, always load the rule
`description`	Frontmatter description where supported

rules:
  - id: code-style
    type: inline
    alwaysApply: true
    description: Project code style guidelines
    content: |
      Use TypeScript strict mode. Prefer const over let.

  - id: test-patterns
    type: inline
    appliesTo:
      - '**/*.test.ts'
      - '**/*.spec.ts'
    description: Testing conventions
    content: |
      Use describe/it blocks. Prefer toBe over toEqual for primitives.

  - id: typescript-standards
    type: github
    def:
      repo: my-org/standards::rules/typescript.md
    providers:
      - cursor

Prefer :: for rules when you know the file path — installs fail loudly if the file moves. Use @basename only when the basename is unique in the repo.

Cursor `.mdc` vs folded instructions

Provider shape	What capa writes
Rules directory (e.g. Cursor → `.cursor/rules/`)	Separate rule file with YAML frontmatter (`description`, `globs`, `alwaysApply`) — Cursor uses `.mdc`
No rules directory (e.g. many CLI agents)	Rule body folded into the provider’s instructions file as a capa-managed marker block

capa clean removes capa-installed rules. Hand-authored provider rules are left alone.