Spec-Driven Development (Spec Kit / Specky)Desenvolvimento Orientado a Especificações (Spec Kit / Specky)Desarrollo Orientado a Especificaciones (Spec Kit / Specky)
Specifications written upstream make AI agents reliable, testable, and reviewable. Spec Kit and Specky provide the executable contract that turns intent into production-grade code.Especificações escritas antes do código tornam agentes de IA confiáveis, testáveis e revisáveis. Spec Kit e Specky fornecem o contrato executável que transforma intenção em código pronto para produção.Las especificaciones escritas antes del código hacen que los agentes de IA sean confiables, testeables y revisables. Spec Kit y Specky proveen el contrato ejecutable que transforma la intención en código listo para producción.
From vibe coding to production discipline
In February 2025, Andrej Karpathy named a pattern that engineers had been living for months: vibe coding — fully giving in to whatever AI generates, without critical review, running it, and moving on. The problem is not that AI-generated code fails to run. It often runs fine. The problem is that code that works is not the same as code that is correct, secure, maintainable, and aligned with business requirements. An SQL injection works, until someone exploits it.
This guide covers the methodology and tooling that close that gap: Spec-Driven Development (SDD), Test-Driven Development (TDD), the GitHub Spec-Kit open source toolkit, and Specky, the MCP engine that executes the methodology programmatically.
The empirical case against uncritical AI adoption
Four studies establish the stakes clearly:
- Pearce et al., 2022 (IEEE S&P): 40% of GitHub Copilot output is vulnerable in security-relevant scenarios.
- Liu et al., 2026 (arXiv 2601.10338): 26.1% of 31,132 agent skills contain at least one security vulnerability.
- Becker et al., 2025 (arXiv 2507.09089): experienced developers are 19% slower on complex projects when using AI without discipline.
- Huang et al., 2025 (arXiv 2512.14012): in an issue tracker agent study, only 8% of agent invocations resulted in a complete success — a merged PR.
The Huang study also found that professionals do not vibe. Qualitative research with 99 experienced developers shows a consistent pattern: pros guide agents through planning and active supervision. As the paper concludes: “As of now, the AIs are not taking over yet, experienced developers are still in control.”
Vibe coding carries four compounding risks: spaghetti architecture that is hard to maintain and expand; context loss that makes Sprint 1 decisions invisible by Sprint 5; a prototype gap where promising demos stall before reaching production; and collaboration friction where nobody can trace why decisions were made.
SDD: the fundamental inversion
Traditional development treats code as the source of truth — documentation goes stale within weeks, tests capture past behavior, and decisions live in chat history. Every new AI prompt starts from scratch.
SDD inverts this. The spec is the source of truth. Code, tests, and documentation are derived artifacts. AI agents carry persistent context. Reviews happen at the spec layer, before a line of code is written.
SDD does not replace prompt engineering or context engineering. It absorbs them and adds a versioned, executable spec layer on top. It is the fifth and final stage of AI-native development maturity, after AI Assistant, Vibe Coding, Prompt Engineering, and Context Engineering.
The four phases of SDD
Every SDD project flows through four phases, where each output is the input for the next:
- Phase 1 — Specify: the product manager defines what and why. Output:
spec.mdcontaining user stories, goals, and success criteria. - Phase 2 — Plan: the architect translates what into how. Output:
plan.mdcovering architecture, tech stack with rationale, data models, API contracts, latency targets, and security specifics. - Phase 3 — Tasks: the dev lead decomposes the plan into atomic, executable, traceable tasks with explicit dependencies and TDD steps. Output:
tasks.mdwith[P]markers for parallelizable work. - Phase 4 — Implement: the developer or coding agent executes tasks, validates continuously against the spec using TDD, and submits for review.
A well-formed spec has six components: a single-sentence goal (the North Star), numbered user stories (US-001 format), measurable success criteria with thresholds rather than adjectives (“login under 200ms p95”, not “fast login”), explicit scope boundaries, external dependencies, and EARS-formatted requirements — the contract the AI compiles against.
TDD in the AI era
Test-Driven Development predates AI agents, but the combination is particularly powerful. The Red-Green-Refactor cycle maps directly onto agent-assisted development:
- RED: write a failing test that expresses desired behavior. If it does not fail, the test is wrong or the behavior already exists.
- GREEN: write the minimum code necessary to pass. No optimization, no extra features.
- REFACTOR: improve design and remove duplication while keeping tests green. Never add behavior in this phase.
With SDD providing the spec, AI agents can translate EARS requirements and acceptance criteria directly into test scaffolds. The developer reviews and runs RED. The agent generates the implementation. RED becomes GREEN. Refactoring remains human-led.
Without TDD, AI-generated code has no safety net for refactoring, edge cases surface in production, and tests get written — if at all — after the fact. With TDD, test failure is the feedback loop, refactoring becomes safe and frequent, and coverage is built in from the start.
EARS: requirements that AI can compile against
Easy Approach to Requirements Syntax (EARS) provides six patterns that eliminate the ambiguity that breaks agent-generated code:
| Pattern | Trigger keyword | Shape |
|---|---|---|
| Ubiquitous | (none) | “The system SHALL [behavior].” |
| Event-driven | WHEN | ”WHEN [event], the system SHALL [behavior].” |
| State-driven | WHILE | ”WHILE [state], the system SHALL [behavior].” |
| Optional | WHERE | ”WHERE [feature included], the system SHALL [behavior].” |
| Unwanted | IF / THEN | ”IF [unwanted], THEN the system SHALL [response].” |
| Complex | combined | ”WHEN A, IF B, THEN system SHALL X.” |
The difference between vague and testable is concrete. “The system should be fast and secure” is rejected. Three EARS requirements replace it: R-001 WHEN a user submits login, the system SHALL respond within 200ms p95 — R-002 The system SHALL hash passwords with bcrypt cost 12 — R-003 IF login fails 5 times, THEN system SHALL lock account for 15 minutes. Each is testable, traceable, and executable. Specky validates EARS programmatically using Zod schemas.
GitHub Spec-Kit: the open source methodology
Spec-Kit (github.com/github/spec-kit) is the methodology layer — slash commands and Markdown templates standardized across 30+ AI agents. Five commands drive the workflow:
/specify— generatespec.mdfrom a business problem statement/plan— generateplan.mdfrom the spec/tasks— decompose intotasks.mdwith parallel markers and TDD steps/implement— execute tasks with a TDD loop: failing tests first, minimum code, then refactor/constitution— define non-negotiable principles, security policies, and architectural constraints
The resulting project structure is five files: constitution.md in .specify/, and spec.md, plan.md, tasks.md inside a numbered feature folder under specs/. Generated code and tests live in src/ and tests/. Every artifact is versioned, reviewable, and the input for the next phase.
Specky: the MCP engine
Specky (github.com/paulasilvatech/specky) is the execution layer — an MCP server with 53 tools across 10 pipeline phases and a state machine that blocks phase-skipping. LGTM gates between Specify, Design, Tasks, and Verify enforce human oversight.
The 53 tools span 12 categories: Input (5 tools for PDF, DOCX, transcripts, Figma), Pipeline Core (8 tools: init through advance_phase), Quality (5 tools including EARS validation and cross-artifact analysis), Diagrams (4 tools, 17 Mermaid types), IaC (3 tools: Terraform, Bicep, Dockerfile), Dev Env (3 tools), Integration (5 tools for branch naming, PR creation, work items), Docs (4 tools), Testing (3 tools covering vitest, pytest, playwright, property-based), plus Turnkey, Checkpointing, and Utility/Ecosystem tools.
Specky handles three project types: greenfield (from scratch), brownfield (existing codebase scanned and initialized with context), and modernization (legacy migration with batch import and transcript ingestion). The 10-phase pipeline is the same; the starting point changes.
Spec-Kit defines the methodology. Specky executes it programmatically.
Constitutional SDD: security by construction
AI-generated code has four recurring security failure modes: injection vectors (string concatenation in SQL, unescaped HTML), weak cryptographic defaults (MD5, SHA-1, ECB mode, hardcoded keys), authorization gaps (missing access checks, IDOR, privilege escalation), and silent error handling (catch-all returning generic 500, no audit trail).
Constitutional SDD addresses these by placing non-negotiable principles in the spec layer, in a CONSTITUTION.md file. Each principle names the behavior required, the CWE compliance reference, and the file or path where the trace lives. Every downstream artifact — spec, plan, tasks, code — must honor the constitution.
The results from Marri 2026 (arXiv 2602.02584) on a controlled case study are measurable:
| Metric | Without SDD | With SDD | Improvement |
|---|---|---|---|
| Security defects detected | 11 | 3 | 73% reduction |
| Time to first secure build | 9 days | 4 days | 56% faster |
| Compliance documentation coverage | 23% | 100% | 4.3x |
| Security review iterations | 4 | 1 | 75% reduction |
| Lines of security code | 612 | 847 | 38% more thorough |
The complete picture
SDD ensures you build the right thing. TDD ensures you build it correctly. Constitutional SDD ensures you build it safely.
The 2026 SDD ecosystem combines three layers: Spec-Kit (open source methodology, templates, slash commands, standard across 30+ AI agents), Specky (53 MCP tools, state machine, programmatic EARS, compliance check, cross-artifact analysis), and Constitutional SDD (non-negotiable principles in the spec layer, secure by construction, not by inspection).
When requirements are unclear, use SDD first — capture intent before writing a single test. When behavior is well-defined, TDD alone locks the contract. For production-grade AI development, the recommended path is SDD + TDD together: spec drives test drives code, with constitutional principles ensuring security is built in from the start, not bolted on during review.
De vibe coding a disciplina de produção
Em fevereiro de 2025, Andrej Karpathy nomeou um padrão que os engenheiros já viviam há meses: vibe coding — entregar-se completamente ao que a IA gera, sem revisão crítica, rodar e seguir em frente. O problema não é que o código gerado por IA deixe de funcionar. Na maioria das vezes funciona. O problema é que código que funciona não é o mesmo que código correto, seguro, manutenível e alinhado com os requisitos de negócio. Uma SQL injection funciona, até alguém explorá-la.
Este guia cobre a metodologia e as ferramentas que fecham essa lacuna: Spec-Driven Development (SDD), Test-Driven Development (TDD), o toolkit open source GitHub Spec-Kit, e o Specky, o motor MCP que executa a metodologia de forma programática.
A evidência empírica contra a adoção acrítica de IA
Quatro estudos estabelecem os riscos com clareza:
- Pearce et al., 2022 (IEEE S&P): 40% do output do GitHub Copilot é vulnerável em cenários relevantes de segurança.
- Liu et al., 2026 (arXiv 2601.10338): 26,1% de 31.132 agent skills contêm pelo menos uma vulnerabilidade de segurança.
- Becker et al., 2025 (arXiv 2507.09089): desenvolvedores experientes são 19% mais lentos em projetos complexos quando usam IA sem disciplina.
- Huang et al., 2025 (arXiv 2512.14012): em um estudo com agente de rastreamento de issues, apenas 8% das invocações resultaram em sucesso completo — um PR mergeado.
O estudo de Huang também constatou que profissionais não fazem vibe. Pesquisa qualitativa com 99 desenvolvedores experientes revela um padrão consistente: os profissionais guiam agentes através de planejamento e supervisão ativa. Como o paper conclui: “Por enquanto, as IAs não estão tomando o controle; desenvolvedores experientes ainda estão no comando.”
O vibe coding traz quatro riscos que se acumulam: arquitetura em espaguete difícil de manter e expandir; perda de contexto que torna as decisões da Sprint 1 invisíveis na Sprint 5; um gap de protótipo onde demos promissoras travam antes de chegar à produção; e atrito de colaboração onde ninguém consegue rastrear por que as decisões foram tomadas.
SDD: a inversão fundamental
O desenvolvimento tradicional trata o código como fonte de verdade — a documentação fica desatualizada em semanas, os testes capturam comportamento passado, e as decisões vivem no histórico de chat. Cada novo prompt de IA começa do zero.
O SDD inverte isso. A spec é a fonte de verdade. Código, testes e documentação são artefatos derivados. Os agentes de IA carregam contexto persistente. As revisões acontecem na camada de spec, antes de qualquer linha de código ser escrita.
O SDD não substitui prompt engineering ou context engineering. Ele os absorve e adiciona uma camada de spec versionada e executável por cima. É o quinto e último estágio de maturidade no desenvolvimento AI-native, após AI Assistant, Vibe Coding, Prompt Engineering e Context Engineering.
As quatro fases do SDD
Todo projeto SDD flui por quatro fases, onde cada saída é a entrada da próxima:
- Fase 1 — Specify: o product manager define o quê e o porquê. Saída:
spec.mdcom user stories, objetivos e critérios de sucesso. - Fase 2 — Plan: o arquiteto traduz o quê em como. Saída:
plan.mdcobrindo arquitetura, stack tecnológico com justificativa, modelos de dados, contratos de API, metas de latência e especificações de segurança. - Fase 3 — Tasks: o dev lead decompõe o plano em tarefas atômicas, executáveis e rastreáveis, com dependências explícitas e passos de TDD. Saída:
tasks.mdcom marcadores[P]para trabalho paralelizável. - Fase 4 — Implement: o desenvolvedor ou agente codificador executa as tarefas, valida continuamente contra a spec usando TDD e submete para revisão.
Uma spec bem formada tem seis componentes: um objetivo em frase única (a Estrela do Norte), user stories numeradas (formato US-001), critérios de sucesso mensuráveis com thresholds em vez de adjetivos (“login em menos de 200ms p95”, não “login rápido”), fronteiras de escopo explícitas, dependências externas e requisitos em formato EARS — o contrato contra o qual a IA compila.
TDD na era da IA
O Test-Driven Development é anterior aos agentes de IA, mas a combinação é particularmente poderosa. O ciclo Red-Green-Refactor mapeia diretamente para o desenvolvimento assistido por agentes:
- RED: escreva um teste que falha e expressa o comportamento desejado. Se não falhar, o teste está errado ou o comportamento já existe.
- GREEN: escreva o mínimo de código necessário para passar. Sem otimização, sem features extras.
- REFACTOR: melhore o design e remova duplicação mantendo os testes verdes. Nunca adicione comportamento nesta fase.
Com o SDD fornecendo a spec, os agentes de IA conseguem traduzir requisitos EARS e critérios de aceite diretamente em esqueletos de teste. O desenvolvedor revisa e roda o RED. O agente gera a implementação. RED vira GREEN. O refactoring permanece liderado por humano.
Sem TDD, o código gerado por IA não tem rede de segurança para refactoring, casos de borda surgem em produção, e os testes são escritos — quando são — depois do fato. Com TDD, a falha do teste é o loop de feedback, o refactoring se torna seguro e frequente, e a cobertura é nativa desde o início.
EARS: requisitos contra os quais a IA pode compilar
A Easy Approach to Requirements Syntax (EARS) fornece seis padrões que eliminam a ambiguidade que quebra o código gerado por agentes:
| Padrão | Palavra-gatilho | Formato |
|---|---|---|
| Ubíquo | (nenhuma) | “O sistema DEVE [comportamento].” |
| Orientado a evento | QUANDO | ”QUANDO [evento], o sistema DEVE [comportamento].” |
| Orientado a estado | ENQUANTO | ”ENQUANTO [estado], o sistema DEVE [comportamento].” |
| Opcional | ONDE | ”ONDE [feature incluída], o sistema DEVE [comportamento].” |
| Indesejado | SE / ENTÃO | ”SE [indesejado], ENTÃO o sistema DEVE [resposta].” |
| Complexo | combinado | ”QUANDO A, SE B, ENTÃO sistema DEVE X.” |
A diferença entre vago e testável é concreta. “O sistema deve ser rápido e seguro” é rejeitado. Três requisitos EARS o substituem: R-001 QUANDO um usuário submete login, o sistema DEVE responder em até 200ms p95 — R-002 O sistema DEVE hashear senhas com bcrypt cost 12 — R-003 SE login falhar 5 vezes, ENTÃO o sistema DEVE bloquear a conta por 15 minutos. Cada um é testável, rastreável e executável. O Specky valida EARS programaticamente usando schemas Zod.
GitHub Spec-Kit: a metodologia open source
O Spec-Kit (github.com/github/spec-kit) é a camada de metodologia — slash commands e templates Markdown padronizados em mais de 30 agentes de IA. Cinco comandos conduzem o workflow:
/specify— geraspec.mda partir de um enunciado do problema de negócio/plan— geraplan.mda partir da spec/tasks— decompõe emtasks.mdcom marcadores de paralelismo e passos de TDD/implement— executa tarefas com loop TDD: testes que falham primeiro, código mínimo, depois refactoring/constitution— define princípios não-negociáveis, políticas de segurança e restrições arquiteturais
A estrutura resultante do projeto consiste em cinco arquivos: constitution.md em .specify/, e spec.md, plan.md, tasks.md dentro de uma pasta de feature numerada em specs/. Código gerado e testes ficam em src/ e tests/. Cada artefato é versionado, revisável e a entrada para a próxima fase.
Specky: o motor MCP
O Specky (github.com/paulasilvatech/specky) é a camada de execução — um servidor MCP com 53 ferramentas em 10 fases de pipeline e uma máquina de estados que bloqueia o salto de fases. Gates LGTM entre Specify, Design, Tasks e Verify garantem a supervisão humana.
As 53 ferramentas abrangem 12 categorias: Entrada (5 ferramentas para PDF, DOCX, transcrições, Figma), Pipeline Core (8 ferramentas: do init ao advance_phase), Qualidade (5 ferramentas incluindo validação EARS e análise cross-artefatos), Diagramas (4 ferramentas, 17 tipos Mermaid), IaC (3 ferramentas: Terraform, Bicep, Dockerfile), Ambiente de Desenvolvimento (3 ferramentas), Integração (5 ferramentas para nomenclatura de branches, criação de PRs, work items), Docs (4 ferramentas), Testes (3 ferramentas cobrindo vitest, pytest, playwright, baseados em propriedades), além de ferramentas de Turnkey, Checkpointing e Utilitário/Ecossistema.
O Specky lida com três tipos de projeto: greenfield (do zero), brownfield (codebase existente escaneada e inicializada com contexto) e modernização (migração de legado com importação em lote e ingestão de transcrições). O pipeline de 10 fases é o mesmo; o ponto de partida muda.
O Spec-Kit define a metodologia. O Specky a executa programaticamente.
SDD Constitucional: segurança por construção
O código gerado por IA tem quatro modos de falha de segurança recorrentes: vetores de injeção (concatenação de string em SQL, HTML não-escapado em templates), defaults criptográficos fracos (MD5, SHA-1, modo ECB, chaves hardcoded), lacunas de autorização (verificações de acesso ausentes, IDOR, escalação de privilégio) e tratamento silencioso de erros (catch-all retornando 500 genérico, sem trilha de auditoria).
O SDD Constitucional endereça esses problemas colocando princípios não-negociáveis na camada de spec, em um arquivo CONSTITUTION.md. Cada princípio define o comportamento exigido, a referência de compliance CWE e o arquivo ou caminho onde a rastreabilidade existe. Cada artefato downstream — spec, plan, tasks, código — deve honrar a constituição.
Os resultados do estudo controlado de Marri 2026 (arXiv 2602.02584) são mensuráveis:
| Métrica | Sem SDD | Com SDD | Melhoria |
|---|---|---|---|
| Defeitos de segurança detectados | 11 | 3 | 73% de redução |
| Tempo até o primeiro build seguro | 9 dias | 4 dias | 56% mais rápido |
| Cobertura de documentação de compliance | 23% | 100% | 4,3x |
| Iterações de revisão de segurança | 4 | 1 | 75% de redução |
| Linhas de código de segurança | 612 | 847 | 38% mais completo |
O quadro completo
SDD garante que você está construindo a coisa certa. TDD garante que está construindo certo. SDD Constitucional garante que está construindo com segurança.
O ecossistema SDD em 2026 combina três camadas: Spec-Kit (metodologia open source, templates, slash commands, padrão em mais de 30 agentes de IA), Specky (53 ferramentas MCP, máquina de estados, EARS programático, verificação de compliance, análise cross-artefatos) e SDD Constitucional (princípios não-negociáveis na camada de spec, seguro por construção, não por inspeção).
Quando os requisitos estão pouco claros, use SDD primeiro — capture a intenção antes de escrever um único teste. Quando o comportamento está bem definido, TDD sozinho trava o contrato. Para o desenvolvimento com IA pronto para produção, o caminho recomendado é SDD + TDD juntos: spec conduz o teste que conduz o código, com princípios constitucionais garantindo que a segurança é incorporada desde o início, não adicionada durante a revisão.
De vibe coding a disciplina de producción
En febrero de 2025, Andrej Karpathy nombró un patrón que los ingenieros ya vivían desde hacía meses: vibe coding — entregarse completamente a lo que la IA genera, sin revisión crítica, ejecutarlo y seguir adelante. El problema no es que el código generado por IA deje de funcionar. Frecuentemente funciona. El problema es que código que funciona no es lo mismo que código correcto, seguro, mantenible y alineado con los requisitos de negocio. Una SQL injection funciona, hasta que alguien la explota.
Esta guía cubre la metodología y las herramientas que cierran esa brecha: Spec-Driven Development (SDD), Test-Driven Development (TDD), el toolkit open source GitHub Spec-Kit, y Specky, el motor MCP que ejecuta la metodología de forma programática.
La evidencia empírica contra la adopción acrítica de IA
Cuatro estudios establecen los riesgos con claridad:
- Pearce et al., 2022 (IEEE S&P): el 40% del output de GitHub Copilot es vulnerable en escenarios relevantes de seguridad.
- Liu et al., 2026 (arXiv 2601.10338): el 26,1% de 31.132 agent skills contienen al menos una vulnerabilidad de seguridad.
- Becker et al., 2025 (arXiv 2507.09089): los desarrolladores experimentados son un 19% más lentos en proyectos complejos cuando usan IA sin disciplina.
- Huang et al., 2025 (arXiv 2512.14012): en un estudio con agente de seguimiento de issues, solo el 8% de las invocaciones resultaron en éxito completo — un PR mergeado.
El estudio de Huang también constató que los profesionales no hacen vibe. Una investigación cualitativa con 99 desarrolladores experimentados revela un patrón consistente: los pros guían a los agentes a través de planificación y supervisión activa. Como concluye el paper: “Por ahora, las IAs no están tomando el control; los desarrolladores experimentados siguen al mando.”
El vibe coding conlleva cuatro riesgos que se acumulan: arquitectura espagueti difícil de mantener y expandir; pérdida de contexto que hace invisibles las decisiones del Sprint 1 en el Sprint 5; una brecha de prototipo donde demos prometedoras se estancan antes de llegar a producción; y fricción de colaboración donde nadie puede rastrear por qué se tomaron las decisiones.
SDD: la inversión fundamental
El desarrollo tradicional trata el código como fuente de verdad — la documentación queda obsoleta en semanas, los tests capturan comportamiento pasado, y las decisiones viven en el historial de chat. Cada nuevo prompt de IA empieza de cero.
SDD invierte esto. La spec es la fuente de verdad. Código, tests y documentación son artefactos derivados. Los agentes de IA llevan contexto persistente. Las revisiones ocurren en la capa de spec, antes de que se escriba una sola línea de código.
SDD no reemplaza prompt engineering ni context engineering. Los absorbe y agrega una capa de spec versionada y ejecutable encima. Es el quinto y último estadio de madurez en el desarrollo AI-native, después de AI Assistant, Vibe Coding, Prompt Engineering y Context Engineering.
Las cuatro fases de SDD
Todo proyecto SDD fluye por cuatro fases, donde cada salida es la entrada de la siguiente:
- Fase 1 — Specify: el product manager define el qué y el porqué. Salida:
spec.mdcon user stories, objetivos y criterios de éxito. - Fase 2 — Plan: el arquitecto traduce el qué en cómo. Salida:
plan.mdque cubre arquitectura, stack tecnológico con justificación, modelos de datos, contratos de API, metas de latencia y especificaciones de seguridad. - Fase 3 — Tasks: el dev lead descompone el plan en tareas atómicas, ejecutables y rastreables, con dependencias explícitas y pasos de TDD. Salida:
tasks.mdcon marcadores[P]para trabajo paralelizable. - Fase 4 — Implement: el desarrollador o agente codificador ejecuta las tareas, valida continuamente contra la spec usando TDD y somete a revisión.
Una spec bien formada tiene seis componentes: un objetivo en frase única (la Estrella del Norte), user stories numeradas (formato US-001), criterios de éxito medibles con umbrales en vez de adjetivos (“login bajo 200ms p95”, no “login rápido”), fronteras de alcance explícitas, dependencias externas y requisitos en formato EARS — el contrato contra el que la IA compila.
TDD en la era de la IA
El Test-Driven Development es anterior a los agentes de IA, pero la combinación es particularmente poderosa. El ciclo Red-Green-Refactor mapea directamente al desarrollo asistido por agentes:
- RED: escribe un test que falle y exprese el comportamiento deseado. Si no falla, el test está mal o el comportamiento ya existe.
- GREEN: escribe el mínimo código necesario para pasar. Sin optimización, sin features extras.
- REFACTOR: mejora el diseño y elimina duplicación manteniendo los tests en verde. Nunca agregues comportamiento en esta fase.
Con SDD proveyendo la spec, los agentes de IA pueden traducir requisitos EARS y criterios de aceptación directamente en esqueletos de test. El desarrollador revisa y corre RED. El agente genera la implementación. RED se vuelve GREEN. El refactoring permanece liderado por humano.
Sin TDD, el código generado por IA no tiene red de seguridad para refactoring, los casos de borde aparecen en producción y los tests se escriben — si es que se escriben — después del hecho. Con TDD, el fallo del test es el loop de feedback, el refactoring se vuelve seguro y frecuente, y la cobertura es nativa desde el inicio.
EARS: requisitos contra los que la IA puede compilar
La Easy Approach to Requirements Syntax (EARS) provee seis patrones que eliminan la ambigüedad que rompe el código generado por agentes:
| Patrón | Palabra-disparador | Formato |
|---|---|---|
| Ubicuo | (ninguna) | “El sistema DEBE [comportamiento].” |
| Orientado a evento | CUANDO | ”CUANDO [evento], el sistema DEBE [comportamiento].” |
| Orientado a estado | MIENTRAS | ”MIENTRAS [estado], el sistema DEBE [comportamiento].” |
| Opcional | DONDE | ”DONDE [feature incluido], el sistema DEBE [comportamiento].” |
| No deseado | SI / ENTONCES | ”SI [no deseado], ENTONCES el sistema DEBE [respuesta].” |
| Complejo | combinado | ”CUANDO A, SI B, ENTONCES sistema DEBE X.” |
La diferencia entre vago y testeable es concreta. “El sistema debe ser rápido y seguro” es rechazado. Tres requisitos EARS lo reemplazan: R-001 CUANDO un usuario envía login, el sistema DEBE responder en 200ms p95 — R-002 El sistema DEBE hashear contraseñas con bcrypt cost 12 — R-003 SI login falla 5 veces, ENTONCES el sistema DEBE bloquear la cuenta por 15 minutos. Cada uno es testeable, rastreable y ejecutable. Specky valida EARS programáticamente usando schemas Zod.
GitHub Spec-Kit: la metodología open source
Spec-Kit (github.com/github/spec-kit) es la capa de metodología — slash commands y templates Markdown estandarizados en más de 30 agentes de IA. Cinco comandos conducen el workflow:
/specify— generaspec.mda partir de un enunciado del problema de negocio/plan— generaplan.mda partir de la spec/tasks— descompone entasks.mdcon marcadores de paralelismo y pasos de TDD/implement— ejecuta tareas con loop TDD: tests que fallan primero, código mínimo, luego refactoring/constitution— define principios no-negociables, políticas de seguridad y restricciones arquitecturales
La estructura resultante del proyecto consiste en cinco archivos: constitution.md en .specify/, y spec.md, plan.md, tasks.md dentro de una carpeta de feature numerada bajo specs/. Código generado y tests viven en src/ y tests/. Cada artefacto está versionado, es revisable y es la entrada para la siguiente fase.
Specky: el motor MCP
Specky (github.com/paulasilvatech/specky) es la capa de ejecución — un servidor MCP con 53 herramientas en 10 fases de pipeline y una máquina de estados que bloquea el salto de fases. Gates LGTM entre Specify, Design, Tasks y Verify garantizan la supervisión humana.
Las 53 herramientas abarcan 12 categorías: Entrada (5 herramientas para PDF, DOCX, transcripciones, Figma), Pipeline Core (8 herramientas: del init al advance_phase), Calidad (5 herramientas incluyendo validación EARS y análisis cross-artefactos), Diagramas (4 herramientas, 17 tipos Mermaid), IaC (3 herramientas: Terraform, Bicep, Dockerfile), Entorno de Desarrollo (3 herramientas), Integración (5 herramientas para nomenclatura de branches, creación de PRs, work items), Docs (4 herramientas), Testing (3 herramientas cubriendo vitest, pytest, playwright, basados en propiedades), más herramientas de Turnkey, Checkpointing y Utilidad/Ecosistema.
Specky maneja tres tipos de proyecto: greenfield (desde cero), brownfield (codebase existente escaneada e inicializada con contexto) y modernización (migración de legado con importación por lotes e ingestión de transcripciones). El pipeline de 10 fases es el mismo; el punto de partida cambia.
Spec-Kit define la metodología. Specky la ejecuta programáticamente.
SDD Constitucional: seguridad por construcción
El código generado por IA tiene cuatro modos de fallo de seguridad recurrentes: vectores de inyección (concatenación de strings en SQL, HTML no escapado en templates), defaults criptográficos débiles (MD5, SHA-1, modo ECB, llaves hardcoded), brechas de autorización (verificaciones de acceso ausentes, IDOR, escalación de privilegios) y manejo silencioso de errores (catch-all retornando 500 genérico, sin trail de auditoría).
SDD Constitucional aborda estos problemas colocando principios no-negociables en la capa de spec, en un archivo CONSTITUTION.md. Cada principio define el comportamiento requerido, la referencia de compliance CWE y el archivo o ruta donde existe la trazabilidad. Cada artefacto downstream — spec, plan, tasks, código — debe honrar la constitución.
Los resultados del estudio controlado de Marri 2026 (arXiv 2602.02584) son medibles:
| Métrica | Sin SDD | Con SDD | Mejora |
|---|---|---|---|
| Defectos de seguridad detectados | 11 | 3 | 73% de reducción |
| Tiempo al primer build seguro | 9 días | 4 días | 56% más rápido |
| Cobertura de documentación de compliance | 23% | 100% | 4,3x |
| Iteraciones de revisión de seguridad | 4 | 1 | 75% de reducción |
| Líneas de código de seguridad | 612 | 847 | 38% más completo |
El panorama completo
SDD asegura que estás construyendo lo correcto. TDD asegura que lo estás construyendo correctamente. SDD Constitucional asegura que lo construyes con seguridad.
El ecosistema SDD en 2026 combina tres capas: Spec-Kit (metodología open source, templates, slash commands, estándar en más de 30 agentes de IA), Specky (53 herramientas MCP, máquina de estados, EARS programático, verificación de compliance, análisis cross-artefactos) y SDD Constitucional (principios no-negociables en la capa de spec, seguro por construcción, no por inspección).
Cuando los requisitos no están claros, usa SDD primero — captura la intención antes de escribir un solo test. Cuando el comportamiento está bien definido, TDD solo basta para fijar el contrato. Para el desarrollo con IA listo para producción, el camino recomendado es SDD + TDD juntos: la spec conduce el test que conduce el código, con principios constitucionales que garantizan que la seguridad es incorporada desde el principio, no añadida durante la revisión.
Start with the platform, not the agents. Comece pela plataforma, não pelos agentes. Comience por la plataforma, no por los agentes.
Building the future of software development with AI and Agentic DevOps.