Writing

One Page Task Spec Template for AI Coding Agents

By Scott Wilder · November 5, 2026 · 4 min read · All writing

A one-page task spec for a coding agent has seven parts: the goal, the context, the files to touch, the files not to touch, acceptance criteria, how to verify, and when to stop and ask. Copy the template below, fill it in for one task, and you can tell in one command whether the agent stayed inside it.

None of this needs a special tool. It is a text file and one git command.

Copy this one-page spec

Paste this into your prompt, or save it as a file and point the agent at it:

# Task: <one sentence goal>

## Context
<2 to 3 lines: what exists now and why this change>

## Files to touch
- path/to/file_a
- path/to/file_b (new)

## Do not touch
- path/to/anything_else
- database schema, config, dependencies

## Acceptance criteria
- [ ] Given <state>, when <action>, then <result>
- [ ] Given <state>, when <action>, then <result>
- [ ] Existing tests still pass

## How to verify
- Run: <command>
- Check: <what to see on screen or in output>

## Stop and ask if
- The change needs a new dependency
- A file outside the list has to change
- All acceptance criteria pass (then stop, do not clean up anything else)

The shape is not mine. Spec templates for coding agents share it: an overview, success criteria and acceptance criteria as checkboxes, as in this agent spec skill. What most of them leave out is the do-not-touch list and the stop rule, so those are the two parts I would never drop.

Fill it in like this

Example: say you run a small app and want a "Forgot password?" link on the login page that goes to a reset page you already have.

# Task: Add a "Forgot password?" link under the password field on the login page

## Context
The login page has an email and password form. The reset page exists at /reset and works. Users cannot find it.

## Files to touch
- app/login/page.tsx
- app/login/login.test.tsx (new)

## Do not touch
- app/reset/
- auth config, package.json, database schema

## Acceptance criteria
- [ ] Given the login page, when it loads, then a link labeled "Forgot password?" shows under the password field
- [ ] Given that link, when I click it, then I land on /reset
- [ ] Existing tests still pass

## How to verify
- Run: npm test
- Check: open /login, click the link, confirm the URL is /reset

## Stop and ask if
- The change needs a new dependency
- /reset has to change
- All acceptance criteria pass (then stop)

That is about 150 words. If yours runs much longer, the task is too big for one page. See the last section.

Write acceptance criteria you can run or see

One criterion per behavior, in Given, When, Then form, is the format DevPlan's agent spec template uses. One line, one check. If a line has "and" in it, split it into two.

The test for every line: can you run something or look at a screen and say yes or no?

Weak line Better line
Login works well Given a wrong password, when I submit, then I see "Incorrect email or password" and stay on /login
Looks good on mobile Given a 375px wide screen, when I open /login, then the link is visible without scrolling sideways
Handle errors Given the server returns 500, when I submit, then I see "Something went wrong" and the form keeps my email

When a line fails the test, rewrite it until it passes. An agent cannot tell when it is done against "works well", so it stops early or keeps going.

Give the agent fewer files and a place to stop

An agent goes out of scope because everything it can see is fair game. Syncfusion's write-up on agent guardrails says the simplest fix is less context: if the agent needs three files, do not hand it thirty.

Three habits keep it in bounds:

  1. Name the files in the spec and say "Do not touch" for the rest.
  2. Tell it to stop and ask if another file has to change, instead of editing it.
  3. Name the success condition and tell it to stop when it sees it. One runtime-failure write-up recommends a structured done signal for exactly this.

If you run the agent in a loop, cap the steps too. That same write-up gives 15 to 25 steps as a reasonable default for code-editing agents. Start at the low end for a small task like the example.

Rules alone are not enough. Users on the Cursor forum report agents ignoring a stop-and-confirm rule and editing files they were not asked to. So check the result.

Check the diff before you commit

After every run:

git diff --name-only

Compare that list to "Files to touch". Any file outside the list is a flag. Revert it, or ask the agent why it was needed. Then run the verify step from the spec. For checking the agent's own claim that it finished, see How to Tell If an AI Agent Actually Finished the Task.

Put project rules in CLAUDE.md, not in every spec

A spec covers one task. Rules that hold for every task, like the test command, style rules and folders no task should touch, belong in your project instructions file once. If you use Claude Code, that is CLAUDE.md. If you use several tools, keep the shared rules in AGENTS.md and import it with an @AGENTS.md line in CLAUDE.md, so there is one copy.

Keep that file short. Bloated CLAUDE.md files can lead Claude to ignore your actual instructions. Put in only what the agent cannot work out from the code: toolchain specifics and project conventions. Then add one line at the top of each spec: "Follow the rules in AGENTS.md. This spec only covers this task."

I wrote up the instructions-file side in How to Write a CLAUDE.md File for a Side Project.

Split the task when one page will not hold it

One change in one area gets one page. When a task spans several features or needs design choices, spec-driven tools split it into three files: requirements, design and tasks, as this roundup of agent spec templates describes for Kiro. Do the same by hand. Write the requirements once, then one one-page spec per task.

The size check is simple: if your "Files to touch" list is longer than you can review in one sitting, split the task. Pick your own cutoff and write it at the top of the spec.

Four mistakes that cost you a review

Do this in the next ten minutes

Pick the next small change you were going to ask an agent for. Paste the template, fill in only the goal, the files to touch and two acceptance criteria, and run it. Then run the diff check and see which files changed.

Need a hand getting a task off your plate?

If there is a manual task you keep meaning to automate, email me with what it is and I will tell you whether it is worth handing to an agent.

Questions

What should I put in a spec for an AI coding agent?

A one-sentence goal, short context, the files to touch, the files not to touch, acceptance criteria as checkboxes, how to verify, and when to stop and ask. That is the shape most agent spec templates share.

How do I write acceptance criteria for an AI coding agent?

Write one criterion per behavior, in Given, When, Then form, and make each line something you can run or see. If a line has 'and' in it, split it in two.

How do I stop an AI agent from editing files I did not ask it to?

List the files it may edit, add a do-not-touch list, tell it to stop and ask if another file has to change, and run git diff --name-only afterward to compare the changed files with your list.

What is the difference between a task spec and CLAUDE.md?

A spec covers one task: the goal, files and acceptance criteria. CLAUDE.md or AGENTS.md holds rules that apply to every task, such as the test command and folders to avoid.

How long should a task spec be?

About one page. If the files-to-touch list is longer than you can review in one sitting, split the work into requirements, design and tasks, and write one short spec per task.