claude-code-ai-development-workflow

KO | EN

gitlite — search

#python #machine-learning #javascript #react #kubernetes #python3 #api #discord #programming-language #cpp #hacktoberfest #nodejs

claude-code-ai-development-workflow

★ 59 Open GitHub ↗

Comprehensive slash commands for a complete software development lifecycle - from research to implementation.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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.

```bash
/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](https://claude.ai/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

```bash
# 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:
```bash
# 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

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

### Examples

```bash
# 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`.

claude-code-ai-development-workflow

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README