Skip to main content

​
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

1

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
2

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

RequirementDetails
LocationProject root directory (same level as package.json)
FilenameMust be uppercase STABLY.md
Source controlMust 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:
FileScopeModesDescription
STABLY.mdProject-wide rulesAll modes (create, fix, build, init)General instructions — project context, selector strategy, do’s and don’ts
STABLY-CREATE.mdTest generation rulescreate and build onlyTest-specific conventions — file naming, folder structure, test patterns
STABLY-FIX.mdFix rulesfix onlyFix-specific conventions — selector strategy, timeout handling, test integrity
stably.yaml → agent.fix.rulesFix agent rulesfixStructured 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

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