How to Write a Clear Specification for an AI Coding Agent

An AI coding agent is a tool that can inspect, change, and test a software project. Some agents can also install software, connect to other systems, or prepare a change for release when people give them those abilities.

That speed is useful, but it can turn one missing decision into many changed files before anyone notices. Before the agent starts, someone still needs to decide what should improve, what must stay untouched, how the result will be checked, and what happens if it is wrong.

The saved record of those decisions is the specification, often shortened to spec. It is not a technical ritual. It is a way for people to remain clear and accountable while an AI tool does part of the work.

It answers six questions:

1. What result do we want?
2. What is outside this job?
3. Which facts and decisions can the agent rely on?
4. What may the agent access or change?
5. What proof will show that the result works?
6. When must the work stop or be undone?

A prompt starts one interaction with the AI. A spec preserves the decisions around the work so another person or agent can review them later.

The goal is not more paperwork. It is the smallest plan that makes the risk visible.

Describe the result from the user's point of view. Avoid starting with the code or tool you expect the agent to use.

“Make the report faster” leaves several decisions hidden. “A customer can open the monthly report in under three seconds on an ordinary connection” names a person, a result, and a condition that can be checked.

Also say why the change matters. That helps a reviewer notice when the agent produces something technically impressive that does not solve the real problem.

A non-goal is something deliberately excluded from the work. Non-goals prevent a useful request from quietly expanding into adjacent changes nobody reviewed.

For example: improve the report-loading time, but do not redesign the report, change its numbers, add a new data provider, or alter who can see it.

This is especially important with coding agents because they may discover several plausible ways to “help.” A helpful idea is still outside the job until an accountable person approves it.

Separate three kinds of information:

• Approved decisions: the owner's instructions and the project's current rules.
• Checked facts: what the team confirmed by reading the current software, tests, records, or observed behaviour.
• Reference material: tickets, transcripts, web pages, suggestions, and old documents that may be useful but could be incomplete or wrong.

This prevents a polished ticket or an outdated document from being mistaken for permission. It also tells the agent when to ask a question instead of filling a gap with a guess.

Write the human permission in plain language: which part of the project, which working copy, which systems, and which actions are allowed.

Then make sure the tools enforce the same boundary. Permission written in a document is not protection by itself. A safe setup may use an isolated work area, a credential that reaches only one service, an approved list of actions, a protected live environment, or a required confirmation before a sensitive step.

OWASP's guidance for secure coding with AI recommends limiting context and permissions and reviewing unexpected changes. The practical lesson is simple: give the agent only the access this task needs.

An acceptance criterion states what must be true. Acceptance evidence shows what actually happened.

The proof may be a focused test, a real screen checked with a keyboard and phone, a measurement, a security review, a record read from the system, or an inspection of every changed file. The right evidence depends on the consequence of being wrong.

A green test is useful, but it is not a universal guarantee. The peer-reviewed UTBoost study found benchmark patches that passed the available tests but failed additional cases. That finding is about a particular coding benchmark, not every software project, but it illustrates why reviewers should compare the real result with the intended outcome.

Name the discoveries that require a person to decide: private information appears, access is broader than expected, the current system behaves differently from the plan, a new service or cost is needed, or the change would reach the live product.

Also record how to return to the last known good version. That is the rollback. A reversible change is easier to inspect honestly because the team can reject it without being trapped by the work already done.

• Goal: The user or system should be able to…
• Outside this job: Do not change…
• Known facts and owner decisions: We verified… / The decision owner approved…
• Allowed access and actions: The agent may… / It must not…
• Proof: We will accept the change when…
• Stop or undo: Pause if… / Return to the last good version by…

If a line is not relevant, write “not applicable” and explain why. A blank section hides a decision; an explained omission can be reviewed.

Spec-driven development with AI means deciding what the software should do before asking an agent to implement it. The labels and files vary.

GitHub Spec Kit moves from a specification to a plan, tasks, and implementation. OpenSpec separates proposals, behaviour, design, tasks, and implementation. Kiro Feature Specs supports requirements-first and design-first paths.

Those are useful examples, not a single industry rule. A bounded change may fit in one short document. Higher-consequence work may need separate product, technical, privacy, security, and rollout decisions. Count the decisions that need owners, not the number of documents.

Choose the planning depth by asking what happens if the work is wrong.

• Prompt and check: use this for a small, local change that is easy to inspect and undo. Example: correct a heading colour in a private working copy. State the result, the one area the agent may touch, and the direct check.
• Reviewed brief: use this for a feature that crosses several parts of a product or includes a bounded decision about data, an interface, or outside software or services. Add non-goals, affected areas, an owner, evidence, and rollback.
• Full spec and staged review: use this for private data, sign-in and permissions, money, deletion, moving or reshaping stored data, outside services, or the reliability of a live site. Add specialist review, enforced access limits, a private trial, independent checks, staged release, and recovery evidence.

Five plain questions help choose:

1. How much harm could a convincing mistake cause?
2. Can the change be undone without losing data, trust, or service?
3. Will the planned checks catch the failure before a user does?
4. Does the work need access or a business decision the agent cannot own?
5. Are important facts still unknown?

