Desarrollo Guiado por Especificaciones para Claude Code
De una idea en lenguaje natural a producción — un comando a la vez.
FORGE es un framework de Desarrollo Guiado por Especificaciones (SDD) para Claude Code. Convierte ideas en productos implementados, probados y desplegados — orquestando un equipo de 14 agentes especializados a través de un pipeline estructurado de 39 comandos.
Tú: "Necesito una API REST con autenticación JWT y PostgreSQL"
FORGE:
✦ Descubre requisitos → ir.json
✦ Diseña el producto → product-design.json
✦ Genera la especificación → spec.md (con criterios de aceptación)
✦ Aprobación humana → forge aprobar spec
✦ Planifica → plan.md + tareas.md
✦ Ejecuta con agentes → backend, tester, revisor, seguridad
✦ Verifica contra la spec → verificacion.json
✦ Despliega → health check pasado ✓
| Sin FORGE | Con FORGE |
|---|---|
| Cada sesión de Claude empieza en blanco | Estado persistente entre sesiones vía .sdd/ |
| Sin memoria de decisiones anteriores | Memoria de agentes + ADRs + memoria compartida entre agentes |
| Coordinación manual de tareas | 14 agentes orquestados automáticamente |
| Sin límites sobre qué toca Claude | Guardia pre-tool enforced a nivel hook (JS + Bash) |
| El pipeline avanza sin revisión humana | Aprobación explícita requerida antes de planificar |
| Atado a un solo proveedor de LLM | Motor agnóstico: Anthropic, OpenAI, Ollama, Stub |
| Sin visibilidad de lo que ocurrió | Dashboard SSE en tiempo real en localhost:3001 |
# Clonar e instalar
git clone https://github.com/carlos060798/FORGE && cd FORGE && npm install
# Verificar instalación
forge doctor
# En Claude Code, dentro de tu proyecto:
/forge→ Ver la Guía de inicio para un recorrido completo.
FORGE implementa un pipeline de 9 etapas con transiciones guardadas:
idea → discovery → ir → design → spec → [aprobación] → plan → tasks → code → done
Cada etapa produce un artefacto duradero en .sdd/. Las etapas son reanudables: si una sesión termina a mitad de la implementación, /sdd.implementar continuar retoma exactamente donde se quedó.
El pipeline tiene guards de transición: no se puede avanzar de spec a plan sin ejecutar forge aprobar spec. Esto garantiza que una persona revisó y aprobó la especificación antes de que los agentes empiecen a escribir código.
→ Ver Arquitectura para el diagrama completo del sistema.
| Módulo | Archivo | Función |
|---|---|---|
| State machine | core/state-machine.js |
Transiciones con guards — ir_generado, spec_aprobado, plan_activo |
| Orchestrator | core/orchestrator.js |
Ejecuta tareas con agentes, retry, circuit breaker |
| Motor LLM | core/llm-providers/ |
Anthropic / OpenAI / Ollama / Stub — auto-detectado |
| Decision store | core/decisions/ |
SQLite + TF-IDF, búsqueda semántica de ADRs |
| Event log | core/event-log.js |
Registro append-only de eventos del pipeline |
| Agent registry | core/agent-registry.js |
Resuelve qué agente ejecuta cada tarea |
| CLI runner | cli/index.js |
forge status/run/resume/aprobar/doctor |
| Guardia pre-tool | claude-hooks/pre-tool-guard.js + .sh |
Bloquea herramientas prohibidas antes de cada llamada |
| Memoria de agentes | claude-hooks/agent-memory.js + .sh |
Registra decisiones, ADRs y memoria compartida |
| AST indexer | claude-hooks/ast-indexer.js |
Índice de símbolos JS/TS para recuperación eficiente |
| Dashboard | ui/server.js |
SSE tiempo real — estado, consumo, eventlog |
FORGE despacha trabajo a 14 agentes especializados. Cada agente tiene un rol fijo, un modelo configurado y acceso solo a las herramientas que necesita.
Niveles: Estratégico (Opus), Diseño (Opus), Implementación (Sonnet), Soporte (Sonnet)
Preset lean (por defecto): activa 6 agentes — arquitecto, asesor-datos, disenador-api, desarrollador-backend, desarrollador-frontend, tester — todos con modelo sonnet. Los 8 restantes se activan individualmente.
→ Ver tabla completa en Agentes
FORGE funciona con cualquier proveedor compatible. El proveedor se resuelve automáticamente:
# Variable de entorno
FORGE_LLM_PROVIDER=openai forge run
# O en sdd.config.yaml
llm:
provider: ollama
base_url: http://localhost:11434
model: sonnet # alias → qwen2.5-coder:7bProveedores soportados: Anthropic (por defecto), OpenAI (y compatibles: Azure, GitHub Models), Ollama (modelos locales), Stub (determinístico, para CI).
forge doctor valida la conexión al proveedor activo, mide latencia y verifica el formato de respuesta.
El pipeline tiene un punto de control obligatorio entre spec y plan:
# Después de que FORGE genera la spec, la revisas y apruebas
forge aprobar spec
# Solo entonces el pipeline puede avanzar a planificación
/sdd.planificarSin esta aprobación, el guard de la state machine bloquea el avance. Esto no es configurable — es una decisión de diseño deliberada para mantener al humano en el bucle antes de que los agentes empiecen a escribir código.
forge ui # dashboard en localhost:3001 (SSE tiempo real)
forge status # presupuesto USD y nivel del circuit breaker
forge logs # historial consumo.jsonl
forge doctor # verifica API key, hooks, LLM y SQLiteEl dashboard recibe actualizaciones por SSE en tiempo real — estado del pipeline, consumo de tokens, event log — sin polling. Los datos vienen de cuatro archivos JSONL en .sdd/:
consumo.jsonl— tokens y USD por operaciónmutaciones.jsonl— cada write/edit con qué agente lo hizoevents.jsonl— transiciones del pipeline y eventos del orchestratoragent-tool-audit.jsonl— auditoría de cada herramienta invocada por cada agente
Los hooks funcionan en proyectos de cualquier stack — no solo Node.js:
- Con Node ≥18: ejecuta el
.jsoriginal (lógica completa: SQLite, 8 fuentes de memoria, regex) - Sin Node: ejecuta el
.shequivalente (lógica mínima en Bash: bloqueos críticos + Markdown)
Esto permite usar FORGE en proyectos Python, Go, Rust, PHP o cualquier lenguaje sin dependencia de Node en el proyecto destino.
# .sdd/sdd.config.yaml
perfil: guiado # guiado | experto
llm:
provider: anthropic # anthropic | openai | ollama | stub
model: sonnet
agentes:
arquitecto:
activo: true
modelo: opus
calidad:
cobertura_tests_minima: 80
memoria:
backend: sqlite # sqlite (Node ≥22.5) | markdown→ Ver Configuración para todas las opciones.
/sdd.crear-agente # nuevo agente con rol y herramientas específicas
/sdd.crear-mcp # integración MCP personalizadaO manualmente: añade archivos .md a commands/, agents/ o skills/ y regístralos en .claude-plugin/plugin.json.
→ Ver Extender FORGE.
| Documento | Descripción |
|---|---|
| Introducción | Qué es FORGE y por qué existe |
| Inicio rápido | Primera ejecución, recorrido guiado |
| Arquitectura | Diseño del sistema, capas, diagramas |
| Conceptos fundamentales | SDD, IR, pipeline, estado, memoria |
| Runtime | Hooks, guardias, memoria, registro de modelos |
| Agentes | Los 14 agentes, roles, modelos, herramientas |
| Flujos de trabajo | Etapas del pipeline, flags, ejemplos |
| Configuración | Referencia de sdd.config.yaml |
| Extender FORGE | Agentes, comandos y hooks personalizados |
| Referencia de API | CLI, ProjectMemory, tipos IR |
| Limitaciones | Restricciones conocidas y compromisos de diseño |
| Ejemplos | Recorridos completos de extremo a extremo |
| Documento | Descripción |
|---|---|
| ESTADO-IMPLEMENTACION.md | Qué funciona hoy, qué no, checklist de prerequisitos |
| TROUBLESHOOTING.md | Errores por fase con solución paso a paso |
| EJEMPLO-API-REST.md | Walkthrough API REST + JWT + PostgreSQL |
| MEMORIA-Y-OBSERVABILIDAD.md | API de memoria persistente, SQLite, compresión |
| RELACION-CON-CLAUDE-CODE.md | Mapping FORGE ↔ primitivas nativas de Claude Code |
| COMPATIBILIDAD.md | Contrato de hooks — versiones verificadas |
| ANALISIS-COMPARATIVO-FRAMEWORKS.md | FORGE vs CrewAI vs LangGraph — 10 dimensiones |
| SEGURIDAD-PARA-NOTECNICOS.md | Seguridad explicada sin jerga técnica |
| QUE-PASA-SI-FALLA.md | Recuperación cuando algo sale mal |
| INTEGRACIONES.md | MCPs: Vercel, GitHub, Figma |
Ver CONTRIBUTING.md. Reportes de bugs y propuestas de agentes bienvenidos vía GitHub Issues.
MIT — ver LICENSE.