---
title: Agent rules
description: Add project-specific QA behavior rules that every agent-qa web or mobile run can read before executing steps.
---



Agent rules are project-specific instructions for the QA agent. Use them for product language, stable selectors, boundaries, accessibility expectations, and verification habits that should apply across tests.

The global config points to the file:

```yaml
workspace:
  agentRules: ./agent-rules.md
```

## workspace.agentRules [#workspaceagentrules]

```yaml
workspace:
  agentRules: ./agent-rules.md
```

Description: Path to the Markdown file containing shared QA rules.

Possible values: any non-empty workspace-relative path.

Required: yes in `agent-qa.config.yaml`.

Default: none.

## Example agent-rules.md [#example-agent-rulesmd]

```md
# agent-qa rules

## Product language

- The product calls work items "tasks", not tickets.
- The left navigation item for active work is "Assigned".
- The completed status is "Done".

## Web selector preferences

- Prefer visible labels and roles before CSS selectors.
- Prefer data-testid attributes only when labels are ambiguous.
- Do not click destructive actions unless the test step explicitly asks for it.

## Verification style

- Verify state in the UI before moving to the next step.
- When a step creates a task, confirm the task title and status are visible.
- If a hook exports TASK_ID, use it only as supporting context; the UI remains the primary assertion for web flows.
```

## Product language rules [#product-language-rules]

```md
## Product language

- The product calls work items "tasks", not tickets.
- The completed status is "Done".
```

Description: Terminology the agent should use when interpreting steps and visible UI.

Use this when: the product has domain-specific names or labels that are easy to confuse.

Default: no product language rules.

## Selector rules [#selector-rules]

```md
## Web selector preferences

- Prefer visible labels and roles before CSS selectors.
- Prefer data-testid attributes only when labels are ambiguous.
```

Description: Guidance for how the agent should interact with web UI.

Use this when: your app has stable labels, roles, or test IDs that should guide actions.

Default: the agent chooses from observed UI context.

## Boundary rules [#boundary-rules]

```md
## Boundaries

- Do not delete production-like data.
- Do not change billing settings.
- Do not invite real users.
```

Description: Actions the QA agent should avoid unless a test explicitly requests them.

Use this when: the app includes destructive or externally visible operations.

Default: no project-specific boundaries.

## Verification rules [#verification-rules]

```md
## Verification style

- Verify state in the UI before moving to the next step.
- Confirm task title and status after creating or editing a task.
```

Description: Shared expectations for assertions and step completion.

Use this when: your team wants consistent evidence quality across tests.

Default: no extra verification rules.

## Hook and variable rules [#hook-and-variable-rules]

```md
## Hooks and variables

- Use TASK_ID from hooks as supporting context, not as the only proof that the UI is correct.
- Never expose secret values in screenshots, step text, or console output.
```

Description: Guidance for values produced by hooks, captures, and secret interpolation.

Use this when: tests combine browser workflows with API verification hooks.

Default: no hook-specific rules.

## Keep rules reviewable [#keep-rules-reviewable]

Treat `agent-rules.md` like code:

* Keep rules specific to observable product behavior.
* Avoid long prompt essays that duplicate individual tests.
* Review changes in pull requests.
* Remove stale labels and selectors when the app changes.