Spec-Driven Development with Real Data: Why the Best AI Coding Tools Don't Start with a Prompt

There's a pattern emerging in AI-assisted development that nobody has fully named yet.

The best AI coding sessions — the ones where the agent produces exactly what you need, first try, with no back-and-forth — share a common trait. They don't start with a vague prompt typed from memory. They start with structured direction grounded in real data.

Not "add schema markup to the blog." Instead: "Blog pages at /blog/[slug] are missing Article schema. Google Search Console shows these pages receive 12,000 monthly impressions but have declining CTR. Here's the exact JSON-LD structure needed, the affected files, and the acceptance criteria for verification."

The difference in output quality is enormous. And it points to something bigger than a productivity tip. It points to a methodology.

The Prompt Problem#

Today, the standard AI-assisted development workflow looks like this:

1. Developer thinks about what needs to happen
2. Developer types a prompt from memory
3. Agent implements based on that prompt
4. Developer reviews the output
5. Repeat until it looks right

Every step depends on the developer's memory, intuition, and attention in that moment. The prompt is improvised. The review criteria are subjective. "Looks right" is the definition of done.

This works for simple tasks. It falls apart for anything that requires domain expertise, project-specific context, or verification against external standards.

Consider: a developer prompting an agent to "improve the SEO" on a Next.js site. What does the agent do? It adds generic meta descriptions, maybe throws in some Open Graph tags, possibly generates some schema markup. It looks reasonable. It might even pass a Lighthouse audit.

But is it right? Does the schema match Google's current validation requirements? Are the meta descriptions targeting queries that people actually search for? Are the pages even indexed? The agent doesn't know. The developer probably doesn't know either. And neither of them has the data to find out within the context of a coding session.

This is the prompt problem: the quality ceiling of AI-generated code is determined by the quality floor of human-provided direction.

From Prompts to Specs#

The first evolution is moving from improvised prompts to structured specifications. Instead of typing what you remember, you create a spec with:

• A clear description of what to build and why
• Acceptance criteria that define "done" in verifiable terms
• Technical constraints and affected files
• Version history that preserves original intent

This is a significant improvement. The agent receives unambiguous direction. The reviewer has criteria to check against. The spec persists across sessions, so any agent can pick up the work later.

But there's a question that specs alone don't answer: where do the specs come from?

If the developer writes the spec from memory and intuition, you've formalized the direction but not improved it. You've structured the guess. The acceptance criteria are only as good as the developer's understanding of the domain — which, for specialized areas like SEO, performance, accessibility, or security, may be incomplete.

The Data-Informed Leap#

The real shift happens when specs are informed by — or generated from — actual data.

Not data in the abstract sense. Specific, deterministic data about your project:

First-party data (your own site):

• What pages exist and their current state (crawl data)
• HTTP status codes, redirect chains, response times
• Schema markup present or missing on each page
• Heading structure, meta tags, Open Graph tags
• Internal linking patterns
• Accessibility violations
• Security headers

External platform data (how the world sees your site):

• Which pages Google has indexed and which it refuses to (Google Search Console)
• What queries drive traffic to which pages, with actual click-through rates (GSC Search Analytics)
• Which pages lost indexing status this week (GSC state changes)
• Keyword search volumes and competitive difficulty (keyword research APIs)
• How your content ranks relative to competitors

Runtime data (how your site performs):

• Core Web Vitals scores per page
• Error rates from monitoring
• User behavior patterns from analytics

Each of these data sources contains signals that should influence development decisions. But traditionally, they sit in separate dashboards that developers rarely check. The data exists. The connection to the development workflow doesn't.

Data-informed spec-driven development closes that connection:

Data sources → Analysis & prioritization → Structured spec →
Agent implementation → Verification against data → Updated spec

The spec isn't written from memory. It's generated from evidence. The acceptance criteria aren't subjective. They're derived from the same data that identified the issue. And verification isn't "looks right" — it's a re-check against the data source that confirms the problem is actually resolved.

How This Works: A Concrete Example#

Let's trace the full loop for a real scenario.

Step 1: Data collection

Rampify crawls your Next.js site and discovers 47 blog posts. It checks each page's HTML structure, schema markup, meta tags, and internal links. Separately, it syncs with Google Search Console and pulls indexing verdicts, coverage states, and search analytics for every URL.

