Specs as the compiler pass for AI code

You've probably been here: you give Claude or Cursor a detailed prompt to build a feature. It generates code. Looks good. You ship it. Then requirements change slightly, and suddenly the AI generates something completely different—breaking existing work, missing edge cases, or reimagining the entire architecture.

The problem isn't the AI. It's that prompts are terrible build instructions.

The Prompt Problem

Natural language is expressive but fundamentally ambiguous. When you prompt an AI agent with "build a payment system with Stripe integration," you're leaving out everything that matters. There's no decomposition telling you what ships first, no acceptance criteria defining when you're actually done, no complexity estimate helping you plan the sprint. You don't get architectural decisions documenting which pieces talk to which, and there's no traceability connecting PRs back to requirements.

This works fine for one-off scripts. But for real features—especially ones that need to pass audits, scale with your team, or survive requirement changes—prompt-only workflows fall apart.

Specs as Compiler Passes

Here's a better mental model: treat specs like a compiler pass for AI development.

When you compile code, the compiler doesn't work directly with your source. It transforms it into an intermediate representation, a structured and typed format that's easier to optimize, analyze, and execute. That IR makes the rest of the pipeline deterministic.

AI agents need the same thing. pre.dev's Architect API converts your natural language into a structured specification, essentially an IR for development. It parses messy language into a typed, hierarchical spec that flows from milestones down to stories and subtasks. It optimizes through decomposition and complexity estimates. And it links in external knowledge by scraping and archiving documentation, so the spec stays grounded in real APIs and frameworks.

The output is reproducible, reviewable, and executable. Instead of re-prompting from scratch when requirements shift, you regenerate spec diffs and iterate like any other build artifact.

Two Spec Levels: Fast vs. Deep

We offer two spec levels with different speed and fidelity trade-offs. Fast-spec costs about 10 credits, returns in roughly 30 to 40 seconds, and gives you high-level milestones and stories. It's ideal for MVPs, spikes, and early stakeholder alignment. Deep-spec costs about 50 credits, takes 2 to 3 minutes, and produces granular subtasks with acceptance criteria that give you much stronger estimation fidelity. Use deep-spec when you're facing high risk, compliance requirements like SOC 2 or PCI, or complex integrations. Use fast-spec to quickly get everyone aligned before you commit to the details.

Bringing Specs Into Your IDE

Architect MCP is our MCP server implementation that wraps the Architect API. It lets you run fast-spec or deep-spec directly inside Cursor, Claude Code, or any MCP-compatible editor. Think of it as the adapter layer between pre.dev's spec generation and your actual coding environment, so specs live right where you write code instead of in some separate tool.

What a Generated Spec Looks Like

When you run a spec, you get a recommended tech stack based on your input and any documentation you provide. You get milestones laid out in phases with complexity estimates attached. User stories come with acceptance criteria, and there's a full subtask breakdown with checkboxes for tracking progress. Here's an excerpt from a real spec generated with pre.dev:

- [ ] Milestone 2: User authentication and profile management
[ ] User Registration - (M): As a: new user, I want to: register an account with email and password, So that: I can access the platform
Acceptance Criteria:
[ ] User can register with valid email and password
[ ] Email verification sent upon registration
[ ] Duplicate emails handled gracefully
[ ] Password strength requirements enforced
[ ] DB: Create/verify table_users migration - (M)
[ ] Infra: Configure Clerk (external_clerk) & auth settings - (M)
[ ] FE: Implement /RegisterPage UI comp_registerPage_mainForm - (M)
[ ] FE: Add client-side validation & reCAPTCHA on register form - (M)
[ ] API: Implement registerWithEmail mutation in router_route_registerPage - (M)
[ ] Backend: Create user record in table_users and auth_methods - (M)
[ ] Integration: Connect API to Clerk for email confirmation/session - (M)
[ ] QA: Write unit and integration tests for registration flow - (M)
[ ] Docs: Document registration API and front-end behavior - (M)
[ ] Password Reset - (M): As a: registered user, I want to: reset my password securely, So that: I can regain access
Acceptance Criteria:
[ ] User can request password reset link via valid email
[ ] Reset link expires after a defined period
[ ] New password must meet strength requirements
[ ] System invalidates existing sessions after password change
[ ] DB: Create password_resets table migration - (M)
[ ] API: Implement requestPasswordReset mutation (validate, create token) - (M)
[ ] API: Implement verifyResetToken and finalizeReset mutation - (M)
[ ] Frontend: Add Password Reset Request page (/auth/password-reset) - (M)
[ ] Frontend: Add Password Reset Form page (/auth/reset?token=) - (M)
[ ] Auth Integration: Wire Clerk for account lookup and session invalidation - (M)
[ ] Infra: Email service integration and template for reset link - (M)
[ ] Security: Add reCAPTCHA and rate limiting to request endpoint - (M)
[ ] Testing: End-to-end tests for reset flow - (M)
[ ] Docs: Document API, pages, and operational runbook - (M)

Task status uses a simple format: empty brackets for not started, an arrow for in progress, a checkmark for complete, and a backslash for skipped. When you include documentation URLs like Stripe's API docs, the response also includes zipped doc archives organized by platform, so all your implementation context stays close at hand.

