Preparar un proyecto para el desarrollo autónomo, con validaciones humanas
La ingeniería de software siempre ha evolucionado, y está cambiando otra vez en la era del desarrollo agéntico. Lo que no ha cambiado es la calidad del código, y los quality gates que garantizan que el código está cubierto por tests y que la aplicación funciona correctamente. Hablo de los tests unitarios y los tests end-to-end como quality gates básicos. En 2026, ya no hay excusa para no tener al menos tests unitarios para el comportamiento, y mejor aún, tests end-to-end para el funcionamiento de las funcionalidades.
Aquí van mis notas y el checklist que sigo en cada proyecto que preparo, sea un proyecto nuevo desde cero o uno existente. El proceso es el mismo, pero un proyecto existente requiere más atención: ya hay una base de código, deuda técnica, y probablemente una mala arquitectura que tener en cuenta para que los agentes trabajen correctamente.
Lectura rápida: el artículo en una imagen
flowchart TB
accDescr: Los pasos 1 a 4 se hacen una vez por repositorio; el paso 5, una spec aprobada por un humano, se hace a nivel de proyecto; después empieza el desarrollo agéntico autónomo.
subgraph repo [Por repositorio]
audit([1. Auditoría: lo que falta]):::human --> critical([2. Funcionalidades críticas, con negocio]):::gate
critical --> gates(3. Quality gates y estructura):::check
gates --> context([4. Archivo AGENTS mínimo]):::human
end
subgraph project [Nivel proyecto]
spec([5. Spec aprobada por un humano]):::gate
end
context --> spec
spec --> dev[Desarrollo agéntico autónomo]:::agent
classDef human fill:#e8f0ee,stroke:#006b56,color:#111827
classDef agent fill:#ffffff,stroke:#3d4654,color:#111827
classDef check fill:#f2f5f4,stroke:#6b7280,color:#111827
classDef gate fill:#e8f0ee,stroke:#006b56,stroke-width:2px,color:#111827
El checklist de un vistazo
| Paso | Qué hago | Qué produce |
|---|---|---|
| 1. Auditoría | Listar lo que existe y lo que falta | Una lista de lo que falta |
| 2. Funcionalidades críticas | Acordar con negocio qué funcionalidades nunca deben romperse | Un checklist de escenarios |
| 3. Quality gates mínimos y estructura | Linter, tests unitarios, cobertura, tests end-to-end, capas | Scripts que los agentes pueden ejecutar |
| 4. Contexto para los agentes | Un archivo AGENTS mínimo | Reglas y referencias que los agentes leen |
| 5. Proceso de especificación | Cómo se escriben las specs y cómo las aprueba un humano | Instrucciones claras para los agentes de desarrollo |
Estos pasos son necesarios para un pipeline totalmente automatizado, donde agentes de IA hacen la implementación, para mantener la aplicación estable.
- La investigación para este artículo no encontró ningún estudio que pruebe estos cinco pasos como secuencia. La secuencia es mi experiencia; las fuentes de abajo respaldan los pasos uno por uno.
Fuentes. La documentación de Claude Code de Anthropic dice que “in most cases, your first plain prompt in a fresh session already does the right thing, without any setup on your part”, y también: “If it has nothing to run that tells it whether the work actually is done, “looks done” is all it has to go on. In practice that makes you the test suite.” (Best practices for Claude Code)
1. Auditar el proyecto
Identificar lo que el proyecto ya tiene como quality gates y automatizaciones:
- la arquitectura, la estructura de carpetas y las capas (controllers, servicios, componentes…),
- la seguridad,
- los linters,
- los tests unitarios y la cobertura de código,
- los tests end-to-end, de integración y de rendimiento,
- el CI/CD, y si el despliegue es manual o automático,
- los agentes que ya hay en el proyecto,
- la deuda técnica conocida.
Esta primera auditoría nos da lo que falta por cubrir, y el plan de despliegue del paso 3 como requisitos mínimos.
Fuentes.
- Google: “74.45% of the code changes and 69.46% of the edits were generated by the LLM” (Migrating Code At Scale With LLMs At Google).
- Airbnb: una migración de tests estimada en “1.5 years of engineering time” terminada en “6 weeks”; “when a check fails, we bring in the LLM to fix it” (Accelerating Large-Scale Test Migration with LLMs).
- Birgitta Böckeler: “the harness is most needed where it is hardest to build” (Harness engineering for coding agent users).
2. Revisar las funcionalidades críticas
Las funcionalidades críticas se definen, o deberían definirse, con el partner de producto, o con alguien de la empresa que conozca muy bien las funcionalidades críticas de la aplicación. Hay que probar sobre todo las funcionalidades que, si se rompen, afectarían mucho el servicio para los usuarios. Por ejemplo:
- la autenticación,
- el proceso de onboarding,
- los embudos de venta,
- el proceso de pago.
Estos escenarios se convierten en la base de los tests end-to-end del paso 3. También pueden mostrar la necesidad de un conjunto de tests más completo, como tests de rendimiento.
3. Planificar los quality gates mínimos y la estructura objetivo
Planifico el onboarding y el despliegue paso a paso. Lo mínimo para arrancar un pipeline de desarrollo totalmente automatizado:
| Quality gate | Por qué |
|---|---|
| Linter (y verificación de tipos, cuando el lenguaje la tiene) | Reglas de estilo y de estructura que el agente no puede discutir |
| Tests unitarios | El comportamiento |
| Cobertura de tests, con un mínimo que el build impone | El código nuevo llega con sus tests |
| Tests end-to-end sobre las funcionalidades críticas, con entornos dockerizados | La aplicación sigue funcionando para los usuarios |
| CI/CD para los quality gates en las PR, y el despliegue de los entornos (sandbox, producción) | Automatizar el proceso |
Cada quality gate viene con un script claro, para que los agentes puedan ejecutarlo e investigar fácilmente. Pasar los quality gates no basta por sí solo:
- los agentes pueden hacer pasar los tests sin corregir el código,
- PR que pasan los tests igual fallan en la revisión humana,
- así que un paso de revisión siempre es necesario antes de validar una PR.
La revisión de código también es una parte clave del onboarding al desarrollo agéntico, porque cada comentario en las PR puede servir para el autoaprendizaje, para mejorar la configuración de los agentes.
Fuentes.
- Simon Willison: “If your project has a robust, comprehensive and stable test suite agentic coding tools can fly with it” (Vibe engineering).
- METR: “roughly half of test-passing SWE-bench Verified PRs written by mid-2024 to mid/late-2025 agents would not be merged into main” (Many SWE-bench-Passing PRs Would Not Be Merged into Main).
- Un agente “with access to unit tests may delete failing tests rather than fix the underlying bug” (ImpossibleBench).
La estructura: dónde escriben código los agentes
Por experiencia, en una aplicación React Native a la que le faltaban estructura y capas de arquitectura: los agentes a veces escribían imports de acceso a la base de datos en la capa de controllers, en lugar del servicio.
Para este proyecto decidí empezar un proceso de migración para las nuevas funcionalidades, porque una migración del backend también era parte del alcance:
- una nueva estructura de carpetas que sigue las capas de clean architecture / arquitectura hexagonal,
- cada nueva funcionalidad va en la nueva arquitectura,
- las funcionalidades existentes se migran progresivamente, con una validación humana,
- el agente de revisión de código tiene la instrucción de verificar la estructura de arquitectura del código nuevo. Ahí es donde se detectaron y corrigieron los imports de base de datos.
Un proyecto organizado permite a los agentes saber dónde escribir el código de cada capa.
Fuentes.
- Los modelos muestran “strong accuracy for explicit, code-inferable decisions”, en un estudio de architecture decision records en 109 repositorios (Evaluating Large Language Models for Detecting Architectural Decision Violations).
- Anthropic: “If something has to happen every time, make it a hook, a deny rule, or a managed setting” (Best practices for Claude Code).
- Böckeler: “Computational sensors catch the structural stuff reliably” (Harness engineering).
4. Preparar el contexto del proyecto para los agentes
Un archivo AGENTS mínimo, y lo mínimo es justamente la idea: un archivo largo cuesta tokens y no hace mejores a los agentes.
Lo que contiene, solo lo que el código no muestra ya:
| Sección | Qué contiene |
|---|---|
| Quality gates | El comando que los ejecuta todos, y lo que el CI verifica y los scripts no |
| Barreras y bloqueos de seguridad | Cada regla con el lugar donde se aplica (regla de lint, hook, CI); todo lo que debe cumplirse siempre vive ahí, no en el archivo |
| Estructura del proyecto | Una referencia a la regla que impone las capas, no una vista general |
| Vocabulario de negocio | Donde los términos de negocio difieren de los nombres en el código |
| Scripts del paso 3 | Solo los que un agente no encontraría en package.json: requisitos previos, puertos, fixtures |
| Errores conocidos | Los errores que los agentes ya han cometido |
Fuentes. Un estudio controlado de ETH Zurich encontró que “providing context files does not generally improve task success rates” mientras van “increasing inference cost by over 20% on average”, que “context files are not effective at providing a repository overview”, y que un archivo “should only contain specific additional instructions beyond what is already available in the codebase” (Evaluating AGENTS.md).
5. Definir el proceso de especificación
Las specs y el diseño se tienen que hacer con un humano antes. Si las specs son claras, los agentes de desarrollo necesitan instrucciones simples y claras.
- Una spec clara no garantiza que un agente la siga, así que los quality gates del paso 3 siguen siendo necesarios.
- Empecé con GitHub Spec Kit para funcionalidades pequeñas en 2025, y luego pasé a BMAD Method para funcionalidades de mayor alcance.
- BMAD es más completo, y se inspira en el método Agile (“Agile AI-Driven Development”).
Fuentes.
- Böckeler, probando tres herramientas de specs, “frequently saw the agent ultimately not follow all the instructions” (Understanding Spec-Driven-Development).
- El README de Spec Kit ahora lo presenta como un conjunto de herramientas para “SDD or any other process” (github/spec-kit).
Los pasos 1 a 4 se hacen por repositorio. Después de varias iteraciones, logré tener aplicaciones estables tras una gran iteración de desarrollo, con buenos resultados en las nuevas PR. En ese momento dejé de gestionar mis repositorios uno por uno, porque a veces las decisiones vienen de un contexto de proyecto más amplio. Así que ahora el paso 5 se hace a nivel de proyecto, y no de repositorio. Compartiré los detalles en un próximo artículo.