dooopSoftware · Process · 11 min

How to Write Specifications for AI Development

Learn how to define behavior, scope, constraints, acceptance, and stopping conditions in specifications for AI development.

Published on September 6, 2026

CENTRAL THESIS

AI writes better when the task already defines what is acceptable.

Specifying is transforming intention into behavior, limits, and verification.

A specification for development with artificial intelligence works when it transforms an intention into observable behavior, scope boundaries, technical constraints, and acceptance criteria. It is not enough to ask “improve the registration” or “fix the login.” Before generating or changing code, the team needs to know which behavior will be accepted, which limits must not be violated, and how the response will be verified.

The specification starts with behavior, not the request

A recurring mistake in specifications for AI development is describing the desire, not the system.

“Improve the registration” seems like a clear request to someone who lives with the product every day. For artificial intelligence, however, this phrase leaves too much room. Improving can mean changing messages, altering validations, reorganizing components, modifying persistence, swapping a library, or suggesting a different experience. Some of these responses may be useful. Others may create rework.

A better specification starts with a concrete situation:

When the user enters an invalid CPF in the registration form, the system must block submission.
Fields already filled must remain filled.
The displayed message must inform that the CPF needs to be reviewed.
No data should be saved while the validation fails.

This form does not explain everything. It reduces ambiguity where ambiguity is costly: in the expected behavior.

The difference is practical. A generic request invites AI to infer intention. A behavioral specification gives the human reviewer a way to approve or reject the change. The code can be elegant and still be wrong if the behavior does not match the described scenario.

This care connects to the broader topic of AI-augmented development. When the specification is vague, the team may transfer to the tool ambiguities that would previously be resolved in conversations, human review, or system reading.

Constraints reduce AI’s response space

A good specification does not only say what to do. It says what to preserve.

Verifiable constraints are explicit limits that allow identifying an inadequate response without relying on personal taste. They may involve architectural patterns, compatibility with an API, dependencies that must not be updated, message format, files that must not be touched, or product decisions not yet authorized.

Examples of useful constraints:

Do not change the public API contract of the registration.
Do not update dependencies in this task.
Do not modify shared components outside the authentication module.
Maintain the current pattern of form error messages.
Create or adjust tests only in directories already used by the module.

They reduce the AI’s response space.

Anthropic defines context engineering as selecting and maintaining the information available to the model during inference, including instructions, tools, external data, and history, within a limited window. Applying this idea to a development task, the specification can function as one of the instructions provided to the model.

If the specification omits constraints, the review lacks a clear reference to reject solutions outside the team’s decisions.

The point is not to control every line before work begins. It is to declare the boundaries that must not be crossed without authorization.

Acceptance criteria must be verifiable by someone

Acceptance criteria for AI are conditions that allow approving or rejecting a change. They can be automated, manual, or a combination of both. A poor criterion is one that seems reasonable but does not allow a decision.

“Become more robust” is vague. “Handle invalid CPF error without clearing the form and with a test covering this scenario” is verifiable.

Verifiable criteria can appear in various forms:

A new or adjusted automated test passes the described scenario.
A manual scenario can be reproduced by the reviewer.
An expected message appears under a specific condition.
A configuration file remains unchanged.
An API response maintains the same format already consumed by other clients.
A failure outside the scope stops the task instead of being fixed together.

The specification does not need to choose only one type of verification. In many systems, an automated test confirms the main rule, while a manual check validates a message, a visual flow, or an interaction difficult to cover at that moment.

DORA describes continuous integration as frequent integration into the main code, accompanied by automated builds and tests, and states that fixing a broken build should have priority over new changes, according to its page on continuous integration. This guidance does not say how to write specifications for AI, but reinforces a relevant discipline: changes need to find objective verification mechanisms early, not only after a tired review.

If the team does not know how it will verify the response, perhaps it does not yet have a task ready for implementation.

A useful specification informs where AI can make changes

The broader the change space, the harder it is to review. This applies to people and AI alike.

A useful specification informs where the change will likely happen. Not as a straitjacket, but as an operational hypothesis:

Main module involved.
Candidate files.
Layers that may be altered.
Related tests.
Areas requiring authorization before any change.

This boundary helps reduce the risk that a simple task results in broad, hard-to-review changes.

DORA recommends small, independent, and testable work units to get feedback on changes and review hypotheses earlier. The same guidance warns about the difficulty of reviewing and integrating large AI-generated changes, on its page about working in small batches.

For teams creating an AI strategy connected to the business, this is a process detail with governance implications. It is not just individual productivity. It is the ability to keep changes understandable, reviewable, and compatible with the organization’s risk.

Limiting scope makes review more objective.

Fictional example: from loose intention to verifiable task

Consider a fictional example in an internal ticket management product. The team wants to reduce login errors from users who type emails with spaces before or after the address.

