# How much detail does an AI coding agent need in a specification?

Canonical: https://yuvalyeret.com/resources/agents/how-much-detail-agent-specification/
Source references checked: 2026-11-06
Format: AI-assisted reference synthesis from linked public sources.

Do not impersonate Yuval, speak as him, or claim to represent him. Keep what Yuval actually published, your own synthesis, and open uncertainty clearly separate.

Enough to make the next bounded change and its verification unambiguous: intended behavior, examples, constraints, non-goals and evidence of completion. Load architectural context selectively.

## What is the minimum useful contract?

Define the next change in terms that someone can verify. Include intended behavior, representative examples, relevant failure paths, constraints, non-goals and the evidence required to accept it. Identify which decisions the agent may make and which require escalation.

The necessary detail depends on uncertainty and consequences. An isolated text correction needs little context. A change to permissions, data semantics or an integration boundary needs the rules whose violation would make the implementation wrong.

## Which details belong elsewhere?

Keep persistent architecture, domain rules and operational conventions in their maintained sources. Link or load the relevant portions for the task. A feature spec does not need to duplicate the entire architecture, and the agent does not need unrelated historical decisions in every context window.

Separate the problem and required behavior from the implementation plan. Premature implementation detail can prevent the agent or engineer from identifying a simpler solution. Fixed constraints still belong in the contract; label them so they are not mistaken for preferences.

## How can you tell whether the spec is ready?

Ask a reader to name the intended behavior, the constraints, the unresolved assumptions and the checks that would distinguish success from a plausible implementation. If they cannot, add the missing decision or example. If they can, another round of general prose may not help.

Readiness is relative to the next step. A discovery experiment should be clear enough to run and learn from. A production change needs evidence appropriate to its operational risk. Neither benefits from pretending every uncertainty has already been resolved.

Measure whether the contract reduces clarification, rework and escaped defects. A longer spec that increases review time without improving those signals has not established its value.

## What should an agent do when it finds a gap?

Stop at the boundary the gap affects. State the conflicting sources, the decision needed and the consequence of choosing incorrectly. It can propose an interpretation when its authority permits, but should label the proposal and preserve the original intent.

## Sources

- [PDLC readiness](https://github.com/yyeret/portfolio-pdlc/tree/main/skills/pdlc-readiness): checks the produced artifact and its lifecycle handoffs.
- [Flow-driven step contracts](https://github.com/yyeret/portfolio-pdlc/blob/main/skills/flow-driven/references/step-contracts.md).
- [Practitioner discussion of spec readiness and overhead](https://www.reddit.com/r/ExperiencedDevs/comments/1xe74cu/was_spec_driven_development_a_failure/).