AI Development Workflow with Claude Code

One command takes a feature from idea to production-ready code. An autonomous expert team — architect, developer, security reviewer, QA, SRE, and tech writer — runs the full software development lifecycle, each in an isolated context, with parallel review and a scoped fix loop.

/sdlc add-oauth-auth "Implement OAuth2 with Google"

That's it. The workflow researches your codebase, plans the implementation, builds and tests it, runs three expert reviews simultaneously, fixes any issues, and updates your documentation.

---

Prerequisites

• Claude Code — the Anthropic CLI (desktop app, VS Code extension, or npm install -g @anthropic-ai/sdk)
• A project to work in (any language — the workflow adapts)
• No other setup required — clone this repo and the /sdlc command is available immediately

New to Claude Code? It's Anthropic's AI coding assistant that runs in your terminal or IDE. Think of it as a developer you can talk to that can read, write, and run code in your project. The /sdlc command in this repo adds an autonomous full-pipeline workflow on top of it.

---

Quick Start

# 1. Clone this repo into your project (or copy .claude/ into an existing project)
git clone https://github.com/denizokcu/claude-code-ai-development-workflow .claude-workflow
cp -r .claude-workflow/.claude .

# 2. Open Claude Code in your project
# 3. Run the command
/sdlc add-oauth-auth "Implement OAuth2 login with Google"

The workflow will:

1. Pre-check your environment (existing state, uncommitted changes)
2. Research your codebase — what files to touch, what patterns to follow
3. Design the architecture — write an ADR if a non-obvious decision is needed
4. Plan — scope, phases, validation commands, acceptance criteria
5. Pause for your review of the plan before implementation starts
6. Implement all phases with actual test output captured
7. Run Security, QA, and SRE review simultaneously
8. Fix any blocking issues (max 3 iterations, only failing reviewers re-run)
9. Update CHANGELOG, README, and API docs
10. Write a production readiness sign-off with deploy checklist

Check progress at any point:

# Human-readable progress
cat docs/add-oauth-auth/STATUS.md

# Final sign-off
cat docs/add-oauth-auth/PRODUCTION_READINESS.md

---

Workflow

Research → Architecture → Plan → [Human Review] → Implement → Expert Review (parallel) → Documentation → Production Ready
                                                                       ↓
                                                              Scoped Fix Loop (max 3)
                                                            (only failing experts re-review)

Phases

Phase	What happens	Output
Pre-flight	Checks for existing state, uncommitted changes, valid description	—
Research	Parallel codebase search — files to touch, patterns, risks	RESEARCH.md
Architecture	Design fit review; ADR written if a non-obvious decision is needed	ADR.md
Planning	Scope, phases, per-phase validation commands, acceptance criteria	PLAN.md
Human Review	Orchestrator presents plan summary — you confirm before implementation starts	—
Implementation	All plan phases built with actual test output captured	IMPLEMENTATION.md + code
Expert Review	Security, QA, and SRE reviewers run simultaneously	SECURITY.md, QA.md, SRE.md
Fix Loop	Blocking issues fixed; only failed reviewers re-run (max 3 iterations)	Updated code
Documentation	CHANGELOG, README, API docs updated; breaking changes flagged	Updated docs
Production Readiness	All expert sign-offs aggregated into final gate	PRODUCTION_READINESS.md

---

Usage

/sdlc <issue-name> [description] [--resume | --plan | --implement | --review]

Examples

# Full workflow — research through production readiness
/sdlc add-oauth-auth "Implement OAuth2 with Google"

# Resume after interruption or approval
/sdlc add-oauth-auth --resume

# Start from a specific phase (useful if you already have prior artifacts)
/sdlc add-oauth-auth --plan          # needs RESEARCH.md + ADR.md
/sdlc add-oauth-auth --implement     # needs PLAN.md
/sdlc add-oauth-auth --review        # needs IMPLEMENTATION.md

Arguments

Argument	Description
issue-name	Kebab-case identifier, 1-50 chars (e.g. add-oauth-auth)
description	What to build — required for new workflows
--resume	Continue from where STATE.json left off
--plan	Start from Planning
--implement	Start from Implementation
--review	Start from Expert Review

---

Expert Team

Each expert runs as an isolated subagent with its own 200K context window — no state bleeds between phases.

Expert	File	Model	What they do
Orchestrator	sdlc-orchestrator	Opus 4.6	Coordinates phases, writes STATE.json, merges expert verdicts
Architect	sdlc-architect	Opus 4.6	Evaluates design fit, writes ADR for non-obvious decisions
Planner	sdlc-solution-planning	Opus 4.6	Scope definition, phases, validation commands, acceptance criteria
Developer	sdlc-code-implementation	Sonnet 4.6	Implements all plan phases, captures actual test output
Security Reviewer	sdlc-security-reviewer	Opus 4.6	OWASP Top 10, STRIDE threat model, dependency audit, secret detection
QA Reviewer	sdlc-qa-reviewer	Sonnet 4.6	Acceptance criteria coverage, test strategy, regression risk
SRE Reviewer	sdlc-sre-reviewer	Sonnet 4.6	Observability, error handling, env vars, rollback plan, runbook
Fix Developer	sdlc-review-fix	Sonnet 4.6	Fixes only the blocking issues, minimal changes
Tech Writer	sdlc-tech-writer	Sonnet 4.6	CHANGELOG, README, API docs, breaking change detection

