Desarrollo Orientado por Especificaciones
Sustituya el prompting ad-hoc por Live Specs estructuradas y Context Packets para producir resultados de agentes deterministas y evaluables a través del ciclo Especificar-Ejecutar-Evaluar.
Resumen
El Desarrollo Orientado por Especificaciones es un patrón de flujo de trabajo en el que cada unidad de trabajo del agente comienza con una especificación estructurada —una Live Spec— en lugar de un prompt ad-hoc en lenguaje natural. El Context Architect redacta la especificación, un agente la ejecuta y un Eval Harness valida el resultado. Este bucle de tres fases —Especificar, Ejecutar, Evaluar— es la metodología de Spec Driven Development descrita en el Agentic Development Handbook, y es la alternativa principal al Vibe Coding.
Problema
Los equipos que dependen del prompting ad-hoc se enfrentan a modos de fallo predecibles:
- Resultados no reproducibles. La misma intención expresada de forma diferente produce código distinto. No hay un artefacto estable para versionar, comparar o revisar.
- Falta de contexto. Los prompts rara vez contienen el contexto completo del sistema que un agente necesita —restricciones de arquitectura, contratos de interfaz, estándares de calidad— por lo que el agente adivina, y las suposiciones divergen.
- Sin anclaje de evaluación. Sin criterios de aceptación legibles por máquina, no hay forma de verificar automáticamente si el resultado del agente satisface el requisito. La revisión se convierte en un proceso manual y subjetivo.
- Deriva entre sesiones. El conocimiento se evapora entre las sesiones del agente. Cada nueva conversación comienza desde cero a menos que el desarrollador vuelva a proporcionar el contexto manualmente.
Estos problemas se agravan a medida que los equipos escalan el número de agentes y tareas. Lo que funciona para un solo desarrollador que interactúa con un copilot falla cuando múltiples agentes se ejecutan en paralelo a través de una base de código.
Solución
Sustituya el prompt ad-hoc por una capa de especificación formal compuesta por dos artefactos:
- Live Spec — Un documento versionado y legible por máquina que define qué debe construir el agente, incluyendo contratos de comportamiento, criterios de aceptación y referencias al contexto relevante.
- Context Packet — Un conjunto agrupado de archivos, esquemas, ejemplos e instrucciones que el agente recibe junto con la especificación. Los Context Packets proporcionan el cómo: decisiones de arquitectura, estándares de codificación, contratos de API y Golden Samples que demuestran la calidad esperada del resultado.
El Context Architect crea y mantiene estos artefactos. La ejecución sigue el Flujo de Trabajo Triangular:
- Especificar — El Context Architect escribe o actualiza la Live Spec con criterios de aceptación claros y adjunta el Context Packet pertinente.
- Ejecutar — El agente recibe la especificación y el contexto, luego produce código, pruebas o documentación.
- Evaluar — El Eval Harness ejecuta comprobaciones automatizadas contra los criterios de aceptación definidos en la especificación. Los fallos vuelven a la fase de Ejecución con contexto de diagnóstico; los aciertos avanzan el resultado hacia las puertas de revisión humana.
Este patrón aplica los principios de Context Engineering: el cuello de botella en el rendimiento del agente no es la capacidad del modelo, sino la calidad y completitud del contexto proporcionado al modelo.
Implementación
Ejemplos de Código
Can you create a React product card component? It should show the
product image, name, price, and have an add-to-cart button. Use
TypeScript and Tailwind. Make it responsive.This prompt lacks architecture context, has no acceptance criteria, and produces non-reproducible results.
# specs/product-card.spec.yaml
spec:
id: product-card-v2
title: Product Card Component
status: active
author: "@context-architect"
behavioral_contract:
description: >
A presentational React component that displays a single product
with image, name, formatted price, and an add-to-cart action.
inputs:
- name: product
type: "Product"
source: "src/types/product.ts"
outputs:
- rendered ProductCard component
- onAddToCart callback invocation with product ID
acceptance_criteria:
- id: ac-1
description: Renders product image with lazy loading
validation: unit-test
- id: ac-2
description: Displays formatted price using currency util
validation: unit-test
- id: ac-3
description: Calls onAddToCart with product.id on button click
validation: unit-test
- id: ac-4
description: Passes axe accessibility audit with zero violations
validation: a11y-check
- id: ac-5
description: Responsive layout at 320px, 768px, and 1024px breakpoints
validation: visual-regression
context_references:
- path: context/frontend-standards.md
- path: context/component-patterns.md
- path: src/types/product.ts
- path: src/components/ExampleCard.tsx # golden sample
scope:
includes:
- ProductCard component implementation
- Unit tests for all acceptance criteria
excludes:
- Cart state management
- API integrationConsideraciones
- • **Reproducibility.** The same spec produces consistent agent output regardless of phrasing, session, or agent model.
- • **Evaluability.** Machine-readable acceptance criteria enable automated validation through the [[eval-harness]], reducing reliance on manual review.
- • **Knowledge accumulation.** Specs and Context Packets are versioned artifacts that capture institutional knowledge. They survive developer turnover and agent model changes.
- • **Parallelization.** Multiple agents can execute against different specs simultaneously because each spec is self-contained with its own context.
- • **Governance integration.** Specs provide a natural gate for [[gate-based-governance]] — review the spec before authorizing execution, then review agent output against the spec criteria.
- • **Measurable improvement.** Teams can track spec pass rates over time and identify which context gaps cause the most failures.
- • **Upfront investment.** Writing a Live Spec takes more time than typing a prompt. The payoff comes from reuse, reproducibility, and reduced rework — but teams must commit to the practice before seeing returns.
- • **Spec maintenance.** Specs must evolve with the codebase. Stale specs produce incorrect agent output. Teams need processes (or agents) to keep specs current.
- • **Context Packet curation.** Assembling and maintaining high-quality Context Packets requires ongoing effort from the [[context-architect]]. Under-specified context leads to the same problems as ad-hoc prompting.
- • **Tooling maturity.** The ecosystem for spec-driven agent workflows is still developing. Teams may need to build custom tooling for spec parsing, context assembly, and eval harness integration.
- • **Cultural shift.** Developers accustomed to direct coding or conversational prompting may resist the overhead of writing specs. Leadership must reinforce that specs are the primary engineering artifact in an agentic workflow.