Why AI Agents Need Executable Specifications, Not Better Prompts

The Death of the Software Requirements Document

For decades, software projects have begun with some variation of the same ritual. Someone writes a requirements document. Product managers convert parts of it into tickets. Engineers discuss those tickets, ask questions, make assumptions, and eventually turn the requirements into code.

The process works because human beings quietly repair it along the way. An experienced engineer notices that two requirements contradict each other. A designer recognises that an important state is missing. A product manager clarifies what "fast," "secure," or "user-friendly" is supposed to mean. A developer remembers an undocumented business rule from a previous project.

The requirements document is rarely complete. Historically, it did not need to be, because the humans implementing it supplied the missing context.

AI agents change this arrangement.

Coding agents can now inspect repositories, modify several files, run tests, diagnose failures, and submit pull requests. They are no longer limited to suggesting the next line of code. They can carry out increasingly complex, multi-step engineering tasks with limited human intervention.

However, an agent cannot reliably implement an intention that the organisation itself has never made precise. Give an experienced engineer an incomplete requirement and they may stop, ask a question, or interpret it using years of organisational knowledge. Give an autonomous agent the same requirement and it may produce a complete, well-structured, and entirely incorrect implementation.

This is the real transition happening in software engineering. We are not simply moving from writing code to writing prompts. We are moving from requirements documents to executable specifications.

1. The Requirements Document Was Always an Incomplete Interface

Traditional requirements documents are written primarily for communication. They explain what a business wants, why it matters, and how users are expected to interact with a system. Their language is intentionally accessible to people across product, engineering, design, legal, and operations.

That accessibility is valuable, but it creates ambiguity. Consider seemingly ordinary requirements:

The customer should receive a refund quickly.
Administrators can access all reports.
The system should prevent suspicious payments.
Users should be notified when their application changes.

Each sentence communicates an intention, but none is sufficient to implement a reliable system. How quickly must the refund be initiated? Does "all reports" include documents containing restricted personal information? What makes a payment suspicious? Which application changes require a notification? Should notifications be sent immediately, grouped together, retried after failure, or suppressed under certain conditions?

A human engineering team discovers these questions during implementation. The requirement acts as the beginning of a conversation. An autonomous agent may instead treat it as the end of one.

Ambiguity in requirements is not a new problem. Requirements engineering research has examined lexical, syntactic, semantic, and referential ambiguity for years. Researchers have developed methods specifically to identify ambiguous software requirements because unclear language can produce fundamentally different implementations.

What is new is the speed and confidence with which AI can turn that ambiguity into working software.

2. AI Does Not Remove Ambiguity; It Automates Its Consequences

A model can generate code from an unclear instruction. That does not mean it understood the instruction correctly. Research into AI-assisted software engineering increasingly shows that ambiguity reduces code generation performance. Models may produce functionally different implementations from the same unclear requirement and often fail to recognise that clarification is necessary.

This reveals a fundamental problem: the agent does not always know what it does not know.

When a human engineer makes an assumption, that assumption may surface in a planning meeting, code review, or conversation with a colleague. When an agent makes the same assumption, it may be buried inside hundreds of lines of generated code. The code may compile. The tests may pass. The feature may still be wrong.

An agent is therefore not merely a faster programmer. It is also a faster mechanism for converting unspecified assumptions into system behaviour. That makes the quality of the specification more important, not less.

3. A Prompt Is Not a Specification

The enthusiasm around AI development has encouraged teams to think of prompts as the new programming language. They are not.

A prompt is usually an instruction for a particular execution:

Add email verification to the registration flow.
Build an approval process for refunds over $1,000.
Restrict this endpoint to administrators.
Migrate the application to the new payments API.

These may be useful starting points, but they do not define the complete behaviour of a system. A specification answers the questions the prompt leaves open.

For email verification, it might define:

When the verification message is sent.
How long the token remains valid.
Whether tokens can be reused.
What happens after an email address changes.
The maximum resend frequency.
Which features remain available before verification.
How mobile and web clients receive the result.
How verification attempts are audited.
How the system behaves when the email provider is unavailable.

