Intent.md Reshapes AI Development: Anthropic's New Paradigm for Agent Collaboration

The Anthropic team recently released a practice handbook for AI-native Software Development Life Cycle (SDLC), with the core concept of restructuring traditional development workflows through Intent.md files. This methodology was proposed by the Claude Code creator Veris Cherney's team, aiming to deeply integrate AI agents into the entire process from requirements to maintenance.

A Paradigm Shift: From Code Bottleneck to Process Bottleneck

The Software Development Life Cycle (SDLC) is a framework model in software engineering that describes the entire process of software from concept to retirement. Classic waterfall models, agile development, DevOps, and other methodologies are all specific implementations of SDLC. In traditional SDLC, the build (coding) phase typically accounts for 30-50% of the total project time cost, as it requires manually writing and debugging code line by line. Meanwhile, testing and maintenance phases often consume 60-70% of total software costs, which is why the industry has been exploring automated testing, continuous integration, and other practices to optimize these stages.

Traditional SDLC comprises six phases: planning, design, build, test, deployment, and maintenance, with the build phase being the most time-consuming and costly. But the emergence of AI agents has changed this landscape — the build phase has been dramatically compressed, with speed improvements of 2x or more. An AI Agent refers to an artificial intelligence system capable of perceiving its environment, making autonomous decisions, and executing tasks. Unlike traditional conversational AI, agents possess tool-calling capabilities — they can read and write files, execute commands, call APIs, and more, rather than merely generating text. Large language models like Claude and GPT-4 have empowered AI agents through mechanisms such as Function Calling and Tool Use. In software development scenarios, agents can operate IDEs, run tests, and commit code just like human developers, but at speeds several times or even tens of times faster.

The key question Anthropic raises is: how can agents optimize all the other phases? This marks a fundamental shift in development bottlenecks — code writing is no longer the limiting factor; process design is. The new paradigm requires us to re-examine the human-machine collaboration model at every phase, and Intent.md is the core artifact of this system.

Intent.md: A New Interface for Human-Machine Collaboration

What Is Intent.md

Intent.md is a requirements document that is both human-readable and machine-parseable. The Product Requirements Document (PRD) is the standard way of expressing requirements in the tech industry, typically written by product managers and containing user stories, feature lists, acceptance criteria, and other structured content. Traditional PRDs suffer from obvious information loss: the customer's original pain point → the product manager's understanding → the developer's technical solution — each layer of translation can deviate from the original intent. Agile development introduced User Stories and Story Points to refine requirements, but these still involve multi-layer handoffs between humans.

The revolutionary aspect of Intent.md lies in bypassing the intermediary layers — through AI agents engaging directly in dialogue with the requirement initiator, encoding tacit knowledge (such as business context, constraints, and historical decisions) directly into the document, dramatically reducing "requirement misunderstanding" — the number one cause of software project failure. It is generated through deep conversation between the agent and the requirement initiator, directly capturing source pain points and context.

The creation process involves three steps:

