AD-SDLC: Ciclo de Vida de Desenvolvimento Orientado por Agentes
kcenon/claude_code_agent
Automatize todo desenvolvimento: requisitos até deployment com 35 agentes especializados
Ver no GitHubSistema de automação completo do ciclo de desenvolvimento de software usando 35 tipos especializados de agentes Claude. Transforma requisitos em código pronto para produção através de pipelines de greenfield, enhancement e import, com validação, testes e gestão de PRs automatizados.
Instalação
npx convez-ai kcenon/claude_code_agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerar documentação técnica (PRD, SRS, SDS) automaticamente a partir de requisitos
- Implementar features end-to-end com validação e testes integrados
- Analisar bases de código existentes e gerar planos de melhoria com impacto
- Gerenciar pipelines de CI/CD com correção automática de falhas
- Onboarding ágil: converter issues GitHub em PRs validadas
Veredito

Solução ambiciosa para automação end-to-end do SDLC usando agentes Claude em escala. Requer integração TypeScript madura e arquitetura de projeto bem definida; ideal para times que querem delegar análise, documentação e implementação a agentes especializados coordenados, mas exige investimento em setup e customização da pipeline.
README
A tradução para o português deste README ainda está na fila.
AD-SDLC: Agent-Driven Software Development Lifecycle
Automate your software development from requirements to deployment, built on the Claude Agent SDK.
Every agent stage runs through a single Claude Agent SDK entry point (ExecutionAdapter). The 35-stage pipeline, V&V gates, and traceability matrix are AD-SDLC's domain layer on top of the SDK; tool use, sub-agent delegation, and session management are handled by the SDK itself.
Quick Start
Get started in under 5 minutes:
# 1. Install AD-SDLC
npm install -g ad-sdlc
# 2. Initialize your project
ad-sdlc init my-project
cd my-project
# 3. Start with your requirements
claude "Implement user authentication with OAuth2"
That's it! The agents will generate documents, create issues, implement code, and open PRs.
What is AD-SDLC?
AD-SDLC is an automated software development pipeline that uses 35 specialized Claude agent types to transform your requirements into production-ready code. It supports three modes:
Greenfield Pipeline (New Projects)
User Input → Mode Detection → Collector → PRD Writer → SRS Writer → SDP Writer
→ Repo Detection → GitHub Repo Setup → SDS Writer
─┬─▶ Threat Model Writer ─┐
├─▶ Tech Decision Writer ─┤
└─▶ UI Spec Writer ──────┤
↓
Doc Indexing ← PR Reviewer ← Validation ← Worker ← Controller ← SVP Writer ← Issue Generator
Enhancement Pipeline (Existing Projects)
Existing Docs + Code → Document Reader → Codebase Analyzer → Code Reader
↓
Doc-Code Comparator
↓
Impact Analyzer
↓
PRD Updater → SRS Updater → SDS Updater
↓
Issue Generator + Regression Tester
↓
Controller → Worker → Validation → PR Reviewer
↓
Doc Indexing + CI Fix (on failure)
Import Pipeline (Existing GitHub Issues)
GitHub Issues → Issue Reader → Controller → Worker → Validation → PR Reviewer
↓
Doc Indexing + CI Fix (on failure)
Agent Pipeline (35 Agent Types)
| Phase | Agent | Role |
|---|---|---|
| Orchestration | AD-SDLC Orchestrator | Coordinates the full pipeline lifecycle |
| Analysis Orchestrator | Coordinates the analysis sub-pipeline | |
| Setup | Mode Detector | Detects Greenfield vs Enhancement vs Import mode |
| Project Initializer | Creates .ad-sdlc directory structure and config | |
| Repo Detector | Determines if existing repo or new setup needed | |
| GitHub Repo Setup | Creates and initializes GitHub repository | |
| Collection | Collector | Gathers requirements from text, files, and URLs |
| Issue Reader | Imports existing GitHub Issues for Import pipeline | |
| Documentation | PRD Writer | Generates Product Requirements Document |
| SRS Writer | Generates Software Requirements Specification | |
| SDP Writer | Generates Software Development Plan from PRD and SRS | |
| SDS Writer | Generates Software Design Specification (SDS) and a separate Database Schema Specification (DBS) | |
| Threat Model Writer | Generates STRIDE/DREAD Threat Model from SDS | |
| Tech Decision Writer | Generates Technology Decision documents with alternatives analysis from the SDS technology stack | |
| UI Spec Writer | Generates UI screen specifications, user flow documents, and design system references from SRS | |
| Doc Index Generator | Generates structured documentation index (manifest, bundles, graph, router) from pipeline artifacts | |
| Planning | Issue Generator | Creates GitHub Issues from SDS components |
| SVP Writer | Generates Software Verification Plan with test cases from SRS and issues | |
| Execution | Controller | Orchestrates work distribution and monitors progress |
| Worker | Implements code based on assigned issues | |
| Local Reviewer | Local-mode PR review variant (no GitHub dependency) | |
| Quality | PR Reviewer | Creates PRs and performs automated code review |
| CI Fixer | Automatically diagnoses and fixes CI failures | |
| Regression Tester | Validates existing functionality after changes | |
| V&V | Stage Verifier | Verifies pipeline stage outputs for content completeness and traceability |
| RTM Builder | Builds Requirements Traceability Matrix from requirements to implementation | |
| Validation Agent | Validates final implementation against requirements and acceptance criteria | |
| Enhancement | Document Reader | Parses existing PRD/SRS/SDS documents |
| Code Reader | Extracts source code structure and dependencies | |
| Codebase Analyzer | Analyzes current architecture and code structure | |
| Doc-Code Comparator | Detects gaps between documentation and code | |
| Impact Analyzer | Assesses change implications and risks | |
| PRD Updater | Incremental PRD updates (delta changes) | |
| SRS Updater | Incremental SRS updates (delta changes) | |
| SDS Updater | Incremental SDS updates (delta changes) |
Note: Local mode agents (
local-issue-reader,local-reviewer) share their GitHub counterparts' implementations and are used automatically with the--localflag.
How it Works
3-Tier Architecture
AD-SDLC is structured as three cooperating tiers. The orchestrator owns the pipeline DAG and V&V gates, the execution layer is a single Claude Agent SDK entry point, and the knowledge layer (.claude/, MCP servers, claude-config plugin) is consumed by the SDK rather than wired through custom bridges.
flowchart TB
Orch[T1 Orchestrator] -->|stage 단위| Adapter[T2 ExecutionAdapter]
Adapter --> SDK[Agent SDK query]
Adapter --> Hooks[Hook Pipeline]
SDK -.reads.-> Knowledge[T3 .claude/ + plugin]
Hooks --> Scratchpad
Hooks --> Telemetry
| Tier | Responsibility | Implementation |
|---|---|---|
| T1 Pipeline Control Plane | Stage DAG, checkpoints, V&V gates, domain writers | src/ad-sdlc-orchestrator/, *-writer/, vnv/ |
| T2 Agent Execution Layer | Single SDK entry point, hooks, telemetry bridge | src/execution/ |
| T3 Knowledge Layer | Agent definitions, skills, commands, MCP servers | .claude/, .mcp.json, claude-config plugin |
See docs/architecture/v0.1-hybrid-pipeline-rfc.md for the full architecture RFC and docs/architecture/v0.1-migration-guide.md for the v0.0.1 → v0.1.0 migration steps.
Pipeline Flow
AD-SDLC automates the full software development lifecycle through a coordinated agent pipeline:
-
Mode Detection: The system analyzes your project to determine the appropriate pipeline -- Greenfield (new project), Enhancement (existing project), or Import (existing GitHub issues).
-
Document Generation: A cascade of writer agents produces structured documents from your requirements. In Greenfield mode: PRD, SRS, SDP, SDS, followed by parallel generation of Threat Model, Technology Decisions, and UI Specifications (when applicable).
-
Planning: The Issue Generator transforms design specifications into actionable GitHub Issues with dependencies and labels. The SVP Writer creates a Software Verification Plan with derived test cases.
-
Implementation: The Controller distributes issues to Worker agents, which implement code, write tests, and create pull requests. Multiple workers operate in parallel for faster delivery.
-
Verification & Validation: Stage Verifier checks each pipeline output for completeness. The RTM Builder traces requirements to implementation. The Validation Agent confirms all acceptance criteria are met.
-
Review & Indexing: The PR Reviewer performs automated code review with quality gates. Finally, the Doc Index Generator creates a searchable documentation index from all pipeline artifacts.
Each agent reads and writes to a shared scratchpad, enabling seamless inter-agent communication. The pipeline supports resume (--resume) and start-from (--start-from <stage>) for interrupted sessions.
Features
- Automatic Document Generation: PRD, SRS, SDP, SDS, DBS, TM, SVP, TD, and UI specification documents from natural language requirements
- UI Specification Generation: Screen specifications, user flow documents, and design system references from SRS use cases; auto-skips for CLI/API/library projects
- Separate Database Schema Specification (DBS): SDS Writer emits a dedicated DBS document alongside the SDS, keeping the full database schema decoupled from architectural design
- Document Frontmatter Metadata: YAML frontmatter with doc_id, version, status, and change history on all generated documents
- Enhancement Pipeline: Incremental updates to existing projects without full rewrites
- Import Pipeline: Process existing GitHub Issues directly, skipping document generation
- Local Mode: Run the full pipeline without GitHub using
--local(orAD_SDLC_LOCAL=1); see Quickstart for details - Mode Detection: Automatically detects Greenfield, Enhancement, or Import pipeline
- Pipeline Resume: Resume interrupted pipelines from the last completed stage (
--resume) - Session Persistence: Automatic state persistence for pipeline recovery
- GitHub Integration: Automatic issue creation with dependencies and labels
- Parallel Implementation: Multiple workers implementing issues concurrently
- Automated PR Review: Code review and quality gate enforcement
- Progress Tracking: Real-time visibility into pipeline status
- Regression Testing: Identifies affected tests when modifying existing code
- Doc-Code Gap Analysis: Detects discrepancies between documentation and implementation
- V&V Framework: Stage verification gates, RTM building, and final validation ensure traceability from requirements to implementation
- Document Audit: CLI script (
npm run audit:docs) that validates pipeline-generated PRD/SRS/SDS/SDP/TM/SVP/TD/DBS documents for frontmatter, required sections, cross-references, and PRD→SRS→SDS traceability; see Document Audit CLI - Customizable Workflows: Configure agents, templates, and quality gates
Installation
Prerequisites
- Node.js 18+ (Download)
- Git 2.30+
- GitHub CLI 2.0+ (optional, for issue/PR management)
- Claude API Key
GITHUB_TOKEN— required for stages that talk to GitHub (pr-reviewer,issue-generator,ci-fixer). Export a Personal Access Token withrepo-level scope; the team-shared.mcp.jsoninterpolates it via${GITHUB_TOKEN}and never stores literals. See docs/configuration/mcp.md for setup, scopes, and troubleshooting.
Install
# Global installation (recommended)
npm install -g ad-sdlc
# Or use directly with npx
npx ad-sdlc init
Configure
# Set your Anthropic API key
export ANTHROPIC_API_KEY="your-api-key"
# For GitHub integration
gh auth login
See Installation Guide for detailed setup instructions.
Dependencies
AD-SDLC v0.1 standardizes on the official Claude Agent SDK as the only AI runtime dependency. The legacy raw @anthropic-ai/sdk client and the in-tree AgentBridge/AgentDispatcher/AgentRegistry stack were removed in v0.1.0 (#798).
| Package | Version | Role |
|---|---|---|
@anthropic-ai/claude-agent-sdk | ^0.2.132 | Single Agent SDK entry point used by ExecutionAdapter for every stage |
commander | ^14.0.3 | ad-sdlc CLI argument parsing |
inquirer | ^13.4.2 | Interactive prompts for ad-sdlc init |
js-yaml | ^4.1.1 | Pipeline config and document frontmatter parsing |
zod | ^4.4.2 | Runtime schema validation for agent registry, configs, and checkpoint schema |
ts-morph | ^28.0.0 | TypeScript AST analysis for the Code Reader / Codebase Analyzer agents |
chalk, dotenv | latest | CLI output and environment loading |
Optional integrations (logging backends, OpenTelemetry exporters, better-sqlite3, ioredis, mammoth, pdf-parse) are declared as optional peer dependencies so the runtime install stays lean; consumers pull them in only when the matching scratchpad backend or document parser is enabled.
Usage
Initialize a New Project
# Interactive mode - guides you through configuration
ad-sdlc init
# Quick setup with defaults
ad-sdlc init my-project --quick
# With specific options
ad-sdlc init my-project \
--tech-stack typescript \
--template standard \
--github-repo https://github.com/user/my-project
Template Options
| Template | Workers | Coverage | Features |
|---|---|---|---|
| minimal | 2 | 50% | Basic structure |
| standard | 3 | 70% | Token tracking, dashboard |
| enterprise | 5 | 80% | Audit logging, security scanning |
Run the Pipeline
# Start with requirements collection
claude "Collect requirements for [your project description]"
# Generate documents step by step
claude "Generate PRD from collected information"
claude "Generate SRS from PRD"
claude "Generate SDS from SRS"
# Create GitHub Issues
claude "Generate GitHub issues from SDS"
# Implement and review
claude "Start implementation with Controller"
CLI Commands
# Initialize new project
ad-sdlc init [project-name]
# Validate configuration files
ad-sdlc validate [--file <path>] [--watch] [--format text|json]
# Check pipeline status
ad-sdlc status [--project <id>] [--format text|json] [--verbose]
# Analyze project for documentation-code gaps
ad-sdlc analyze [--project <path>] [--scope full|documents_only|code_only]
# Generate shell completion script
ad-sdlc completion --shell <bash|zsh|fish>
Document Audit
Once the pipeline has generated documents, validate them with the document audit CLI:
# Audit the current project (writes reports to .ad-sdlc/audit/)
npm run audit:docs -- --project-dir .
# Audit a different project and pick the output directory
npm run audit:docs -- --project-dir ./my-project --output audit-reports
# Or run the script directly with tsx
npx tsx scripts/audit-docs.ts --project-dir ./my-project
The auditor runs frontmatter, required-section, cross-reference, PRD→SRS→SDS
traceability, orphan, Mermaid, and relative-link checks across PRD, SRS, SDS,
SDP, TM, SVP, TD, and DBS documents. It writes both a machine-readable
audit-report.json and a human-readable audit-report.md, and exits with a
non-zero status on any error-severity finding — making it suitable as a local
pre-merge check or as a CI quality gate. See the
Document Audit CLI guide for the full list of checks,
report format, exit codes, and CI integration.
Full Pipeline Script
Run the complete AD-SDLC pipeline end-to-end:
# Auto-detect mode and run full pipeline
./ad-sdlc-full-pipeline.sh [project_path] [mode]
# Specify mode explicitly
./ad-sdlc-full-pipeline.sh . greenfield
./ad-sdlc-full-pipeline.sh . enhancement
./ad-sdlc-full-pipeline.sh . import
# Resume an interrupted pipeline
./ad-sdlc-full-pipeline.sh . auto --resume
# Resume a specific session
./ad-sdlc-full-pipeline.sh . auto --resume <session-id>
# Start from a specific stage
./ad-sdlc-full-pipeline.sh . greenfield --start-from sds_generation
# List available sessions for resume
./ad-sdlc-full-pipeline.sh . auto --list-sessions
Shell Autocompletion
Enable tab completion for AD-SDLC commands in your shell:
# Bash
ad-sdlc completion --shell bash >> ~/.bashrc
source ~/.bashrc
# Zsh
ad-sdlc completion --shell zsh > ~/.zsh/completions/_ad-sdlc
source ~/.zshrc
# Fish
ad-sdlc completion --shell fish > ~/.config/fish/completions/ad-sdlc.fish
See Quickstart Guide for a step-by-step tutorial.
Use Cases
New Feature Implementation
claude "Implement user dashboard with usage statistics and charts"
Bug Fix Workflow
claude "Fix #42: Login fails when email contains +"
Refactoring Project
claude "Refactor auth module to use dependency injection"
From Requirements File
claude "Read requirements from docs/requirements.md and implement"
See Use Cases Guide for more examples.
Project Structure
your-project/
├── .claude/
│ └── agents/ # Agent definitions (34 prompt files, 35 registered types)
│ └── *.md # Agent prompts (English, used by Claude)
├── .ad-sdlc/
│ ├── config/ # Configuration files
│ │ ├── agents.yaml # Agent registry
│ │ └── workflow.yaml # Pipeline configuration
│ ├── logs/ # Audit logs
│ ├── scripts/ # Pipeline shell scripts
│ │ └── ad-sdlc-full-pipeline.sh
│ ├── templates/ # Document templates
│ └── scratchpad/ # Inter-agent state (Scratchpad pattern)
│ └── pipeline/ # Pipeline session state (resume support)
├── docs/ # Generated documentation
├── src/ # Generated source code
└── README.md
Documentation
Getting Started
- Installation Guide - Detailed setup instructions
- Quickstart Guide - 5-minute tutorial
- Use Cases - Common scenarios and examples
- FAQ - Frequently asked questions
Reference
- System Architecture
- v0.1 Hybrid Pipeline RFC — 3-tier architecture and Claude Agent SDK adoption rationale
- v0.1 Migration Guide — v0.0.1 → v0.1.0 contributor and consumer migration steps
- Document Status Definitions
- Document Audit CLI — validate generated PRD/SRS/SDS/... documents for integrity and traceability
- PRD-001: Agent-Driven SDLC
- SRS-001: Agent-Driven SDLC
- SDS-001: Agent-Driven SDLC
Guides
- Agent Deployment
- Usage Scenarios — All execution environments and pipeline modes
- Reference Documentation
Korean Documentation
Agent Definitions
Each agent is defined in .claude/agents/ with:
- YAML frontmatter (name, description, tools, model)
- Markdown body with role, responsibilities, schemas, and workflows
Agent prompt files (.md) are in English and used by Claude during execution.
Slash Commands
.claude/commands/*.md files are auto-loaded by Claude Code (and the Agent SDK) and exposed as slash commands inside the session. Each file declares its argument shape via YAML frontmatter (description, optional argument-hint) and a short markdown body that instructs the assistant which CLI subcommand to run.
| Command | File | Wraps |
|---|---|---|
/run-greenfield | .claude/commands/run-greenfield.md | ad-sdlc init + ad-sdlc run --mode greenfield |
/resume | .claude/commands/resume.md | ad-sdlc run --resume <session-id> (no dedicated resume subcommand) |
/audit-docs | .claude/commands/audit-docs.md | npm run audit:docs (scripts/audit-docs.ts) |
/status | .claude/commands/status.md | ad-sdlc status |
To use them, open the project inside a Claude Code session and type the command (for example /run-greenfield "Build a todo app"). Claude reads the matching markdown file, substitutes $ARGUMENTS / $1, and executes the underlying CLI call. New commands can be added by dropping a markdown file with valid frontmatter into .claude/commands/.
Document Frontmatter
All documents generated by the pipeline (PRD, SRS, SDP, SDS, DBS, TM, SVP, TD, UI) include structured YAML frontmatter for machine-readable metadata:
---
doc_id: PRD-my-project
title: Product Requirements Document
version: 1.0.0
status: Draft
generated_by: ad-sdlc v0.0.1
generated_at: '2026-04-12T09:00:00.000Z'
source_documents:
- collected_info.yaml
change_history:
- version: 1.0.0
date: '2026-04-12'
author: ad-sdlc
description: Initial generation
---
Frontmatter Fields
| Field | Type | Description |
|---|---|---|
doc_id | string | Unique document identifier (e.g., PRD-my-project) |
title | string | Human-readable document title |
version | string | Semantic version (MAJOR.MINOR.PATCH) |
status | enum | Draft, Review, or Approved |
generated_by | string | Tool and version that generated the document |
generated_at | string | ISO 8601 generation timestamp |
pipeline_session | string | Pipeline session ID (optional) |
source_documents | string[] | Input document references (optional) |
approval | object[] | Approval entries with role, name, date, status (optional) |
change_history | object[] | Version history entries (optional) |
The frontmatter schema is defined in src/schemas/document-frontmatter.ts and validated with Zod at generation time. Utility functions for generating, parsing, and prepending frontmatter are in src/utilities/frontmatter.ts.
Contributing
We welcome contributions! Please see our Contributing Guide for details.
Quick Start for Contributors
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes using conventional commits
- Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Related Projects
claude-config
A Claude Code configuration management and development guidelines system. Agents in this project can reference claude-config's guidelines during code generation and review to improve code quality.
- Repository: kcenon/claude-config
- Reference Guide: docs/claude-config-reference.md
License
BSD 3-Clause License - see LICENSE for details.
Need help? Check the FAQ or open an issue.