# EARS Requirements Course: [Intent Engineering](https://www.devtutorials.ai/learn/intent-engineering) · Section: Foundations Source: https://www.devtutorials.ai/learn/intent-engineering/foundations/ears-requirements > Write requirements in EARS, five fixed sentence patterns that an agent and a checker can both read. Cover the edge and error cases, and see why a spec is right for one stakeholder, not for every stakeholder. ## "Handle It Gracefully" Many specs have a line like this: ```text The export should handle errors gracefully. ``` It sounds like a good requirement. But it does not tell the agent what to do. What does "gracefully" mean? For example: - Show an error message? - Add a Retry button? - Make a smaller file? - Download nothing at all? Different people may read it in different ways. The agent has the same problem, so it guesses. It usually picks the simplest option. For example, it may write the error to the browser console, where users never see it. **Simple lesson:** a vague requirement sounds useful, but the agent cannot act on it. ### A Real-World Example An airplane safety card does not say "Stay calm and handle emergencies well." It says what to do in each situation: - **If** the cabin loses pressure, oxygen masks drop. - **When** the seatbelt sign is on, stay seated. - **While** the plane is taxiing, keep bags stored. Good requirements work the same way. They say what happens, and when. Click the button and open the **Agent** tab. - **The vague line:** the agent marks it **NOT UNDERSTOOD**. - **The four edge cases:** the agent decides all of them on its own. Now open **Preview & Checks**. Four checks fail. The feature may look finished. But it does not do what the stakeholder expected, because the line never said what should happen. **Simple lesson:** if a requirement is vague, it is still a guess. ## TL;DR 1. **EARS** = Easy Approach to Requirements Syntax. It gives you five fixed patterns for writing requirements. 2. Every EARS line starts with one of five words: - **The** → always true - **When** → something happens - **While** → something stays true - **If … then** → something goes wrong - **Where** → a feature or role is on 3. Every EARS line uses **shall** exactly once. 4. One line = one behaviour. 5. Vague words like *gracefully*, *fast* and *properly* cannot be checked. 6. Most bugs hide in edge cases: - nothing to work with - too much to work with - something fails 7. A spec records what **one** stakeholder wants. Another stakeholder may want something else. ## What You Will Learn In this lesson, you will learn: 1. What EARS is and why a fixed pattern helps. 2. The five EARS patterns, and when to use each one. 3. The small rules every EARS line follows. 4. How to write requirements for edge cases and failures. 5. Why different stakeholders may want different behaviour. **About the EARS checker in this lab** - It uses fixed rules, not an AI model. - It checks the first word, "shall", the punctuation and vague words. - A line that fails the check is ignored, so the agent keeps guessing. ## The Five EARS Patterns ### Why a Fixed Pattern Matters People write requirements in many different ways. One person writes: ```text The export should create a file. ``` Another writes: ```text Users must receive an Excel file. ``` A third writes: ```text Export functionality is expected. ``` All three may mean the same thing. But reviewers have to work out each one separately. EARS fixes this with one shape. Every line has: - a condition, if one is needed - the word **shall** - one clear behaviour Because every line looks the same, people and tools can read requirements much faster. EARS was first made by Alistair Mavin and his colleagues at Rolls-Royce. **Simple lesson:** one fixed shape makes every requirement easy to read and easy to check. ### Pattern 1: Always Use this when something is always true. Format: ```text The ... shall ... ``` Example: ```text The export shall write an .xlsx file. ``` There is no condition, because it is always true. ### Pattern 2: Event Use this when something happens at one moment. Format: ```text When ..., the ... shall ... ``` Example: ```text When the user clicks Export, the grid shall download the visible rows. ``` This pattern fits clicks, requests and other actions. ### Pattern 3: State Use this when something stays true for a while. Format: ```text While ..., the ... shall ... ``` Example: ```text While the grid has no rows, the Export button shall be disabled. ``` An empty grid is not an event. It is a state. It stays true until data appears. ### Pattern 4: Something Goes Wrong Use this when something fails. Format: ```text If ..., then the ... shall ... ``` Example: ```text If the export fails, then the grid shall show an error message with a Retry button. ``` This pattern fits failures, bad input and other problems. ### Pattern 5: Optional Feature Use this when the behaviour applies only to some users, settings or features. Format: ```text Where ..., the ... shall ... ``` Example: ```text Where the user has the Finance role, the export shall include the Margin column. ``` This pattern fits roles, permissions and feature flags. ### The First Word Tells You the Pattern | First word | Pattern | |---|---| | The | Always | | When | Event | | While | State | | If … then | Something goes wrong | | Where | Optional feature | **Simple lesson:** read the first word, and you know what kind of requirement it is. ## The Small Rules ### Use "Shall" Every requirement uses the word **shall**. **Shall** means the behaviour is required. Words like **should**, **must** and **will** can mean different things to different people. One fixed word removes that doubt. ### One Behaviour per Line Each line describes only one behaviour. This line has two: ```text When the user clicks Export, the grid shall download the file and shall show a toast. ``` - Download the file. - Show a toast message. Split it into two lines: ```text REQ-1: When the user clicks Export, the grid shall download the file. REQ-2: When the user clicks Export, the grid shall show a toast. ``` Now each line can pass or fail on its own. You can see exactly which part broke. ### Avoid Vague Words These words cannot be measured or checked: - gracefully - fast - properly - user-friendly Say exactly what should happen instead. ❌ Vague: ```text The export shall handle errors gracefully. ``` ✅ Clear: ```text If the export fails, then the grid shall show an error message with a Retry button. ``` The clear line tells the agent what to build. It also gives testers something they can check. Now watch a vague line become a valid EARS line. Each step fixes one rule. The line passes only when every rule is green. **In simple words:** if two developers can read a line and build different things, the line is not finished. **Important:** a line that fails the EARS check does not count. - The agent marks it **NOT UNDERSTOOD**. - It still guesses. - A half-right line is no requirement. ## Edge and Error Cases ### The Three Cases Most Teams Forget Many specs only describe the happy path: ```text The user clicks Export. The file downloads. Everything works. ``` But most real problems happen somewhere else. For almost every feature, ask three questions: 1. What happens when there is **nothing**? 2. What happens when there is **too much**? 3. What happens when something **fails**? For example: - an empty grid - more rows than the limit - a timeout or a server error Each answer becomes its own EARS line. Usually: - **While** fits an empty state. - **When** fits a limit. - **If … then** fits a failure. Watch the vague line get replaced, one edge case at a time. Each clear line turns one edge case green. Four lines, four passing checks. **Simple lesson:** give every edge case its own line, or the agent will guess it. ### Lab Exercise: Write the Edge Cases in EARS The stakeholder has already said what should happen in each edge case. Your task: replace the vague line with four clear EARS lines. Watch the **EARS Check** panel while you type. Every line should get a green check. When all lines pass, press **Check my spec**. Every edge-case test should pass. **Start with the pattern, then finish the sentence.** "While the grid has no rows, the Export button shall …" is half written before you begin. ## One Spec, One Stakeholder ### Different Stakeholders Want Different Things Not every stakeholder wants the same behaviour. One stakeholder may say: ```text When the grid is empty, export a file with only the headers. ``` Another may say: ```text When the grid is empty, disable the Export button. ``` Both answers are reasonable. Neither one is right for everyone. The right answer depends on who asked. That is why you cannot copy requirements from one project to another. Watch the same spec checked against two stakeholders. The agent followed every line both times. The spec was simply written for someone else. **Simple lesson:** a spec is not an answer sheet you can reuse. It records what one stakeholder asked for. ### Practice: One More Feature Now try another feature. React app: ```text Bulk edit orders. ``` ASP.NET Core app: ```text Paged search results. ``` The ticket leaves several decisions open. Use stakeholder C's note to write the missing EARS lines. Run it and compare the results. A spec can pass for one stakeholder and fail for another. That does not mean the agent is broken. It means the spec was written for a different person. ## What Changes per Tool EARS is plain text, so it works with almost every spec tool. | Tool | Where EARS lines go | |---|---| | Claude Code, Codex, Cursor | In the requirements section of `spec.md` | | Spec Kit | In the functional requirements | | Kiro | Kiro uses a similar EARS-style format for requirements | The patterns stay the same in every tool. Only the place where you write them changes. ## Common Mistakes | Mistake | Wrong idea | Correct idea | What goes wrong | |---|---|---|---| | Writing "handle errors gracefully" | "It sounds like a requirement." | Write "If the export fails, then the grid shall show an error with a Retry button." | The agent logs the error where nobody sees it. | | Using "should" | "Should" and "shall" mean the same. | Use "shall". It means the behaviour is required. | The line fails the EARS check, so it does not count. | | Two behaviours in one line | "Fewer lines is tidier." | Write one behaviour per line. | You cannot tell which half failed. | | Writing only the happy path | "Edge cases are rare." | Write lines for nothing, too much and failure. | Most real bugs hide in edge cases. | | No comma after the condition | "Punctuation does not matter." | Write "When X, the grid shall Y." | People and checkers cannot see where the condition ends. | | Copying another stakeholder's answer | "Every export works like this." | Ask this stakeholder what they want. | The spec is right, but for someone else. | ## Exercises These exercises help you practise writing clear EARS lines. Press **Check** when you are ready. Use **Show Hint** if you get stuck. ## What to Remember - EARS gives you five fixed patterns. - The first word tells you the pattern. - Every line uses "shall" once. - One line, one behaviour. - Vague words lead to guesses. - A line that fails the EARS check does not help the agent. - Every edge case needs its own line. - A spec records what one stakeholder wants. ## Further Reading - [EARS: the Easy Approach to Requirements Syntax, by Alistair Mavin](https://alistairmavin.com/ears/): the original patterns, with examples. - [Kiro specs](https://kiro.dev/docs/specs/index): how Kiro writes requirements in an EARS-style form. - [GitHub Spec Kit](https://github.com/github/spec-kit): where requirements live in a Spec Kit feature. Next: **Acceptance Criteria**. You will learn how to write checks that catch bugs before users do, and make your first spec kit.