AGENTS.md

Simple markdown file for defining AI instructions

AGENTS.md is a simple markdown file for defining agent instructions. Place it in your project root as an alternative to .firebender/rules/*.mdc for straightforward use cases.

AGENTS.md files are plain markdown with no frontmatter required. Perfect for simple, readable instructions.

Unlike Project Rules, AGENTS.md is a plain markdown file without metadata or complex configurations. It’s perfect for projects that need simple, readable instructions without the overhead of structured rules.

File Locations

Firebender searches for AGENTS.md files in the following order:

1. Project directory (and parent directories): .firebender/AGENTS.md or AGENTS.md
2. Personal defaults: ~/.firebender/AGENTS.md

The first file found is used. This allows for project-specific instructions that can be committed to version control.

Format

AGENTS.md is a plain markdown file with no frontmatter required:

AGENTS.md

# Project Instructions

## Code Style
- Use Kotlin for all new files
- Follow Material Design 3 guidelines
- Prefer Jetpack Compose for UI components

## Architecture
- Use MVVM pattern with ViewModels
- Keep business logic in use cases
- Use Room for local data persistence
- Use Retrofit for network calls

## Testing
- Write unit tests for ViewModels and use cases
- Use MockK for mocking
- Prefer property-based testing where applicable

Automatic Application

AGENTS.md files automatically apply to all conversations. You don’t need to specify file patterns or configuration - just write your instructions in plain markdown.

Examples

Android App Guidelines

AGENTS.md

# Firebender Android App

This is a food delivery app similar to DoorDash.

## Tech Stack
- Kotlin with Jetpack Compose for UI
- Room for local database
- Retrofit + OkHttp for networking
- Kotlin coroutines and Flow for async operations
- Hilt for dependency injection
- Coil for image loading

## Code Style
- Use Kotlin coroutines for async operations, never runBlocking in production code
- Prefer data classes for simple data holders
- Use @SerializedName for Retrofit/Gson classes (code gets obfuscated)
- Follow Material Design 3 guidelines for UI components
- Use meaningful variable names (avoid single letters except in lambdas)

## Architecture
- MVVM pattern with ViewModels
- Repository pattern for data access
- Use cases for complex business logic
- Single source of truth with Room as local database
- Offline-first approach

## Compose Guidelines
- Use Material 3 components (androidx.compose.material3)
- Implement proper state hoisting
- Use remember and derivedStateOf appropriately
- Preview components with @Preview annotations
- Keep composables focused and reusable

## Testing
- Write unit tests for ViewModels using JUnit 5
- Use MockK for mocking
- Integration tests for repositories
- UI tests for critical user flows

Library/SDK Project

AGENTS.md

# Android SDK Project

This is a Kotlin library for Android developers.

## Guidelines
- Public APIs must have KDoc documentation
- Use explicit types for public APIs (no type inference)
- Maintain binary compatibility (use @Deprecated instead of removing APIs)
- All public functions should have example usage in KDoc
- Use semantic versioning

## Dependencies
- Minimize third-party dependencies
- Prefer AndroidX libraries over support libraries
- Use Kotlin stdlib only, avoid bringing in large libraries

## Testing
- Aim for 80%+ test coverage on public APIs
- Test both success and error cases
- Include integration tests for complex scenarios

Discovery

AGENTS.md files are automatically discovered when you start a conversation. No configuration in firebender.json is required.

Search Order

Firebender searches for AGENTS.md in this order:

1. .firebender/AGENTS.md in project root
2. AGENTS.md in project root
3. .firebender/AGENTS.md in parent directories (walking up the tree)
4. AGENTS.md in parent directories (walking up the tree)
5. ~/.firebender/AGENTS.md (personal fallback)

The first file found is used.

Place AGENTS.md in .firebender/ to keep your project root clean, or use AGENTS.md for maximum visibility and version control convenience.

Live Reload

AGENTS.md files are automatically reloaded when you save changes. The updated instructions take effect immediately - no need to restart or create a new chat.

Version Control

AGENTS.md files can be committed to version control to share instructions across your team:

# Recommended approach - keep in .firebender/
git add .firebender/AGENTS.md

# Alternative - project root
git add AGENTS.md

Add to .gitignore if you want project-specific personal instructions:

# Project-specific personal AI instructions
AGENTS.md

# But allow team instructions
!.firebender/AGENTS.md

When to Use AGENTS.md vs Rules

Use AGENTS.md when…	Use Rules when…
You want simple, readable instructions	You need file-specific rules with glob patterns
All instructions apply project-wide	Different rules for different file types
You prefer a single file	You want modular, reusable rule files
Getting started quickly	You have complex rule organization needs

You can use both AGENTS.md and Rules together. They complement each other and all apply to conversations.

Related Documentation

• Rules - Structured rules with glob patterns and metadata
• Global Rules - Overview of rules system
• Commands - Custom AI commands for your workflow