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…
Intent.md is an artifact within Anthropic's AI-Native Software Development Life Cycle (SDLC) playbook. Its purpose is to capture the desired change before the team decides on a technical solution. The file records what someone wants to change and why, serving as a proposed workflow artifact rather than a new Claude Code command or a special configuration file that Claude automatically discovers.
The workflow with intent.md involves agreeing on the outcome before committing to an implementation. According to this workflow, a person or product owner shares their request, which then goes through several stages: review, design, building plan, and verification. This is a departure from the typical order of designing a solution and then writing intent statements.
A practical example of an intent.md file outlines a desire for a "Select All" checkbox on an order-planning screen with filters and paginated results. This checkbox would allow planners to select every order matching the current filters, even if the results span several pages. This example highlights the importance of clarifying ambiguous terms like "all" and ensuring that the interface displays how many orders the action will affect.
The example also lists affected users, constraints, and open questions. These open questions are intentionally left for the team to discuss and resolve, preventing Claude Code from silently making assumptions.
Comparatively, CLAUDE.md contains repository commands, conventions, architecture, and recurring pitfalls. It is useful for ongoing project guidance. Spec.md, on the other hand, outlines requirements and design decisions derived from accepted intent, serving as a defined change plan.
In summary, intent.md is a valuable tool for clarifying and documenting the intent behind a change, reducing ambiguity, and ensuring that the eventual implementation accurately addresses the right problem.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