A four-line visual correction and a customer-data export do not deserve the same process.

Imagine a company wants an administrator to download an activity report: a spreadsheet showing who changed what and when. The request sounds simple. It also crosses a privacy and permission boundary, so it needs more than “add an export button.”

A plain-language spec could record:

• Goal: an authorized administrator can download only the activity records already visible for their own organization and chosen dates.
• Outside this job: no scheduled emails, custom columns, unlimited history, or reports spanning several organizations.
• Known facts: the current screen already checks that the person belongs to that organization and applies date, person, and action filters. The team must verify that the download uses the same rules.
• Allowed access: the agent may work with invented test data in a private trial. It may not read real customer data, change the live service, or add an outside provider.
• Proof: tests must cover an authorized and unauthorized person, two different organizations, each filter, an empty result, size limits, and the exact approved columns. A reviewer must also use the real download control with a keyboard and inspect the file.
• Stop: pause if the existing permission rule cannot be proved, the file includes unapproved personal details, or the work requires a new retention rule, service, or live-system change.
• Undo: keep the download function and button separate from database changes so both can be removed cleanly.

There is one less obvious risk. Spreadsheet programs can treat values beginning with certain characters as formulas. OWASP's CSV-injection testing guidance explains why the design must name the spreadsheet programs it supports and test the actual file safely. The agent should not invent a universal fix.

The example is intentionally specific because “secure,” “fast,” and “user-friendly” are not evidence. The spec turns those wishes into decisions and checks a reviewer can challenge.

A person may approve a private trial, but an overpowered account could still reach the live system. The written boundary and the technical limit must agree. This is also why a signed-in tool or visible account does not automatically authorize the agent to use it.

Behaviour is what a user or connected system can observe. Design is how the software produces it. Keep those levels separate so the agent can suggest a better method without quietly changing the promised result.

NASA's requirements guidance comes from systems engineering, not everyday website work, but its questions translate well: is the requirement clear, consistent, traceable, and possible to verify?

“The export contains only this organization's records” is a condition. A test using two organizations plus inspection of the downloaded file is evidence. Review both the written condition and the proof; they can share the same mistaken assumption.

An agent may discover that the current software differs from its documentation or that a planned step affects private data. It should not improvise past that discovery. Record the new fact, identify the decision owner, and revise, stop, or undo the work.

For higher-risk work, NIST's Secure Software Development Framework supports defining and tracking security requirements across the software lifecycle. A good spec stays useful because it changes deliberately when the evidence changes.

Use a short decision loop for each reviewable part of the change:

1. Look: confirm the current facts, allowed actions, and last known good version.
2. Decide: review the next requirement, its owner, and the proof it needs.
3. Change and check: let the agent complete one bounded part, then inspect the real result and every changed file.
4. Choose: accept it, revise the plan, stop, or undo it. Record the evidence and decision instead of leaving them in a chat history.

Anthropic's guide to agent evaluations distinguishes what an agent reports from the outcome that exists in the environment. A coding workflow needs the same separation.

Three warning signs deserve attention:

• A polished guess: formal-looking language hides a product, privacy, security, or operating decision nobody made.
• Circular proof: the spec, code, and test repeat the same wrong assumption and therefore agree with one another.
• Ceremonial paperwork: every task gets the same long template, so reviewers approve completed boxes instead of thinking about consequence.

For important work, use a reviewer who did not write the spec, implementation, and tests. Independent eyes reduce the chance that all three artifacts inherit one shared misunderstanding.

A good specification earns its value after the first surprise. It tells the team who decides, what proof is missing, what the AI may do next, and whether the safest choice is to continue or undo the change.

That record—not the length of the document—is the durable asset. Use the smallest plan that keeps the important decisions visible.

For the wider ownership principle and its practical review questions, continue with AI Can Write the Code. You Still Own the System..

• GitHub, Spec Kit documentation, accessed 2026-09-01.
• OpenSpec, Spec-driven schema, accessed 2026-09-01.
• Kiro, Feature Specs documentation, updated 2026-08-04; accessed 2026-09-01.
• NASA, Systems Engineering Handbook — Appendix C: How to Write a Good Requirement, accessed 2026-09-01.
• NIST, Secure Software Development Framework (SP 800-218), accessed 2026-09-01.
• OWASP, Secure Coding with AI Cheat Sheet, accessed 2026-09-01.
• OWASP, Testing for CSV Injection, accessed 2026-09-01.
• Anthropic, Demystifying evals for AI agents, published 2026-01-09; accessed 2026-09-01.
• Boxi Yu, Yuxuan Zhu, Pinjia He, and Daniel Kang, UTBoost: Rigorous Evaluation of Coding Agents on SWE-Bench, ACL 2025; accessed 2026-09-01.

• Owain Lewis, How I Code With AI Agents (Spec-Driven Development), published 2026-01-30.
• IBM Technology, presented by Cedric Clyburn, Spec-Driven Development: AI Assisted Coding Explained, published 2026-02-28.