Spec Cheat Sheet

By the Syncfusion DevTutorials team · Last updated October 21, 2026

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.

What you will learn

• Find any template or rule from the course quickly

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:

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.

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.

# 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

The <system> shall <response>.

Use it when something must always be true.

When

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

Use it when something happens, like a click.

While

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

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

If, Then

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

Use it for errors and failures.

Where

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.

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:

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.

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.

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:

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.

- 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.

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:

Update the specification.

If it was an accident:

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:

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:

100 points

Each problem takes points away:

A score of:

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.

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.

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.

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.

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: a free short course.
• Intent Engineering Framework for AI Agents, by Product Compass: a product manager's view of goals, limits and decision rights for agents.
• Hooks and Permissions: how a harness enforces the rules a spec states.
• GitHub Spec Kit
• Kiro specs and Kiro steering
• EARS, by Alistair Mavin
• Understanding Spec-Driven Development, by Birgitta Böckeler
• Harness engineering, by OpenAI