CircleCI's Intent-Driven Development: A Six-Step Framework for Steering AI Agents from Idea to Ship

The premise of AI-assisted development has shifted from “generate code snippets” to “complete multi-step tasks end to end.” The tooling has mostly caught up. The process hasn’t. Most teams are still using agent-driven coding the way they used code completion: describe what you want in natural language, evaluate what comes back, iterate. That works for isolated functions. It doesn’t scale to features that touch infrastructure, tests, and deployment pipelines.

CircleCI’s intent-driven development framework is a response to this gap. The idea: before you hand a task to an AI coding agent, write an intent document that structures the task in a way the agent can actually execute reliably. The document is the interface between human judgment and agent execution.

The Four Components of Intent

An intent document has four required components:

Objective: What the agent is trying to accomplish. Specific and measurable — not “improve performance” but “reduce average response time on the /search endpoint from 450ms to under 200ms under 100 concurrent users.”

Constraints: What the agent must not do. Explicit bounds that protect things you haven’t specified in the objective. “Do not modify the authentication layer.” “Do not change the database schema.” “Do not introduce new external dependencies without flagging them.” Constraints are where most agent failures originate — not from misunderstanding the objective, but from taking technically valid paths the developer didn’t intend.

Behavior to preserve: What currently works that must continue to work. This is different from constraints — constraints are about scope, behavior preservation is about regression prevention. “The file upload flow must continue to work on mobile Safari.” “All existing API responses must remain backward-compatible.” This component forces you to articulate what you’re relying on, which often reveals implicit assumptions about the system that weren’t previously documented.

Success criteria: How to know the task is complete. Verifiable, ideally runnable. “The test suite passes. Load testing shows p95 response time under 200ms. No new TypeScript compilation errors.” This is what the agent evaluates against before reporting completion — and what the CI pipeline validates independently.

The Six-Step Framework

Step 1 — Write the intent document using the four components. This is the only human-authored step in the main loop. The quality of this document determines the quality of the output.

Step 2 — Chunk sidecar files: For complex tasks, break the intent into sub-intents with their own sidecar documents. Each sidecar covers a distinct scope — separate the frontend changes from the API changes from the migration. Agents handle chunked tasks with higher fidelity than monolithic specs because context stays focused.

Step 3 — Set up CI pipeline integration: Configure CircleCI to run validation automatically. The agent isn’t trusted to self-certify completion — the CI pipeline independently evaluates the success criteria from the intent document.

Step 4 — Run the agent with the intent document: Hand the agent the intent document and let it work. The document’s constraints and behavior preservation requirements are the guardrails.

Step 5 — Run CircleCI CLI with --failure-report: circleci --failure-report generates a structured failure analysis when the CI run doesn’t pass. This output becomes the feedback loop: give the failure report back to the agent as the next input. The agent has the intent document (what it was trying to do) and the failure report (how the attempt fell short) — both structured, both actionable.

Step 6 — Iterate with failure reports: Repeat steps 4–5 until the CI pipeline passes. The intent document stays constant; the failure report changes each iteration. Most non-trivial tasks converge in 2–4 iterations.

The CircleCI MCP Server

The circleci MCP server (available from CircleCI) makes pipeline status readable by agents during the loop — agents can query build status, read test failure details, and surface relevant context without requiring human intermediation. Combined with the --failure-report flag, this closes the feedback loop: the agent can both run the pipeline and read its output directly.

Why This Works Better Than Unstructured Prompting

Unstructured prompting asks the agent to infer constraints, success criteria, and preservation requirements from a natural-language description. The agent fills gaps with plausible assumptions — which are often wrong about the specific system.

Intent documents externalize those choices. The developer specifies what was previously implicit. The agent doesn’t need to infer the constraints because they’re explicit. The CI pipeline doesn’t need the agent to self-evaluate because it independently verifies the success criteria.

The framework also changes the failure mode. Unstructured prompting fails by producing outputs that are plausibly correct but wrong in context. Intent-driven development fails in the CI run — the failure is visible, structured, and returnable to the agent rather than requiring developer inspection to diagnose.

Practical Adoption

The barrier to entry is writing the intent document, which is the kind of upfront specification work that feels like overhead compared to immediate prompting. The payoff is faster convergence on complex tasks and fewer hand-back cycles.

For platform teams deciding whether to adopt this: the framework adds the most value on tasks that touch multiple systems, have implicit requirements about what must not break, or involve any infrastructure or deployment changes. Simple isolated function generation doesn’t need a four-component intent document.

Source: CircleCI Blog

Content created with AI assistance and reviewed for accuracy.