Intent Engineering tutorial

Write the intent, spec and acceptance criteria that let an AI coding agent build the right thing without guessing, then export them for your own feature.

Start the course

Course contents

Foundations

  1. 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.
  2. Guess Gallery — Replay six failed agent runs. Sort each one into a context gap, an intent gap or a verification gap, then fix it in the layer where it lives: intent.md, a requirement, an acceptance criterion, a constraint or the repo docs.
  3. Problem Statements — Interview a stakeholder with a 5-question budget, pick the evidence that proves the problem is real, and write your first intent.md: user, problem, evidence, outcome with a number, and owner.
  4. Scope and Non-Goals — The agent lists every decision it would make alone. Close each one the right way: a requirement it must build, a non-goal it must leave alone, or an open question it must ask about. Then name a health metric so the agent does not break something else.
  5. 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.
  6. Acceptance Criteria — Write acceptance criteria as Given, when, then checks that a runner can execute. Prove they work by catching three planted bugs while the correct build passes. Then download your v1 spec kit: intent.md and spec.md for your tool.

Real Codebases

  1. API Contracts — Stop the agent from inventing public names. Declare the interface other code already expects, in a code block in spec.md, and watch a consumer test compile against it.
  2. Constraints and Trade-offs — Keep the agent's change small and in the team's style. Point it at the file to copy, list the APIs it must not change, limit the paths it may touch, and rank the trade-offs so it picks the right approach.
  3. Decision Rights — Decide which choices the agent may make alone, which it must report, which it must ask about, and which only a person may do. Add a stop rule so a failing loop ends with a report, not an empty budget.
  4. Non-Functional Requirements — Turn "fast", "accessible" and "works everywhere" into requirements a check can measure: a number, a unit, and the condition it is tested under.
  5. Task Planning — Break a feature into agent-sized tasks in plan.md, with the files each task touches and what it waits for. Land the contract first, so parallel agents never collide.
  6. Subagent Briefs — Write a brief a subagent can follow and an orchestrator can merge: goal, inputs, allowed tools, output shape and done-when.

Review and Scale

  1. Spec Review — Review a pull request against the spec: block only what breaks a REQ, an AC or a constraint, and cite it. Then sort incidents into spec gaps and agent errors, and pick the layer that stops each one.
  2. Living Specs — Keep the spec true after it ships: change the spec and its check together, find drift between spec and code, and judge the outcome by its own measure, turning a miss into a new intent.md.
  3. Team Templates — Scale specs across a team: a spec-review skill calibrated on graded examples, a definition of ready, and matching the spec's depth to the size of the change.
  4. Spec Capstone — Spec a new feature from scratch, or a feature in your own product, and pass every check from the course: intent, EARS, zero guesses, acceptance criteria, scope, health and decision rights. Then download your spec kit.

Reference

  1. Spec Cheat Sheet — Every template, pattern and rule from the course on one page: intent.md, EARS, acceptance criteria, scope, constraints, decision rights, NFRs, plan.md, briefs, the linter and tool paths.