The difference is not verbosity; the difference is enforceability.

A prompt tells an agent what someone would like it to do. A specification defines the conditions under which the result is correct.
Prompts are normally temporary; specifications should be durable.
Prompts are often conversational; specifications must be reviewable.
Prompts can tolerate interpretation; specifications must expose interpretation.
Prompts initiate work; specifications govern it.

4. We Already Know How to Do This

Executable specifications are not an entirely new idea. Software engineering has been moving important parts of system behaviour out of prose for years:

OpenAPI provides a machine-readable description of an HTTP API.
JSON Schema provides a declarative language for defining and validating the structure, constraints, and types of data.
Terraform allows teams to declare the desired state of infrastructure.
Policy-as-code systems allow organisations to express authorisation and operational rules separately from application logic.
Automated tests define expected behaviour through executable examples.

These tools all reflect the same principle: important intentions become more reliable when they are converted into structures that machines can validate.

An API contract can be checked. A data schema can reject invalid input. An infrastructure plan can show the difference between the current state and the desired state. A policy engine can allow or deny an action based on explicit rules.

None of these systems eliminates human judgement. They move critical decisions from informal understanding into visible, versioned, and testable artefacts.

AI agents extend the need for this approach across the entire development lifecycle. The next generation of software specifications will not be one enormous formal document. It will be a connected set of artefacts that together define what the system is permitted and expected to do. That may include:

Domain models
API contracts
State-transition rules
Data schemas
Examples and counterexamples
Acceptance tests
Access-control policies
Performance budgets
Architectural constraints
Observability requirements
Migration rules
Failure behaviour
Explicit escalation conditions

The prose still matters because it explains the intent. The executable parts determine whether the implementation satisfies it.

5. The Specification Becomes the Real Source of Truth

Most organisations claim that their documentation is the source of truth. In practice, the truth is usually scattered: part in the ticket, part in the code, part in automated tests, part buried in a Slack conversation from two years ago, and part existing only in the memory of the engineer who built the first version.

This arrangement is already expensive for human teams. For agents, it is a structural limitation. A repository containing years of code and documentation is not automatically good context. It may contain:

Obsolete architectural decisions
Contradictory documentation
Deprecated interfaces
Unfinished experiments
Tests that encode accidental behaviour
Comments that no longer describe the code beneath them

An agent can inspect all of this and still reach the wrong conclusion. A specification layer gives the agent a hierarchy of authority:

Security and regulatory policies cannot be violated.
Domain invariants must always hold.
Published API contracts must remain compatible.
Acceptance criteria define the expected feature behaviour.
Existing implementation details may change unless explicitly protected.
When authoritative sources conflict, the agent must stop and request clarification.

This hierarchy is far more useful than simply placing more documentation into the context window. The goal is not maximum context; the goal is authoritative context.

6. The New Unit of Software Work

The user story has been the dominant unit of product development for years:

As a customer, I want to reset my password so that I can regain access to my account.

It is useful because it describes a user, a need, and an outcome. It is insufficient because it does not define the system.

An agent-ready specification for the same feature would also define:

Preconditions: The account exists and supports password authentication.
Inputs: An email address or username supplied through a public recovery endpoint.
Privacy behaviour: The external response must not reveal whether the account exists.
Token rules: The token must be random, single-use, securely stored, time-limited, and invalidated after a successful password change.
Rate limits: Requests must be restricted by account identifier, IP address, and relevant abuse signals.
Session behaviour: Existing sessions must either be revoked or preserved according to an explicit security policy.
Failure behaviour: Email delivery failure must not reveal account status and must remain observable internally.
Cross-platform behaviour: The backend should own the recovery process so that web and mobile clients can use the same flow.
Acceptance tests: The specification should cover successful recovery, expired tokens, reused tokens, changed email addresses, concurrent requests, excessive requests, and unavailable email delivery.

