Executable specs for coding agents are specifications that already include acceptance criteria, file boundaries, verification commands, and stop rules. They do not try to persuade the agent with more prose. They create a contract that Codex, Claude Code, subagents, and CI can execute, fail, and repeat.

In 2026, GitLab reported that 85% of respondents agree AI shifted the bottleneck from writing code to reviewing and validating it (GitLab, "AI Accountability Report", 2026, retrieved 2026-07-07). The practical answer is not longer prompts. It is specs that become proof.

Practical summary

  • An agent follows better when the spec defines acceptance, scope, and tests.
  • The issue should point to files, risks, commands, and expected evidence.
  • CI needs to enforce the spec, not only run the generic suite.
  • Subagents help when each one validates a small part of the contract.

Abstract diagram showing a specification becoming a validated coding agent flow without visible text.

Why did executable specs become urgent?

In 2026, GitLab also reported that 82% see AI-generated code as a new kind of technical debt their organization is not ready to manage (GitLab, "AI Accountability Report", 2026, retrieved 2026-07-07). Executable specs became urgent because the cost moved from creation to verification.

The common mistake is treating an issue like a conversation. A conversation allows ambiguity, assumptions, and after-the-fact justification. The agent fills gaps with repository patterns, and that can work for small tasks. In real work, the gap becomes scope drift.

An executable spec changes the request shape. It says what behavior must change, where the agent should look, which commands must pass, and what risk requires a stop. The agent can still be wrong. The difference is that the error leaves verifiable evidence.

This complements the article on PR evals for agents in CI. The eval measures the change afterward. The executable spec defines, before the first edit, what evidence will count as success.

Citation capsule: Executable specs reduce agent-created technical debt by replacing loose intent with a verifiable contract. GitLab reported 82% concern about AI-generated technical debt; each delegated task therefore needs acceptance, scope, command, and evidence before the patch.

What belongs in a spec for Codex or Claude Code?

In 2025, DORA found that 90% of technology professionals already use AI at work, and more than 80% believe it increased their productivity (DORA, "Balancing AI tensions", 2026, retrieved 2026-07-07). That adoption becomes sustainable delivery only when the spec describes the system, not just the wish.

The minimum structure has six parts. First, expected behavior in testable language. Second, likely files or modules. Third, required commands. Fourth, risks and limits. Fifth, evidence that must appear in the PR. Sixth, stop rules when proof fails.

Addy Osmani frames the same pattern as six core areas: commands, testing, project structure, code style, git workflow, and boundaries (Addy Osmani, "How to write a good spec for AI agents", 2026, retrieved 2026-07-07). I add one operational detail: each area needs to become something CI or a reviewer can deny.

goal: "fix expired session renewal"
acceptance:
  - "revoked token does not renew a session"
  - "valid token preserves current behavior"
likely_files:
  - "src/auth/session.service.ts"
  - "tests/auth/session-renewal.spec.ts"
required_commands:
  - "npm run test -- session-renewal"
  - "npm run typecheck"
limits:
  - "do not change database schema without migration"
  - "do not relax expiration rules"
pr_evidence:
  - "test that failed before"
  - "required command output"
stop_if:
  - "failure requires secret access"
  - "fix touches auth outside the module"

Citation capsule: A good spec for Codex or Claude Code must cover behavior, context, command, limit, and evidence. DORA measured AI adoption by 90% of professionals; without an executable contract, that adoption amplifies both productivity and operational fragility.

How do specs, TDD, and CI connect without ceremony?

In 2026, GitHub said Copilot code review had processed more than 60 million reviews and that more than one in five reviews on GitHub involve an agent (GitHub, "Agent pull requests are everywhere. Here's how to review them", 2026, retrieved 2026-07-07). TDD with agents needs to fit that volume.

Start small: turn each acceptance criterion into at least one check. It can be a unit test, API contract, visual snapshot, reversible migration, typecheck, or lint script. The rule is simple: if the criterion cannot be tested, it needs to be rewritten.

Abstract loop showing specification, implementation, validation, and feedback without any visible text.

Do not ask the agent only to "create tests". Ask it to create the test that fails before the fix, run the test, apply the patch, and repeat verification. When the agent cannot show the initial failure, it should explain why that criterion needs another kind of proof.

OpenAI describes the Codex loop as a sequence where the model decides, uses tools, observes the result, and tries again until completion (OpenAI, "Unrolling the Codex agent loop", 2026, retrieved 2026-07-07). The executable spec gives the loop a smaller objective function: pass the right contracts, not please the prompt.

Practical experience: when I let an agent touch backend code, the first file I want to see in the diff is a test, contract, or fixture. If the first diff is broad implementation without proof, I stop the loop and ask for a smaller spec.

Citation capsule: TDD with an agent works best when the spec becomes a CI checklist. GitHub reported more than 60 million Copilot code reviews; at that volume, reviewers need reproducible failure, a new test, and executed commands, not persuasive summaries.

Where does context fit without wasting tokens?

In 2026, OpenAI wrote that Codex runs can work for more than six hours on a single task and that context is one of the biggest challenges in large tasks (OpenAI, "Harness engineering: leveraging Codex in an agent-first world", 2026, retrieved 2026-07-07). Executable specs are also context economy.

A bad spec pastes whole documents into the prompt. A good spec points to paths. It says which file indexes architecture, which contract is canonical, which test represents behavior, and which directory is off limits. The agent reads on demand.

This is the same principle as context engineering for coding agents: map first, detail later. When a flow involves Claude Code and Codex across many steps, I use RemoteCode to preserve context continuity in agentic flows without dumping the whole history into the main prompt; it is my own tool, so this mention is editorial and tied to context cost.

