{"slug": "what-is-intent-md-in-claude-code-a-practical-guide-with-an-example", "title": "What Is intent.md in Claude Code? A Practical Guide with an Example", "summary": "Anthropic's AI-Native SDLC playbook introduces intent.md, a proposed workflow artifact that captures what a team wants to change and why before any technical solution is chosen. Unlike CLAUDE.md, which provides ongoing repository context, intent.md records the problem, desired outcome, affected users, constraints, and open questions for a single proposed change, feeding into later spec.md and plan.md stages. The guide illustrates the approach with a paginated order-planning example where a vague \"Add Select All\" request is clarified into explicit intent before implementation.", "body_md": "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.\n\nThat is the problem behind **`intent.md`**, an artifact in Anthropic's [AI-Native SDLC playbook](https://claude.com/blog/the-ai-native-sdlc-playbook). It captures the desired change *before* the team settles on a technical solution.\n\nHere is what the file means, how it fits with Claude Code, and a practical example you can adapt.\n\n**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.\n\n| Stage | Artifact | Question it answers | Reviewer | \n|---|---|---|---|\n| Capture | `intent.md` | What problem and outcome matter? | The person or product owner requesting the change | \n| Design | `spec.md` | What behavior and requirements follow? | Product owner, with relevant specialists | \n| Build | `plan.md` | How will we change this codebase? | Engineer | \n| Verify | PR and tests | Does the change meet the agreed behavior? | Engineering team | \n\nThis 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.\n\n`intent.md` example\nImagine an order-planning screen with filters and paginated results. Someone requests a **Select All** checkbox.\n\n“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:\n\n```\n# Intent: Select orders across paginated results\n\nStatus: Draft\nOwner: Order planning team\n\n## Problem\n\nPlanners see only one page of orders at a time. The current selection\nflow makes it difficult to act on all orders matching their filters.\n\n## Desired outcome\n\nPlanners can select every order matching the current filters, even when\nthe results span several pages. The interface shows how many orders\nthe action will affect.\n\nOrders selected individually remain selected when filters change.\nA bulk selection applies only to the filter used to create it.\n\n## Affected users\n\nPlanners assigning orders to vehicles.\n\n## Constraints\n\nThe count displayed in the UI must match the set of orders processed.\nExisting manual selection behavior should remain available.\n\n## Open questions\n\n- Can the API process the active filters directly?\n- If the API requires IDs, how will it obtain IDs across all pages?\n- What should happen if an order stops matching the filter before submit?\n```\n\nThis 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.\n\nNotice 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.\n\n`CLAUDE.md` vs. `spec.md`\nThe filenames look similar, but their jobs differ:\n\n| File | Useful contents | Scope | \n|---|---|---|\n| `CLAUDE.md` | Repository commands, conventions, architecture, recurring pitfalls | Ongoing project guidance | \n| `intent.md` | Problem, desired outcome, affected users, constraints, unknowns | One proposed change | \n| `spec.md` | Requirements and design decisions derived from accepted intent | One defined change | \n| `plan.md` | Steps to implement the spec in the existing codebase | Engineering execution | \n\nAnthropic describes [`CLAUDE.md`](https://academy.claude.com/courses/ai-native-sdlc-playbook/claude-md) as context Claude Code reads for a repository. Its [intent lesson](https://academy.claude.com/courses/ai-native-sdlc-playbook/capture-intent) 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](https://academy.claude.com/courses/ai-native-sdlc-playbook/requirements-and-design).\n\nAn `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.\n\nStart with a problem, not a file path. For example:\n\n```\nHelp me draft an intent.md for this feature. First ask me about the\naffected users, the current problem, the desired outcome, constraints,\nand unresolved questions. Keep the document about behavior and intent.\nDo not choose an architecture or edit code yet.\n```\n\nReview the resulting document yourself or with the person requesting the change. Check especially for statements that Claude inferred but nobody actually approved.\n\nOnce the intent is accepted, move to codebase investigation:\n\n```\nRead intent/select-orders.md and inspect the existing implementation.\nIdentify the UI, state, and API behavior relevant to this request.\nSeparate confirmed facts from assumptions. Propose a spec that preserves\nthe accepted intent and calls out unresolved decisions. Do not implement yet.\n```\n\nAnthropic 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.\n\nFor 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.\n\nThe 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.\n\n**My takeaway:** the faster an AI agent can write code, the more useful it becomes to agree on the intent before it starts.\n\nWould you add `intent.md` to an existing project, or keep this information in your issue tracker?\n\n*Sources: [Anthropic's AI-Native SDLC playbook](https://claude.com/blog/the-ai-native-sdlc-playbook), [Capture as intent.md](https://academy.claude.com/courses/ai-native-sdlc-playbook/capture-intent), and [Requirements and design](https://academy.claude.com/courses/ai-native-sdlc-playbook/requirements-and-design).*", "url": "https://wpnews.pro/news/what-is-intent-md-in-claude-code-a-practical-guide-with-an-example", "canonical_source": "https://dev.to/naelawadallah/what-is-intentmd-in-claude-code-a-practical-guide-with-an-example-506d", "published_at": "2026-09-23 00:48:20+00:00", "updated_at": "2026-09-23 01:22:40.944163+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "ai-products"], "entities": ["Anthropic", "Claude Code"], "alternates": {"html": "https://wpnews.pro/news/what-is-intent-md-in-claude-code-a-practical-guide-with-an-example", "markdown": "https://wpnews.pro/news/what-is-intent-md-in-claude-code-a-practical-guide-with-an-example.md", "text": "https://wpnews.pro/news/what-is-intent-md-in-claude-code-a-practical-guide-with-an-example.txt", "jsonld": "https://wpnews.pro/news/what-is-intent-md-in-claude-code-a-practical-guide-with-an-example.jsonld"}}