# Spec Cheat Sheet

Course: [Intent Engineering](https://www.devtutorials.ai/learn/intent-engineering) · Section: Reference
Source: https://www.devtutorials.ai/learn/intent-engineering/reference/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.

## The Whole Course on One Page

This page puts every template and rule from the course in one place.

Use it while you write a real spec.

**Spec** = the instructions you write for the agent.

**Guess** = a choice the agent makes because your spec says nothing.

**The main rule:** every missing detail becomes a guess. The only exception is when the spec tells the agent to stop and ask.

**The habit:** when the agent guesses wrong, fix the spec file or add a check. Do not just tell it again in the chat.

**Simple lesson:** a fix in a file helps every future run. A fix in the chat is gone when the chat ends.

## The Three Files

You write three files, one after the other.

- **`intent.md`** = who the user is, what is hard for them, and what success looks like.
- **`spec.md`** = what to build, how to check it, and what the agent may decide.
- **`plan.md`** = the small tasks, and the order to do them in.

Each file feeds the next one:

```text
intent.md
    ↓
spec.md
    ↓
plan.md
    ↓
implementation
    ↓
measurement
    ↓
new intent.md
```

After release, you measure the result.

If the result was missed, the numbers become a new `intent.md`.

## intent.md Template

**Use this when:** you start a new feature, before you write any requirements.

```text
User: <who, and their role>
Problem: <what is difficult today, and what it costs>
Evidence: <tickets, incidents, metrics, or customer feedback>
Outcome: <what success looks like, with a measurable target>
Owner: <the person who answers questions>
```

Tips:

- Write about the user and the problem, not the code.
- Add real evidence, like tickets or numbers.
- Give the outcome a number and a unit.
- Name one owner who answers questions.

## spec.md Template

**Use this when:** you know what to build and want the agent to stop guessing.

```text
# Spec: <feature>

## Requirements
- REQ-1: When <trigger>, the <system> shall <response>.

## Acceptance criteria
- AC-1 (REQ-1): Given <state>, when <action>, then <observable result>.

## Non-goals
- Do not change <something nearby>.

## Open questions
- <question>? Ask <owner> before implementation.

## Interfaces
<code block containing contracts>

## Constraints
- C-1: Follow the pattern in `<path>`.
- C-2: Do not change `<frozen API>`.
- C-3: Only change files in `<folder>/` and `<hook file>`.

## Trade-offs
- correctness > performance > bundle size

## Non-functional requirements
- NFR-1: <condition>, the <system> shall <target with number and unit>.

## Health metrics
- <metric that must not regress>

## Decision rights
- Decide alone:
- Decide, then report:
- Ask first:
- Human only:

## Stop rules
- Stop after 3 failed attempts at the same fix and report what was tried.
```

**Simple lesson:** each section closes a different kind of guess.

## The Five EARS Patterns

**EARS** = a simple shape for writing one clear requirement.

**Use this when:** you write a line under `## Requirements`.

### Always

```text
The <system> shall <response>.
```

Use it when something must always be true.

### When

```text
When <trigger>, the <system> shall <response>.
```

Use it when something happens, like a click.

### While

```text
While <state>, the <system> shall <response>.
```

Use it when a condition lasts for a while, like an empty grid.

### If, Then

```text
If <problem>, then the <system> shall <response>.
```

Use it for errors and failures.

### Where

```text
Where <feature is enabled>, the <system> shall <response>.
```

Use it for optional features.

Rules for every EARS line:

- Use "shall" once.
- Write one behaviour per line.
- Put a comma after the condition.
- Use "then" after "If".
- Avoid vague words like "fast" or "properly".

## Acceptance Criteria

**Acceptance criterion** = a check that proves a requirement was built.

**Use this when:** you have written a requirement and need to test it.

```text
Given <starting condition>,
when <action>,
then <observable result>.
```

A good "then" is something a check can see:

- a row count;
- a file format;
- a status code;
- a button or message on the screen.

This is not a check:

```text
It works.
```

Nobody can test it, so it proves nothing.

**Simple lesson:** every requirement needs at least one acceptance criterion.

## Close Every Guess

When the agent guesses, decide where the missing detail belongs.

| The situation | Write it as | What the agent does |
|---|---|---|
| Someone decided it | Requirement | FOLLOWS |
| It is left out on purpose | Non-goal | SKIPS |
| Nobody has decided yet | Open question | ASKS |
| It must not get worse | Health metric | KEEPS |

**Health metric** = something that must not get worse, written with a number and a unit.

Example: "Grid first render stays under 1 second."

## Three Gaps and Where to Fix Them

Most agent mistakes come from one of three gaps.

### Context Gap

**Context gap** = the answer exists, but the agent cannot see it.

Fix it with:

- a constraint in `spec.md`;
- the repo docs, like `AGENTS.md` or `CLAUDE.md`.

### Intent Gap

**Intent gap** = nobody clearly wrote what to build or why.

Fix it with:

- `intent.md`;
- a requirement.

### Verification Gap

**Verification gap** = the spec was right, but nothing checked the result.

Fix it with:

- an acceptance criterion.

**Simple lesson:** find the gap first. Then fix it in the right place.

## Problems Found After Release

Sort each problem into one of two kinds:

- **Spec gap** = nobody wrote the rule down. Fix it in the spec or the repo docs.
- **Agent error** = the rule was written, but the agent broke it. Fix it with a test or a lint rule.

```text
Spec gaps become documentation.
Agent errors become checks.
```

## Decision Rights

**Decision rights** = rules about who makes which decision.

**Use this when:** the agent will work alone for a while.

There are four zones.

### Decide Alone

Small choices. The agent just does them.

Examples:

- names for local variables;
- unit tests for new code;
- formatting.

### Decide, Then Report

The agent does it, then lists it in its summary.

Examples:

- column order;
- running a flaky test again.

### Ask First

The agent proposes the change and waits for a yes.

Examples:

- adding a new package;
- changing a shared hook or shared type.

### Human Only

The agent never does it. A person does.

Examples:

- deploying to production;
- renaming a public API;
- deleting important data.

Very important "never" rules also need a tool that blocks them.

**Stop rule** = a limit on retries, like "Stop after 3 failed attempts and report what you tried."

**Simple lesson:** too many "ask first" lines are also a problem. Each question stops a person's work.

## Non-Functional Requirements

**Non-functional requirement (NFR)** = how well the feature must work, like speed or accessibility.

Every NFR needs three parts.

### Measure

What you check.

- speed;
- accessibility;
- number and date formats.

### Target

The number it must reach.

- under 3 seconds;
- WCAG 2.2 AA;
- less than 1% errors.

### Condition

When the target applies.

- with 100,000 rows;
- at p95 (95 out of 100 requests);
- for en-US and de-DE users.

Example:

```text
Exporting 100,000 rows shall complete in under 3 seconds on a mid-range laptop.
```

**Simple lesson:** "fast" is a wish. "Under 3 seconds with 100,000 rows" is a check.

## plan.md

**Use this when:** the work is big enough to split into tasks.

```text
- T1: Declare the types (files: src/features/export/types.ts)
- T2: Build exportOrders (files: src/features/export/exportOrders.ts) (after: T1)
- T3: Write the tests (files: src/features/export/exportOrders.test.ts) (after: T1)
- T4: Add the button (files: src/components/Toolbar.tsx) (after: T1)
```

**Wave** = a group of tasks that run at the same time.

Rules for a plan:

- The contract task goes first, on its own.
- Every task that uses the contract waits for it.
- Two tasks in the same wave must not change the same file.
- Write the "after" rule for every task.
- Never make tasks wait for each other in a circle.
- Keep each task small: three files or fewer.

## Subagent Brief

**Subagent** = a helper agent that does one task for the main agent.

**Use this when:** you hand one task to a subagent.

```text
Goal: <single task>

Inputs: <specific files and spec references>

Tools: read, edit, test
No push.
No install.

Output: JSON {
  "<field>": <type>
}

Done when: <pass/fail validation check>
```

Every brief has five parts:

1. **Goal** = the one task.
2. **Inputs** = the exact files and spec lines.
3. **Tools** = only the tools the task needs.
4. **Output** = the exact shape of the answer.
5. **Done when** = a check that passes or fails.

**Simple lesson:** each missing part becomes a guess.

## Spec Review

Review the code against the spec, not against your own taste.

**Blocking** = the code breaks a requirement, an acceptance criterion, a contract or a constraint.

**Nit** = a small taste comment. The author may ignore it.

Rules:

- Block only when the code breaks the spec.
- Name the line it breaks, for example `REQ-1` or `AC-2`.
- Leave formatting to tools, not to reviews.

If the same nit keeps coming back, turn it into a formatter or lint rule.

## Living Specs

**Living spec** = a spec you keep up to date after the feature ships.

### Change Request

**Change request** = the stakeholder asks for something different.

Update both in the same edit:

- the requirement;
- its acceptance criterion.

### Drift

**Drift** = the spec and the code no longer agree.

If the change was agreed:

```text
Update the specification.
```

If it was an accident:

```text
Fix the code.
```

### Outcome Review

Passing tests show the code matches the spec.

They do not show the user got the result they needed.

So measure the outcome after release. If it was missed:

```text
Create a new intent.md
```

Put the numbers you measured in it.

## Team Templates

**Skill** = a Markdown file (`SKILL.md`) an agent loads for one job.

**Spec-review skill** = a skill that checks a spec before anyone builds from it.

A good rule finds **one** clear problem that anyone can check. Good rules catch:

- vague words like "fast"
- a requirement with no acceptance criterion
- an outcome with no number
- no non-goals
- a risky action with no decision rule

**Calibration** = testing the skill on specs you already graded.

- Weak specs must fail.
- Strong specs must pass.

**Definition of ready** = the team checklist for when an agent may start.

**Simple lesson:** a team rule only helps if a checker can apply it the same way every time.

## The Spec Linter

**Linter** = a tool that checks your spec and gives it a score.

The score starts at:

```text
100 points
```

Each problem takes points away:

| Problem | Points lost |
|---|---|
| No REQ lines at all | -20 |
| A requirement has no acceptance criterion | -15 |
| A TODO is still in the file | -15 |
| An intent.md field is missing | -10 |
| The outcome has no number and unit | -10 |
| A requirement fails the EARS check | -10 each |
| An acceptance criterion is not Given, when, then | -10 each |
| A "then" is not something a check can see | -10 each |
| No non-goals | -10 |
| No health metric with a number | -10 |
| A risky action has no decision rule | -10 |
| The problem names no cost | -5 |
| The problem links no evidence | -5 |
| A vague word | -5 |
| A pattern constraint has no file path | -5 |

A score of:

```text
85+
```

means the spec is ready for an agent.

The score is feedback. It does not prove the feature is right.

## How Much Spec to Write

Match the spec to the size of the change.

| Change | What to write |
|---|---|
| Tiny change | A clear ticket or a short spec |
| Small feature | `spec.md` with requirements and acceptance criteria |
| Long-lived or shared feature | All three files: `intent.md`, `spec.md` and `plan.md` |

**Simple lesson:** the more people depend on a feature, the more spec it deserves.

## Tool Paths

Each tool keeps its files in a different place. The ideas stay the same.

### Spec Folder

**Use this when:** you decide where `intent.md`, `spec.md` and `plan.md` live.

```text
Claude Code: docs/specs/<feature>/
Codex: docs/specs/<feature>/
Cursor: docs/specs/<feature>/
Spec Kit: specs/<NNN-feature>/
Kiro: .kiro/specs/<feature>/
```

### Project Rules

**Use this when:** a rule applies to every feature, not just one.

```text
Claude Code: CLAUDE.md
Codex: AGENTS.md
Cursor: AGENTS.md or .cursor/rules/
Spec Kit: constitution files
Kiro: steering files
```

### Review Rules

**Use this when:** you want the agent to review specs the same way every time.

```text
Claude Code: .claude/skills/spec-review/
Codex: .agents/skills/spec-review/
Cursor: .cursor/skills/spec-review/
```

Tools change often. Check each tool's current docs.

## Glossary

- **Acceptance criterion (AC)** = a check that proves a requirement works.
- **Agent** = an AI that can read code and change it for you.
- **Contract** = the exact shape of an API: its name, inputs and output.
- **Decision rights** = rules about who decides what.
- **Drift** = the code and the spec no longer agree.
- **EARS** = a simple shape for writing one requirement.
- **Guess** = a choice the agent makes because the spec says nothing.
- **Health metric** = something that must not get worse, with a number.
- **Intent** = the user, the problem, the evidence and the outcome.
- **Non-goal** = something left out on purpose.
- **Open question** = a decision nobody has made yet.
- **Orchestrator** = the main agent that hands tasks to subagents.
- **Requirement (REQ)** = one clear behaviour the agent must build.
- **Stop rule** = a limit that stops endless retries.

## Further Reading

- [Spec-Driven Development with Coding Agents, DeepLearning.AI with JetBrains](https://www.deeplearning.ai/short-courses/spec-driven-development-with-coding-agents/): a free short course.
- [Intent Engineering Framework for AI Agents, by Product Compass](https://www.productcompass.pm/p/intent-engineering-framework-for-ai-agents): a product manager's view of goals, limits and decision rights for agents.
- [Hooks and Permissions](/learn/harness-engineering/foundations/hooks-and-permissions): how a harness enforces the rules a spec states.
- [GitHub Spec Kit](https://github.com/github/spec-kit)
- [Kiro specs](https://kiro.dev/docs/specs/index) and [Kiro steering](https://kiro.dev/docs/steering/)
- [EARS, by Alistair Mavin](https://alistairmavin.com/ears/)
- [Understanding Spec-Driven Development, by Birgitta Böckeler](https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html)
- [Harness engineering, by OpenAI](https://openai.com/index/harness-engineering/)