What an agent-ready requirement actually contains

An engineer who picks up a thin ticket fills in the gaps as they go: a question in chat, a look at how the existing feature works, a guess checked with the product owner. A coding agent works from what’s written, and it works fast. Give it a requirement with a gap, and within minutes you can have a pull request that fills the gap with an assumption.

The clarifying still happens. It happens later, though: after the change has been written, and while someone is spending review time on it. What the requirement didn’t say comes back as a wrong pull request or as a thread of questions in review.

That’s why the requirement matters more when an agent writes the code. A requirement is ready for an agent when someone who wasn’t part of the conversation could act on it and check the result. That takes five things: the outcome, the boundaries, acceptance criteria that can be checked, the dependencies and the known risks. It also needs a list of the questions that are still open. Writing these down doesn’t remove uncertainty. It makes the uncertainty visible, so the agent, or the engineer, stops and asks instead of guessing.

Why it matters more with agents

Companies that build coding agents give much the same advice about what to hand them. GitHub recommends treating the issue you assign to its agent as a prompt, and says a well-suited task has a clear description of the problem, complete acceptance criteria that define what a good solution looks like, and directions on which files need to change. It also lists tasks to keep away from the agent, including vague ones and ones involving security, personally identifiable information or authentication. See GitHub’s guidance on tasks for Copilot.

Anthropic’s best practices for Claude Code say that the more precise your instructions, the fewer corrections you’ll need, and that without a check the agent can run, “looks done” is the only signal you have and you become the verification loop. Read Anthropic’s best practices for Claude Code. OpenAI’s Codex guide describes a good prompt as one that names the behavior you want, points to the relevant code, keeps the important constraints and says how to verify the change. Read OpenAI’s Codex prompting guide.

This is vendor advice about their own products, not evidence of outcomes. It does line up, though, and every item belongs in the requirement.

Size matters too. DORA’s guidance on small batches says that work taking more than a week to complete and check is too big. Its note on AI says the tools tend to produce large, complete features, that reviewing AI-generated code may take more effort per line, and that teams should avoid huge pull requests. Read DORA on working in small batches. A requirement that says what’s out of scope and how each part will be checked helps keep a change small enough to review.

The five parts, and the questions still open

Each part has three lines: what it says, a quick test, and what tends to go wrong when it’s missing. The examples all come from the export request this series has been following.

1. Outcome

What it says: Who has the problem, what they’ll be able to do once it’s solved, and who will confirm it’s solved.
Good enough if: Someone outside the conversation can say in one sentence who benefits and what changes for them.
When it’s missing: The agent solves the literal words. Asked for a “Customer ID”, it may add the internal ID it finds in the schema, and you get a clean pull request that solves the wrong problem.

GitHub’s write-up of its spec-driven toolkit starts the same way: who the users are, what the problem is and what success looks like. The technical approach goes in a separate plan. Read the GitHub Blog on spec-driven development.

2. Boundaries

What it says: What’s in scope, what’s explicitly out of scope, what must not change, and who can see what.
Good enough if: It names at least one thing someone could plausibly have assumed was in scope.
When it’s missing: The change grows. The agent adds the field to other reports as well, reorders the columns while it’s there, or reads the data through a path that bypasses the permission check.

Malte Ubl’s account of design docs at Google describes non-goals as things that could plausibly be goals but are deliberately ruled out. They aren’t negated goals, such as “the system shouldn’t crash”. Read Ubl on design docs at Google. Anthropic’s guidance says the most useful specs state what’s out of scope, and OpenAI’s example prompt includes the constraint “Do not change the API shape.” One line like that protects behavior an acceptance criterion probably wouldn’t mention.

3. Acceptance criteria

What it says: Examples of behavior that count as done, each one checkable as pass or fail.
Good enough if: A reviewer, or the agent, could run each one and get a clear result, and each one checks one thing.
When it’s missing: The agent’s own tests become the definition of done, and the reviewer has to work out what done was supposed to mean.

Given/When/Then is a simple way to write them. The Agile Alliance glossary describes it as a template for acceptance tests: some context, an action and a set of observable consequences. See the Agile Alliance glossary entry for Given-When-Then. Its entry on acceptance testing adds that a failing test suggests, though does not prove, a defect. See the Agile Alliance glossary entry for acceptance testing. Cucumber’s Gherkin reference says the outcome should be something that comes out of the system, such as a report, a screen or a message, rather than a record sitting inside it. See the Cucumber Gherkin reference. For an export, check the file the user receives, not the query that produced it.

4. Dependencies

What it says: What the work relies on: code paths, where the data lives, other teams, and decisions it’s waiting on.
Good enough if: The agent would know where to start, and what it must not assume exists.
When it’s missing: The agent finds one route and stops. The CSV export gets the new column and the XLSX export doesn’t, or the change assumes every account has a value.

