AI-DLC methodology

The AI-Driven Development Lifecycle (AI-DLC) is a post-Agile software development methodology that combines systematic planning with AI-augmented execution and built-in governance. It addresses known limitations of Agile while leveraging large language models for requirements analysis, design, and code generation.

What is AI-DLC and why it exists

Agile revolutionized software development, but it introduced trade-offs that teams continue to struggle with: documentation gaps, a "just start coding" culture, weak governance, and manual requirements gathering that often produces incomplete or vague specifications.

AI-DLC does not replace Agile. It evolves Agile for the AI era by reintroducing systematic planning where it matters, automating the tedious parts of requirements and design, and adding approval gates that keep humans in control of every critical decision.

The result is a framework that moves faster than traditional methods while producing more thorough documentation and a complete audit trail.

The three phases

AI-DLC organizes work into three sequential phases, each with a clear focus.

Phase 1: Inception (planning and architecture)

Focus: determine WHAT to build and WHY.

Inception always executes three core stages:

1. Workspace detection -- scan existing code to determine brownfield vs. greenfield context
2. Requirements analysis -- the interactive agentic questionnaire (see key innovation below)
3. Workflow planning -- determine which stages to execute in the rest of the lifecycle

Inception conditionally executes additional stages based on complexity:

• Reverse engineering -- analyze existing codebase (brownfield only)
• Feasibility analysis -- competitive landscape scan and go/no-go scoring (product features only)
• Value case -- ROI analysis with cost estimation and scenario modeling
• User stories -- persona-based acceptance criteria
• Application design -- component and service architecture
• Units generation -- decompose the system into work units

Phase 2: Construction (design and implementation)

Focus: determine HOW to build it.

Construction operates as a per-unit loop. Each unit of work completes fully before the next one begins. Within each unit, these stages may execute:

• Functional design -- data models, business logic, business rules
• NFR requirements -- performance, security, scalability, tech stack decisions
• NFR design -- patterns for implementing non-functional requirements
• Infrastructure design -- cloud resources, deployment architecture
• Code generation -- two-phase approach (plan, then execute) with comprehensive tests

After all units finish, a Build and test stage generates comprehensive build, unit test, and integration test instructions.

Phase 3: Operations (deployment and monitoring)

Focus: how to DEPLOY and RUN it.

Operations is currently a placeholder for future expansion. Planned capabilities include deployment planning, monitoring and observability setup, incident response procedures, and maintenance workflows.

Adaptive workflow principle

AI-DLC is not waterfall. The workflow adapts to the work.

Before executing any optional stage, the workflow planner assesses complexity and only runs stages that add value. A simple bug fix skips design stages entirely and goes straight to code generation. A complex multi-service system executes every available stage at full depth.

This adaptivity is the key difference from rigid phase-gate methodologies. You get thorough treatment when complexity warrants it and fast turnaround when it does not.

Three depth levels

The depth level controls how many questions are asked, how many stages execute, and how detailed the artifacts become.

The workflow planner recommends a depth level based on complexity assessment. You can always override the recommendation.

Key principles

User control

Approval gates pause the workflow at critical milestones:

• After requirements analysis
• After workflow planning
• After each design stage
• Before code generation execution

At every gate, you can approve and continue, request changes (the stage re-executes with your feedback), or override stage inclusion and exclusion.

State management

The file aidlc-docs/aidlc-state.md tracks the current phase, the current stage within that phase, all executed stages with timestamps, all skipped stages with rationale, and the next pending stage. This enables resuming interrupted sessions.

Audit trails

The file aidlc-docs/audit.md logs your complete raw input (never summarized), AI responses and actions, approval decisions, stage transitions, and timestamps in ISO 8601 format. This provides full traceability from requirement to implementation.

Content validation

All generated content is validated for Mermaid diagram syntax, proper character escaping, text alternatives for visual content, and well-formed markdown.

Progressive disclosure

Initial documentation is lean. Deep-dive details live in separate files. External rules in ~/.claude/aidlc-rules/ provide the detailed implementation specifications that agents consume at runtime.

Comparison: Waterfall vs. Agile vs. AI-DLC

The key innovation: agentic requirements gathering

The single most important differentiator in AI-DLC is how it gathers requirements.

Traditional approach (manual): The AI creates a requirements.md template with blank sections. You open an editor, stare at a blank document, manually fill in 500+ lines of markdown over 30 minutes, and frequently skip sections or write vague descriptions like "API should be fast."

AI-DLC approach (agentic Q&A): The AI presents one question at a time using the Claude Agent SDK's AskUserQuestion tool. Each question has clear multiple-choice options with descriptions. You select answers or type custom responses. The AI uses branching logic to skip irrelevant questions. After 5--10 minutes of Q&A, a complete requirements document is generated automatically.

Requirements Analysis - Question 3/12

Authentication method

How should the API authenticate clients?

A) JWT tokens (stateless)
   JSON Web Tokens stored client-side

B) Session cookies (stateful)
   Server-side session storage

C) API keys
   Simple key-based authentication

D) OAuth 2.0
   Delegated authorization with third-party providers

[Other - custom response]

The agentic approach reduces cognitive load, forces specificity (you choose "< 100ms p95 latency" instead of writing "fast"), ensures completeness through mandatory questions, and produces a traceability matrix linking every requirement back to the question and answer that generated it.

When to use AI-DLC

Use AI-DLC when:

• Starting greenfield projects (new codebases)
• Building significant new features in existing code
• Working on projects that require governance and documentation
• Adopting AI-augmented development workflows
• Collaborating across teams with approval gates

Do not use AI-DLC for:

• Trivial bug fixes (fewer than 10 lines changed) -- use /ai-dlc:fix or direct editing instead
• Documentation-only changes
• Configuration tweaks
• Prototype or throwaway code

For simple changes, use traditional workflows or the lightweight /ai-dlc:fix command which provides a fast-path TDD-first bug fix workflow.

Next steps

Ready to try it? Work through the hands-on tutorial: Your first AI-DLC project.

For a complete reference of commands and agents, see: AI-DLC commands and agents.

For practical workflow patterns, see: AI-DLC workflow patterns.