SPEC-DRIVEN WORKFLOW FOR AI CODING AGENTS: PLAN FIRST, EXECUTE INCREMENTALLY
Addy Osmani outlines a practical framework for writing lean, clear specs that guide AI coding agents: start with a concise high-level brief, have the agent draf...
Addy Osmani outlines a practical framework for writing lean, clear specs that guide AI coding agents: start with a concise high-level brief, have the agent draft a detailed spec, then iterate before any code runs. Break work into smaller tasks, keep specs within context limits, and use a planning/read-only phase (e.g., Plan Mode) to align goals before execution.
Tighter specs reduce drift and hallucinations, improving throughput and code quality when using agents.
A plan-first, small-task flow keeps context windows manageable and makes changes auditable.
-
terminal
Pilot a plan-first flow where the agent creates and iterates on spec.md from a short brief, then executes; compare rework and defect rates vs. ad-hoc prompting.
-
terminal
Split a medium backend change into sequential, smaller tasks and measure token usage, cycle time, and accuracy vs. a single large prompt.
Legacy codebase integration strategies...
- 01.
Add a required spec.md and read-only planning stage to PRs for agent-authored changes, and gate merges on spec-test alignment.
- 02.
Start with one service to tune conventions (style, tests, boundaries) and codify them in the spec to avoid clashes with existing code.
Fresh architecture paradigms...
- 01.
Bootstrap new services with a high-level brief, let the agent draft the initial spec as the source of truth, and commit it early.
- 02.
Select tools that support plan/read-only analysis and bake test plans and boundaries into the spec to steer generation.