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

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

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

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:

```markdown AGENTS.md theme={null}
# 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

<AccordionGroup>
  <Accordion title="Android App Guidelines">
    ```markdown AGENTS.md theme={null}
    # 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
    ```
  </Accordion>

  <Accordion title="Library/SDK Project">
    ```markdown AGENTS.md theme={null}
    # 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
    ```
  </Accordion>
</AccordionGroup>

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

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

## Live Reload

<Info>
  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.
</Info>

## Version Control

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

```bash theme={null}
# 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:

```gitignore theme={null}
# 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        |

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

## Related Documentation

* [Rules](/api-reference/rules) - Structured rules with glob patterns and metadata
* [Global Rules](/multi-agent/global-rules) - Overview of rules system
* [Commands](/api-reference/commands) - Custom AI commands for your workflow