Preparing Specs for AI Coding Agents - Forkline Blog<br>Back to blog<br>AI coding agents now edit repositories, run commands, and produce branches. That makes the spec before the work more important: it carries the context, boundaries, and success criteria the agent needs.

What a good coding-agent spec includes

Specs are becoming more important because AI coding agents are no longer only answering questions. They<br>are reading repositories, editing files, running commands, producing branches, and asking humans to review<br>the result. That changes what a prompt needs to become.

When an assistant only answers a question, a private prompt can be enough. When an agent changes a shared<br>codebase, the prompt becomes an assignment. And an assignment needs more than good wording. It needs the<br>right context, boundaries, examples, and a way to judge whether the work matched the original intent.

That is the practical reason to prepare a spec before sending a coding agent into a repository. The spec<br>does not need to be long. It does need to tell the agent what problem it is solving, what behavior should<br>change, what must not change, and how the result will be reviewed.

At minimum, a good coding-agent spec should give the agent five things:

the context behind the task

the behavior that should change

the constraints the agent should preserve

examples or scenarios that define correctness

the validation evidence a reviewer should inspect

This is the useful idea behind spec-driven development, behavior scenarios, issue templates, lightweight<br>design docs, OpenSpec, GitHub Spec Kit, and many internal engineering proposal formats. The specific<br>framework matters less than the shape of the spec: the agent should receive enough context to act, and the<br>team should receive enough structure to review the result.

The spec is not a nicer prompt. It is the prepared assignment between human intent and machine execution.

Prompts are good at starting work. Specs are better at carrying it.

A private prompt is optimized for immediacy. It lives in a chat session. It can include shorthand, missing<br>context, and assumptions the author understands but nobody else sees.

That can work for a local explanation or a throwaway script. It is weaker for team engineering work.

The problem is not that prompts are informal. Informality is often useful. The problem is that private<br>prompts usually disappear from the workflow after the agent starts. They do not naturally become review<br>criteria. They are hard to compare against a pull request. They do not help the next person understand why<br>the change exists.

Specs solve a different problem. They give the assignment a visible shape the team can keep inspecting.

That spec can live in different places. It can be a repo-local spec, an issue with acceptance criteria, a<br>BDD scenario, a small design note, a change proposal, or a pull request description that names the behavior<br>being changed. OpenSpec is one useful implementation of this pattern, but it is not the only one. GitHub<br>Spec Kit, Gherkin-style scenarios, team RFC templates, and ordinary issue templates can all carry the same<br>discipline when they make context and review criteria explicit.

That is the shift teams should care about. A good spec does not merely instruct the agent. It gives humans<br>and agents something shared to inspect before, during, and after implementation.

FIG 01 Assignment shape<br>Private prompt<br>fix thismake it cleanerprobably auth?you know what I mean<br>Useful for starting thought, weak as a shared review object.

Team-visible spec<br>proposal

spec delta

design notes

tasks

review criteria

Visible before implementation, useful during review, durable after the session ends.

Private prompts are fast but unstable. Team-visible specs give the assignment a structure reviewers can inspect later.

The assignment layer separates intent from execution

The strongest specs behave like small behavior contracts. Requirements say what the system should do.<br>Scenarios give concrete examples, often in a Given/When/Then style. Design notes and task lists can<br>describe the technical approach and implementation checklist, but those are not the same thing as the<br>requirement.

This separation is one of the most useful disciplines for AI-assisted engineering.

If the intent and implementation are mixed together too early, the agent can optimize for the wrong<br>thing. It may faithfully follow a suggested implementation detail while missing the behavior the team<br>actually needed. Or it may produce a plausible design that is hard to review because the success criteria<br>were never made explicit.

An assignment layer keeps three questions apart:

What behavior should change?

What constraints or examples define correctness?

What implementation path seems appropriate right now?

Those questions are connected, but they should not collapse into one blob of instructions. The<br>implementation can evolve as the agent reads the codebase. The requirement should remain...