Moving the Spec: Solving Alignment in AI-Driven Engineering

The spec is in the wrong place

Paul Schneider identifies a critical flaw in current AI coding agent workflows. He notes that while tools like SpecKit improve output, they are often used as just-in-time artifacts rather than team alignments.

Why This Matters

In traditional development, expensive execution costs allowed misalignment to surface slowly over weeks. With AI agents, execution is now nearly free and instant, meaning an agent can perfectly build the wrong feature based on an ambiguous brief before a human notices, shifting all project risk to the gap between agreement and implementation.

Key Insights

• Spec-driven development (e.g., SpecKit, Kiro) produces superior output compared to prompt-based ‘vibe’ coding.
• Current tool fragmentation leads to ‘intent rot’: Confluence holds intent far from code, Jira strips reasoning for tickets, and IDE specs are written too late by a single engineer.
• Accessibility barriers exist where product managers lack GitHub licenses, preventing them from reviewing the durable specs living in repositories.

Practical Applications

• [Collaborative Teams] Shape rough ideas into durable Markdown specs committed to the repo before breaking them into buildable work for agents. Pitfall: Writing specs at implementation time leading to ‘translations of translations’ and feature drift.
• [AI Agent Workflows] Use shared environments for spec authoring to ensure cross-functional alignment between product and engineering. Pitfall: Relying on Jira tickets as primary specifications, which removes necessary context and success criteria.

References:

• https://dev.to/paul_schneider_06ad61671a/the-spec-is-in-the-wrong-place-2ai4