The user story remains valuable because it explains the purpose. The specification makes the purpose implementable.

This will change how work is prepared before an agent receives it. The task will no longer simply be "build password recovery." It will be a package of intent, constraints, contracts, and verification. That package becomes the new unit of software work.

7. What Building TalonHR and Tinker Payments Taught Me About Specifications

This argument is not theoretical. I have encountered it directly while engineering two very different platforms: TalonHR and Tinker Payments.

TalonHR coordinates hiring and career workflows across employers, recruiters, applicants, and coaches.
Tinker Payments provides a control layer across payment providers, routing decisions, ledgers, and reconciliation processes.

At first glance, the products appear to have little in common. One manages people and hiring workflows; the other manages money and payment infrastructure. From an engineering perspective, however, both exposed the same fundamental truth: the difficult part was rarely writing the code. The difficult part was defining exactly what the system was supposed to mean.

TalonHR: When a Status Is Really a Business Decision

A recruitment platform can appear deceptively simple. A role is created, candidates apply, recruiters move them through a pipeline, interviews are scheduled, an offer is made, and someone is hired.

That sounds like a straightforward sequence of database updates. It is not.

TalonHR connects employer requisitions, approval processes, candidate records, recruiter workflows, structured feedback, interviews, offers, application tools, coaching programmes, and privacy operations. Once those workflows interact, apparently simple requirements become ambiguous.

Consider the instruction: Allow a recruiter to move a candidate to the interview stage.

Before implementing it, the system needs answers to several questions:

Has the candidate consented to their information being shared with this employer?
Has the hiring manager approved the role?
Does moving the candidate also create an interview task?
Should the candidate immediately receive an update?
Can the recruiter reverse the transition?
What happens to previously scheduled screening tasks?
Can an external recruiter see feedback written by an internal hiring manager?
Does the status change affect analytics immediately?
What should happen when two people move the candidate at almost the same time?

The word move hides a collection of business decisions. The word candidate may refer to a person, an application, a talent-pool entry, or the relationship between that person and a particular role. The word interview may describe a pipeline state, a scheduled calendar event, an evaluation process, or all three.

A requirements document may say: Recruiters can move candidates through the hiring pipeline. That sentence describes the intended capability, but it does not define the system.

To engineer the workflow safely, we need a specification that establishes entities, permissions, valid transitions, side effects, and exceptions. For example:

A recruiter may move an application from screening to interview only when the role is open, the recruiter has permission to manage the application, the application is active, any mandatory screening steps have been completed, and no conflicting final decision exists.

On success:

The application stage changes to interview.

The transition is recorded in the audit history.

The relevant interview tasks become available.

Authorised participants are notified.

Candidate-visible communication follows the configured disclosure policy.

The transition must not expose private interviewer feedback, duplicate an existing interview, or delete the previous stage history.

This is far more useful to an agent than: Build candidate stage movement.

The same problem appears throughout TalonHR:

A quick-apply feature must define which profile information can be reused, which information requires fresh consent, and what happens when the role asks for information the applicant has not supplied.
An interview-scheduling feature must define time zones, cancellations, rescheduling, interviewer availability, and whether creating a calendar event automatically changes the application state.
A privacy-deletion request must distinguish information that can be deleted from information that must be retained for contractual, security, or regulatory reasons.
An offer is not merely a document; it is a stateful process involving permissions, versioning, acceptance, withdrawal, expiration, and possibly several parties.

This is why TalonHR is not simply a collection of screens. Its engineering challenge is preserving meaning as work crosses organisational, technical, and privacy boundaries. In such a system, ambiguity does not always produce an obvious crash. It may produce something more dangerous:

A candidate receives information too early.
Private feedback becomes visible to the wrong participant.
A recruiter acts on an outdated application.
An interview is booked without the required approval.
Analytics record a business outcome that never occurred.

The application may remain online. Every API may return 200 OK. The system is still wrong.

Tinker Payments: When Ambiguity Moves Money