GitHub notes that its agent can often find the right code without an exact file path. A dependency line covers what the code can’t tell it, such as a field being optional or another team owning the data.

5. Known risks

What it says: What could go wrong even if every criterion passes, and who it would affect.
Good enough if: Every risk is covered by a criterion, a check or a named person.
When it’s missing: If you’re lucky, the risk turns up in review. If you’re not, a customer finds it.

When a change adds data to a download, name exposure first. OWASP describes this class of mistake for APIs, returning properties a user isn’t authorized to read, and recommends checking that the user may read each property returned and returning only what’s needed. Read OWASP on property-level authorization. An export isn’t an API, but the boundary and the risk line guard against the same problem.

Open questions

What it says: What hasn’t been decided, who will answer it, and whether work can start before then.
Good enough if: Every question has an owner, and the requirement says when the agent should stop and ask.
When it’s missing: The agent quietly answers the question itself, and the answer turns up as a line of code nobody chose.

No requirement is complete when work starts, so say what’s missing. GitHub’s spec-kit templates require the model to mark each ambiguity with a “needs clarification” note and a specific question rather than guess. See GitHub’s spec-kit on marking what needs clarification. A “stop and ask if” line does the same job in advance by stating when the agent should come back to a person.

One final check. As Lubos et al. summarize ISO/IEC/IEEE 29148, a good individual requirement is, among other things, singular, unambiguous, verifiable and free of implementation detail it doesn’t need. See Lubos et al. on requirement quality. In practice, that means one idea per line, one way to read it and a way to check it.

Illustrative example: the export request

The previous article in this series took one customer request from question to resolution: “Can this export include our Customer ID?” At the scope step, the product owner approved a seven-line requirement. Here it is in full, including the parts that article didn’t show: acceptance criteria written out, dependencies, known risks and open questions.

Illustrative example. The customer, the export and the requirement are invented to show the template filled in.

Outcome

Who: The customer’s account admin, who matches account activity to the accounts in their own systems.
What becomes possible: Matching each row of the account activity export to their own records by account reference, with no manual lookup.
Confirmed by: The customer’s admin, through support.

Boundaries

In scope: The account activity export, CSV and XLSX. Add an “Account reference” column after the existing columns.
Access: Fill it only for records the requesting user can already export.
Isolation: Never return a value from another tenant.
Must not change: Existing column names and order.
Out of scope: Changing the internal ID; all other reports.

Acceptance criteria

New column: Given an admin who can export account activity, when they export as CSV or XLSX, then the last column is “Account reference” and each row shows that record’s account reference.
Existing columns: Given an export taken before the change, when the same user exports after it, then every existing column has the same name and position.
Access: Given a user who can’t export a record today, when they export, then the file contains neither that record nor its account reference.
Isolation: Given two tenants, when an admin in one exports, then no account reference from the other tenant appears.
Blank references: Added once the first open question is answered.

Dependencies

Data: Where the account reference is stored, and whether every account has one.
Code: The export code path for CSV and for XLSX, and whether they share one column definition.
Access: The existing export permission check. The new column goes through it, not around it.
People: Support, to confirm the result with the customer’s admin.

Known risks

Column position: Some customers’ import scripts may read the export by column position. Adding the column at the end protects them; renaming or reordering columns would break them.
Blank values: Accounts with no reference produce blank cells, which a customer could read as missing data.
Exposure: A mistake in the access or tenant check would show a reference to someone who shouldn’t see it. Covered by the access and isolation criteria and a named engineer’s review.
Formula characters: If people type account references in by hand, a value that starts with =, +, @ or a minus sign can run as a formula when the CSV is opened in a spreadsheet. OWASP describes this as CSV injection and notes there is no single universal fix. See OWASP on CSV injection. Covered by the engineer’s review and the open question below.

Open questions

Blank references: Should an account with no reference show a blank cell or a placeholder? The product owner answers. Work can start, and the criterion is added once there’s an answer.
One reference or several: Can an account have more than one? The engineer checks the data. If it can, stop: the product owner decides which one the export shows.
Formula characters: How should the CSV export neutralize leading formula characters without breaking customers’ import scripts? The engineer proposes; the product owner approves.
Stop and ask if: Filling the column needs a query that reaches across tenants, either format needs a change to an existing column, or a test only passes if you widen who can export.

Who does what

An agent can draft: The outcome from the support conversation, candidate acceptance criteria, and the dependencies, by finding the export code paths and where the reference is stored.
An agent can check: That each criterion can pass or fail, that every risk is covered, and that every open question has an owner.
A person decides: The scope and what’s out of it (the product owner), the answers to the open questions (whoever owns each one), and the access and tenant rules (a named engineer).