Step 2: Analysis and prioritization

The system cross-references crawl data with GSC data and identifies:

• 12 blog posts have no Article schema (deterministic check)
• 8 of those 12 receive more than 1,000 monthly impressions (GSC data)
• 3 of the 8 have declining click-through rates over the past 90 days (GSC trend)
• Those 3 pages target queries where rich results appear in the SERP (keyword data)

Adding Article schema to those 3 pages is the highest-impact action. Not because a developer guessed it — because the data shows it.

Step 3: Spec generation

A structured specification is created:

Title: Add Article schema to high-impression blog posts with declining CTR

Description: Three blog posts receive significant search traffic but have declining CTR, likely due to missing rich result eligibility. Adding valid Article schema with the required properties will make these pages eligible for rich results in Google Search.

Acceptance criteria:

• Each page renders valid JSON-LD with @type: "Article"
• Required properties present: headline, datePublished, dateModified, author, image
• Schema passes Google's Rich Results Test validation
• No existing structured data is broken or duplicated

Affected files: app/(marketing)/blog/[slug]/page.tsx, lib/blog/schema.ts

Priority: High (data-backed: 3 pages × 1,000+ impressions × declining CTR)

The developer didn't write this. They didn't need domain expertise in schema markup requirements. The data identified the issue, the analysis prioritized it, and the spec captured the solution in structured, actionable terms.

Step 4: Agent implementation

An AI agent reads this spec via MCP. It knows exactly which files to modify, what schema properties are required, and what validation the output needs to pass. It implements the Article schema, runs the rich results test against the output, and commits.

Step 5: Verification

The system re-crawls the affected pages. It confirms the JSON-LD is present, parses it, validates the required properties, and checks against Google's schema requirements. Acceptance criteria: met. Spec status: verified.

If a future code change removes or breaks the schema — a layout refactor, a component migration, a well-meaning agent that "cleans up" the page — the next crawl detects the regression, flags the spec as drifted, and the loop starts again.

No step in this process required the developer to have SEO expertise. The data provided the intelligence. The spec provided the direction. The agent provided the implementation. The verification loop provided the quality assurance.

The Data Layer Pattern#

This example uses SEO data, but the pattern is domain-agnostic. Any domain where external data should inform development decisions follows the same structure:

In each case:

1. Data identifies the issue and quantifies its impact
2. Analysis prioritizes based on evidence, not intuition
3. Specs capture the solution in structured, verifiable terms
4. Agents implement with full context
5. Verification confirms against the original data source

The developer's role shifts from "know everything about every domain" to "review specs generated from data and approve the ones that matter." This is a fundamentally different — and more scalable — way to build software.

Why Data Changes Everything About Specs#

Without data, a spec is structured intuition. Better than a prompt, but still dependent on what the human knows and remembers. Data transforms specs in four ways:

1. Discovery becomes automatic#

You don't need to know that Article schema is missing from your blog posts. You don't need to remember to check your GSC coverage states. You don't need to run Lighthouse manually every sprint. The data surfaces issues you didn't know existed — and quantifies ones you vaguely suspected.

2. Prioritization becomes evidence-based#

Not all issues are equal. A missing meta description on a page with zero traffic is noise. A missing meta description on a page with 10,000 monthly impressions is urgent. Data turns a flat list of issues into a ranked action plan where the most impactful work rises to the top.

3. Acceptance criteria become objective#

"Improve the SEO" is subjective. "All blog posts render valid Article schema with required properties, verified by Google's Rich Results Test" is objective. When specs are derived from data, the acceptance criteria inherit that objectivity. Verification becomes a data check, not a human judgment call.

4. The feedback loop closes#

The most powerful property of data-informed specs is that they create a closed loop. The same data source that identified the issue can verify whether the fix worked. Crawl data found missing schema → agent adds schema → crawl data confirms schema is present. No human verification required for the mechanical check.

This is what makes the system self-maintaining. Specs don't just capture a point-in-time decision — they establish an ongoing contract between the codebase and the data. When the data says the contract is violated, the system responds.

The Three Data Tiers#

Not all data is equal. There's a natural hierarchy of data sources that informs spec quality:

