Skip to main content
rule CX Codex

ears-format — Claude Code rule: what it does, how to install

The ears-format rule formats acceptance criteria with EARS patterns. Use it when a specification needs clear conditions, subjects, and system responses.

MIT ★ 3,774 updated 2026-10-22

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/ears-format.md
Open on GitHub

What ears-format does

ears-format sets an EARS structure for acceptance criteria. A requirement can describe an event, a precondition, an unwanted situation, an optional feature, or behavior that always applies. Each statement should express one testable behavior.

The rule keeps When, If, While, Where, The system shall, and The [system] shall in English. Only variable parts are localized to the language configured in spec.json.language, such as en. Mandatory behavior uses shall, while recommendations use should.

It targets Claude Code and Codex. In Claude Code, place the file at .claude/rules/ears-format.md. This is a poor fit for teams that require fully localized EARS syntax, since its trigger and fixed phrases stay in English.

What it helps with

  • write acceptance criteria in EARS form
  • separate conditions from system responses
  • cover event and state-driven behavior
  • describe error handling as testable requirements
  • keep specification language rules consistent

Example prompts for the agent

  • Write the payment acceptance criteria using EARS patterns.
  • Review this specification and keep When, If, and The system shall in English.
  • Rewrite the criteria in the language from spec.json.language, translating only the variable parts.

How to install ears-format

Manually: put the files in place

.claude/rules/ears-format.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about ears-format

How do I install ears-format in Claude Code?

Place the file at .claude/rules/ears-format.md.

What does ears-format do?

It gives acceptance criteria an EARS structure built from conditions, subjects, and system responses. The resulting requirements should describe one testable behavior.

Can EARS criteria use a fully localized syntax?

No. Variable parts follow the specification language, but EARS trigger keywords and fixed phrases such as When and The system shall remain in English.

Source text

ears-format.md · MIT
# EARS Format Guidelines

## Overview
EARS (Easy Approach to Requirements Syntax) is the standard format for acceptance criteria in spec-driven development.

EARS patterns describe the logical structure of a requirement (condition + subject + response) and are not tied to any particular natural language.  
All acceptance criteria should be written in the target language configured for the specification (for example, `spec.json.language` / `en`).  
Keep EARS trigger keywords and fixed phrases in English (`When`, `If`, `While`, `Where`, `The system shall`, `The [system] shall`) and localize only the variable parts (`[event]`, `[precondition]`, `[trigger]`, `[feature is included]`, `[response/action]`) into the target language. Do not interleave target-language text inside the trigger or fixed English phrases themselves.

## Primary EARS Patterns

### 1. Event-Driven Requirements
- **Pattern**: When [event], the [system] shall [response/action]
- **Use Case**: Responses to specific events or triggers
- **Example**: When user clicks checkout button, the Checkout Service shall validate cart contents

### 2. State-Driven Requirements
- **Pattern**: While [precondition], the [system] shall [response/action]
- **Use Case**: Behavior dependent on system state or preconditions
- **Example**: While payment is processing, the Checkout Service shall display loading indicator

### 3. Unwanted Behavior Requirements
- **Pattern**: If [trigger], the [system] shall [response/action]
- **Use Case**: System response to errors, failures, or undesired situations
- **Example**: If invalid credit card number is entered, then the website shall display error message

### 4. Optional Feature Requirements
- **Pattern**: Where [feature is included], the [system] shall [response/action]
- **Use Case**: Requirements for optional or conditional features
- **Example**: Where the car has a sunroof, the car shall have a sunroof control panel

### 5. Ubiquitous Requirements
- **Pattern**: The [system] shall [response/action]
- **Use Case**: Always-active requirements and fundamental system properties
- **Example**: The mobile phone shall have a mass of less than 100 grams

## Combined Patterns
- While [precondition], when [event], the [system] shall [response/action]
- When [event] and [additional condition], the [system] shall [response/action]

## Subject Selection Guidelines
- **Software Projects**: Use concrete system/service name (e.g., "Checkout Service", "User Auth Module")
- **Process/Workflow**: Use responsible team/role (e.g., "Support Team", "Review Process")
- **Non-Software**: Use appropriate subject (e.g., "Marketing Campaign", "Documentation")

## Quality Criteria
- Requirements must be testable, verifiable, and describe a single behavior.
- Use objective language: "shall" for mandatory behavior, "should" for recommendations; avoid ambiguous terms.
- Follow EARS syntax: [condition], the [system] shall [response/action].

© gotalab · MIT · gotalab/cc-sdd

Similar IDE rules

IDE rules catalog →

From the same set12

The whole set →
steering-principles steering-principles defines standards for project memory files, capturing architecture patterns without cluttering context with exhaustive file catalogs. CX Codex +1 ★ 3,774repo stars tasks-parallel-analysis The tasks-parallel-analysis rule sets checks for marking tasks in tasks.md as parallel work. Use it when an agent drafts an implementation plan and needs to account for dependencies. CX Codex +1 ★ 3,774repo stars requirements-review-gate The requirements-review-gate rule halts work and requires fixing the requirements draft before requirements.md is written. It validates scope coverage, EARS format compliance, and structural quality. CX Codex +1 ★ 3,774repo stars design-review-gate design-review-gate audits draft architectures before generating design.md. It links requirement IDs to concrete components and prevents speculative interfaces. CX Codex +1 ★ 3,774repo stars design-discovery-full The design-discovery-full rule systematically maps requirements, existing code, technologies, and risks before design begins. It ensures architectural choices rest on facts rather than assumptions. CX Codex +1 ★ 3,774repo stars design-review design-review reviews technical design documents before coding starts and issues a GO/NO-GO verdict. Caps feedback at three critical issues tied directly to project requirements. CX Codex +1 ★ 3,774repo stars cc-sdd-new-agent The cc-sdd-new-agent skill guides a new coding-agent integration in cc-sdd, from official-format research and planning to implementation checks. CX Codex +1 ★ 3,774repo stars gap-analysis The gap-analysis rule structures the analysis of your existing codebase, identifies what's missing for a feature, and helps you decide whether to extend existing components or build new ones. CX Codex +1 ★ 3,774repo stars

Project sponsors

Companies that keep this analytics open