Tinker Payments exposes the same problem at a much higher consequence level. The platform sits above multiple payment providers and is designed to provide routing, failover, ledger visibility, reconciliation, and operational control without requiring merchants to replace their entire payment infrastructure.

A broad requirement might say: If a payment provider fails, route the transaction to another provider.

That sounds sensible, but it is dangerously incomplete.

What counts as failure? A connection timeout? An HTTP error? A provider declining the card? A response that cannot be parsed? A successful authorisation whose response was lost before the merchant received it?
Can every payment be retried?
Can the same provider be retried?
Should retries be allowed for subscriptions but not one-time payments?
How do we prevent the customer from being charged twice?
What happens when the first provider recovers after the second provider has already approved the transaction?
Which transaction reference remains authoritative?
How are fees and exchange rates compared?
Does the merchant prefer a higher authorisation probability or a lower processing cost?
At what point must the system stop making autonomous routing decisions and ask for human intervention?

A vague instruction such as "retry failed payments" can create duplicate charges, inconsistent ledgers, and reconciliation problems. The implementation needs a much stronger specification. For example:

A payment may be retried through another provider only when no definitive approval has been recorded, the previous result belongs to a retryable failure category, the payment method and merchant configuration permit retrying, the retry limit has not been reached, the idempotency policy can still guarantee one logical payment, and the selected provider supports the required currency, region, and payment capability.

A definitive customer decline must not be treated as provider unavailability.

An unknown result must enter a reconciliation state before another charge is attempted unless the provider contract explicitly guarantees that retrying is safe.

Every provider attempt must remain linked to one logical payment instruction.

That is not merely documentation; it is the foundation of the routing state machine, provider adapters, ledger records, idempotency controls, observability model, and reconciliation process.

Take reconciliation. A simplistic requirement might say: Match provider transactions with our internal payments.

Match based on what? A provider reference? A merchant reference? An amount and timestamp? What if the provider settles a transaction in several parts? What if its settlement currency differs from the transaction currency? How are fees represented? How are refunds, reversals, and chargebacks connected to the original payment? When does a difference become a discrepancy? Which record is authoritative when the provider report and the internal ledger disagree?

The statement "the amounts should match" is not a specification. The system needs an invariant such as:

Provider gross amount, minus provider fees, refunds, and chargebacks, plus or minus authorised adjustments, must equal the expected net settlement amount for the defined settlement period.

Even that rule is only the beginning. Every term requires a precise definition, currency treatment, rounding policy, source of authority, and time boundary.

This is where the distinction between a prompt and a specification becomes impossible to ignore. A prompt might tell an agent to add smart payment routing. A specification must define:

Eligible providers
Provider capabilities
Health signals
Performance windows
Routing priorities
Retryable outcomes
Terminal outcomes
Cost limits
Regional restrictions
Currency requirements
Idempotency guarantees
Approval thresholds
Rollout controls
Audit records
Fallback behaviour

Without those definitions, "smart" merely means the agent is free to invent the policy. That is not intelligence; it is uncontrolled discretion.

8. Matching Specification Depth to Consequence Level

TalonHR and Tinker Payments demonstrate why specifications should be proportional to risk.

In TalonHR, a poorly defined workflow may send an incorrect notification, reveal information to the wrong participant, or move a candidate into the wrong state. These can be serious failures, particularly where privacy, fairness, and employment decisions are involved.

In Tinker Payments, a poorly defined workflow may duplicate a charge, misstate a merchant balance, route a transaction through an unsuitable provider, or leave finance teams unable to reconcile the movement of funds.

Both systems need specifications, but they do not always need the same depth:

Low Consequence

Examples: Changing UI text, adjusting visual layout, reordering non-critical information, generating an internal summary.
Specification needs: Intended outcome, design constraints, and basic acceptance tests.

Medium Consequence

Examples: Moving a candidate through a workflow, sending applicant notifications, changing interview availability, updating merchant configuration, modifying a non-financial operational record.
Specification needs: Explicit permissions, state transitions, side effects, validation rules, audit history, failure behaviour, and integration tests.

