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
.claude/rules/ears-format.mdWhat 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, andThe system shallin 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.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/ears-format.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/ears-format.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/ears-format.mdManually: put the files in place
.clinerules/ears-format.mdStep 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