
AI SDLC: From Intent to Done
Build the right things, and build things right, when AI writes most of the code. How intent, spec, plan and CLAUDE.md files turn the software lifecycle into a loop with human judgment at the gates.
12 min read
- AI SDLC
- Spec-Driven Development
- Engineering
- Product Management
- AI Strategy
Build the right things, and build things right, when AI writes most of the code
I am writing this for myself, and for every product and engineering leader who has watched agents write code faster than their process can keep up with.
For a long time, writing code was the slowest part of shipping software. Everything around it, the requirements, the designs, the reviews, the sign-offs, was built to protect that expensive step. That is no longer true. So I sat down with Anthropic's AI-native SDLC playbook, put it next to how I actually work, and wrote down what came out, one piece at a time.
Why We Got Here

The traditional software lifecycle was built for a world where writing code was the slowest and most expensive step. Product managers wrote requirements, architects turned them into designs, engineers built them, QA verified them, release teams shipped them, and operations watched production. Work moved between those phases through documents, tickets and sign-offs.
That world has changed. Agents now write code at a speed that was hard to imagine a year ago, while the process around the code has barely moved. As the playbook puts it, "Build is no longer the constraint — the human-speed steps around it are."
The bottleneck has moved to the steps on either side of the build: planning, review and testing, and deployment. Reviewing every line by hand made sense when a person wrote it. It cannot keep up once agents write most of the change.
The process was designed for human builders. So it is time to apply first-principles thinking.
Insight: When the build gets fast, the slow parts around it become the whole problem.
A Loop, Not a Line

The playbook describes six stages: Plan, Design, Build, Test, Deploy and Maintain. They run as a loop instead of a straight line, with AI at every stage and people accountable for every decision that needs judgment.
The thread running through it is simple: "Every stage commits an artifact the next stage can read." Each stage ends by writing a file to version control, and the next stage begins by reading it. In the early stages those files are Markdown, because a product owner and an agent can both read and act on the same file. Together they become the audit trail: who asked for what, what the agent produced, and who approved it.
I think of this as two kinds of discipline:
Build the right things. Capture the intent and the spec before anyone plans the code.
Build things right. Agree on a plan, let every session check its own work, and keep a human at the approval gates.
Most teams are already good at the second one. The first one is where most of the value, and most of the waste, actually lives.
Insight: Building things right only matters if you are building the right things.
Four Files Carry Most of the Work

Four files carry most of the work. The playbook shows worked examples of the intent, the plan and CLAUDE.md, and I use its intent and plan examples below.
File | Stage | What goes in it |
|---|---|---|
Plan | Problem, proposed outcome, affected users and systems, constraints, open questions | |
Design | Requirements and design, shaped by brand, security, compliance and UX rules, with areas of concern flagged | |
Build | Files that change, order of work, risks, and the proof that it works | |
Build | Commands, conventions, architecture, and the mistakes the agent keeps making |
intent.md
The intent is a short proto-spec in the originator's own words. It says what is wanted, why, and under which constraints.
The originator describes the problem to Claude and brainstorms until the idea is concrete. Claude asks the questions an analyst would ask: scope, users, constraints and what success looks like. Claude then writes the intent using the organization's template, and the originator corrects anything it misunderstood. The product owner reviews it and decides whether it is accepted into Design.
spec.md
Once the intent is accepted, Claude turns it into a requirements and design spec. The organization's skills for brand, security, compliance and UX guide it, so policy is applied while the spec is written instead of being discovered weeks later in a review.
The product owner reviews the spec but does not write it. They check two things: does it solve the stated problem, and are the intent's open questions answered or carried forward? Any concerns the agent flagged, especially contradictory policies, are resolved with the policy owner before engineering sees the spec. The playbook does not prescribe a fixed spec template.
plan.md
The plan comes from plan mode, where the agent can read the codebase without changing anything. It names the files that change, the order of the work, the risks, and the tests that prove it.
The playbook's bar is that an engineer who never saw the conversation could build the change from the plan alone. Review later checks the code against the plan. When the build departs from the plan, the plan is updated in the same commit.
CLAUDE.md or AGENTS.md
This file gives the agent the context a new joiner needs on day one: build, test and lint commands, the conventions that matter, the architecture, and the things the agent keeps getting wrong.
It sits at the repo root, is reviewed like code, and stays under a page because the agent reads all of it at the start of every session. The working rule: when the agent makes a mistake twice, the correction goes into the file. The playbook calls it CLAUDE.md. If you use more than one tool, AGENTS.md is the shared format that Cursor and others read.
It reminds me of the onboarding notes every good team lead keeps for new hires. The difference is that this new hire reads every word, every single morning.
Supporting files
Skills hold institutional knowledge that must be applied consistently, such as a security standard or an API convention.
Hooks are scripts that allow, ask or block an action. They are the deterministic layer behind advisory skills.
REVIEW.md defines the review passes: bugs, security, and compliance against the spec, the plan and the design principles.
Evals are real tasks with checks, run whenever the agent's configuration changes, so you know it still works to standard.
Insight: If it is not written down in a file the next stage can read, it did not really happen.
A Day in the Life: New Feature

