In practice the intent stage produces one artifact, intent.md, which I treat as a regulated record from day one. An intent.md is a short, version-controlled Markdown file that records the ask, the reason behind it, and the constraints it has to respect — committed before anyone designs or builds anything. It is the file Claude Code reads before it plans. Anthropic introduced the convention on August 21, 2026 in The AI-Native SDLC playbook, where it is the first of six artifacts in a loop that runs intent, spec, plan, diff, pull request, incident record, and back to intent again. There is now a course for engineering leads built around it.
My argument in this post is narrow and I will state it up front. Most teams will read intent.md as a developer nicety, a tidier ticket. It is not. The three questions it answers — who asked for this, why, and under which constraints — are the questions an examiner asks, and the file is already shaped like the evidence they want. Treat it as a regulated record on day one, or spend two years retrofitting one.
What the file actually holds
The originator writes it, and the originator does not have to be an engineer. In Anthropic’s worked example the author is a claims operations manager, and the file has five parts: the problem, the proposed outcome, the affected users and systems, the constraints, and the open questions. The constraints line in that example is one sentence about not putting new personal data into a portal session. That single line is the whole idea in miniature — a business person’s limit, captured in a place an agent will read.
The mechanics matter more than the template. Claude drafts the file from a conversation, the product owner corrects it, and only then does it get committed to a shared folder in the repository. Author and timestamp come along for free. Acceptance is what triggers the design pass, so nothing downstream happens until a human has signed off on the why. And in the maintenance stage the loop closes on itself: a monitoring agent that detects a breached control band writes its diagnosis as a new intent.md, in the same format a human would have used.
Anthropic is direct about what the resulting commit chain is. It is the audit trail: “who asked for what, what the agent produced, and who approved it.”
It is not CLAUDE.md, and it is not quite an ADR
Two comparisons will save an architecture review a lot of confusion.
CLAUDE.md and AGENTS.md are instructions to the agent — build commands, conventions, what not to touch. They are standing context, they apply to every change, and AGENTS.md in particular has become a genuine cross-vendor convention since OpenAI released it in August 2025, now sitting under the Linux Foundation with tens of thousands of repositories using it. intent.md is the opposite kind of object. It is a record of human purpose for one specific change, and it applies exactly once. Conflating the two is the mistake I see most often, and it is expensive, because a governance program built on the wrong file governs the agent’s habits rather than the organization’s decisions.
The closer relative is the architecture decision record, which enterprises have been writing since Michael Nygard proposed the format in 2011. An ADR captures a decision and its rationale after a choice has been made. intent.md captures a problem and a desired outcome before design begins. And an ADR is passive — a log somebody reads years later, if ever — while an accepted intent.md fires the next stage of an automated pipeline. Call it an ADR for the request rather than the decision, machine-actionable, with a human approval on the front of it.
The wider industry landed on the same instinct with different vocabulary. GitHub open-sourced its spec-driven toolkit in September 2025 with the line that intent is the source of truth rather than code, and Kiro built a requirements-design-tasks chain on the same premise. What is distinctive about Anthropic’s version is that it names intent as its own artifact upstream of the spec, and gives it a non-engineer owner.
More on the AI-Native SDLC
- The Definition: What separates an AI-native lifecycle from an AI-assisted one, in three tests that have nothing to do with which model you bought.
- Playbook, Mapped: I take Anthropic’s six lifecycle stages one at a time and name the discipline it omits in the mapping post.
- Adoption Order: All sixteen plays sorted onto the Five-Stage Roadmap, with what to hold back at each stage.
- Govern the Harness: The controls wrapped around the model, not the model itself, are what an enterprise actually governs.
- A Missing Boundary: An agent deleted a live production database during a declared code freeze, which is what an absent approval gate looks like.
Rationale capture has failed before
Engineers do not do unpaid documentation work whose payoff arrives years later, for someone else. A 2023 study in Requirements Engineering asking why practitioners still don’t trace found the same two barriers that killed the earlier tools — cost, and the stubbornly manual nature of the work — even among people who believe tracing is worth it.
Two things are structurally different now, and I think they are enough to be interesting. The model does the writing, which takes most of the cost out of capture. And the file pays back immediately rather than eventually, because accepting it is what generates the spec. Capture as a byproduct of getting your work done is precisely the condition the research says was always missing.
How to tell whether yours is theater
Watch two numbers. If your acceptance rate is near a hundred percent, nobody is reading these. If product owners are spending under a minute per file, the model is writing intent and a human is stamping it, which is a diligence costume rather than a record.
That failure mode is not hypothetical. Stack Overflow’s 2025 developer survey found forty-six percent of developers distrust the accuracy of AI output against thirty-three percent who trust it, and two-thirds named answers that are almost right as their leading frustration. An almost-right intent file is worse than a missing one, because everything downstream inherits it with confidence. Nor is the productivity case settled: Google’s 2024 DORA research associated rising AI adoption with a 7.2 percent drop in delivery stability, and ThoughtWorks still has spec-driven development in the assess ring of its radar, not adopt.
So my recommendation is deliberately small. Pilot this in one regulated repository, keep the survival rate honest, and make the compliance function a reader of the folder from the first week rather than the last.
The bottom line
intent.md is the sentence I have been repeating for more than a year turned into a file format. Instructions in, results out was IT. Intent in, outcomes out is agentic AI, and this is the first time the intent has had somewhere durable to live. My frameworks are laid out in full in my two books, Agentic AI and Earned Autonomy.
If your regulator asked tomorrow why your last production change was made, would you hand them a file with an author and a timestamp on it, or would you go and find the person who remembers?
Go deeper
- Agentic AI Architect: control design for enterprise agents.
- Agentic AI Case Studies: deployment evidence, one teardown at a time.
- Agentic AI P&L: cost, payback, and risk in a CFO’s voice.
- Agentic AI Governance: who owns the harness.
- Substack first access: agenticaiarch.substack.com/subscribe
© Dr. Harish Kotadia, Ph.D., All Rights Reserved, 2026.
Dr. Harish Kotadia, Ph.D., is an Enterprise AI Architect with 20+ years of IT consulting experience serving Fortune 100 clients, specializing in agentic AI systems built on Anthropic Claude, AWS Bedrock, and Google Vertex AI.
Disclaimer: This blog post is based on publicly available academic publications, vendor documentation, open standards, and news items from reputed media sources linked above. This post is intended for educational purposes, to help the enterprise agentic AI community build a shared vocabulary from public, authoritative sources.
Views and opinions expressed here are my own and do not represent those of any employer or client, past or present. The analysis presented is my independent interpretation of the published sources linked above and does not constitute legal, financial, or consulting advice of any kind.