What Is intent.md? Claude Code's Team Just Published an 'AI-Native Dev Workflow' That Turns Your Intent Into a File

The Task Took Thirty Minutes. So Why Is the Project Still Stuck?

It's eleven at night, and you're staring at the terminal. The agent just finished writing the code for a feature — tests included — and when the message popped up, you glanced at the timestamp: thirty minutes. The same task took your team a full three days last week.

You're about to shut down the laptop and call it a night when your phone buzzes with a notification: the backlog still has eight untouched tickets sitting in it, and yesterday's pull request still hasn't been reviewed by anyone. It suddenly hits you — the only thing that got faster was "writing the code." Every other stage is exactly the same as before.

This is precisely the problem that Claude Code's creator Boris Cherny and the Anthropic team wanted to call out when they recently published an "AI-native software development lifecycle (SDLC) playbook." YouTuber Rob Shocks broke the document down on his channel, and the core line is: code was never the bottleneck. Your process is.

The "2x Speedup" Is Real — But It Only Happened in One Place

The traditional software development lifecycle looks something like this: plan, design, build, test, deploy, maintain — finish one loop, then come back to the start to greet the next feature, the next bug, the next release.

Before agents came along, "build" was almost always the longest and most expensive stage. Once agents arrived, that stage got dramatically compressed — according to Rob Shocks, roughly twice as fast. The problem is, planning, design, testing, review, and maintenance didn't speed up along with it. What Anthropic's document is trying to answer is exactly this: agents helped us compress "build" — so how do we redesign every other stage around agents too?

From "Meetings to Gather Requirements" to "Arguing with an Agent Until You Both Agree"

Start with the planning stage. The traditional approach is to sit down in a meeting, gather requirements, write a PRD, run workshops, and align with stakeholders round after round.

In the new workflow Anthropic describes, the first step is flipped: you let the agent interview you, repeatedly, asking questions until the feature you want to build, the bug you want to fix, or the shape of the whole product is crystal clear — building up full context along the way. Rob Shocks mentions that he personally uses an exploratory skill called "Switch Dimension Discovery," and also notes that there's Matt Pocock's "Realm" and Cursor's built-in "Requirements Discovery" out there — the tools can differ, but the goal is the same: let the agent keep probing until it genuinely understands what you want. Your job is to pour as much of your own experience, domain knowledge, and background context into that conversation as possible.

The agent then takes the pain points distilled from that conversation and writes them up into a file — intent.md. What makes this file special is that it's both human-readable and machine-actionable.

In a traditional SDLC, an idea first becomes a user story on a backlog, gets assigned story points, and passes through several handoffs before a human finally acts on it. In the world Anthropic describes, anyone who raises an issue — a customer reporting a bug, a product manager with a feature idea, or an engineer who wants to log a process improvement — can brainstorm directly with Claude and turn the result into an intent.md. The actual mechanics are simple: open a folder called `intent` in the project, and every intent.md lives there.

Once the file is written, the work isn't over. The person who raised the intent — Anthropic calls them the originator — needs to go back and check what the agent wrote, to confirm both sides understand the same thing. The originator doesn't have to be an expert on the team; anyone can play this role. After that, these scattered intent.md files get consolidated into something like a backlog — maybe a pile of markdown files, maybe organized into Notion or Linear — and a product owner prioritizes them. The agent can even do the first pass of triage, tagging things like frontend/backend, task size, feature type, and priority level.

intent.md Is Just the First Step: A Production Line Called the "Artifact Chain"

Once intent.md is signed off, the process moves to the next stop — spec. Anthropic recommends that as soon as an intent is confirmed, a hook or fixed workflow should automatically trigger the generation of the spec, and it offers a sample prompt: read the attached intent.md, produce a requirements and design spec, apply whatever skills you have on hand to plan it and make it conform to brand guidelines, and write the whole thing into spec.md. There's no single right answer here — you can use the built-in plan mode in Cursor, Claude Code, or Codex, or you can build your own spec-generation skill tailored to your team's style.

