When we first started building with AI agents, we did what everyone did — we wrote prompts. Long, detailed, carefully worded prompts. And they worked... sometimes.
The fundamental problem with prompt-driven agent workflows isn't the prompts themselves. It's the assumption that natural language alone can carry the full weight of engineering intent.
The Spec Layer
A spec is not a prompt. A spec is a structured declaration of intent that includes:
- Goal: What the agent should accomplish
- Constraints: What the agent must not do
- Context: What the agent needs to know
- Verification: How we know the agent succeeded
This distinction matters because it separates what from how. The agent decides how. You decide what.
Results in Practice
After migrating 23 internal workflows from prompt-based to spec-based architecture:
- Task completion rate: 41% → 94%
- Error recovery rate: 12% → 78%
- Human intervention frequency: every 3rd task → every 15th task
"The best spec reads like a contract between human intent and machine execution."
Implementation Pattern
interface AgentSpec {
goal: string;
constraints: string[];
context: Record<string, unknown>;
verification: VerificationRule[];
fallback: FallbackStrategy;
}
The key insight: specs are composable. A complex workflow becomes a DAG of simple specs, each independently verifiable.