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, chat, 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.
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
- Always use `data-testid` attributes for element selectors
- 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
stably chat
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, chat, 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
- Always use `data-testid` attributes for element selectors
- Fall back to `getByRole` with accessible names when test IDs aren't 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
- Wait for loading spinners to disappear before asserting content
- Our app uses a dark theme by default — account for this in visual assertions

​
How It Works

​
CLI

When you run any Stably CLI command, the agent searches upward from your current directory to find STABLY.md. This means you can run commands from a subdirectory and it will still find the file at your project root. The content is appended to the agent’s system prompt as a ## Project Rules (STABLY.md) section.

​
Server-Side (CI/ECS)

The server-side agent reads STABLY.md directly from the root of your cloned repository. This ensures the same rules apply whether you’re running tests locally or through CI/PR-triggered test generation.

​
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, chat, 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.yaml → agent.fix.rulesFix agent rulesfixStructured config for the fix agent (max turns, parallel workers, rules)
When multiple files are present, they are concatenated in this order: 
[Base System Prompt]
  → stably.yaml agent.fix.rules
  → 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 test-generation-specific conventions (like file naming patterns or test structure) in STABLY-CREATE.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.