How to give an AI coding agent a specification it can execute

AI coding agents are good at carrying out a sequence of concrete actions. They are much less reliable when the request is a cloud of unstated expectations: “make onboarding better,” “clean up the dashboard,” or “add the usual validation.” The missing ingredient is usually not a stronger prompt. It is a shared specification that tells the agent what success means.

Microsoft describes spec-driven development as an AI-native process built around a living specification. The specification captures business intent and acceptance criteria before implementation, stays version-controlled, and evolves with the code and tests. That gives an agent a stable target and gives humans something more useful to review than a long diff.

Here is a small workflow you can use with Claude Code, Codex, Copilot, or another coding agent.

1. Write the outcome before the implementation

Start with the user and the observable result. Name who needs the change, what they are trying to do, and what should be different when it works. Avoid prescribing files or libraries until the behavior is clear.

For example:

Goal: A signed-in learner can resume the lesson they started most recently.

User-visible behavior:
- The dashboard shows the most recently started lesson.
- Selecting it opens the lesson at the next incomplete step.
- A learner with no progress sees the existing “Start learning” action.

This is deliberately boring. Boring language reduces the number of decisions the agent has to guess.

2. Turn expectations into acceptance criteria

Add the cases that would make the feature incomplete or unsafe. Write them as checks that a person or a test can verify. Include the normal path, empty states, invalid input, permissions, and failure behavior.

Acceptance criteria:
- A learner sees only their own progress.
- Missing progress does not cause a request or render error.
- A completed lesson points to the next lesson, or to the completion state.
- The existing dashboard remains unchanged for signed-out visitors.
- Automated tests cover the resume, empty, and unauthorized cases.

Microsoft’s account of SDD emphasizes business goals, user requirements, edge cases, and acceptance tests as inputs to the specification. The point is not to predict every line of code. It is to make the important outcomes explicit before the agent starts editing.

3. Ask the agent to inspect and plan

Give the agent the specification and ask it to map the current codebase before making changes. Request the relevant routes, components, data access, tests, and constraints it found. Then ask for a short implementation plan and a list of uncertainties.

Do not treat the first plan as permission to change everything it mentions. Review whether the proposed files really own the behavior and whether the plan preserves existing contracts. If the agent cannot explain where the current behavior lives, the specification is not ready for implementation yet.

4. Make the specification executable

Put the specification near the project’s source of truth: a version-controlled feature document, issue, or repository instruction that your team actually updates. Link each acceptance criterion to a test, a manual check, or both. Ask the agent to implement in small slices and to run the relevant checks after each slice.

A useful completion report has four parts: files changed, acceptance criteria satisfied, commands run with their results, and remaining risks. This turns “the agent says it is done” into evidence you can inspect.

5. Keep human review at the decision points

A specification improves autonomy; it does not remove responsibility. VS Code’s agent guidance describes agents as systems that gather context, plan, edit files, run commands, and iterate while the developer reviews actions and chooses which changes to keep. Its trust-and-safety guidance recommends reviewing generated code before committing, testing security- and data-sensitive logic, and treating files, tool output, and web pages as possible prompt-injection sources.

Use that guidance to define explicit stop points:

• approve the specification before implementation;
• inspect the plan before broad edits;
• review changes before committing;
• verify tests and important user flows;
• confirm that network access, secrets, and external-service actions were within scope.

6. Update the spec when reality changes

The document is not a disposable prompt. If an edge case changes, a test reveals a new rule, or the product decision shifts, update the specification and then ask the agent to reconcile the implementation with it. This prevents the code, tests, and team memory from drifting apart.

The larger lesson is simple: agent speed magnifies the quality of the direction it receives. A living specification gives the agent context, gives reviewers a checklist, and gives the team a durable record of why the code behaves the way it does. You do not need a heavyweight process to start. Pick one small feature, write its goal and acceptance criteria, and require evidence for each criterion before you call the work finished.