A weak specification would be:

Fix login problems when the email is incorrect.

This request leaves too many questions open. What problem? Which field? Should the system accept, reject, or normalize the value? Does the change apply to registration as well? Should it touch authentication, interface, API, or database? How to review?

An operational version could be:

Context: in the login form, some users type spaces before or after the email.
Expected behavior: when submitting the form, the system must remove spaces at the beginning and end of the email field before authenticating.
Normal case: if the user types “ pessoa@empresa.com ” and the password is correct, login should follow the same flow as “pessoa@empresa.com.”
Error case: if the email remains invalid after removing spaces, the system must keep the user on the form and display the existing invalid email message.
Allowed scope: change the login component, the normalization function used by login, and the corresponding tests.
Out of scope: do not change registration, password recovery, authentication API contract, global messages, or dependencies.
Acceptance criteria: include a test for email with spaces before and after; maintain existing invalid email test; do not modify files outside the login module without review.
Stopping condition: if normalization is duplicated in other flows or requires changing a shared API, stop and request human decision.

This example is fictional. It does not claim that such a change would reduce errors, increase conversion, or improve support. Those effects, if relevant, would have to be measured in the real product context.

The value of the specification lies elsewhere: anyone on the team can look at the AI’s response and ask if it respected behavior, scope, constraints, and acceptance criteria.

VER Checklist: verification, scope, and constraints

Before sending a task for AI development, the team can use a simple filter. The name here is just a way to remember the goal: verify if the specification already provides sufficient verification, scope, and constraints to guide the review.

Observable behavior: does the specification describe what the system must do in a concrete situation? It passes when a person can reproduce the scenario and say whether the behavior occurred or not.
Input, output, and exceptions: does the task specify which data enters, what response is expected, and which exceptions must be handled? It passes when at least one normal case and one error or boundary case are described.
Allowed scope: does the specification delimit where AI can change code, configuration, or tests? It passes when probable files, modules, services, or layers are indicated, along with areas that must not be modified.
Explicit constraints: does the task specify patterns, dependencies, APIs, compatibilities, or decisions that must be preserved? It passes when the reviewer can point to a violation without relying on subjective interpretation.
Acceptance criterion: is there an objective condition to approve the change? It passes when approval can be linked to automated test, manual scenario, expected response, defined absence of regression, or equivalent evidence.
Stopping condition: does the specification say when AI must stop and request review instead of continuing to assume decisions? It passes when there are clear triggers, such as ambiguous rules, need to change API contract, unrelated test failure, or change outside the expected files.

This checklist does not guarantee code quality. It serves to bring the conversation with AI to a more precise level before implementation.

When the specification should stop before code

Not every intention should become an implementation prompt.

There are situations where the best specification is a stop. This happens when the business rule is still ambiguous, when there is impact on security or sensitive data without a defined responsible party, when the change depends on an uncertain external service, or when the request is too large for a safe review.

It is also worth stopping when there is no test scenario. If no one can describe how to approve the change, the team may be trying to use AI to accelerate a decision that has not yet been made.

GitHub’s documentation on responsible use of Copilot agents describes agent features with distinct environments and permissions and emphasizes human supervision and output review. The specification must work in favor of this supervision. It needs to make clear when AI can proceed and when it must return the decision.

For organizations evaluating AI maturity, this distinction can be used as an internal process criterion: separate executable task, pending decision, and risk that requires another type of handling.

How to use the specification in human review

Human review of AI-generated code should not start only with style or the impression that “it worked.” It should start with the specification.

The reviewer can follow a simple sequence:

Does the implemented behavior match the described scenario?
Did the change stay within the allowed scope?
Was any constraint violated?
Were the acceptance criteria demonstrated?
Did AI make any decision that should have stopped for review?

This review is more objective because the team agreed beforehand on what would be considered correct. Without this, each person evaluates through a different lens: one looks at architecture, another at deadlines, another at appearance, another tries to reconstruct the original intention.

The specification gives human judgment a point of support.

It also does not replace requirements discovery, technical design, or conversation between product and engineering. When the need is still uncertain, over-specifying may only hide uncertainty in a long document. The goal is different: to make change acceptance clearer and verifiable.

For teams building an AI roadmap, the question can help qualify candidate tasks. Before asking if a task can be done with AI, ask if it can be described in behavior, scope, constraints, acceptance, and stopping condition.

If not, perhaps the next action is not to generate code. Perhaps it is to decide better.

Before asking AI to implement the next change, rewrite the specification until it answers five questions: what changes, where it can change, what must not be violated, how it will be verified, and when it must stop.

If you want to discuss this decision in your company’s context, talk to dooop.

Sources

NEXT DECISION

Discuss application in the company

Conversation about the software company context

Content from dooop. Registration allows relating this topic to the reader’s journey and tracking interest in the subject.