- [ ] Not started
- [→] In progress
- [✓] Complete
- [\] Skipped

Hands On: Generate Your First Spec

You can start with a simple curl request to generate your first spec. Post to the fast-spec endpoint with your input and API key, and you'll get back a URL with your structured specification. Here's the basic pattern for building a REST API with user authentication.

curl -X POST https://api.pre.dev/fast-spec \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "input": "Build a payment system with Stripe integration",
    "docURLs": ["https://stripe.com/docs/api", "https://stripe.com/docs/payments"],
    "outputFormat": "url"
  }'

If you prefer working in Python, import the PredevAPI client, pass in your API key, and call fast_spec with your input. Same idea in Node—import the client, instantiate it with your key, and await the fastSpec call. The syntax varies by language, but the concept stays consistent.

import { PredevAPI } from 'predev-api';

const client = new PredevAPI({ apiKey: "YOUR_API_KEY" });

const response = await client.fastSpec({
  input: "Build a REST API for task management with user authentication",
  outputFormat: "url"
});

console.log(response);

Or use the Node SDK (npm) from a TypeScript/JavaScript project:

import { PredevAPI } from 'predev-api';

const client = new PredevAPI({ apiKey: "YOUR_API_KEY" });

const response = await client.fastSpec({
  input: "Build a REST API for task management with user authentication",
  outputFormat: "url"
});

console.log(response);

Pro tip: always include documentation URLs for external APIs. It dramatically reduces ambiguity. When you're building a payment system with Stripe integration, passing in links to Stripe's API docs and payment guides means the spec generation can ground its decisions in actual implementation details rather than guessing. https://docs.pre.dev/quickstart

{
  "output": "https://api.pre.dev/s/a6hFJRV6",
  "zippedDocsUrls": [
    {
      "platform": "stripe.com",
      "masterZipShortUrl": "https://api.pre.dev/s/xyz789"
    }
  ]
}

Architecture: The Hidden Backbone

During spec generation, the model builds an internal architectural representation of your system. It's selecting a stack, layering concerns, sketching service boundaries, and mapping cross-cutting requirements like auth, logging, and observability. That architectural IR drives everything downstream—how milestones get decomposed, what acceptance criteria look like, how complexity gets estimated, and which external dependencies get pulled in.

In fast-spec, architecture shows up implicitly through the recommended tech stack and high-level plans. In deep-spec, it becomes explicit through granular subtasks and tighter acceptance criteria that reflect real architectural decisions. Documentation scraping grounds those decisions in reality, binding external APIs and frameworks directly into the plan so architectural choices stay aligned with actual integrations.

Integrating Into Your SDLC

Treat specs as source by committing them alongside code. Map your PRs to milestones and stories so there's a clear thread from requirement to implementation. Iterate like you would with a compiler: change your inputs, regenerate spec diffs, and run the next pass from inside your IDE via Architect MCP.

Encode your non-functional requirements directly into the spec. Security constraints, performance targets, compliance requirements—all of these become acceptance criteria that provide guardrails during implementation. Use the complexity scores to scope sprints and set realistic SLAs. And close the loop by wiring Architect MCP into your CI, VCS, and ticketing tools. Make specs first-class artifacts in your deployment pipeline, not an afterthought.

What Teams Are Seeing

Teams using structured specs, especially through Architect MCP, are reporting faster time-to-first-commit because there's less thrashing on what to build. They're seeing fewer reverts because alignment happens upfront. Spec-to-PR fidelity goes up because the AI stays on track even when requirements change. And for US-based startups and enterprises navigating SOC 2, HIPAA, or PCI compliance, they're getting an observable audit trail from input through spec to shipped code. Not just vibes, but a real pipeline you can point auditors at.

Pitfalls to Avoid

Over-prompting while under-specifying is the classic mistake. Vague inputs produce vague specs, so be crisp about what you're asking for. Don't skip documentation scraping—external APIs are inherently ambiguous without their actual docs to reference. And don't treat specs as throwaway artifacts. Version them like you version code, because they're your reproducible build plans. If you're working on high-risk features, don't shortcut with fast-spec when you really need deep-spec's granularity.

Instead, start small and compose milestones that build on each other. Encode clear acceptance criteria upfront. Wire Architect MCP into the tools you actually use daily. And close the feedback loop with automated tests so you catch drift early.

Where to Start

Run fast-spec to shape scope on your next feature. See how it feels to have a structured plan instead of a wall of prose. When you're ready to build something for production or tackle compliance-heavy work, switch to deep-spec for the extra granularity. Install Architect MCP so you can run specs directly in your IDE without context-switching. And start committing specs alongside your code, mapping PRs back to stories so the thread from requirement to implementation stays visible.

If you're building an API platform, it's worth exploring how the Model Context Protocol standard can serve as a durable interface for AI agents while your underlying SDKs evolve. We've seen it help teams keep their agent integrations stable even as implementation details shift underneath.

Connect with us

Connect with me on LinkedIn via Adam Elkassas, follow on X/Twitter at @predotdev, and watch our featured YouTube video (1M+ views) Cursor Plan Mode vs. pre.dev Architect MCP on 2 Perplexity clones here: https://www.youtube.com/watch?v=EzFLAw9sRKc.