The spec should also constrain MCP. If the agent needs to read a ticket, log, or live documentation, record which MCP server may be used and which actions remain blocked. External context helps investigation, but it should not authorize writes, shell, or network by itself.

Citation capsule: Executable specs save context because they point to canonical sources instead of loading everything. OpenAI described long Codex runs and treated context as a central challenge; the spec should act as a map, with progressive reading and explicit limits.

How can subagents validate a spec without creating noise?

In 2025, the study "What Makes a GitHub Issue Ready for Copilot?" analyzed 3,180 PRs associated with issues and proposed 32 criteria to measure issue readiness for agents (arXiv, "What Makes a GitHub Issue Ready for Copilot?", 2025, retrieved 2026-07-07). Subagents work best when each criterion becomes a narrow review.

One subagent can validate tests. Another can inspect the security boundary. Another can compare the diff with target files. Another can check migration risk. The main agent does not need full logs; it needs finding, severity, proof, and action.

OpenAI documents that Codex only creates subagents when you explicitly ask and consolidates results when all finish (OpenAI Developers, "Subagents", 2026, retrieved 2026-07-07). That favors read fan-out and decision merge, not several authors editing the same module.

Abstract matrix showing acceptance, risk, and evidence signals for subagent review without visible text.

Use a short, standard return format:

area: tests
status: block
file: tests/auth/session-renewal.spec.ts
proof: no case for revoked token
action: create negative case before changing implementation

Citation capsule: Subagents are useful when the spec separates verifiable criteria. The study on Copilot-ready issues evaluated 32 criteria across 3,180 PRs; in practice, each subagent should validate one slice of the contract and return concise proof.

What is the minimum viable setup this week?

In 2026, GitLab reported that only 28% say their SDLC tools are fully integrated with shared data and workflows (GitLab, "AI Accountability Report", 2026, retrieved 2026-07-07). The minimum viable setup must fit the repository you already have.

Create an issue template named agent-task.yml. It should require expected behavior, likely files, commands, risks, and PR evidence. If the team uses AGENTS.md, put the rule there that agents do not start implementation without those fields.

Then create a small script, such as scripts/check-agent-spec.mjs, to validate field presence and block PRs without evidence. Do not automate the whole judgment on day one. First block the worst case: an agent working on an ambiguous task without test, scope, or proof.

Finally, connect it to the PR. The PR body must show executed commands, new test, residual risk, and any spec deviation. If the agent changed the scope, the PR should request human review before continuing.

Spec field Enforced by Blocks when
Acceptance criterion Test or reviewer No executed proof exists.
Likely files Diff script Patch touches a boundary without justification.
Commands CI Command fails or was not run.
Risk Code owner Sensitive area changes without review.
Evidence PR template Summary lacks verifiable output.

Citation capsule: The minimum viable setup is an issue template, a field checker, and a PR template with evidence. Because only 28% report fully integrated SDLC tools, executable specs should start as simple files and evolve into gates.

Frequently asked questions about executable specs

Does an executable spec replace product or architecture?

No. In 2026, GitLab reported that 85% see review and validation as the bottleneck, and that includes human judgment. The executable spec removes repeatable ambiguity, but product, architecture, and business risk still require accountable people.

Does every agent task need formal TDD?

No. In 2026, GitHub reported more than one in five reviews involve an agent, so the process must be proportional. Bugs and business rules need a test that fails first. Refactors can use typecheck, snapshot, contract comparison, or diff analysis.

Should the spec live in the prompt, issue, or repository?

Use all three in layers. In 2026, OpenAI recommends that Codex receive tests, checks, and review as part of what "good" means. The issue defines the task; the repository stores stable rules; the prompt points only to the necessary slice.

How do you measure whether the spec improved the agent?

Measure rework. In 2025, the Copilot-ready issue study used 3,180 PRs and associated well-scoped issues with a higher chance of merge. In your team, compare reopened PRs, repeated comments, post-merge failures, and time to sufficient proof.

Closing

Executable specs are the antidote to loose requirements in agentic workflows. They do not make the agent "smarter". They make the work smaller, verifiable, and enforceable. That is software engineering applied to agents.

Start with the next issue. Write acceptance, likely files, commands, limits, and evidence. Ask the agent to prove before it explains. If proof fails, the spec did its job: it prevented a polished narrative from becoming quiet debt.

Sources consulted

  • GitLab, "AI Accountability Report", retrieved 2026-07-07, https://ir.gitlab.com/news/news-details/2026/GitLab-Research-Reveals-Organizations-Are-Generating-AI-Code-Faster-Than-They-Can-Control-It/default.aspx
  • DORA, "Balancing AI tensions: Moving from AI adoption to effective SDLC use", retrieved 2026-07-07, https://dora.dev/insights/balancing-ai-tensions/
  • GitHub, "Agent pull requests are everywhere. Here's how to review them", retrieved 2026-07-07, https://github.blog/ai-and-ml/generative-ai/agent-pull-requests-are-everywhere-heres-how-to-review-them/
  • OpenAI, "Unrolling the Codex agent loop", retrieved 2026-07-07, https://openai.com/index/unrolling-the-codex-agent-loop/
  • OpenAI, "Harness engineering: leveraging Codex in an agent-first world", retrieved 2026-07-07, https://openai.com/index/harness-engineering/
  • OpenAI Developers, "Subagents", retrieved 2026-07-07, https://developers.openai.com/codex/subagents
  • OpenAI Developers, "Best practices", retrieved 2026-07-07, https://developers.openai.com/codex/learn/best-practices
  • Addy Osmani, "How to write a good spec for AI agents", retrieved 2026-07-07, https://addyosmani.com/blog/good-spec/
  • arXiv, "What Makes a GitHub Issue Ready for Copilot?", retrieved 2026-07-07, https://arxiv.org/html/2512.21426v1