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.

Type /help in the chat to get help creating rules

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.

Rules apply to all features of Firebender: autocomplete, chat, and inline AI changes

File Format

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

.firebender/rules/kotlin-style.mdc

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

.firebender/rules/project-context.mdc

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.

description: Threading and coroutine guidelines

globs

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

globs: "*.kt, *.kts"

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.

alwaysApply: true

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

Examples

Always-Apply Project Rules

.firebender/rules/project-context.mdc

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

.firebender/rules/test-rules.mdc

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

.firebender/rules/compose-guidelines.mdc

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

~/.firebender/rules/personal-preferences.mdc

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

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

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

.firebender/rules/general.mdc

---
alwaysApply: true
---

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

.firebender/rules/test-rules.mdc

---
globs: "*Test.kt"
---

- Use Kotest BDD style

(contents of test-rules.txt)

The rules field in firebender.json is deprecated. Use .firebender/rules/*.mdc files instead.

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.