The playbook follows one example from start to finish: claims status self-service.
Capture the intent
Someone in claims operations notices that customers phone the contact center just to ask where their claim is. She brainstorms with Claude, and Claude writes the intent:
# Intent: claims status self-service
Author: J. Ortiz (claims operations). Status: draft.
## Problem
Customers phone the contact center to ask where their claim is.
Handlers spend roughly a third of call time on status-only queries.
## Proposed outcome
Customers see claim status, next step and expected date in the portal.
## Affected users and systems
Claims handlers, portal team, claims-core API.
## Constraints
No new PII in the portal session. Existing authentication only.
## Open questions
Do third-party loss adjusters need access too?She corrects what Claude misunderstood, and it is committed to the intent/ folder in the product repo. The product owner picks it up from there.
Notice who started this. Not an engineer, not a product manager. Someone close to the actual problem.
Shape the spec
The product owner opens a session with the organization's skills and attaches the intent. The playbook's prompt asks Claude to read it, produce a requirements and design spec for the existing codebase, apply the brand, security and UX skills, and clearly describe any concerns, especially where policies contradict each other.
For front-end work like this portal panel, the product owner can mock the design from the intent, iterate on it, and hand it to the build. The spec is committed alongside the intent, so the pair records what was asked for and what was decided. A human always decides whether it moves to Build.
Agree on the plan
An engineer starts in plan mode with the intent and the spec. Claude reads the code, interviews the engineer, and proposes a plan. The engineer pushes on it: what could this break, which step is riskiest, what options did you rule out? The approved plan looks like this:
# Plan: claims status self-service (from intent.md 2026-06-02)
## Files that change
portal/src/claims/StatusPanel.tsx (new), claims-api/routes/status.py,
claims-api/tests/test_status.py
## Order of work
1. Add the status endpoint behind existing auth.
2. Panel against the endpoint.
3. Wire into the portal nav.
## Risks
The claims-core API rate-limits at 50 rps; the panel must cache.
## Proof
test_status.py covers the four claim states; screenshot matches the
approved mock.Plan mode enforces the order, because the agent cannot edit files until the plan is accepted. Changing course at this point means editing a document, not rewriting code. With a solid plan, the build is often a single pass.
It is the same reason I prep every ingredient before I start cooking biryani. Once the pot is on the fire, it is too late to discover you are out of saffron.
Build, check, review
The session checks its own work as it goes. The target is concrete: the tests in test_status.py pass and the screenshot matches the mock. Two or three rounds of screenshot, compare and adjust is normal for UI work. Before saying it is done, the agent runs the tests and shows the output.
The pull request then goes through review passes for bugs, security, and compliance with the spec and the plan. Findings are ranked by severity, and the human reviewer focuses on whether the change does what the plan intended and whether the risk is acceptable. The agent that wrote the code has no way to approve it. A code owner approves through branch protection.
Insight: Changing a plan costs a few edits. Changing code costs a few days.
A Day in the Life: Updated Feature
The playbook does not prescribe a separate flow for updates, but it gives the signals. It counts changes to an intent after the spec is written, and spec changes after the plan is written, as rework to measure. It also requires the plan to change in the same commit whenever the build departs from it.
Here is how I apply that. The intent above left one open question: do third-party loss adjusters need access too? If the answer later becomes yes, that is new intent. It gets its own short intent.md covering what changes, why and what must not break. Then it goes through spec, plan and review like any other change. The original files stay as the record of what was built and why.
Insight: Don't rewrite history. Add a new chapter.
A Day in the Life: Bug Fix
Bugs follow the playbook's feedback loop. First the agent reproduces the bug as a test, runs it, and confirms it fails for the expected reason. That test is committed. Only then does the agent make it pass, without editing the test. A hook can block test edits during a fix, so the agent cannot weaken its own check. A test that existed before the fix, and that the agent could not rewrite, is proof the bug is gone.
Size decides the route. A small, well-bounded fix goes straight to a pull request through the review gate. Anything larger, such as an architectural weakness or a pattern repeated across services, is written up as an intent and starts at Plan.
When the fix ships, the incident gets an eval that stays in the suite, so the same class of problem is caught from then on.
Insight: Never let the one being tested also grade the test.
A Day in the Life: Maintenance

