How do you write a good spec for a coding agent?

A coding agent is an AI tool that does not just suggest code but works in a project: it reads files, edits them, runs commands and tests, and reports back. Anthropic's Claude Code runs in your terminal; OpenAI's Codex, launched as a research preview in May 2025, runs each task in its own cloud sandbox with a copy of your repository. Both can work for many minutes without you.

That independence is why the request matters so much. A spec, short for specification, is a written description of what to build. For a person, a vague spec leads to questions. For an agent, it often leads to confident work on the wrong thing. Anthropic's guidance for Claude Code says success rates improve significantly with more specific instructions, especially on the first attempt, and that the agent does best with a clear target to iterate against, such as tests.

The four parts of a useful spec

1. Goal. One or two sentences: who will use this, and what problem does it solve?
2. Scope. What is in this task, and just as important, what is out.
3. Constraints. Language, libraries, files the agent may touch, things it must not do.
4. Acceptance tests. Concrete examples of input and expected output that decide when the work is done.

Add a short process note too. Anthropic recommends asking the agent to explore the code and make a plan first, and explicitly telling it not to write code until you have approved that plan. Without that step, it notes, the agent tends to jump straight into a solution.

A worked one-page spec

Here is a spec for a small tool a school librarian might want. Save it as SPEC.md in the project folder and point the agent to it.

# Spec: overdue-books report

## Goal
A command-line tool that reads the library's loans export (CSV) and prints
the books that are overdue, so the librarian can send reminders on Mondays.

## Scope
In: read loans.csv, find overdue loans, print a sorted report, optional --days filter.
Out: sending emails, editing the CSV, any web interface.

## Input
loans.csv columns: student_name, book_title, due_date (YYYY-MM-DD), returned (yes/no)

## Behaviour
- A loan is overdue if returned is "no" and due_date is before today.
- Print one line per overdue loan: student_name | book_title | days overdue
- Sort by days overdue, most overdue first.
- --days N shows only loans overdue by N days or more.
- If the file is missing or a date is malformed, print a clear error and exit with code 1.

## Constraints
- Python 3.11, standard library only (csv, datetime, argparse).
- One file: overdue.py. Tests in test_overdue.py, run with pytest.
- "Today" must be injectable so tests do not depend on the real date.
- Do not create or modify any other files.

## Acceptance tests
1. Given due 2025-07-01, returned no, today 2025-07-29 -> listed, 28 days overdue.
2. Given due 2025-07-30, returned no -> not listed.
3. Given due 2025-07-01, returned yes -> not listed.
4. With --days 30, a loan 28 days overdue -> not listed.
5. Missing file -> error message, exit code 1.
6. Date "07/01/2025" -> error naming the row, exit code 1.

## Process
1. Read this spec and ask any questions.
2. Propose a plan. Do not write code until I approve it.
3. Write the tests first and run them to confirm they fail.
4. Write the code until all tests pass. Do not change the tests.
5. Summarize what you did and how to run it.

The process section follows a workflow Anthropic describes as one of its favorites: have the agent write tests from expected inputs and outputs, confirm they fail, then write code until they pass without modifying them. Tests give the agent something objective to aim at, and they give you a fast way to check its claims.

Make the project easy to work in

A spec describes one task. Standing instructions about the project belong in a file the agent reads every time. Claude Code loads a CLAUDE.md file automatically, a good home for test commands and style rules. Codex reads AGENTS.md files, which OpenAI says tell it how to navigate the code and which test commands to run. OpenAI also notes that Codex performs best with a configured development environment, reliable tests and clear documentation.

For larger jobs, ask the agent to keep a checklist in a Markdown file and tick items off as it goes, another technique Anthropic recommends for multi-step work.

Finally, review what comes back. OpenAI says Codex cites terminal logs and test results as evidence, and still advises users to review agent-written code before using it. Read the diff, run the tests yourself and try the tool on real data.

How detailed should it be?

Detailed about what, light about how. Spell out inputs, outputs, edge cases, limits and the definition of done, because the agent cannot guess those from the code. Leave the internal design to the agent unless you have a real reason to fix it, such as a library your team already uses. Anthropic's own example of a good instruction names the edge case to cover and says to avoid mocks, a small addition that changes the result.

A useful test of detail: could someone else decide, from your spec alone, whether the finished work passes? If an acceptance test reads "works well," it is too vague; if it gives an input and an exact expected output, it is right.

Size matters as well. Codex tasks typically take between one and thirty minutes, according to OpenAI, and it suggests giving agents well-scoped tasks. If your spec runs past a page, it probably describes several tasks. Split it, and give each piece its own acceptance tests.