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

# STABLY.md

> Provide project-level rules and instructions to the Stably AI agent across all modes and surfaces.

## Introduction

`STABLY.md` is a markdown file you place in your project root to give the Stably AI agent project-specific instructions. Rules defined here apply across **all agent modes** (`create`, `fix`, `build`, `init`) and **all surfaces** (local CLI and server-side CI/ECS test generation).

Think of it like `CLAUDE.md` for Claude Code — but for Stably. It's a great way to customize the agent to match your team's workflow — your conventions, your selector strategy, your project context — while still getting the full benefit of Stably's built-in browser management, test debugging tooling (e.g. Playwright Trace Viewer), and intelligent test generation under the hood.

<Tip>
  `STABLY.md` is automatically created when you run `stably init` in a new project.
</Tip>

***

## Quick Start

<Steps>
  <Step title="Create the file">
    Add a `STABLY.md` file to your project root:

    ```markdown STABLY.md theme={null}
    # Project Rules

    - This is a Next.js 14 e-commerce app running on localhost:3000
    - Prefer `getByRole` and `getByText` locators; fall back to `data-testid`
    - Never hard-code credentials — use environment variables
    ```
  </Step>

  <Step title="Run any Stably command">
    The rules are automatically loaded and applied:

    ```bash theme={null}
    stably create "test the login flow"
    stably fix
    ```

    You'll see a confirmation in the CLI output:

    ```
    ✓ STABLY.md loaded (245 chars)
    ```
  </Step>
</Steps>

***

## File Location and Naming

| Requirement        | Details                                               |
| ------------------ | ----------------------------------------------------- |
| **Location**       | Project root directory (same level as `package.json`) |
| **Filename**       | Must be uppercase `STABLY.md`                         |
| **Source control** | Must be committed to git                              |

<Warning>
  The filename **must** be uppercase `STABLY.md`. macOS is case-insensitive, so `stably.md` will work locally — but Linux (used in CI/ECS) is case-sensitive and will silently ignore the wrong case.
</Warning>

<Note>
  `STABLY.md` must be committed to your repository. If it's `.gitignore`'d, the CLI will still read it locally, but the server-side agent (CI/ECS) won't be able to find it — meaning your rules won't apply during PR-triggered or scheduled test generation.
</Note>

***

## File Format

`STABLY.md` uses **freeform markdown**. There's no required structure — write whatever instructions you want the agent to follow. The content is appended directly to the agent's system prompt.

**Maximum length:** 10,000 characters (\~2,500 tokens). Files exceeding this limit are automatically truncated with a CLI warning.

***

## Template

When you run `stably init`, the following template is created:

```markdown STABLY.md theme={null}
# STABLY.md — Project Rules for Stably Agent

<!--
  This file provides project-specific instructions to the Stably AI agent.
  Rules here apply to ALL agent modes (create, fix, build) and
  to both local CLI and server-side (PR/CI) test generation.
  Max 10,000 characters. Delete sections you don't need.
-->

## Project Context
<!-- Describe your app, tech stack, and anything the agent should know -->

## Selector Strategy
<!-- How should the agent find elements? -->

## Do's and Don'ts
<!-- Add project-specific rules here -->
```

***

## Example

Here's a real-world example for a Next.js e-commerce app:

```markdown STABLY.md theme={null}
# Project Rules

## Project Context
This is a Next.js 14 e-commerce application.
- Frontend runs on localhost:3000
- API runs on localhost:4000
- Auth uses NextAuth with Google OAuth
- Database is PostgreSQL with Prisma ORM

## Selector Strategy
- Prefer user-facing locators: `getByRole`, `getByText`, `getByLabel`
- Fall back to `data-testid` when no accessible locator is available
- Never use CSS class selectors — they change frequently

## Do's and Don'ts
- Always create new test data instead of modifying existing records
- Use `agent.act()` for complex multi-step UI interactions (e.g., drag-and-drop)
- Never hard-code credentials — use environment variables from Test Data
- Assert on expected end-state directly — Playwright auto-waits, so avoid explicit spinner/loading waits
- Our app uses a dark theme by default — account for this in visual assertions
```

***

## Relationship to Other Config Files

Stably has three mechanisms for customizing agent behavior. Each serves a different purpose:

| File                                                 | Scope                 | Modes                                | Description                                                                    |
| ---------------------------------------------------- | --------------------- | ------------------------------------ | ------------------------------------------------------------------------------ |
| `STABLY.md`                                          | Project-wide rules    | All modes (create, fix, build, init) | General instructions — project context, selector strategy, do's and don'ts     |
| [`STABLY-CREATE.md`](/core-configuration/mode-rules) | Test generation rules | `create` and `build` only            | Test-specific conventions — file naming, folder structure, test patterns       |
| [`STABLY-FIX.md`](/core-configuration/mode-rules)    | Fix rules             | `fix` only                           | Fix-specific conventions — selector strategy, timeout handling, test integrity |
| `stably.yaml` → `agent.fix.rules`                    | Fix agent rules       | `fix`                                | Structured config for the fix agent (max turns, parallel tests, rules)         |

When multiple files are present, they are concatenated in this order:

```
[Base System Prompt]
  → stably.yaml agent.fix.rules
  → STABLY-FIX.md            (fix mode only)
  → STABLY-CREATE.md         (create/build modes only)
  → STABLY.md                (all modes)
```

<Tip>
  Don't duplicate rules across files. Put general project rules in `STABLY.md`, and mode-specific conventions in [`STABLY-CREATE.md` / `STABLY-FIX.md`](/core-configuration/mode-rules).
</Tip>

***

## Best Practices

| Do                                                                             | Avoid                                                                        |
| ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| Commit `STABLY.md` to source control so CI and teammates share the same rules. | Adding `STABLY.md` to `.gitignore` — the server-side agent won't find it.    |
| Keep rules concise and actionable.                                             | Writing novel-length instructions that exceed the 10,000 character limit.    |
| Use `STABLY.md` for project-wide concerns (context, selectors, conventions).   | Duplicating rules that already exist in `STABLY-CREATE.md` or `stably.yaml`. |
| Use the uppercase filename `STABLY.md`.                                        | Using lowercase `stably.md` — it will fail silently on Linux CI servers.     |
| Review `STABLY.md` changes in PRs like any other config file.                  | Putting sensitive information (API keys, passwords) in the file.             |