Security, QA, and SRE review in parallel — all three run simultaneously, cutting review time by ~66%.

In the fix loop, only the experts that flagged issues re-review. An expert that approved does not re-run.

---

Artifacts

All output lives in docs/{issue-name}/:

File	Who writes it	What it contains
STATE.json	Orchestrator	Machine state — current phase, which experts failed, --resume data
STATUS.md	Each phase	Human-readable progress (checkboxes, key findings, next step)
RESEARCH.md	Research	Files to touch, patterns to follow, risk level
ADR.md	Architect	Design decision + rationale + constraints for the planner
PLAN.md	Planner	Scope, 2-4 phases with validation commands, acceptance criteria
IMPLEMENTATION.md	Developer	What was built, files changed, actual test/lint/type-check output
SECURITY.md	Security Reviewer	OWASP checks, dependency audit output, APPROVED/NEEDS_FIX verdict
QA.md	QA Reviewer	Test run output, coverage map, APPROVED/NEEDS_FIX verdict
SRE.md	SRE Reviewer	Operational surface, observability, rollback plan, optional runbook
REVIEW.md	Orchestrator	Aggregated verdict across all three experts
PRODUCTION_READINESS.md	Orchestrator	Final gate — all sign-offs, deploy checklist

Production Readiness Gate

A feature is not complete until:

• Security, QA, and SRE all return APPROVED
• CHANGELOG.md updated
• README.md updated (if user-facing changes were made)
• PRODUCTION_READINESS.md all checks passed
• Retrospective appended to .claude/sdlc/RETROSPECTIVES.md

---

Design Principles

Principle	What it means in practice
Single command	Full pipeline in one invocation — no manual steps between phases
Isolated contexts	Each phase gets a fresh 200K context — no overflow, no cross-phase contamination
Parallel review	Security, QA, SRE run simultaneously — not sequentially
Scoped fix loop	Only failing experts re-review; approved experts stay approved
Human checkpoint	Plan is presented for your review before implementation starts
Evidence required	Implementation captures actual command output — claims don't count
Single artifact owner	Each output file is written by exactly one agent (DRY)
YAGNI gates	ADRs, runbooks, and API docs are only written when actually needed
Secure by default	Scoped Bash permissions, no writes outside the project, secret detection in every review

---

How It Works — For LLM/Agent Engineers

The workflow is a three-tier architecture:

Tier 1: /sdlc command (Haiku) — parse and validate input only
            ↓
Tier 2: Orchestrator (Opus) — coordinate phases via Agent tool, manage STATE.json
            ↓
Tier 3: Specialist agents/skills (Sonnet/Opus) — isolated 200K context per phase

Key patterns:

• The orchestrator never does phase work inline — every phase delegates to a subagent via the Agent tool
• STATE.json is the source of truth for --resume; STATUS.md is for humans only
• Parallel review uses multiple Agent() calls in a single orchestrator response
• failing_experts in STATE.json scopes the fix loop — prevents unnecessary re-reviews
• settings.json uses scoped Bash patterns (e.g. "Bash(npm test*)") — prevents destructive commands during autonomous execution

For a deep dive on the design patterns, see .claude/sdlc/AGENTIC_WORKFLOW_BEST_PRACTICES.md.

---

Documentation Index

File	For whom	What's in it
README.md	Everyone	This file — overview, usage, expert team
CLAUDE.md	Contributors & agents	Architecture summary, modification guide
.claude/sdlc/ARCHITECTURE.md	Deep-dive	Visual architecture, model strategy, DRY/KISS/YAGNI
.claude/sdlc/STATE_MANAGEMENT.md	Deep-dive	STATE.json spec, phase transitions, resume logic
.claude/sdlc/COMMAND_USAGE.md	Reference	Full command syntax and argument reference
.claude/sdlc/TROUBLESHOOTING.md	Debugging	Recovery guide for common issues
.claude/sdlc/AGENTIC_WORKFLOW_BEST_PRACTICES.md	Agents & architects	Expert review of this workflow, 2026 best practices, anti-patterns
.claude/sdlc/RETROSPECTIVES.md	All	Append-only log of completed workflow runs
.claude/sdlc/templates/ARTIFACT_TEMPLATES.md	Contributors	All artifact format templates
.claude/sdlc/examples/	Contributors	Example RESEARCH.md and PLAN.md outputs

New here? Start with this README, then CLAUDE.md for the internals. Modifying the workflow? See the "Modifying the Workflow" section in CLAUDE.md. Something broken? See .claude/sdlc/TROUBLESHOOTING.md.