This is where the loop closes. A deterministic script watches a metric such as post-deploy errors or CI test failure rate. When it breaches a control band, it invokes Claude with no person in the path.
At a small breach the script only logs. At a larger one Claude diagnoses, with read-only access. At the highest tier Claude may act, but only by opening a pull request into the review gate or running a pre-approved runbook such as a rollback. What it finds is written as a new intent.md, with the evidence, a proposed outcome, the affected systems and open questions. An on-call engineer triages it, and the cycle starts again.
Insight: Production is not the end of the line. It is where the next intent gets written.
How It Looks in a Repository
The playbook recommends an intent/ folder in the product repo, with CLAUDE.md and REVIEW.md at the repo root. Where the spec and plan sit is your choice. I keep each change's files together:
repo/
├── CLAUDE.md # or AGENTS.md
├── REVIEW.md
├── intent/
│ └── claims-status/
│ ├── intent.md
│ ├── spec.md
│ └── plan.md
└── .claude/
├── skills/
├── agents/
└── settings.json # hooksThe playbook is written for Claude Code. In Cursor, the same ideas live in .cursor/rules, .cursor/skills and .cursor/plans, with AGENTS.md read from the root, as described in Cursor's documentation.
Design Principles I Hold Onto
Ideas stop waiting for someone to write them up
Intent is captured once, in the originator's own words, as a version-controlled file the next stage can act on. Anyone with an idea can start the process.
Policy is applied while the spec is written
Brand, security, compliance and UX rules are encoded as skills and shape the spec from the start. Conflicts surface before engineering begins.
Nothing is implemented without an accepted plan
The plan is reviewed while changing course is still a matter of editing a document. Review later checks the code against it.
Every session checks its own work
A session is done when its checks pass and the output is shown. The check itself is protected, so the agent cannot weaken it.
The agent that wrote the code cannot approve it
Automated review ranks the findings. A human makes the call through branch protection.
Advisory rules need a deterministic backstop
A skill makes violations rare. A hook makes them close to impossible. Policies that must always hold get both.
Mistakes become rules
A mistake made twice goes into CLAUDE.md. A production incident becomes a permanent eval.
The agent stops at the production gate
The agent may do everything up to the production gate and nothing past it. A named release manager authorizes the release.
Where to Start
The AI-native SDLC playbook from Anthropic, for every stage with templates and examples.
Claude Code best practices, for planning, verification and review in daily use.
GitHub Spec Kit, for a step-by-step spec-driven flow.
AGENTS.md, for a rules file that works across tools.
Cursor plan mode, for planning before building in Cursor.
Where Human Judgment Goes Now
When the build collapses to hours, the work that matters moves to the gates. Human attention concentrates there, on reviewing what the agent flagged instead of starting each stage from scratch.
Roles change with it. Anyone with an idea can turn it into an intent. Product owners review and decide instead of writing specs by hand. Engineers move from writing every line to steering several sessions and reviewing what they produce, and eventually to building and monitoring the loop itself.
The playbook ends with the line I keep coming back to: "The loop keeps running. Human judgement stays above it."
Insight: The machines can run the loop. Deciding what is worth building is still our job.
To self and to curious folks out there, keep building, keep checking, and have fun.
8 views
Respond
Select a passage if you want it included. Your email is never shown. I read each response before it appears here.