STABLY.md

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.

STABLY.md is automatically created when you run stably init in a new project.

Quick Start

Create the file

Add a STABLY.md file to your project root:

STABLY.md

# 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

Run any Stably command

The rules are automatically loaded and applied:

stably create "test the login flow"
stably fix

You’ll see a confirmation in the CLI output:

✓ STABLY.md loaded (245 chars)

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

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.

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.

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:

STABLY.md

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

STABLY.md

# 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`	Test generation rules	`create` and `build` only	Test-specific conventions — file naming, folder structure, test patterns
`STABLY-FIX.md`	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)

Don’t duplicate rules across files. Put general project rules in STABLY.md, and mode-specific conventions in STABLY-CREATE.md / STABLY-FIX.md.

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.

Getting started

Stably Web Editor

Stably CLI

Stably Cloud Runner

Stably SDK

Stably Test Reporter

Configuration

Troubleshooting

Migration Guides

Resources

Introduction

Quick Start

File Location and Naming

File Format

Template

Example

Relationship to Other Config Files

Best Practices

​Introduction

​Quick Start

​File Location and Naming

​File Format

​Template

​Example

​Relationship to Other Config Files

​Best Practices

Introduction

Quick Start

File Location and Naming

File Format

Template

Example

Relationship to Other Config Files

Best Practices