# Tu código con IA es un desastre (y no es culpa de la IA) *TDD, specs, criterios BDD y archivos de reglas: lo que conviene definir antes de pedirle una sola línea a un agente.* By [QA Step by Step](https://paragraph.com/@simonethg) · 2026-10-22 programar con ia, tdd, bdd, spec-driven development, qa --- La primera vez que le pedí a un agente que me armara una pequeña app de punta a punta, funcionó. Y a la tercera semana ya no me animaba a tocar nada. Cada cambio rompía algo que no tenía nada que ver, los nombres no seguían ninguna lógica y no había un solo test que me dijera qué estaba bien y qué no. El problema no fue la IA. Fue que yo arranqué a pedir código sin haber decidido antes cómo íbamos a trabajar. En mi experiencia como QA, la calidad nunca se agrega al final. Se define al principio. Con la IA pasa exactamente lo mismo, solo que todo ocurre diez veces más rápido, incluido el desorden. Por eso en este artículo te cuento qué metodologías conviene definir **antes** de escribir la primera línea con Claude Code, Codex o Cursor. Por qué la IA genera código difícil de mantener ----------------------------------------------- Un agente de IA está entrenado para darte algo que parezca resolver lo que pediste. Si no le das límites, va a elegir el camino más corto: duplicar lógica, inventar estructuras nuevas en cada archivo o, mi favorito, "arreglar" un test borrándolo. Kent Beck, el creador de TDD, lo llama la diferencia entre _vibe coding_ y _augmented coding_. En el vibe coding solo te importa que el sistema "ande". En el augmented coding te importa el código, su complejidad, los tests y su cobertura, aunque no lo escribas vos a mano. Y el vibe coding tiene costos concretos. Hace poco circulaba que buscando `OPENAI_API_KEY` en GitHub aparecían miles de claves expuestas por proyectos hechos a las apuradas. Eso no es un problema de la herramienta: es un problema de proceso. TDD con IA: primero el test, después el código ---------------------------------------------- ![](https://storage.googleapis.com/papyrus_images/d1e5eab41fdfdee15fee363466e0b8315f9d9274e4774cd93b2482e6c81761c4.png) **Qué es TDD, en criollo.** TDD (Test-Driven Development, desarrollo guiado por pruebas) es escribir primero una prueba automática que describe lo que el código debería hacer, verla fallar, y recién ahí escribir el código mínimo para que pase. El ciclo tiene tres pasos: * **Rojo:** escribís un test que falla, porque la funcionalidad todavía no existe. * **Verde:** escribís (o le pedís a la IA) el código justo para que ese test pase. * **Refactor:** con el test en verde, ordenás el código sin cambiar su comportamiento. ### Cómo lo aplico con un agente Lo que mejor me funciona es que **yo** defina el comportamiento esperado y la IA haga la implementación. Le paso el test (o los escenarios escritos en lenguaje natural para que los convierta en test), reviso que el test pruebe lo que yo quiero, y después le pido: "hacé pasar este test sin modificarlo". Esa última frase es clave. Kent Beck contó que uno de sus mayores problemas con los agentes era que borraban tests para que "pasaran". Si el test es tu contrato, el agente no lo puede tocar sin tu aprobación. Birgitta Böckeler, en el sitio de Martin Fowler, probó pedirle al agente que haga todo el ciclo TDD solo, dentro de su propio loop, y no encontró una diferencia clara frente a no hacerlo. Para mí la lectura es esta: el valor de TDD con IA no está en el ritual, está en que **una persona decide qué significa "funciona"** antes de que aparezca el código. Ahí es donde entramos los QA. Spec-driven development: planificar antes de pedir -------------------------------------------------- ![](https://storage.googleapis.com/papyrus_images/e29a6f5215d73b85326605c0e6f2240a241b0a7eaa9a5f2de3d1ea29ff4a9f44.png) Spec-driven development (SDD) significa escribir una especificación antes de codear con IA. La spec es la fuente de verdad, tanto para vos como para el agente. Herramientas como GitHub Spec Kit proponen un flujo de requerimientos, diseño técnico y lista de tareas, cada uno en un archivo markdown dentro del repo. No hace falta instalar nada para empezar. En la práctica, antes de cada funcionalidad le pido al agente que **no escriba código** y que me arme un plan: qué archivos va a tocar, qué tareas hay y en qué orden. Lo leo, lo corrijo y recién después le doy luz verde. Claude Code, Codex y Cursor tienen modos de planificación pensados justamente para esto. BDD: criterios de aceptación que entiende cualquiera ---------------------------------------------------- ![](https://storage.googleapis.com/papyrus_images/b6bd54310d27869d3c52e800f1e32399834b32f75edc25a52e32714d48b3f63f.png) BDD (Behavior-Driven Development) es describir el comportamiento con ejemplos concretos en formato **Dado / Cuando / Entonces**. Por ejemplo: > **Dado** un usuario con el carrito vacío > **Cuando** intenta finalizar la compra > **Entonces** ve el mensaje "Tu carrito está vacío" y no se genera la orden. Para quien viene de QA, esto es terreno conocido: son nuestros casos de prueba. La diferencia es que ahora también son la mejor instrucción que le podés dar a una IA. Yo los tengo documentados en Qase y se los paso al agente como criterio de "terminado". Si no cumple todos los escenarios, la tarea no está lista. Archivos de contexto y reglas del proyecto ------------------------------------------ ![](https://storage.googleapis.com/papyrus_images/550ac21792566309f64728a64dfdb581997091a35f39fd22a6f3eb06e8ab20ab.png) Cada vez que abrís una conversación nueva, el agente arranca sin memoria. Si no le decís cómo es tu proyecto, va a improvisar. Para eso existen los archivos de contexto: `AGENTS.md` (que leen Codex y otros agentes), `CLAUDE.md` para Claude Code y las reglas de proyecto de Cursor. Ahí escribo cosas como: * Cómo se corren los tests y que siempre tienen que pasar antes de dar algo por terminado. * La estructura de carpetas y dónde va cada cosa. * Convenciones de nombres y patrones que se usan (y los que están prohibidos). * Que nunca se suban claves ni secretos al repo. A esto la comunidad le está llamando _harness engineering_: diseñar las herramientas, los límites y la memoria alrededor del agente. Suena sofisticado, pero arranca con un archivo de texto bien escrito. Pasos chicos y commits frecuentes --------------------------------- En mi experiencia, la mayoría de los desastres con IA vienen de pedidos gigantes. "Armame el módulo de pagos" es una invitación a 800 líneas imposibles de revisar. Lo que funciona: una tarea chica, el test que la valida, el agente la implementa, corro la suite, hago commit en GitHub. Y vuelta a empezar. Si algo se rompe, vuelvo al último commit sano en segundos en lugar de perder una tarde buscando qué cambió. Revisión humana: la responsabilidad sigue siendo tuya ----------------------------------------------------- El código lo escribió la IA, pero la responsabilidad de lo que llega a producción es de quien lo aprueba. Por eso todo cambio pasa por un pull request y lo leo como leería el de un compañero: ¿Hace lo que pide la spec? ¿Hay tests nuevos? ¿Tocó archivos que no tenía que tocar? ¿Modificó algún test existente? Esa última pregunta es la que más veces me salvó. Checklist para arrancar ----------------------- Antes de pedirle código a la IA, revisá que tengas: 1. Un `AGENTS.md` o `CLAUDE.md` con cómo correr los tests y las reglas del proyecto. 2. La funcionalidad descrita en una spec corta, con criterios Dado / Cuando / Entonces. 3. Un plan aprobado por vos antes de que el agente toque código. 4. Al menos un test que falla y describe el comportamiento esperado. 5. La regla explícita de que el agente no puede borrar ni modificar tests sin avisar. 6. Tareas chicas y un commit por cada paso en verde. 7. Una revisión humana del pull request antes de mergear. Para cerrar ----------- La IA no reemplaza el criterio: lo amplifica. Si arrancás sin reglas, amplifica el desorden. Si definís antes cómo se valida, cómo se planifica y quién revisa, te devuelve código que vas a poder seguir manteniendo dentro de seis meses. Y ahí, quienes venimos de testing tenemos una ventaja enorme: llevamos años pensando primero en cómo saber si algo funciona. * * * Fuente: Kent Beck, "Augmented Coding: Beyond the Vibes": [https://newsletter.kentbeck.com/p/augmented-coding-beyond-the-vibes](https://newsletter.kentbeck.com/p/augmented-coding-beyond-the-vibes) Fuente: Gergely Orosz, "TDD, AI agents and coding with Kent Beck": [https://newsletter.pragmaticengineer.com/p/tdd-ai-agents-and-coding-with-kent](https://newsletter.pragmaticengineer.com/p/tdd-ai-agents-and-coding-with-kent) Fuente: Birgitta Böckeler, "TDD inside the agent loop": [https://www.martinfowler.com/articles/exploring-gen-ai/tdd-in-the-agent-loop.html](https://www.martinfowler.com/articles/exploring-gen-ai/tdd-in-the-agent-loop.html) Fuente: Birgitta Böckeler, "Understanding Spec-Driven-Development: Kiro, spec-kit, and Tessl": [https://www.martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html](https://www.martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html) Fuente: GitHub Spec Kit: [https://github.com/github/spec-kit](https://github.com/github/spec-kit) --- *Originally published on [QA Step by Step](https://paragraph.com/@simonethg/metodologias-antes-de-programar-con-ia)*