Contents
As AI shortens coding time, planning, review, testing, and releases determine how long development takes overall. This playbook focuses on adapting the SDLC for AI and establishing human decision points for each artifact.
Key Takeaways#
- Connect the six stages from planning to maintenance through artifacts rather than manual handoffs.
- Version-control
intent.md,spec.md, andplan.mdto preserve a record of decisions and changes. - Share organizational knowledge through
CLAUDE.mdand skills, and enforce mandatory rules with hooks. - Have AI handle testing and review so people can focus on areas requiring judgment, such as intent and risk.
- Start with one task, record the time spent and rework required, then expand.
Connect the Six Stages Through Artifacts#
In an AI-native SDLC, each stage reads the artifacts from the previous one. The primary artifacts are intent.md for planning, spec.md for design, plan.md and code for building, execution results for testing, review records for deployment, and incident records for maintenance.
Keeping these in the repository makes change history easier to trace. Organizations using Jira or requirements management tools should decide which system is the official source of record and link to it from the other. Even if you begin by maintaining both, record the record ID in the artifact and the commit SHA in the existing system.
A person approves each stage, and that approval becomes a prerequisite for starting the next task. Once this process is established, you can consider automating subsequent work, such as generating a specification from an approved intent.md.
From Intent to Implementation Plan#
First, the person proposing the idea creates intent.md through a conversation with Claude. Documenting the problem, desired outcome, affected users and systems, constraints, and open questions lets you begin exploring without waiting for a formal requirements document. The product owner reviews the content before it is committed and decides whether it can proceed to the next stage.
After approval, Claude creates spec.md based on the organization’s rules, and the product owner reviews it. Next, an engineer uses Claude Code’s plan mode to create plan.md, covering files to change, task order, testing methods, and risks. Implementation begins after the engineer approves the plan.
This sequence helps uncover design problems before coding begins. If implementation deviates from the plan, update both the code and the plan so they can be checked against the diff later.
Bring Organizational Knowledge Closer to the Code#
Use CLAUDE.md to document build and test commands, important design conventions, and common agent mistakes. Rather than keeping everything generated by /init, narrow it to information useful at the start of a task and share it in the repository. One useful cue for adding a correction is when Claude repeats the same mistake.
Organizational rules for security and API design can be packaged as skills. However, skills are instructions to AI, not a mechanism that guarantees compliance. Mandatory rules, such as blocking changes containing credentials or preventing edits to protected files, should also be checked through hooks or CI.
For parallel work, use a separate Git worktree for each task. A practical approach is to start with two or three sessions and add more as review capacity allows.
Speed Up Testing and Review#
Enable Claude to run tests, builds, and lint checks during development. Define completion criteria clearly and require results in reports so problems can be fixed before human review. For bug fixes, one approach is to first write a failing test that reproduces the issue, then make the fix pass that same test without modifying it.
For UI changes, compare screenshots against approved mockups. The playbook suggests two or three rounds of revision as a guideline. What matters more than the number is establishing a loop that uses test and visual comparison results to drive improvements.
You can also add evaluations to CI to check Claude’s configuration. Collect 20–50 tasks from actual work and record their prompts and pass criteria. Run them when changing models, skills, hooks, or similar settings, and investigate changes that lower the pass rate. Adding production incidents to the evaluations also makes recurring problems easier to detect.
Keep People Involved in Releases and Maintenance#
In PRs, AI reviews changes against organizational rules and lists findings by severity. People can focus on the intent and risks of the changes and on significant findings, rather than reading every line at the same depth. Retain human approval for regulated code and high-impact changes.
After merging, use production monitoring results to inform the next improvements. Investigate events that fall outside operational thresholds and, where needed, incorporate them into a new intent.md or regression tests. This turns maintenance into a loop back to planning rather than a separate endpoint.
Track effectiveness through metrics such as time to create a specification, the share of implementations merged on the first attempt, CI first-pass rate, review time, and rework count. Record baseline values before adoption and compare the same metrics. Alongside numerical changes, assess review quality and incidents.
Next Step#
Choose one small upcoming change, create intent.md and plan.md, record them in the repository with the test results, and measure the time from planning to merge and the number of rework cycles.
Source: https://claude.com/ja/resources/articles/the-ai-native-sdlc-playbook
Contents
