convez.ai
AgenteAutomaçãoAvançado
kcenon

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 GitHub
BomPluginScore · de 0 a 100

Sistema 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_agent

1 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

Estrelas
32
Forks
13
Acompanhando
1
Saúde
85%
Último commit
há 3 dias
Versão
—
Issues abertas
8
Contribuidores
2

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.

License: BSD-3-Clause Node.js Built with 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)

PhaseAgentRole
OrchestrationAD-SDLC OrchestratorCoordinates the full pipeline lifecycle
Analysis OrchestratorCoordinates the analysis sub-pipeline
SetupMode DetectorDetects Greenfield vs Enhancement vs Import mode
Project InitializerCreates .ad-sdlc directory structure and config
Repo DetectorDetermines if existing repo or new setup needed
GitHub Repo SetupCreates and initializes GitHub repository
CollectionCollectorGathers requirements from text, files, and URLs
Issue ReaderImports existing GitHub Issues for Import pipeline
DocumentationPRD WriterGenerates Product Requirements Document
SRS WriterGenerates Software Requirements Specification
SDP WriterGenerates Software Development Plan from PRD and SRS
SDS WriterGenerates Software Design Specification (SDS) and a separate Database Schema Specification (DBS)
Threat Model WriterGenerates STRIDE/DREAD Threat Model from SDS
Tech Decision WriterGenerates Technology Decision documents with alternatives analysis from the SDS technology stack
UI Spec WriterGenerates UI screen specifications, user flow documents, and design system references from SRS
Doc Index GeneratorGenerates structured documentation index (manifest, bundles, graph, router) from pipeline artifacts
PlanningIssue GeneratorCreates GitHub Issues from SDS components
SVP WriterGenerates Software Verification Plan with test cases from SRS and issues
ExecutionControllerOrchestrates work distribution and monitors progress
WorkerImplements code based on assigned issues
Local ReviewerLocal-mode PR review variant (no GitHub dependency)
QualityPR ReviewerCreates PRs and performs automated code review
CI FixerAutomatically diagnoses and fixes CI failures
Regression TesterValidates existing functionality after changes
V&VStage VerifierVerifies pipeline stage outputs for content completeness and traceability
RTM BuilderBuilds Requirements Traceability Matrix from requirements to implementation
Validation AgentValidates final implementation against requirements and acceptance criteria
EnhancementDocument ReaderParses existing PRD/SRS/SDS documents
Code ReaderExtracts source code structure and dependencies
Codebase AnalyzerAnalyzes current architecture and code structure
Doc-Code ComparatorDetects gaps between documentation and code
Impact AnalyzerAssesses change implications and risks
PRD UpdaterIncremental PRD updates (delta changes)
SRS UpdaterIncremental SRS updates (delta changes)
SDS UpdaterIncremental SDS updates (delta changes)

Note: Local mode agents (local-issue-reader, local-reviewer) share their GitHub counterparts' implementations and are used automatically with the --local flag.

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
TierResponsibilityImplementation
T1 Pipeline Control PlaneStage DAG, checkpoints, V&V gates, domain writerssrc/ad-sdlc-orchestrator/, *-writer/, vnv/
T2 Agent Execution LayerSingle SDK entry point, hooks, telemetry bridgesrc/execution/
T3 Knowledge LayerAgent 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:

  1. Mode Detection: The system analyzes your project to determine the appropriate pipeline -- Greenfield (new project), Enhancement (existing project), or Import (existing GitHub issues).

  2. 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).

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

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

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

  6. 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 (or AD_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 with repo-level scope; the team-shared .mcp.json interpolates 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).

PackageVersionRole
@anthropic-ai/claude-agent-sdk^0.2.132Single Agent SDK entry point used by ExecutionAdapter for every stage
commander^14.0.3ad-sdlc CLI argument parsing
inquirer^13.4.2Interactive prompts for ad-sdlc init
js-yaml^4.1.1Pipeline config and document frontmatter parsing
zod^4.4.2Runtime schema validation for agent registry, configs, and checkpoint schema
ts-morph^28.0.0TypeScript AST analysis for the Code Reader / Codebase Analyzer agents
chalk, dotenvlatestCLI 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

TemplateWorkersCoverageFeatures
minimal250%Basic structure
standard370%Token tracking, dashboard
enterprise580%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

Reference

Guides

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.

CommandFileWraps
/run-greenfield.claude/commands/run-greenfield.mdad-sdlc init + ad-sdlc run --mode greenfield
/resume.claude/commands/resume.mdad-sdlc run --resume <session-id> (no dedicated resume subcommand)
/audit-docs.claude/commands/audit-docs.mdnpm run audit:docs (scripts/audit-docs.ts)
/status.claude/commands/status.mdad-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

FieldTypeDescription
doc_idstringUnique document identifier (e.g., PRD-my-project)
titlestringHuman-readable document title
versionstringSemantic version (MAJOR.MINOR.PATCH)
statusenumDraft, Review, or Approved
generated_bystringTool and version that generated the document
generated_atstringISO 8601 generation timestamp
pipeline_sessionstringPipeline session ID (optional)
source_documentsstring[]Input document references (optional)
approvalobject[]Approval entries with role, name, date, status (optional)
change_historyobject[]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

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes using conventional commits
  4. Push to the branch (git push origin feature/amazing-feature)
  5. 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.


License

BSD 3-Clause License - see LICENSE for details.


Need help? Check the FAQ or open an issue.

Ver o original no GitHub

Bom para

Relacionados