Tier 1: Deterministic first-party data#

Data you can collect by examining your own site. Crawling pages, parsing HTML, checking HTTP responses. This data is deterministic — it's the same every time you check, and it's unambiguous. A page either has schema markup or it doesn't. A link either returns 200 or it doesn't.

This is the foundation. It requires no external accounts, no API keys, no third-party dependencies. Any site can be crawled and analyzed deterministically.

Tier 2: Authenticated platform data#

Data from platforms that see your site from the outside — primarily Google Search Console. This data tells you things you can't learn from crawling alone: how Google interprets your pages, which queries drive traffic, which pages are indexed, which are rejected and why.

This is where the intelligence gets powerful. GSC data is authoritative — it's Google telling you directly how it sees your site. But it requires authentication, has API rate limits, and the data needs to be synced and stored to be useful over time.

Tier 3: Market and competitive data#

Data from keyword research APIs, competitor analysis tools, and market intelligence platforms. This data contextualizes your site within the broader landscape — what people search for, how competitors rank, where content gaps exist.

This is the strategic layer. It informs not just "fix what's broken" but "build what's missing." It turns specs from reactive (fix this issue) to proactive (capture this opportunity).

Each tier builds on the previous:

Tier 1: "Your blog posts are missing Article schema"
  + Tier 2: "...and 8 of them get 1,000+ monthly impressions from Google"
    + Tier 3: "...and the top queries trigger rich results that competitors have"

The spec generated from all three tiers is dramatically more valuable than one generated from any single tier. The data compounds.

Building Toward This#

If this approach resonates, the practical question is: how do you start?

Start with Tier 1 data. Crawl your own site. Check for basic issues — missing meta tags, broken links, missing schema, heading structure problems. These are deterministic checks that require no external dependencies and produce immediately actionable specs.

Add Tier 2 when you're ready. Connect Google Search Console. Sync indexing data. Cross-reference crawl findings with actual search performance. The prioritization jump from "missing schema on blog posts" to "missing schema on high-traffic blog posts" is where the real value appears.

Layer in Tier 3 for strategic work. Keyword data and competitive analysis inform content strategy and opportunity identification. This is less about fixing what's broken and more about building what's missing.

At each tier, the workflow is the same: data → analysis → spec → agent implements → verify. The data sources change, the domain expertise deepens, but the pattern holds.

The Methodology#

Data-informed spec-driven development isn't a tool. It's a methodology. The principles:

1. Direction should come from data, not memory. The developer's job is to choose which data-informed specs to pursue, not to generate direction from scratch.

2. Specs should be generated, not written. A conversation between you and your AI agent — informed by actual data — produces a spec. You refine and approve it. You don't start from a blank document.

3. Acceptance criteria should be verifiable against data. If the data source that identified the issue can confirm the fix, the criteria is objective. If it requires human judgment, it should be flagged as such.

4. The loop should be continuous. Verification isn't a one-time step. It's an ongoing process. Data collection runs continuously, specs are monitored for drift, and regressions are caught automatically.

5. Domain expertise is encoded in the system, not required of the developer. The developer doesn't need to know Google's schema requirements, WCAG color contrast ratios, or CVE severity scores. The intelligence layer knows, and the specs it generates reflect that knowledge.

This is the evolution of spec-driven development. Spec-driven development brought structured specifications into AI coding workflows. Data-informed specs take the next step: that direction isn't just structured — it's generated from evidence, prioritized by impact, and verified against the same data source that identified the issue.

Where This Fits in the Stack#

In the emerging agentic coding stack, this methodology occupies the intelligence layer — the layer between "manage agents" and "agents write code" that provides structured direction and verification.

The layers below (agents, editors, infrastructure) are maturing rapidly and commoditizing. The layer above (developer planning and review) is inherently human. The intelligence layer — where data becomes specs, and specs become verified implementations — is where the leverage is highest and the tooling is least developed.

This is also why living specifications matter. A data-informed spec that goes stale is just a better-sourced document that nobody trusts. Living specs — specs that detect drift, update from code changes, and re-verify against data — are what make the methodology sustainable.

Data-informed specs aren't a feature. They're the foundation of a development workflow where AI agents reliably build the right thing — not because the developer remembered to tell them, but because the data made it impossible to miss.