The next step down the line is plan: engineers feed the intent and spec together to the agent in plan mode, which produces a plan.md. Anthropic recommends interrogating this plan at this stage — ask it what changes could go wrong. The goal is for plan.md to be complete enough that if you handed it, on its own, to a different engineer, that person could execute it directly without ever going back to look at the intent or the spec. This point matters a lot, because Rob Shocks specifically flags: this entire pipeline was never meant to be run start to finish by the same single agent — different stages get picked up by different agents, or even different conversation threads (context windows). So you need to treat intent, spec, and plan as formal handoff documents — artifacts that let the next agent pick up right from the document itself, with no memory of the prior conversation.

plan.md has its own fixed format too: a list of files that need to change, a work order or checklist, risks and constraints, and "proof" — some verifiable standard of success, whether that's a lint check or whether tests pass. Anthropic also recommends saving every version of intent, spec, and plan, along with who changed what and when — something many companies find the hardest part to actually implement, yet the piece that matters most for tracking outcomes (like DORA metrics).

Once you're in the build stage, Anthropic recommends speeding things up with "auto mode" — but Rob Shocks cautions that this depends heavily on your organization: run it in a locked-down permission environment for a while first, then gradually loosen it up. Once you've figured out which tools, which external packages, and which network sources fall within an acceptable "reasonable use" range, lock those permissions into your Cursor or Claude settings — only then can the agent move faster without you having to watch it every second, while keeping the "blast radius" under control. Teams are also advised to pair this with worktrees, so multiple agents can work on different tasks at once; and what ties all of this together and keeps the process on track is the hook — for example, automatically updating the plan once a build finishes, blocking an agent from touching certain folders, or stopping it from installing an npm package that hasn't been approved yet. A good enough agent execution environment can even split a plan into multiple independent tasks and hand them off to multiple sub-agents to run in parallel.

By the time you reach the test stage, Anthropic's principle is: let the agent get as much testing done as possible before a human engineer or QA ever steps in — writing tests, running lint, running the build to confirm there are no errors. If a team uses something like Playwright, the agent can even actually spin up the service, take screenshots, and record the whole operation before handing it back. Anthropic also recommends running a round of evals every time a skill changes or a model is swapped: first collect about twenty real cases you've handled before along with their expected outcomes, and then re-run that set every time there's a new model, a change in scale, or a fundamental shift in how the work gets done, to confirm the whole SDLC hasn't regressed.

Moving into deploy, the agent opens a pull request based on the review a human has already completed; Anthropic recommends having a separate Claude instance asynchronously review that PR against your team's policies and security standards — and if it disagrees, yet another Claude instance handles the back-and-forth on those review comments. On the governance side, you can design hooks so that a deployment can't go through without a specific person's approval, or without clearing some release gate; once a PR is approved, another agent runs a round of security and CI checks — that might be a hard lint-and-threshold gate, or it might be an agent like Cursor Bugbot or Claude's security review catching one more bug for you.

Last is maintenance — and Rob Shocks says outright that this is the "most ambitious" section of the whole document. Traditional maintenance is reactive: you're at lunch, you're on call, or maybe it's three in the morning and a server-down alert comes in, and a ticket sits buried and completely ignored in a mountain of a backlog. In an AI-native SDLC, a security incident, a new ticket, a Slack message, or even a schedule can wake up Claude with zero human involvement, letting it asynchronously diagnose and handle the issue — and based on the logs it finds or the messages it receives, it generates its own intent.md. In practice, you might set up some thresholds you want to protect ahead of time, and the moment a page goes down or API traffic suddenly spikes, it triggers the agent to diagnose, write up an intent, and propose a solution — all before you've even touched your computer.

The Twist: What's Really Being Tested Isn't How Smart the Agent Is — It's Whether You've Done the Governance Work

At this point, it's easy to read this playbook as "just stuff an agent into every stage and the process speeds up automatically." But once you break it down, what actually holds up this artifact chain is a pile of decidedly unsexy things: saving every version of intent, spec, and plan, with a clear record of who touched what; testing things out in a locked-down permission environment first before gradually loosening it; using hooks to block folders and packages that shouldn't be touched; running a round of regression evals every time you swap models; and giving PRs an independent review and security gate. Miss any one of these pieces, and "letting the agent take over the entire SDLC" can easily turn into "letting the agent copy chaos across more stages, just faster."

