The Spec System

The spec is the skill, not the prompt

The Spec Is the Skill

Most people think the skill in vibe-coding is writing good prompts. It is not. The skill is writing good specs. A prompt is a single instruction. A spec is a complete blueprint. The difference between a prompt and a spec is the difference between telling someone "build me a house" and handing them architectural drawings.

Queue-Based Specs

The most effective spec format for AI agents is the queue-based spec. Instead of writing one long document, you break your project into numbered, sequential queue items. Each queue item is a single, atomic task that the AI can complete without ambiguity.

Queue Item 1: Project Setup
- Initialize Express + EJS project
- Set port to process.env.PORT
- Install: compression, ejs, express
- Create folder structure: views/, public/css/, routes/, lib/

Queue Item 2: Design System
- Background: #FAFAF8
- Accent: #D95F2B
- Headings: Fraunces (serif, Google Fonts)
- Body: Inter (sans-serif, Google Fonts)
- Create public/css/main.css with full design tokens

Queue Item 3: Base Layout
- Create views/layouts/base.ejs
- Include meta tags, OG tags, canonical URL
- Include header partial, footer partial
- Load main.css, main.js

Each queue item has a clear scope, specific deliverables, and no ambiguity about what "done" means. This is what makes AI agents effective: they can complete one queue item, you can verify it, and then move to the next.

Companion Docs

For complex projects, the spec alone is not enough. You need companion documents that provide context the AI cannot infer:

• Design System Doc: Colors, fonts, spacing, tone of voice, examples of sites you admire
• Data Model Doc: What data exists, where it is stored, what is sacred (never overwrite), what is ephemeral
• Route Map: Every URL in the application, what it renders, what data it needs
• Integration Doc: API keys, third-party services, rate limits, error handling expectations

Common Spec Mistakes

1. Too Vague

"Build a nice landing page" is not a spec. "Build a landing page with a hero section containing an H1, subhead, two CTA buttons, and a responsive SVG illustration positioned to the right on desktop and below on mobile" is a spec.

2. Too Large Per Item

If a single queue item takes more than 15 minutes for the AI to implement, break it down further. Smaller items mean faster verification and fewer compound errors.

3. No Design Before Build

If your spec jumps straight to building UI components without first defining colors, fonts, and spacing, every component will look different. Define the design system in Queue Items 1-3. Build components from Queue Item 4 onward.