# Agents and Prompts Course: [Intent Engineering](https://www.devtutorials.ai/learn/intent-engineering) · Section: Foundations Source: https://www.devtutorials.ai/learn/intent-engineering/foundations/agents-and-prompts > What an AI coding agent does with your words: it reads, fills gaps, plans and builds. Learn why every gap in a spec becomes a guess, and write your first three spec lines. ## Watch an Agent Guess Every lesson starts the same way. You watch an AI agent build the wrong thing. Then you learn how giving better instructions helps the agent build the right thing. For the first task, the agent gets only one instruction. React app: ```text Add an Excel export button to the Orders grid. ``` ASP.NET Core app: ```text Add an endpoint that exports orders. ``` This sounds simple, but some details are missing. The agent does not know: - Which orders to export - Which columns to include - Which file type to make - How dates should look - If there is a row limit - What to do when there is no data Because these details are missing, the agent has to guess. And sometimes, the guess is wrong. Press **Run**. **In simple words:** The ticket was missing six important details. The agent did not ask for those details. Instead, it guessed. Most of those guesses were wrong, so the result did not match what was needed. ## TL;DR 1. An **AI coding agent** reads your instructions and turns them into code. 2. It works in four steps: - Read the instructions - Fill in missing details - Plan the work - Build the solution 3. **Every missing detail becomes a guess.** - If information is missing, the agent will usually guess. - The only way to avoid this is to tell the agent to stop and ask questions. 4. **Intent** means what you want and why you want it. 5. **Implementation** means how the solution will be built. 6. **Requirements** give the details the agent needs and reduce guessing. 7. **Acceptance criteria** define what success looks like and help confirm the result is correct. 8. In this course, you will create three files: - `intent.md` → what and why - `spec.md` → requirements and details - `plan.md` → implementation plan and steps to build it ## A Real-World Example You ask for a chocolate cake, but don't give the details. The baker guesses and makes the wrong cake. AI agents do the same thing. Missing details lead to guesses. ## What You Will Learn In this lesson, you will learn: 1. What an AI agent does with your instructions. 2. Why missing details lead to guesses. 3. The difference between intent and implementation. 4. How requirements reduce guessing. 5. How acceptance criteria check the result. 6. How intent engineering is different from prompt, context and harness engineering. 7. How to turn a request from a stakeholder into clear instructions. **About the agent in this course** - The agent here is **simulated**. It is not a real AI. - It gives the same answer every time, so your work can be checked. - A real agent behaves the same way. When a detail is missing, it picks the answer that seems most likely. ## What an Agent Does With Your Words ### Read, Fill Gaps, Plan, Build An **AI coding agent** can read code and make changes for you. It follows four simple steps: 1. **Read** your instructions and the existing code. 2. **Fill in missing details** by guessing what you didn't specify. 3. **Plan** the changes. 4. **Build** the code. The important step is **Fill in missing details**. If your instructions are unclear, the agent will make its own decisions. It usually does this quietly, without telling you about every guess it makes. Press **Play** to watch the agent work through the ticket. Each box is one decision the agent has to make. The ticket does not answer any of the six important questions. Even saying "Excel export" is not enough. Excel can open both `.xlsx` and `.csv` files. So the agent still has to guess which file type you want. **Simple lesson:** if a detail is not specified, the agent will make a guess. ### Every Gap Becomes a Guess This is the most important idea in this course: **If information is missing, the agent will guess.** Unless you tell the agent to stop and ask questions, it will fill in the missing details on its own. #### Three Simple Terms - **Spec** = instructions for what to build - **Gap** = a missing detail in the instructions - **Guess** = the answer the agent chooses for that missing detail The agent does not guess randomly. It usually picks the most common or obvious answer. The problem is that the common answer is not always the right answer for your users. **Important:** a wrong guess can be hard to notice. - The code may run correctly. - The tests may pass. - Everything may look fine. But when real users use the feature, problems can appear because the agent guessed incorrectly. ## Intent vs Implementation When you give instructions to an agent, there are two parts. ### Intent = What and Why Intent explains: - Who needs the feature - What problem it solves - What should be included - What should not change Example: - **User:** Priya (Finance Lead) - **Goal:** Get a weekly report without manual work - **Include:** Only filtered rows in the export - **Do not change:** Existing CSV export ### Implementation = How Implementation explains how to build it: - Libraries - Functions - Files - APIs - Folders Agents are usually good at the how. But they cannot reliably guess the what and why. **In simple words:** you decide the what and the why. The agent helps with the how. #### Intent vs. Implementation **Intent = what you want and why** - Priya sends a weekly report to the CFO. - The report should not need any manual fixing. - Do not change the existing CSV export. **Implementation = how to build it** - Use the SheetJS library. - Add an `onClick` handler to `ExportButton.tsx`. - Put the code in `src/export/`. **Simple lesson** - Intent tells the agent what success looks like. - Implementation tells the agent where and how to write the code. If your instructions only explain how, the agent can still build the wrong thing because it doesn't understand what you really need. ### Requirements Remove Guesses A requirement gives the agent a clear answer. Example: ```text Export only the rows shown by the filter. ``` This removes one guess. ### Acceptance Criteria Prove It Works An acceptance criterion is a test to verify the result. Example: ```text If the filter shows 3 rows, and the user exports the data, then the file should contain exactly 3 rows. ``` This confirms the requirement was implemented correctly. Now watch what happens when you add clear instructions. Each step adds one line. The agent reads the instructions again each time. Each clear line removes one guess. With six clear lines, the agent has nothing left to guess. ### Why a Late Guess Costs More A wrong guess is easy to fix early. The longer it stays hidden, the harder it is to fix. More work gets built on top of it. | When you find the wrong guess | What you have to fix | |---|---| | While writing the instructions | One line of text | | In code review | The line and the code | | In testing | The line, the code and the tests | | After release | All of that, plus the users' files and their trust | **Simple lesson:** find wrong guesses early, while they are cheap to fix. **Fix the instructions, not just the chat.** - If you correct the agent in the chat, it only fixes this one run. - If you fix the spec file, it fixes every run after that. ## Where Intent Engineering Fits You may hear four similar names. Each one solves a different problem. | Practice | The question it answers | |---|---| | Prompt engineering | How should I word my request? | | Context engineering | What information should the agent see? | | Intent engineering | What should be built, and how do we know it is right? | | Harness engineering | What rules and checks should the agent follow? | They work together, but one cannot replace another. - A well-written prompt cannot add a detail you forgot. - Strict rules cannot tell the agent what your users need. Intent engineering answers what to build, before any code is written. #### The Three Files You Will Write 1. **`intent.md`** → who it is for, what they need, what is included and what must not change 2. **`spec.md`** → the requirements and the acceptance criteria 3. **`plan.md`** → the steps to build it Each file builds on the one before it. ### Lab Exercise: Your First Spec Lines Priya, the finance lead, sends you a short note: ```text Only the rows the filter shows. Leave hidden columns out. Use a real Excel file (.xlsx). ``` If you chose ASP.NET Core, Marco sends a similar note: - Only matching orders - No soft-deleted orders - A real `.xlsx` file Your task: turn the note into three clear instructions. Then press **Check my spec**. Open the **Agent** tab. Each clear instruction shows up as a **FOLLOWS** line. This means the agent did what you asked. #### A Vague Line Does Not Work ```text Handle hidden columns. ``` This line names the topic, but it does not say what to do. Should the hidden columns be left out, or kept in? The agent cannot tell. So it marks the line **NOT UNDERSTOOD** and guesses anyway. Watch the difference, one line at a time: **Simple lesson:** a good instruction says what to do, not just what it is about. ## What Changes per Tool The ideas in this course work with every AI coding tool. The only difference is where the files are kept. - **Claude Code, Codex and Cursor** read your files straight from your project folder. - **Spec Kit and Kiro** guide you step by step through writing the spec, the plan and the tasks. Later lessons show the exact folders each tool uses. ## Common Mistakes | Mistake | Wrong idea | Correct idea | What goes wrong | |---|---|---|---| | Sending only a one-line ticket | "The agent will figure out the rest." | Write down each detail the agent needs. | Every missing detail becomes a guess. The export has the wrong rows. | | Expecting the agent to ask | "If it is not sure, it will ask me." | Tell the agent when to stop and ask. | It picks a common answer and does not tell you. | | Writing only the how | "Use SheetJS" is enough. | Start with who needs it, what they need and what must not change. | The code looks neat, but it solves the wrong problem. | | Writing vague lines | "Handle hidden columns" is clear enough. | Name the choice: "Leave hidden columns out." | The agent does not know what to do, so it still guesses. | | Fixing it only in the chat | "I will just tell it again next time." | Fix the spec file once. | The same wrong guess comes back in the next run. | | Thinking a requirement is proof | "I wrote it down, so it works." | Add an acceptance criterion that tests the result. | A wrong result can pass, because nothing checked it. | ## Exercises These exercises help you practise reading and writing clear instructions. Press **Check** when you are ready. Use **Show Hint** if you get stuck. **New to Markdown?** Every file in this course, like `AGENTS.md` and `SKILL.md`, is written in Markdown. If Markdown is new to you, start with [Markdown for AI-Native Development](/learn/markdown/fundamentals/markdown-basics). ## What to Remember - An agent reads, fills in missing details, plans and builds. - If a detail is missing, the agent guesses, unless you tell it to stop and ask. - Intent is what you want and why. - Implementation is how to build it. - Requirements reduce guessing. - Acceptance criteria check that the result is right. - A vague line still leads to a guess. - In this course, you will write `intent.md`, `spec.md` and `plan.md`. ## Further Reading - [Understanding Spec-Driven Development: Kiro, spec-kit, and Tessl, by Birgitta Böckeler](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html): a clear look at three spec-first tools. - [GitHub Spec Kit](https://github.com/github/spec-kit): an open-source toolkit for spec, plan and tasks. - [Kiro specs](https://kiro.dev/docs/specs/index): how Kiro turns a spec into requirements, design and tasks. - [Harness engineering, by OpenAI](https://openai.com/index/harness-engineering/): the behaviour side, which this course pairs with. Next: **Guess Gallery**. You will look at runs that went wrong and find out why. Was the agent missing information, missing your intent, or missing a check?