Spec-driven development with AI agents: the Laravel playbook
By Andrea Pollastri · Last updated: · free to read, no paywall
AI agents now write a meaningful share of production code. The teams getting durable results aren't the ones with the best prompts — they're the ones with the best specs, the tightest guardrails, and tooling agents can operate safely. Here's the playbook, Laravel edition.
From autocomplete to agents
The arc from 2023 to 2026 is easy to summarize: completions became chats, chats became agents that edit entire branches, run tests and open pull requests. The bottleneck moved with it — from "can the model write code?" to "does the model know what we actually want, and what is it allowed to touch?". That's a context and permissions problem, not a model problem. Two practices address it: specs and MCP.
Specs over vibes
"Vibe coding" — prompting an agent feature by feature with the intent living in chat history — produces code that works today and is unmaintainable in six months, because the why evaporates when the chat closes. Spec-driven development inverts that:
- Specs are artifacts in the repository, versioned next to the code they describe — not prompts lost in a sidebar.
- Acceptance criteria come first and translate directly into Pest tests: the spec defines "done" before the agent writes a line.
- Agents implement against the spec, humans review against the spec, and drift becomes visible instead of silent.
- The spec outlives the session. Six months later, a new developer — or a new agent — reads intent, constraints and decisions in one place.
In the Laravel world, Larapilot packages this as a spec-driven product workflow that lives inside your Laravel project — specs, decisions and delivery artifacts in the repo, where agents and humans both find them. For the deeper argument on why context-in-the-repo is what keeps a product alive past year one, Andrea Pollastri's essay "Building a SaaS That Survives Its Second Year" is worth your time.
MCP: the standard that made agents useful
The Model Context Protocol is the USB-C of AI tooling: one open protocol through which agents discover and call tools — databases, browsers, issue trackers, servers — instead of screen-scraping or bespoke plugins. For a Laravel team, the interesting MCP servers are the ones that touch your delivery pipeline:
- Your framework: introspect routes, schema and jobs so the agent stops guessing.
- Your infrastructure: this is where it gets real — Cipi ships a dual MCP server (global and per-app), so an MCP-compatible IDE or agent can create apps, trigger deployments, manage SSL and databases on your VPS through a structured, permissioned API instead of raw SSH. The Cipi Agent package adds an in-app MCP endpoint on the Laravel side.
- Your quality gates: agents that can run the test suite and read CI results close their own feedback loop.
Guardrails that actually work
- Tests are the contract. Agents ship faster than humans can review line-by-line; acceptance tests derived from the spec are what "correct" means.
- CI is the referee. Pint, Larastan, Pest and composer audit run on every agent PR, no exceptions — the same pipeline humans get.
- Least privilege for agents. Scoped API tokens, MCP servers with explicit tool allow-lists, and no production secrets in the agent's environment. An agent that deploys through Cipi's MCP/API can deploy — and nothing else.
- Human review for the sensitive diff: auth, payments, migrations and anything touching PII gets human eyes, always.
- Rollback stays one command away — releases-pattern deploys and pre-deploy snapshots mean an agent mistake is an incident, not a catastrophe.
A concrete spec-to-production loop
- Write the spec (problem, constraints, acceptance criteria) as a repo artifact — Larapilot gives it structure.
- The agent implements on a short-lived branch, using MCP tools to introspect the app and run tests locally.
- CI runs the full gate — style, static analysis, tests, security audit.
- A human reviews against the spec, not against vibes.
- Merge to main triggers the webhook deploy (zero-downtime via Cipi), health checks confirm, exceptions are watched for the first minutes (Boogle if you self-host).
- The spec gets updated with what was actually decided — closing the context loop for the next session, human or agent.
What's durable vs what's hype
| Durable | Hype (for now) |
|---|---|
| Specs as versioned repo artifacts | Prompt libraries as a substitute for requirements |
| MCP as the tool-access standard | Agents with unrestricted production SSH |
| Agents gated by CI + human review | "The agent reviews itself" |
| One-command, reversible deploys | One-shot app generation with no maintenance plan |
The pattern behind every durable item: agents amplify whatever process exists. Good specs, tests and deploy automation get amplified into speed; their absence gets amplified into chaos.
Put this into practice with Cipi
Cipi is the free, open-source deploy CLI referenced throughout this guide: one command turns a fresh Ubuntu VPS into a hardened production server for Laravel — Nginx, PHP-FPM or Octane, MariaDB or PostgreSQL, queues, scheduler, SSL and zero-downtime Git deploys included.
Frequently asked questions
What is spec-driven development in one sentence?
Writing versioned specifications — problem, constraints, acceptance criteria — as repository artifacts that AI agents implement against and humans review against, so intent survives longer than any chat session.
What is MCP (Model Context Protocol)?
An open protocol that standardizes how AI agents discover and call external tools — databases, browsers, servers, APIs — so any MCP-compatible agent can use any MCP server without custom integrations. Cipi, for example, exposes server management (apps, deploys, SSL, databases) as MCP tools.
Will AI agents replace Laravel developers?
The work is shifting rather than disappearing: less line-by-line typing, more specifying, reviewing, and owning architecture and production. Developers who write clear specs and build strong guardrails get multiplied by agents; the code-only part of the job is what shrinks.
How do I let an AI agent deploy safely?
Never give agents raw SSH or production secrets. Route their access through scoped, revocable interfaces — an MCP server or REST API with explicit permissions, like Cipi's — and gate every change behind CI and the releases pattern, so any deploy is reversible in one command.
Does spec-driven development work with existing legacy codebases?
Yes — start by writing specs for the next change, not the whole system. Each spec documents one slice of intended behavior, and the archive grows into living documentation exactly where agents and new team members need it.