High Consequence

Examples: Exposing or deleting personal data, making automated candidate recommendations, retrying a payment, posting to a ledger, changing balances, routing money across providers, reconciling settlements.
Specification needs: Formal invariants, explicit authority boundaries, idempotency rules, immutable decision history, approval and escalation paths, policy enforcement outside the model, rollback or compensation behaviour, adversarial/failure testing, and complete provenance of the agent's action.

The important distinction is not whether AI was used; it is what authority the system gave the AI and what could happen if its interpretation was wrong.

9. Tests Are Necessary, but They Are Not the Whole Specification

It is tempting to say that automated tests already solve this problem. They do not.

Tests are powerful because they provide executable evidence that particular behaviours work. Coding agents benefit enormously from them because they can write code, execute tests, and iterate using the results. However, a test suite normally checks selected examples; it does not necessarily explain the underlying rule.

A test may confirm that a refund of $500 is automatically approved and a refund of $1,500 requires review. It may not explain:

Whether the threshold is inclusive.
Whether the amount is calculated before or after fees.
Whether the threshold changes by currency.
Whether certain customer groups are exempt.
Whether the policy was introduced as a temporary operational measure.

Tests can also preserve the wrong behaviour. A test written around an old bug becomes an obstacle if nobody knows whether the behaviour is intentional. An agent attempting to satisfy every existing test may reproduce historical accidents rather than implement the current business policy.

The strongest system therefore combines several forms of specification:

Prose for goals and rationale
Schemas for data constraints
Contracts for interfaces
Policies for permissions and operational rules
State machines for workflow transitions
Tests for observable examples
Invariants for conditions that must always remain true

No single artefact is sufficient. Together, they create a system that both humans and machines can reason about.

10. Specifications Must Include What Must Not Happen

Traditional requirements tend to focus on desired capabilities:

The system should allow the user to do this.
The service should send that.
The administrator should be able to change something.

Autonomous agents require equally explicit negative boundaries:

The agent must not reveal whether an email address exists.
The agent must not change a public API response without a migration plan.
The agent must not allow a refund to exceed the captured payment.
The agent must not modify production infrastructure from an unapproved environment.
The agent must not send customer communication before the transaction commits.
The agent must not infer permission from a person's job title.

These are not implementation details; they are system constraints.

This is especially important because an agent is usually rewarded for completing a task. If the shortest path to completion violates an unstated organisational rule, the model cannot be expected to respect a rule it was never given.

Guardrails included in a prompt are helpful, but critical restrictions should not depend only on model obedience. Where possible, they should be enforced outside the model through permissions, schemas, policy engines, isolated environments, approval gates, and runtime validation.

A rule written only in natural language asks the agent to behave; a rule enforced by the system limits what the agent can do. That is a far stronger guarantee.

11. The Specification Is the Product's Institutional Memory

Building TalonHR and Tinker Payments has made one organisational problem clear: a product's true behaviour is often known only by the people who built it.

An engineer knows why a particular payment result must never be retried.
A product manager remembers why candidates cannot see a particular status.
A finance operator knows that one provider's settlement report uses a different date boundary.
A recruiter understands that two pipeline stages which appear similar represent completely different decisions.

As long as these rules remain in people's heads, an AI agent cannot reliably use them. Neither can a new human engineer.

The specification therefore serves two purposes: it tells the agent what to build, and it prevents the organisation from forgetting why the system works the way it does.

For TalonHR, this means defining the meaning of roles, applications, stages, permissions, communications, and privacy transitions.
For Tinker Payments, it means defining the meaning of payment attempts, authorisations, failures, retries, balances, settlements, and discrepancies.

The more authority we give agents, the less acceptable it becomes for these definitions to remain implicit. Code shows what the system currently does; a specification records what the system is supposed to do. The difference matters whenever the two disagree.

12. Specification Quality Is Becoming a Competitive Advantage