Access and tenant rules are close to the security and authentication work GitHub suggests handling yourself, so a named engineer owns that part.

What a requirement can’t do

Writing a requirement down doesn’t mean the agent will follow it. Birgitta Böckeler of Thoughtworks tried three spec-driven tools in 2025. Even with all the files, templates and checklists, she often saw the agent not follow all the instructions. The specs were verbose and tedious to review. In Kiro, one small bug turned into four user stories with 16 acceptance criteria. With Tessl, generating code from the same spec more than once gave different results, though a more specific spec was more repeatable. Read Böckeler on spec-driven development tools. The tools have changed since, but three lessons still hold.

• Keep it short. Use the short form for small issues. Anthropic’s advice is that if you could describe the diff in one sentence, you can skip the plan.
• Lean on the checks. A failing check is harder to miss than a skipped instruction, and the acceptance criteria still work when the prose is ignored.
• Expect it to change. INVEST, which DORA uses, includes “negotiable”: a batch of work can be renegotiated as feedback comes in. A requirement is a starting point, and the agent should be free to question it.

The Ambig-SWE study, accepted at ICLR 2026, built underspecified versions of tasks from the SWE-Bench Verified benchmark. The models it evaluated struggled to tell well-specified instructions from underspecified ones. When they could interact with a user, they got the missing information and did better, by up to 74 percent over working without interaction. Read the Ambig-SWE paper. That’s a best case on a constructed benchmark, not a measure of your tickets, and it doesn’t show that a better template removes the need to ask. It does show that asking helps, and that the models didn’t reliably recognize when they should ask. So write the open questions down, and say when to stop.

The template

Copy this into an issue or a pull request description. Use the short form for small issues. Use the full form for anything that touches access or customer data, crosses more than one code path or team, or has an open question that blocks work. Leave a field blank rather than make something up; a blank field tells the reader something is still unknown.

Short form

Outcome: Who needs what, and how they’ll know it worked.
Out of scope: At least one thing someone could plausibly assume is included.
Done when: One to three checks, each pass or fail.
Open questions: What isn’t decided, and who answers. Write “None” if there are none.

Full form: outcome and boundaries

Who: Who has the problem.
What becomes possible: What they can do once it’s solved, in their words.
Confirmed by: Who will say it worked.
In scope: The change, in a sentence or two.
Out of scope: Things that could reasonably be included and aren’t.
Must not change: Existing behavior to protect.
Access and data rules: Who can see or change what.

Full form: acceptance criteria

Given / When / Then: One per line. Each checks one thing, with an outcome a user or reviewer can see.

Full form: dependencies and risks

Code: Where the change is likely to go, and related paths.
Data: Where it lives, and what might be missing.
People and decisions: Who else is involved, and what’s waiting on someone.
Risk: What could go wrong even if every check passes.
Covered by: A criterion, a check or a named person.

Full form: open questions and decisions

Question: What isn’t decided.
Who answers: A name or a role.
Blocks work: Yes or no.
Stop and ask if: When the agent, or the engineer, should come back to a person.
Scope approved by: Usually the product owner.
Security-sensitive parts owned by: A named engineer.

Try it on a small issue

Pick one small issue your team plans to start this week, ideally one an agent will work on. Fill in the short form, or the full form if it involves access or customer data. Before work starts, ask the person who will review the change what questions they’d have, and add the answers.

When the pull request comes in, note every question raised in review and which part of the requirement could have answered it. Also note any open question the agent answered without asking. After a few issues, you’ll see which parts of the requirement the questions keep coming from, and that’s where your team’s requirements need the most work.

Where Blacktops fits

You don’t need a particular tool to use the template. An issue description is enough.

The harder part is keeping the requirement accurate as the work gets done. Questions get answered in chat, scope changes in a meeting, and by the time the change reaches review, the issue no longer matches what was agreed. Blacktops is the Agentic SDLC Platform built to keep the requirement connected to the work. It keeps one thread from the customer’s question to the release: the approved requirement, the agent’s work, the evidence, each decision and who made it. Agents do the work between the decisions, and people decide the scope. We call the operating model Continuous Agentic Software Delivery™, or Blacktops CASD™.

Start with one requirement. If questions still come up in review, check where each one was answered, and whether anyone could find that answer now.

Try the requirement template on a small issue.

Related: Why the customer loop matters more with agentic coding walks this export request from the customer’s question to a confirmed resolution. Find the handoff where progress stops asks who owns each handoff and what evidence they need, as a six-stage checklist. What a support ticket needs before it reaches engineering picks the export up after release, when a support ticket about the new column reaches engineering.

Continuous Agentic Software Delivery, CASD and Blacktops CASD are trademarks of Blacktops, Inc.