Anthropic's 'intent.md' File: Development Strategy in the Age of AI

The 'intent.md' file proposed by Anthropic is a document that clearly defines the intent behind writing a piece of code before the code itself is created. It goes beyond a simple development rule, serving as a crucial starting point for an AI-driven Software Development Lifecycle (SDLC).

This file is a key tool for the efficient utilization of AI agents in the development process, helping to record development intent and ensure all team members understand it.

Currently, the 'intent.md' file is not structured to be directly recognized and read by coding agents like Claude. Therefore, developers must provide separate configurations (e.g., by setting references in Claude.md or Agent.md files) to instruct Claude or other coding agents to read this file.

The five sections included in 'intent.md' (Problem, Proposed outcome, Affected users and systems, Constraints, Open questions) are merely a format recommended by Anthropic and are not yet established as an industry standard, allowing for flexible application.

While traditional SDLC focused on optimizing the build phase, leveraging AI agents has drastically reduced code generation time from weeks or months to mere hours. However, despite this revolutionary shortening of the build phase, subsequent stages like planning, design, testing, deployment, and maintenance still consume significant time and rely on human intervention, creating bottlenecks in the overall development process.

This is based on the recognition that tasks performed manually, such as code reviews and approvals, have not been streamlined to match the speed of AI, leading to inefficiencies in the overall development cycle.

Ultimately, even if agents rapidly generate code, if the remaining processes are manual, there are limitations to overall productivity improvement.

In traditional development, code often lacked a record of its intent, burdening developers with interpreting it during code reviews. While the overall stages of an AI-Native SDLC are similar to a traditional SDLC, there are significant differences in flow and operation for each stage.

Crucially, AI agents actively intervene at all points of the development loop to perform tasks, maximizing AI's role across the entire process, from code intent and design to implementation, testing, and deployment.

In the past, ideas were documented through communication between planners and stakeholders. In an AI-Native SDLC, a system is built to generate 'intent.md' documents through conversations with AI agents like Claude. This means anyone, from customers with ideas to those handling CS tickets, can create documents by communicating with AI.

Consequently, 'intent.md' functions as a 'Single Source of Truth' referenced jointly by humans and agents, playing a key role in clarifying and sharing intent from the earliest stages of development.

In the build phase using AI agents, code writing itself is no longer the bottleneck; the critical bottleneck has shifted to how well AI understands our team's rules. Accordingly, teams must utilize rule files like Claude.md and define individual skills to ensure AI agents adhere to architectural and security standards.

Through this process, technical norms shared by the entire team become ingrained as internal rules for the AI agent, ensuring the quality and consistency of the code generated by AI. In essence, AI functions not merely as a code generation tool but as a development entity that has internalized the team's development culture and norms.

In an AI-Native SDLC, the emphasis is not just on testing code, but also on ensuring consistency when system rules or skills referenced by agents are changed. This can be implemented by triggering automatic execution of 20 to 50 test cases in a CI (Continuous Integration) pipeline when a rule change occurs.

This continuously verifies that results of the same quality as previously deployed features are consistently produced, maintaining the stability and reliability of the entire AI system.

In an AI-Native SDLC, agents perform multi-layered automated reviews to resolve variations in code review quality that can arise from human conditions. This allows humans to maximize review efficiency by focusing only on high-risk core code areas, such as payment or authentication, instead of examining every line of code.

By having agents handle basic reviews, humans can concentrate on more critical decision-making and security issues, thereby enhancing both the stability and speed of the development process.

In an AI-Native SDLC, deliverables generated at each development stage are clearly defined and managed in an integrated manner. First, in the plan phase, an 'intent.md' file defining the intent is created. Following this, in the design phase, a 'spec.md' file is created to define specific specifications based on 'intent.md'.

Then, in the build phase, a 'plan.md' file containing the implementation plan is generated. As such, deliverables from all development stages are accumulated and managed in a single repository, contributing to the establishment of a Single Source of Truth (SSOT) for knowledge.

Since the 'intent.md' file is a document that conveys development intent, it's crucial to create a structure where virtually anyone with that intent, not just a developer, can begin writing it. This involves various stakeholders such as planners, PMs, and CS representatives participating and refining the intent through conversations with AI based on templates.

For example, the 'intent.md' writing process can begin by defining a specific problem, such as a change in delivery status.

In the first step of an AI-Native SDLC, stakeholders draft the 'intent.md' file. This draft then goes through a system that requires approval from the PO (Product Owner).

Once PO approval is complete, the 'intent.md' file is managed by being stored as an MD file within the 'intent' folder in the team's repository.

Both the 'intent.md' and 'spec.md' files are designed to have AI agents create the initial drafts, not humans. The final approval authority for these drafts rests with the PO (Product Owner). This is because these decisions reflect important policies or business objectives.

Conversely, the 'plan.md' file is reviewed and completed directly by developers.

In AI-driven development, creating an SSOT (Single Source of Truth) structure that centralizes all knowledge is extremely important. To achieve this, a structure that integrates all work and knowledge within a single repository, instead of using various tools like Jira or Confluence, is proposed.

By simplifying the development environment to use only GitHub, Slack, and Claude, and by enabling non-developers such as planners or CS representatives to be the authors of 'intent.md', an environment is fostered where all stakeholders can access and contribute to the same information.

When an 'intent.md' draft is created, a PR (Pull Request) is generated and uploaded to GitHub, following a workflow where the team's PO (Product Owner) verifies and approves it. Once this PR is approved and merged, a CI (Continuous Integration) job automatically runs to generate the specification document.

The generated specification document then undergoes another approval process, and upon final approval, a Slack mention notification is sent to the responsible developer, seamlessly connecting to the next stage of the development process.

Anthropic's proposed initial structure starts from the perspective that the 'Intent' is the beginning of all development. Therefore, creating an 'intent' folder in the project's root directory is fundamental.

Within this 'intent' folder, subfolders are created for each feature or problem (slug), and these contain three core files: 'intent.md', 'spec.md', and 'plan.md', systematically managing everything from development intent to design and planning.

When creating an intent, a GitHub PR (Pull Request) is generated through a separate intent branch. This PR includes only the 'intent.md' file, and once the responsible party's review is complete, merging the PR is considered the stage of formally approving the intent.

Subsequently, spec PRs and plan PRs proceed sequentially, ensuring all stages from development intent to implementation planning are transparently managed and approved based on PRs.

For efficient intent management, it is crucial to create only one intent, one spec, and one plan per folder. If more than one spec is needed within a single folder, it suggests the need to break down the higher-level feature unit into smaller parts, thus separating the intent itself into two.

Furthermore, if coexistence with existing legacy systems is necessary, a gradual and phased adoption of AI-Native SDLC is recommended rather than a full, immediate implementation.

The core value emphasized in this video regarding the adoption of AI-Native SDLC is the importance of clearly communicating intent when using AI. Unlike traditional development lifecycles, it is becoming crucial to introduce AI as much as possible at every development stage to generate drafts, allowing humans to approve only essential parts.

This contributes to reducing the cost of interpreting intent during code reviews and maximizing the overall efficiency of the development process.