AI coding tools are becoming broadly available. A capable model will not remain an exclusive advantage for one company—competitors can access similar models, development environments, and agent frameworks.

The lasting advantage will come from what an organisation can give the agent. A company with clean domain models, current documentation, explicit business rules, reliable test suites, and versioned policies can delegate meaningful work. A company whose logic exists mainly in meetings and individual memory will spend its time correcting confident misunderstandings.

This means technical debt is no longer limited to bad code:

Undocumented business logic is agent debt.
Contradictory documentation is agent debt.
Missing acceptance criteria are agent debt.
Unclear ownership is agent debt.
Tests that cannot distinguish intentional behaviour from historical accident are agent debt.

The organisations that address these problems will not merely generate code faster; they will be able to give agents larger scopes of responsibility without losing control. That is the real value. The goal is not to produce more code; the goal is to safely increase the size of the outcome that can be delegated.

13. Product Managers Will Not Become Prompt Engineers

There is a popular prediction that product managers and software engineers will become "prompt engineers." That framing is too narrow. Prompting is an interaction technique; it does not replace product reasoning, requirements analysis, or system design.

The more important role will be specification engineering. A specification engineer does not necessarily write formal mathematical proofs. Their role is to take an intention and progressively remove dangerous ambiguity from it. They ask:

What outcome are we trying to create?
Which behaviours are mandatory?
Which decisions remain open?
What assumptions are being made?
What states can the system enter?
Which transitions are valid?
What must never happen?
How will we verify the result?
Which existing contracts must remain stable?
When should the agent stop and ask a human?

This work cannot be reduced to "write a better prompt." It requires product knowledge, technical understanding, risk awareness, and the ability to translate between human goals and machine-verifiable behaviour.

In many organisations, senior engineers already do this informally. They take a vague ticket, reconstruct the real requirement, identify hidden constraints, and decide what a correct implementation would mean. AI makes this work visible. When code generation becomes cheaper, precise decision-making becomes more valuable.

14. The Agent Should Be Allowed to Challenge the Specification

Executable specifications do not need to be perfect before an agent sees them. In fact, agents can help improve them.

A requirement-review agent can examine a proposed change against the codebase, existing contracts, and previous architectural decisions. It can identify missing error states, incompatible assumptions, incomplete migrations, and unaddressed security concerns.

Before asking the agent to implement the specification, ask it to attack it:

What is missing?
Which statements are ambiguous?
Which requirements conflict with the existing architecture?
Which failure states have not been considered?
Which acceptance criteria permit several incompatible implementations?
What security or operational assumptions remain hidden?

The agent can generate questions, but a human remains responsible for answering those that involve business judgement. The process becomes:

Intent
  ↓
Draft Specification
  ↓
Agent Critique
  ↓
Human Decisions
  ↓
Executable Contracts & Tests
  ↓
Implementation
  ↓
Verification

This is safer than giving an agent a rough ticket and hoping code review catches everything.

15. The Requirements Document Does Not Literally Disappear

The title of this article is deliberately provocative. Requirements documents will not vanish. People still need narratives:

Executives need to understand why an investment matters.
Product teams need to explain customer problems.
Designers need context.
Engineers need rationale.
Regulators and auditors may require readable documentation.

Natural language remains the best medium for many forms of human communication. What dies is the assumption that prose alone can be the authoritative definition of a software system.

A document can describe the business objective, but it should not be the only place where critical behaviour is defined. The future requirements package will contain two complementary layers:

The Human Layer

Contains the problem, intended outcome, user context, business rationale, trade-offs, unresolved decisions, and explanations of why constraints exist.

The Machine-Verifiable Layer

Contains interfaces, schemas, invariants, states, policies, examples, tests, evaluation criteria, and operational limits.

The human layer gives the work meaning; the machine-verifiable layer gives it precision. Neither replaces the other.

16. A Practical Specification Stack

Teams do not need to introduce formal methods across every project tomorrow. They can begin with a simple hierarchy:

