What is a technical spec?

A technical spec is an engineering artifact that defines the system behavior, constraints, acceptance criteria, and verification plan for a change. It turns product intent into implementation agreement.

How is a spec different from a PRD?

A PRD aligns teams on what to build, for whom, and why. A spec aligns implementers on how the approved change should work inside the system and how completion will be verified.

How detailed should a spec be for an AI coding agent?

Detailed enough that the agent does not need to invent product policy, scope boundaries, examples, or done criteria. The spec should name relevant files or patterns, non-goals, acceptance examples, and verification commands.

Should a spec include implementation details?

Yes when the detail is a contract, constraint, migration requirement, security rule, compatibility concern, or verification need. No when the detail is imaginary code that the codebase should decide locally.

Do small changes need specs?

Small changes need proportional specs. A copy tweak might need only a ticket and acceptance check. A small permission or data change may need a compact spec because the risk is high.

What makes a spec AI-executable?

An AI-executable spec includes local context, explicit scope fences, concrete examples, non-goals, implementation constraints, done criteria, and reporting expectations.

Can a spec have open questions?

Yes. A good spec surfaces open questions with owners and impact. The failure is not uncertainty; the failure is hiding uncertainty inside implementation.

What should acceptance criteria look like?

Acceptance criteria should be observable and testable. Given/When/Then examples are useful because they force the writer to state starting state, action, and expected result.

Can I use a technical spec generator?

Yes, if you treat the generated spec as a structured draft rather than a final decision. A generator can enforce sections, but humans still own product policy, architecture choices, and verification.

How do I review a spec for ambiguity?

Look for vague words, missing current behavior, untestable requirements, weak non-goals, missing edge cases, and verification that another reviewer could not repeat.

Expanded guidance

What is the minimum viable spec?

The minimum viable spec includes a goal, non-goals, current behavior, proposed behavior, acceptance criteria, and verification. For an AI coding agent, add working directory, relevant files, constraints, stop conditions, and final-report requirements.

How do I avoid over-specification?

Specify obligations and constraints, not every line of future code. If a detail is necessary for correctness, compatibility, security, performance, migration, or review, include it. If the codebase's existing pattern should decide it, point to the pattern instead of inventing new structure.

How do I avoid under-specification?

Look for places where the implementer would have to ask "which one?" Which user? Which data? Which state? Which failure mode? Which files? Which tests? Which behavior is out of scope? Every unanswered "which" is likely hidden ambiguity.

For a quick pass, use the Ambiguity Checker. For a broader review, use the Spec Review Checklist.

Source-backed rules of thumb

  • Use requirements standards as a quality checklist, not as a bureaucratic costume.
  • Use PRD guidance for product alignment and spec guidance for implementation alignment.
  • Use persistent agent instruction files for standing repo rules and task specs for change-specific decisions.
  • Use examples when prose can be interpreted more than one way.