The Problem with Specs: Why They Fail AI Agents
When developing AI agents like Claude Code for complex tasks, the default approach is often to provide abstract specifications. These might include design conventions, component rules, or forbidden patterns. While seemingly comprehensive, this method consistently yields output that hovers around 80% quality, requiring numerous rounds of manual correction to reach completion. This inefficiency stems from a fundamental flaw: specifications, by their very nature, begin to diverge from reality the moment they are written. Every minor implementation decision—a specific padding choice, an exception for a particular edge case—that isn't meticulously documented back into the spec creates a gap. This lack of real-time synchronization makes it unsustainable to maintain accurate specifications, leaving AI agents working from outdated blueprints.
Consider the process of building a fleet of 600 web tools. If each tool is initially specified abstractly, the drift between spec and reality will compound rapidly. The AI, tasked with generating new tools or modifying existing ones based on these specs, will inevitably produce code that requires significant rework. This isn't a failure of the AI's understanding, but a failure of the input data to accurately reflect the desired end state. The core issue is that specs are static descriptions of intent, while code is a dynamic, evolving artifact.
The solution isn't to refine the specification process endlessly. It's to change the fundamental input entirely. Instead of asking an AI agent to interpret abstract rules, we should direct it to analyze and modify working, deployed code. This shift transforms the AI's task from speculative design to informed adaptation. It’s like asking a junior mechanic to build a car from a blueprint versus asking them to fix a specific, running car of the same model. The latter is far more practical and yields better results because the reference artifact is the ground truth.
Restructuring AI Agent Skills: Reference-Driven Development
The architectural shift involves moving from a "read the spec and build" paradigm to a "copy the working artifact and modify" approach. This means the AI agent receives a URL to a live, production-deployed reference instead of a lengthy document outlining rules. The agent then inspects this live artifact, understands its structure, functionality, and styling, and uses that as the direct template for its task. Whether the goal is to build a new tool with similar characteristics or to repair an existing one, the live reference serves as the single source of truth.
This strategy has proven remarkably effective in managing a large fleet of tools. For instance, when tasked with creating a new notification component, instead of providing a spec that details color palettes, hover states, and animation timings, the agent is pointed to an existing, well-functioning notification component. It then replicates the successful patterns and applies specified modifications. This drastically reduces the iteration cycles. The AI doesn't need to infer how a particular CSS property should be applied in context; it can observe it directly in the deployed code. This is particularly powerful for front-end development, where subtle visual cues and interactive behaviors are critical.
The benefits extend beyond mere efficiency. By grounding AI agent tasks in live code, we ensure a higher degree of consistency and adherence to established patterns. The AI learns from actual implementations, not theoretical ones. This reduces the probability of generating code that, while technically compliant with a spec, doesn't align with the project's actual design language or technical constraints. It’s akin to how a human developer learns best by studying and working with existing codebases rather than just reading style guides.
Separating Build and Repair Skills
A crucial second design decision for optimizing AI agent workflows is the separation of