Rob Shocks himself admits that the workflow he teaches on his channel isn't identical to this Anthropic document, and that there are other schools of thought out there too, like Superpowers or BMAD — there's no one-size-fits-all standard answer. What matters is that a team picks one approach and sticks with it, rather than switching every few days.

Starting Today, the First Thing You Write Isn't Code — It's an intent.md

If you can only take away one habit change from this entire workflow, it's probably this: the next time you're about to build a feature or fix a bug, let the agent repeatedly question you first, pour the context in your head out into words, write it up as an intent.md — and only then move forward.

This is also why this workflow is especially interesting for something else we care about: once a feature has to pass through seven gates — intent, spec, plan, build, test, deploy, maintain — each gate might be run by a different agent, or a different model, and the total number of calls is far higher than "one agent writing everything from start to finish." Once the process is standardized, usage becomes more predictable, but it also becomes more scattered — and that's exactly what AI Token King is designed to help teams with: no matter how many agents are chained together behind the scenes, or how many models get swapped in, you can check, in one place, which model was used for every single call, how many tokens it burned, and how much it actually charged.

Frequently Asked Questions (FAQ)

Q1: What exactly is intent.md? According to Rob Shocks's retelling of Anthropic's approach, intent.md is an intent document produced through a brainstorming session between the "originator" (the person raising the issue) and Claude, with the defining feature that it's "human-readable and machine-actionable." It replaces the scattered user stories of a traditional backlog and becomes the starting point for downstream artifacts like spec and plan.

Q2: Who is allowed to write an intent.md? Anyone. It could be a customer reporting a bug, a product manager who wants a new feature, or an engineer who wants to document a process improvement idea — none of them need to be an expert on the team. Once it's written, Anthropic recommends that the person who raised the issue go back and check what the agent put together, to make sure both sides understand it the same way.

Q3: What's the relationship between intent.md, spec.md, and plan.md? The three together form what Rob Shocks calls the "artifact chain": intent.md first establishes the problem and its context; once the intent is signed off, a hook or fixed workflow triggers the generation of spec.md (the requirements and design spec); then engineers feed the intent and spec together to the agent in plan mode to produce plan.md (the specific files to change, the order of work, risks, and verification criteria).

Q4: Does this mean the entire pipeline can run completely unattended? No. The transcript repeatedly stresses that humans stay at the key review checkpoints: the originator has to check the intent, an engineer has to confirm the plan before it's executed, and deployment needs human approval or has to clear a release gate. What Anthropic is describing is reducing the human time spent at each stage, not eliminating human judgment altogether.

Q5: Do you have to copy Anthropic's version of this workflow exactly? No. Rob Shocks himself says in the video that the workflow he actually teaches isn't identical to this Anthropic document, and that there are other schools of thought out there too, like Superpowers and BMAD. What matters is that a team picks one approach and standardizes on it as much as possible, rather than switching playbooks with every project.

Source Statement

This article is compiled from a video published in September 2026 on the YouTube channel Rob Shocks, "Claude Codes New INTENT.MD, What is It?." The content is that channel's spoken breakdown and retelling of the "AI-native software development lifecycle playbook" published by Anthropic (the team behind Claude Code creator Boris Cherny) — it is not a verbatim citation drawn directly from Anthropic's original official document by this article's author. The process steps and tool names described here (such as Switch Dimension Discovery, Realm, and Cursor's Requirements Discovery) faithfully reflect the content of the video; this is not a literal translation, but a reorganized and re-articulated summary. If your team plans to formally adopt a similar workflow, we recommend reviewing Anthropic's official published document directly to verify the details.

Take Action Now

When a single feature has to pass through seven gates — intent, spec, plan, build, test, deploy, maintain — there might be several agents and several models taking turns behind the scenes, and your token bill ends up scattered across call after call. Try AI Token King for free and lay out, in one place, the tokens burned, the model used, and the amount actually charged for every single call — no matter how many agents and models your AI-native SDLC has chained together, you'll be able to see exactly where the money went.