1. Agent Interview: Use Discovery skills (such as Switch Dimension Discovery or Cursor Requirements Discovery) to have the agent ask questions repeatedly until it fully understands the requirements
2. Context Injection: The requirement initiator feeds domain knowledge, experience, and constraints extensively into the conversation
3. Document Generation: The agent synthesizes the information and saves it as /intent/*.md files

The key advantage is eliminating the multiple translation losses in traditional workflows — requirements no longer pass through user stories, story points, backlog items, and other layers, but flow directly from the initiator to the agent.

Who Can Create an Intent

The initiator of an Intent can be anyone:

• A customer filing a bug report
• A product manager with a feature idea
• A developer documenting process improvements

This openness breaks through the hierarchical constraints of traditional requirements management. All Intents are aggregated and then reviewed and categorized by the product owner, who can use a tagging system (frontend/backend, large task/small task, priority, etc.) for management, and can even have agents auto-classify them.

The Artifact Chain: From Intent to Deployment

An artifact in software engineering refers to a deliverable produced during the development process, such as requirements documents, design diagrams, code, and test reports. In traditional development, these artifacts are often scattered across different tools (Jira, Confluence, GitHub) with no organic connection. The Intent → Spec → Plan → Code artifact chain draws on the concept of Documentation-Driven Development but adds machine readability — each document serves both as a record of human decisions and as input for downstream agents. This design enables AI to maintain contextual coherence throughout the entire SDLC, rather than starting from scratch to understand requirements at each phase.

Spec.md: Auto-Generated Technical Specifications

Once an Intent is approved, Spec.md generation is triggered through hooks or automated workflows. A hook is an event-response mechanism in programming, originating from the interrupt handling concept in operating systems. In modern software development, Git Hooks, Webhooks, and CI/CD Pipelines are all applications of hooks — when a specific event occurs (such as a code commit or issue creation), a predefined action is automatically triggered. Anthropic's mention of "triggering Spec.md generation through hooks" extends this mechanism to AI workflows: when an Intent.md is approved, an agent is automatically invoked to perform the transformation task.

Anthropic provides prompt templates that can transform Intents into detailed requirements and design specifications, applying style guides and best practices.

Key practices:

• Use Agents.md or skill libraries to ensure specifications comply with organizational governance standards
• Native plan mode (Cursor/Claude Code) can directly generate specifications
• Custom skills can generate spec documents in team-specific formats

Plan.md: An Executable Implementation Plan

Engineers pull the Intent and Spec, then generate Plan.md through plan mode. This document should be detailed enough to be handed off independently to any engineer for execution, without needing to reference upstream documents.

Plan.md structure includes:

• List of files to be changed
• Work order and task list
• Risks and constraints
• Success criteria and verification checks

During review, repeatedly ask "what could go wrong" to ensure the plan's completeness.

Balancing Autonomous Execution and Governance

Permission Design for Auto Mode

Anthropic recommends using auto mode in controlled environments, but only after establishing a comprehensive permission system:

• Clearly define the scope of tools the agent can access
• Lock down allowed network sources and dependency packages
• Implement policies through Cursor or Claude permission systems

Only after policy tuning is complete should agents be allowed to operate at full speed without human supervision.

Multi-Agent Collaboration

Worktree is a feature introduced in Git 2.5+ that allows checking out multiple branches simultaneously into different directories within the same repository, enabling true parallel development without cloning multiple copies of the code. Traditionally, developers needed to frequently switch branches (git checkout) or maintain multiple repository copies, resulting in high context-switching costs. In AI-native development, the value of worktrees is amplified: multiple agent instances can each work in independent worktrees handling different tasks (e.g., one fixing bugs, another developing new features), without interfering with each other.

Modern development environments support worktrees and sub-agents, enabling:

• Multiple agents to process different tasks in parallel
• Each agent to work within an independent context window
• Information to be passed through artifact documents (Intent/Spec/Plan) rather than conversation history

The context window is one of the core limitations of large language models, referring to the maximum amount of text (measured in tokens) the model can process at once. Early GPT-3 supported only 4K tokens (approximately 3,000 English words), while Claude 3.5 currently supports 200K tokens. Conversation history and codebase content all consume the context window, and once the limit is exceeded, the model "forgets" earlier information. This is why the traditional approach of "one conversational AI completing an entire project" is infeasible — the codebase of complex projects easily exceeds millions of tokens. Anthropic's multi-agent + artifact-passing approach cleverly circumvents this limitation: each agent only needs to understand the current task's Intent/Spec/Plan (typically a few thousand tokens), without loading the entire project history.

This architecture avoids the limitations of a single context window, making parallel development of large projects possible.

Code Review and Quality Gates

Visual testing is an important branch of UI testing that detects interface changes through screenshot comparison. Traditional functional testing only validates DOM structure and interaction logic and cannot capture CSS rendering errors, layout breakage, and other visual issues. Modern testing frameworks like Playwright and Cypress support pixel-level screenshot comparison, capable of detecting shifts as small as 1 pixel. In AI-native development, agents can automatically generate test cases, run Playwright scripts, and analyze visual differences — this is especially important in rapid iteration scenarios, where manual visual inspection is costly and prone to oversight.

The testing phase introduces multiple layers of automated verification:

1. Agent Self-Testing: Writing and running unit tests and end-to-end tests
2. Code Linting: Running linters and build verification
3. Visual Testing: Using Playwright/Cursor Browser for UI testing and screenshots
4. PR Review: An independent Claude instance reviews pull requests based on security policies

Autonomous Diagnostics in the Maintenance Phase

Observability is one of the three pillars of modern cloud-native architecture (alongside microservices and containerization), providing comprehensive understanding of system runtime status through the three pillars of Logs, Metrics, and Traces. Traditional monitoring is passive — setting threshold alerts and responding manually when limits are exceeded. Proactive Monitoring combined with AI capabilities can achieve anomaly prediction and autonomous diagnostics: using machine learning to identify abnormal patterns in metrics (such as sudden traffic drops or error rate spikes), triggering response processes before the impact of failures escalates.

The most forward-looking part is the automation of the maintenance phase. Traditionally, maintenance is reactive — waiting for alerts or tickets. In AI-native workflows, agents can:

1. Proactive Monitoring: Automatically triggered based on metric anomalies (page crashes, API throttling)
2. Autonomous Diagnostics: Analyzing logs and generating problem Intent.md files
3. Solution Recommendations: Providing diagnostics and fix suggestions before human intervention

For example, when a server fails at 3 AM, the agent has already completed preliminary diagnostics and generated an Intent. When the engineer wakes up, they can review the proposed solution instead of starting the investigation from scratch. This embodies the AIOps (AI for IT Operations) philosophy — transforming operations from firefighting-style responses to preventive governance.

Evaluation and Continuous Optimization

Continuous Evaluation is a key practice in machine learning systems engineering, similar to Continuous Integration (CI) in software engineering. Since large language models are periodically updated (e.g., Claude 3.5 Sonnet → Claude 4), or teams adjust their prompts and skill libraries, it's necessary to verify whether these changes improve or degrade AI performance on actual tasks. A benchmark dataset typically contains 20-100 real cases covering common scenarios and edge cases. After each change, evaluations are run to detect whether metrics such as accuracy and generation quality have regressed — this is consistent with A/B testing, canary releases, and other gradual rollout strategies, ensuring that AI capability iterations are controllable and verifiable.

Anthropic recommends establishing a continuous evaluation system:

• Collect 20 typical issues from the codebase as a benchmark test set
• Run evaluations each time a model is upgraded or skills are updated
• Detect whether any regression has occurred in the SDLC process

This approach extends traditional CI/CD continuous integration into "continuous evaluation," ensuring that AI capability improvements genuinely translate into process improvements.

Implementation Recommendations and Caveats

This methodology is not a reason to tear down your existing workflows. If you're already using Superpowers, BMAT, or a custom-built system, you should:

• Incrementally adopt core concepts like Intent.md
• Retain effective practices your team has already validated
• Adjust the depth of human review involvement based on project criticality

There is no one-size-fits-all solution. From simple plan mode to complex orchestration systems, the key is finding the right human-machine collaboration balance for your team. The governance framework (permissions, hooks, linting) is a prerequisite for ensuring safety and quality and should not be skipped.

Conclusion

The essence of the Intent.md paradigm is making tacit knowledge explicit and making ephemeral conversations persistent. It is not merely an innovation in document format but a restructuring of development collaboration models — from humans writing code by hand to humans defining intent while agents handle implementation. As multi-agent collaboration and autonomous maintenance capabilities mature, every phase of the SDLC is being redefined. For teams looking to build AI-native development workflows, this practice handbook provides an actionable starting point.