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

# Rules

> Complete reference for AI behavior rules configuration

Rules help Firebender understand how to write high quality code. Define rules using `.mdc` files in the `.firebender/rules/` directory.

<Info>
  Type `/help` in the chat to get help creating rules
</Info>

## Configuration Locations

Firebender supports two rule scopes:

* **Project Rules**: `.firebender/rules/*.mdc` in your project root
* **Personal Rules**: `~/.firebender/rules/*.mdc` for rules that apply across all projects

**Merge behavior**: All rules from both locations are combined and applied together.

<Tip>Rules apply to **all** features of Firebender: autocomplete, chat, and inline AI changes</Tip>

## File Format

Rule files use the `.mdc` extension with optional YAML frontmatter:

```markdown .firebender/rules/kotlin-style.mdc theme={null}
---
description: Kotlin coding standards for this project
globs: "*.kt, *.kts"
alwaysApply: false
---

# Kotlin Style Guidelines

- Use Kotlin coroutines for async operations, never `runBlocking`
- Prefer data classes for simple data holders
- Use `@SerializedName` for Retrofit/Gson classes (code gets obfuscated)
- Follow Material Design 3 guidelines for UI components
```

### Frontmatter Fields

All frontmatter fields are optional:

| Field         | Type      | Description                                             |
| ------------- | --------- | ------------------------------------------------------- |
| `description` | `string`  | Brief description of the rule's purpose                 |
| `globs`       | `string`  | Comma-separated glob patterns for file matching         |
| `alwaysApply` | `boolean` | If `true`, rule applies to all files (default: `false`) |

### No Frontmatter

If you omit the frontmatter, the rule always applies to all files:

```markdown .firebender/rules/project-context.mdc theme={null}
This is a food delivery app similar to DoorDash.

Key technologies:
- Kotlin with Jetpack Compose for Android
- Room for local database
- Retrofit for networking
- Kotlin coroutines for async operations
```

## Frontmatter Reference

### description

A brief description of what the rule covers. Helps identify the rule's purpose.

```yaml theme={null}
description: Threading and coroutine guidelines
```

### globs

Comma-separated glob patterns to match files. The rule only applies when working with matching files.

```yaml theme={null}
globs: "*.kt, *.kts"
```

```yaml theme={null}
globs: "*Test.kt, *Spec.kt"
```

Glob patterns follow `.gitignore` syntax:

* `*.kt` matches all Kotlin files
* `**/*Test.kt` matches test files in any directory
* `src/main/**/*.kt` matches Kotlin files under src/main

### alwaysApply

When `true`, the rule applies to all files regardless of `globs`. Useful for project-wide guidelines.

```yaml theme={null}
alwaysApply: true
```

If both `alwaysApply: true` and `globs` are specified, `alwaysApply` takes precedence.

## Examples

### Always-Apply Project Rules

```markdown .firebender/rules/project-context.mdc theme={null}
---
alwaysApply: true
---

# Project Context

This is the Firebender Android plugin for JetBrains IDEs.

Key guidelines:
- Use `println()` for logging instead of Android's `Log`
- Prefer JBUI and IntelliJ SDK components (`JBPanel` over `JPanel`)
- Use `@SerializedName` for data classes (plugin is obfuscated)
- Never use `runBlocking {}`, use coroutine scopes from services
```

### Conditional Test Rules

```markdown .firebender/rules/test-rules.mdc theme={null}
---
description: Guidelines for test files
globs: "*Test.kt, *Spec.kt"
---

# Test Guidelines

- Use JUnit 5 with Kotest assertions
- `runBlocking {}` is acceptable in tests
- Prefer property-based testing where applicable
- Mock external dependencies, don't use real network calls
```

### UI Component Rules

```markdown .firebender/rules/compose-guidelines.mdc theme={null}
---
description: Jetpack Compose best practices
globs: "*.kt"
---

# Compose Guidelines

When writing Compose UI:
- Use Material 3 components and theming
- Implement proper state hoisting
- Use `remember` and `derivedStateOf` appropriately
- Preview components with `@Preview` annotation
```

### Personal Rules

```markdown ~/.firebender/rules/personal-preferences.mdc theme={null}
---
alwaysApply: true
---

# My Preferences

- Always add KDoc comments to public functions
- Prefer explicit types over type inference for public APIs
- Use meaningful variable names, avoid single letters except for lambdas
```

## Symbolic Links

Rules support symbolic links. You can symlink rule files from a shared location:

```bash theme={null}
ln -s ~/shared-rules/team-standards.mdc .firebender/rules/team-standards.mdc
```

## Migration from firebender.json

If you have rules defined in `firebender.json`, migrate them to `.mdc` files:

**Before** (deprecated):

```json theme={null}
{
  "rules": [
    "Follow Material Design 3 guidelines",
    "Use Kotlin coroutines for async operations",
    {
      "filePathMatches": "**/*Test.kt",
      "rules": ["Use Kotest BDD style"],
      "rulesPaths": "test-rules.txt"
    }
  ]
}
```

**After**:

```markdown .firebender/rules/general.mdc theme={null}
---
alwaysApply: true
---

- Follow Material Design 3 guidelines
- Use Kotlin coroutines for async operations
```

```markdown .firebender/rules/test-rules.mdc theme={null}
---
globs: "*Test.kt"
---

- Use Kotest BDD style

(contents of test-rules.txt)
```

<Warning>
  The `rules` field in `firebender.json` is deprecated. Use `.firebender/rules/*.mdc` files instead.
</Warning>

## Cursor Rules Compatibility

Firebender also supports `.cursor/rules/*.mdc` files for teams migrating from Cursor. This can be disabled by setting `useCursorRules: false` in `firebender.json`.

For user-facing overview and examples, see [Rules](/multi-agent/global-rules).