Intent: Explain the user problem, business objective, and desired outcome in plain language.
Definitions: Define domain terms that could otherwise be interpreted differently.
Behaviour: Describe the main workflow, alternative paths, and expected outcomes.
State: List the relevant states and permitted transitions between them.
Contracts: Define APIs, events, input formats, output formats, and compatibility requirements.
Invariants: State what must always remain true, regardless of implementation.
Prohibitions: State what the system and agent must never do.
Failure modes: Define expected behaviour when dependencies fail, data is invalid, or operations are repeated.
Verification: Provide acceptance tests, properties, evaluation criteria, and observability requirements.
Authority: Define which artefacts take precedence and when the agent must escalate a conflict.

This stack can be lightweight for a small internal feature and rigorous for a payment, identity, or security workflow. The level of specification should match the consequence of failure. A formatting change does not need the same treatment as moving money, exposing personal information, or altering access permissions.

17. From Code Review to Decision Review

As agents write a larger share of implementation code, code review itself will change. Today, reviewers often spend their attention on naming, syntax, framework conventions, duplicated logic, implementation structure, and obvious defects. Many of these checks can be automated.

The higher-value review will happen earlier:

Did we choose the correct behaviour?
Did we identify the important states?
Did we define the security boundary?
Does the specification preserve existing contracts?
Are the tests proving the intended policy or merely one implementation?
What assumptions did the agent make?

This is a shift from reviewing how the agent wrote the code to reviewing why the system is supposed to behave that way. The implementation remains important, but critical decisions increasingly move upstream.

When an agent changes a live system, the organisation should be able to reconstruct the instruction it received, the specification it followed, the context it used, the assumptions it made, the tests it executed, the approvals it obtained, and the resulting change. Without that chain, an organisation may know what changed without being able to explain why.

18. The Scarce Resource Is No Longer Code

For most of software history, implementation capacity was scarce. Businesses had more ideas than engineers available to build them. Requirements could remain imperfect because skilled developers were responsible for translating them into functioning systems.

AI is reducing the cost of implementation, but it is not reducing the cost of deciding what should be implemented. That decision still requires knowledge of customers, operations, regulation, economics, risk, and the existing system.

As code becomes easier to generate, unclear thinking becomes easier to expose. A vague requirement that once produced several days of meetings may now produce a complete pull request in an hour. The speed feels productive until the team discovers that it automated the wrong interpretation.

The bottleneck moves:

From typing code to defining truth.
From implementation capacity to decision quality.
From instructions to constraints.
From documentation as explanation to specification as infrastructure.

19. The Future Belongs to Teams That Can State What They Mean

The rise of AI agents will not eliminate software engineering discipline; it will punish the absence of it.

Building TalonHR has shown me how much complexity can hide behind words such as candidate, stage, approval, and notification. Building Tinker Payments has shown me how much financial risk can hide behind words such as failure, retry, balance, and reconciliation. None of these terms is useful to an autonomous agent until the organisation defines exactly what it means.

Agents will make disciplined teams faster because their knowledge can be consumed, checked, and executed. They will make undisciplined teams chaotic because uncertainty can now be converted into software at unprecedented speed.

The companies that succeed will not simply have access to the best models. They will have systems that can tell those models:

What is true
What is allowed
What is expected
What is forbidden
How success is measured
When a human decision is required

The requirements document was designed for a world in which humans carried meaning from prose into code. That world is changing.

The next generation of software development will still begin with human intent. But before that intent is handed to an autonomous agent, it must become something stronger than a document: it must become a specification that can be reviewed, versioned, tested, and enforced.

Because when implementation is automated, ambiguity is no longer merely a communication problem. It becomes executable.

I have seen that ambiguity move candidates. I have seen it route payments. The next challenge is making sure it never makes those decisions without rules we can inspect, test, and defend.

Share this writing

Twitter LinkedIn

Why AI Agents Need Executable Specifications, Not Better Prompts

The Death of the Software Requirements Document