What Is intent.md in Claude Code? A Practical Guide with an Example

You ask Claude Code to build a feature. Minutes later, the code looks reasonable—but it solves a slightly different problem from the one your team had in mind.

That is the problem behind intent.md, an artifact in Anthropic's AI-Native SDLC playbook. It captures the desired change before the team settles on a technical solution.

Here is what the file means, how it fits with Claude Code, and a practical example you can adapt.

The key distinction: intent.md records what someone wants to change and why. It is a proposed workflow artifact, not a new Claude Code command or a special configuration file that Claude automatically discovers.

The workflow at a glance

Stage	Artifact	Question it answers	Reviewer
Capture	intent.md	What problem and outcome matter?	The person or product owner requesting the change
Design	spec.md	What behavior and requirements follow?	Product owner, with relevant specialists
Build	plan.md	How will we change this codebase?	Engineer
Verify	PR and tests	Does the change meet the agreed behavior?	Engineering team

This is a simplified reading of Anthropic's playbook. The point is the order: agree on the outcome before committing to an implementation. Anthropic describes the originator brainstorming with Claude, correcting the draft intent.md, and having a product owner review it before it moves to the spec stage.

A practical intent.md example

Imagine an order-planning screen with filters and paginated results. Someone requests a Select All checkbox.

“Add Select All” leaves an important ambiguity: does all mean the visible page or every order matching the filter? This is the sort of decision I would put in an intent file:

# Intent: Select orders across paginated results

Status: Draft
Owner: Order planning team

## Problem

Planners see only one page of orders at a time. The current selection
flow makes it difficult to act on all orders matching their filters.

## Desired outcome

Planners can select every order matching the current filters, even when
the results span several pages. The interface shows how many orders
the action will affect.

Orders selected individually remain selected when filters change.
A bulk selection applies only to the filter used to create it.

## Affected users

Planners assigning orders to vehicles.

## Constraints

The count displayed in the UI must match the set of orders processed.
Existing manual selection behavior should remain available.

## Open questions

- Can the API process the active filters directly?
- If the API requires IDs, how will it obtain IDs across all pages?
- What should happen if an order stops matching the filter before submit?

This is an illustrative example, not a template required by Claude Code. The open questions are intentional. An intent file should expose unresolved decisions instead of silently letting the agent make them.

Notice what the example does not say: “add a Zustand store,” “change this controller,” or “create an endpoint.” Those may become good implementation choices later, after someone inspects the existing system.

intent.md vs. CLAUDE.md vs. spec.md

The filenames look similar, but their jobs differ:

File	Useful contents	Scope
CLAUDE.md	Repository commands, conventions, architecture, recurring pitfalls	Ongoing project guidance
intent.md	Problem, desired outcome, affected users, constraints, unknowns	One proposed change
spec.md	Requirements and design decisions derived from accepted intent	One defined change
plan.md	Steps to implement the spec in the existing codebase	Engineering execution

Anthropic describes CLAUDE.md as context Claude Code reads for a repository. Its intent lesson describes a separate, reviewed artifact that starts a particular change. Once accepted, Claude can turn that intent into a more detailed requirements and design spec.

An intent.md does not replace a ticket, a product decision, or review. If your team already has a reliable source of truth in another tool, keep the relationship between that record and the Markdown file explicit.

How to try it with Claude Code

Start with a problem, not a file path. For example:

Help me draft an intent.md for this feature. First ask me about the
affected users, the current problem, the desired outcome, constraints,
and unresolved questions. Keep the document about behavior and intent.
Do not choose an architecture or edit code yet.

Review the resulting document yourself or with the person requesting the change. Check especially for statements that Claude inferred but nobody actually approved.

Once the intent is accepted, move to codebase investigation:

Read intent/select-orders.md and inspect the existing implementation.
Identify the UI, state, and API behavior relevant to this request.
Separate confirmed facts from assumptions. Propose a spec that preserves
the accepted intent and calls out unresolved decisions. Do not implement yet.

Anthropic suggests an intent/ folder in a product repository as one simple place to keep these files. The directory and filename are workflow choices; you still need to direct the agent to the relevant intent when asking it to work on the change.

When is this worth the extra file?

For a typo fix or an obvious one-line bug, a separate artifact may add little. I would consider intent.md when a change involves several people, crosses frontend and backend, or contains words like “all,” “active,” “done,” or “same as before” that different people may interpret differently.

The value is not that Markdown makes requirements correct. The value is that the proposed outcome is visible, reviewable, and available when the team asks whether the eventual implementation solved the right problem.

My takeaway: the faster an AI agent can write code, the more useful it becomes to agree on the intent before it starts.

Would you add intent.md to an existing project, or keep this information in your issue tracker?

---

Sources: Anthropic's AI-Native SDLC playbook, Capture as intent.md, and Requirements and design.