Claude Code 中的 intent.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. 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? Enter fullscreen mode Exit fullscreen mode 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. Enter fullscreen mode Exit fullscreen mode 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. Enter fullscreen mode Exit fullscreen mode 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.