Desarrollo de software con IA: el método, no la herramienta

Llevo tiempo viendo la misma escena en proyectos distintos. Alguien pide un endpoint nuevo, la herramienta lo escribe en veinte segundos, el código compila, los tests pasan, y aun así el cambio está mal: devuelve un campo con otro nombre, trata un caso de negocio de una forma que nadie acordó o «arregla» de paso algo de lo que dependía otro equipo.

El código no era malo. Era un código perfectamente razonable para un requisito que nadie llegó a escribir.

Eso es lo que ha cambiado. Durante veinte años el cuello de botella fue teclear: convertir una idea clara en clases, métodos y consultas costaba tiempo, y por eso casi toda la ingeniería de software se organizó alrededor de producir código con menos errores. Hoy esa parte se ha abaratado muchísimo. Controladores, DTOs, tests, refactorizaciones mecánicas, SQL, configuración: todo eso se genera en minutos.

Cuando escribir cuesta poco, la pregunta interesante deja de ser cómo consigo que genere más rápido y pasa a ser cómo sabe esta herramienta qué tiene que implementar. Y la respuesta honesta, en la mayoría de equipos, es: lo deduce. De un ticket de tres líneas, del código que tiene alrededor y de lo que estadísticamente suele hacerse en proyectos parecidos.

A veces acierta. Cuando falla, no falla de forma escandalosa: falla de forma razonable, que es mucho peor, porque nadie lo nota en la revisión.

Este artículo va sobre cómo se cierra ese hueco. Qué es lo que hay que tener escrito antes de generar nada, por qué las empresas están pagando por herramientas que en apariencia hacen lo mismo que una IA gratuita, y por qué comprar las licencias sin cambiar el método deja casi todo el valor sobre la mesa.

Un desarrollador con una IA gratuita en otra pestaña resuelve su problema. Una organización con quinientos desarrolladores haciendo eso tiene cinco problemas distintos, y ninguno es la calidad del código.

No sabe qué código ha salido de la empresa. No puede retirar el acceso a quien se va. No puede aplicar una convención a todo el equipo. No tiene ni un registro de lo que ha pasado. Y el resultado del trabajo entra en el repositorio por copiar y pegar, sin pasar por ningún sitio donde alguien pueda revisarlo con criterio.

Visto así, la comparación «Copilot frente a una IA gratuita» está mal planteada. No se comparan dos generadores de código: se compara un generador de código con una capa integrada donde ya vive el trabajo —editor, repositorio, pull request, identidades—. Por eso la decisión suele tomarla el responsable de plataforma y no el equipo que va a programar.

Y por eso el argumento a favor de una herramienta concreta siempre es contextual. Para quien ya trabaja sobre GitHub, Copilot reduce superficie: menos sistemas, menos cuentas, menos sitios por donde algo puede escaparse. Si tu código vive en otra plataforma, buena parte de esa ventaja desaparece y hay que rehacer la comparación con los mismos criterios. No hay respuesta universal, y desconfía de quien te la dé.

La herramienta es una condición necesaria y no es la parte difícil. La parte difícil es el método, y esa no viene en la licencia.

«Créame este endpoint.» «Refactoriza esta clase.» «Genera los tests.» «Arregla este error.»

Son las cuatro peticiones que concentran casi todo el uso real, y las cuatro comparten el mismo defecto: describen una tarea, no un comportamiento. No dicen qué debe pasar cuando el correo ya existe, ni qué se devuelve si no hay resultados, ni cuál de las tres formas de manejar errores que conviven en el proyecto es la buena.

La herramienta necesita esas respuestas para escribir la primera línea, así que se las da ella. Y ahí aparecen tres fallos que cualquiera que haya metido IA en un equipo reconoce al instante.

Fíjate en la tercera columna. Ninguno de los tres se detecta en el momento, y ninguno se arregla escribiendo instrucciones más largas o eligiendo un modelo mejor. Son fallos de información ausente, no de capacidad: la herramienta no podía saber lo que nadie había escrito.

La conclusión práctica es poco glamurosa: el trabajo importante ocurre antes de abrir el editor. Y como ese trabajo consiste en escribir cosas —qué hay, qué decidimos, qué debe hacer— el método que mejor funciona es sorprendentemente parecido a documentar bien. Con una diferencia de peso: ahora la documentación tiene un lector que la usa de verdad.

La idea de fondo es una sola: el código es la consecuencia de algo que se decidió antes, no el sitio donde se decide. Lo que sigue es cómo se estructura ese «antes» para que una herramienta pueda trabajar con él.

AS-IS · qué existe hoy

Antes de pedir un cambio hay que saber qué se está cambiando. Parece obvio y casi nunca está escrito: qué hace ese endpoint, quién lo llama, qué comportamiento raro tiene y desde cuándo, qué pasa si dejamos de devolver ese campo.

La regla que hace útil esta capa es separar lo que se ha verificado de lo que se supone. «Este servicio no se usa» es una conclusión; «no he encontrado quién lo llama» es una observación. La primera autoriza a borrarlo, la segunda no. Cuando las dos se escriben igual, alguien acaba borrando algo que sí se usaba.

Decisiones · qué hemos elegido

Aquí viven las decisiones de arquitectura y las restricciones: qué stack, qué patrón de errores, qué no se toca, qué requiere aprobación. Son los ADR de toda la vida y cualquier formato sirve, siempre que cada decisión diga entre qué alternativas se eligió y qué consecuencias acepta.

La restricción más rentable de escribir es casi siempre la de alcance: qué entra en este cambio y qué no. Es la que evita la «mejora de oportunidad», que es el fallo más caro de los tres de la sección anterior.

Spec · qué debe hacer

Es la capa que convierte una intención en algo comprobable. «El usuario debe poder consultar sus vuelos» es un requisito y no sirve para generar nada: no dice qué pasa si no tiene vuelos, si los cancelados cuentan ni cómo se ordenan.

La prueba para saber si algo está especificado es simple: ¿puedo escribir un test que falle si esto no se cumple? Si no puedo, sigue siendo un requisito.

Implementación, tests y revisión

Aquí entra la herramienta, y llega con el trabajo hecho: sabe qué existe, qué se decidió y qué tiene que hacer. Su tarea deja de ser interpretar y pasa a ser construir.

Con los tests hay un matiz que decide su valor. Un test escrito a partir del código recién generado describe lo que ese código hace, y pasa igual si el comportamiento es correcto que si es incorrecto de forma consistente. Para que un test informe de algo, el comportamiento esperado tiene que venir de fuera del código: de la spec, del contrato o de un caso de aceptación acordado. La pregunta útil al revisar un test generado no es si pasa, sino qué defecto concreto lo haría fallar.

Las cuatro capas, y por qué no se mezclan

El ejemplo que mejor explica por qué esto importa: en un proyecto, el análisis documentó que una clase de auditoría heredaba métodos de escritura. Si esa observación hubiera pasado directa a especificación, el sistema nuevo habría implementado altas que nadie invoca. La separación obligó a preguntar si había evidencia de que alguien las llamara. No la había. Una supuesta funcionalidad se convirtió en una restricción de solo lectura. Método heredado no es lo mismo que funcionalidad.

La diferencia entre explicar la arquitectura en un chat y tenerla escrita en el repositorio no es de comodidad. Un contexto versionado tiene tres propiedades que uno conversacional no puede tener: se revisa en un pull request, así que su calidad se discute como se discute el código; aplica a todo el equipo, en vez de depender de quién escribió el prompt; y evoluciona con el proyecto, así que cuando una convención cambia se corrige en un sitio.

Qué recibe la IA

No un prompt gigante. Los artefactos que el proyecto ya debería tener:

• El documento de arquitectura, que dice dónde va cada pieza.
• Las decisiones y restricciones vigentes: qué está decidido, qué no se toca y qué requiere aprobación.
• La spec del cambio, con los casos raros incluidos.
• El contrato, cuando hay una API de por medio.
• Un caso de uso ya resuelto. Es el contexto más eficaz por volumen: un ejemplo bueno ahorra páginas de descripción.
• Los tests existentes, que muestran qué se considera correcto aquí.

En un repositorio de GitHub esto se traduce en rutas concretas. Las instrucciones generales viven en .github/copilot-instructions.md; las que solo aplican a determinadas rutas, en .github/instructions/*.instructions.md con un campo applyTo que las activa por patrón. Existe además el convenio AGENTS.md, que varias herramientas leen y permite escribir las reglas una sola vez sin atarlas a un proveedor.

---
applyTo: "src/main/java/**/infrastructure/rest/**"
---

# Adaptadores REST

- El contrato vive en `resources/openapi/customers.yaml` y es la
  especificación: si el código y el contrato divergen, el defecto
  está en el código.
- No se añaden endpoints que el contrato no declare.
- No se devuelven entidades de persistencia.
- Los errores se traducen en el `@RestControllerAdvice` a las
  respuestas declaradas. No se inventan códigos de estado.
- `OrderController` es la referencia de estilo para este paquete.

Es corto a propósito. Hace tres cosas que ningún prompt hace igual de bien: declara cuál es la fuente de verdad y en qué dirección se resuelve un conflicto, prohíbe comportamientos concretos en lugar de describir un ideal, y señala un ejemplo dentro del propio repositorio.

La regla que evita que esto se convierta en burocracia

Hay un modo de fallo que aparece justo cuando un equipo se toma esto en serio: documentación que crece más rápido que el conocimiento. Las señales son reconocibles: la misma regla redactada de tres formas en tres ficheros, documentos que nadie ha leído desde que se escribieron, un cambio trivial que obliga a tocar cinco ficheros de instrucciones.

La contramedida es escribir cada restricción una sola vez, en el sitio más general donde sea cierta. Y que las reglas prescriban una acción, no una virtud: «no cuentes de memoria, obtén los recuentos buscando en el código» sirve; «sé riguroso» no sirve para nada, porque no se puede verificar.

Lo que se escribe antes

La especificación de un cambio así cabe en media pantalla. No hace falta más.

## Alta de cliente

- Con nombre y correo válidos se crea un cliente con identificador
  propio y se devuelve **201**.
- Si faltan campos o el correo no tiene formato válido, **400**.
- Si el correo ya pertenece a otro cliente, **409** y no se crea nada.

Fuera de alcance: modificación y baja de clientes.
Pendiente de decisión: si el correo se normaliza antes de comparar.

Dos detalles que parecen menores y no lo son. «Fuera de alcance» es lo que evita que aparezcan de regalo un PUT y un DELETE que nadie pidió. Y «pendiente de decisión» es la regla de escape en acción: la normalización del correo es una decisión de producto con consecuencias, así que se marca en lugar de resolverse en el editor.

Como es una API, ese comportamiento se concreta además en el contrato:

paths:
  /v1/customers:
    post:
      operationId: createCustomer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CustomerRequest"
      responses:
        "201":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CustomerResponse"
        "400": { $ref: "#/components/responses/BadRequest" }
        "409": { $ref: "#/components/responses/Conflict" }

Lo que hace la herramienta

Con eso delante, la petición deja de ser «créame una API de clientes» y pasa a ser implementar un contrato conocido siguiendo las convenciones del paquete. La herramienta ya no elige nombres de campo, ni códigos de estado, ni la forma del error: todo eso venía dado. Genera el controlador, el servicio de dominio y el manejador de excepciones.

@RestControllerAdvice
class CustomerExceptionHandler {

    /** El 409 del contrato. Sin esto, el conflicto saldría como 500. */
    @ExceptionHandler(EmailAlreadyRegisteredException.class)
    ResponseEntity<ProblemDetail> onDuplicate(EmailAlreadyRegisteredException ex) {

        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
            HttpStatus.CONFLICT,
            "El correo ya pertenece a otro cliente"
        );

        problem.setProperty("field", "email");

        return ResponseEntity.status(HttpStatus.CONFLICT).body(problem);
    }
}

Ese manejador es el sitio donde más veces se pierde la conformidad, y merece la pena entender por qué. Si nadie traduce la excepción de dominio, sale como 500. El contrato decía 409. El código compila, los tests de servicio pasan, y el consumidor recibe un error de servidor ante una situación de negocio perfectamente prevista —que además va a reintentar, porque un 500 parece transitorio—.

Nada de eso lo detecta el compilador. Lo detecta un test que valide la respuesta contra el contrato, que es distinto de un test de integración: el de integración comprueba que las piezas funcionan juntas y pasaría igual aunque el servicio devolviera customerId donde el contrato promete id. Herramientas como swagger-request-validator hacen esa comprobación sobre las peticiones y respuestas reales del servicio.

El problema del agente que lo hace todo es que mezcla observar con decidir. Analiza el sistema, y en el mismo paso concluye qué hay que hacer con él. Cuando eso ocurre no queda constancia de cuál de las dos cosas estaba haciendo, y una deducción razonable del análisis reaparece dos pasos después citada como hecho verificado.

Separar por roles no es una preferencia organizativa. Es lo que permite que una afirmación tenga un origen comprobable, y que cada paso se pueda verificar por separado.

Todos trabajan sobre el mismo material —el de la sección anterior— y eso es lo que hace que el reparto funcione. Sin contexto compartido, cuatro agentes especializados son cuatro fuentes de interpretaciones distintas.

Dos límites merecen estar escritos. Una condición de parada: qué hacer cuando falta un requisito previo —decirlo y detenerse—, porque el comportamiento por defecto es improvisar el paso que falta. Y un límite de alcance: «refactoriza lo que veas mal por el camino» produce diffs que nadie puede revisar.

Los agentes no se entrenan: se curan

Cuando un agente falla, la reacción instintiva es escribir una regla nueva. Casi siempre es el arreglo equivocado. Si afirmó una cifra falsa, no le faltaba disciplina: le faltaba el dato, y hay que añadirlo al contexto. Si propuso una mejora no pedida, sí le faltaba una regla de alcance. Si el agente de análisis editó un fichero, lo que falla es el reparto de tareas.

Escribir una regla donde faltaba contexto engorda las instrucciones sin arreglar nada, y a la larga las vuelve inútiles de puro largas. Merece la pena parar un momento a clasificar el fallo antes de corregirlo.

Qué revisa una persona

La revisión ha cambiado de pregunta. Cuando el código lo escribía una persona, «¿está bien escrito?» discriminaba. Ahora no: el código generado casi siempre está bien escrito. Está mal decidido, que es otra cosa.

Lo que una persona tiene que mirar es el comportamiento frente a lo acordado, el alcance —¿hay aquí algo que nadie pidió?—, el impacto sobre consumidores, la seguridad y si los tests podrían fallar alguna vez. Una primera pasada automática puede resolver lo que no requiere criterio —conformidad con el contrato, análisis de seguridad, dependencias, secretos— y dejar la atención humana para lo que sí.

Hay un séptimo que aparece justo cuando un equipo hace bien todo lo anterior: medir la mejora por la sensación. Conviene saber que la evidencia sobre productividad es contradictoria. Los experimentos sobre tareas acotadas y proyectos nuevos tienden a mostrar mejoras notables; en cambio, un ensayo controlado sobre desarrolladores expertos trabajando en repositorios grandes que conocían bien midió tiempos de finalización mayores con herramientas de IA, mientras los propios participantes creían haber ido más rápido.

Ese desajuste entre percepción y medición es el dato más útil del conjunto, porque implica que preguntar al equipo no sirve como evidencia. Si vas a justificar la inversión, mide sobre tu propio proceso, con una línea base previa, y cuenta el coste de revisión y de corrección dentro del resultado.

Falta un paso que no aparece porque no es lineal: el retorno. Cuando la revisión detecta que la herramienta vuelve a equivocarse en lo mismo, lo útil no es corregir ese pull request, sino añadir lo que faltaba al contexto. Un equipo que corrige el mismo problema tres veces en tres revisiones tiene un problema de contexto, no de modelo.

Por dónde empezar

No hace falta montar todo esto de golpe, y montarlo de golpe suele salir mal. El orden que mejor funciona es el inverso al que parece: empezar por donde equivocarse cuesta más caro.

Primero, escribir lo que el equipo ya sabe de memoria: las convenciones, el patrón de errores, cómo se estructura un caso de uso aquí. Es barato y se nota en la primera semana. Después, especificar antes de implementar en los cambios que tocan algo compartido. Y solo entonces los agentes, que sin lo anterior son una forma cara de generar pull requests que nadie puede revisar con criterio.

Lo que realmente separa a unas empresas de otras

Dentro de poco todas las organizaciones tendrán acceso a herramientas equivalentes. Los modelos se alcanzan entre sí en meses y se cambian en un desplegable. Lo que no se cambia en un desplegable es el conocimiento del proyecto estructurado de forma que alguien —o algo— pueda usarlo: qué existe, qué se decidió, qué debe hacer el sistema y cómo se comprueba.

Esa es la parte que pertenece a la empresa, la que no viene en ninguna licencia y la que convierte la IA en algo repetible en lugar de en una sucesión de aciertos individuales. Visto así, la IA no sustituye al proceso de ingeniería: hace que el proceso de ingeniería importe más que antes, porque ahora tiene un consumidor que lo lee literalmente y no rellena los huecos con sentido común.

La IA ya sabe escribir código. Conseguir que escriba el código correcto es un problema de conocimiento, no de modelo.

Puede escribir la implementación. Pero qué debe implementar lo decidimos nosotros, y hay que decidirlo antes.

Si estás intentando meter IA en el ciclo de desarrollo de una plataforma con integraciones vivas, varios equipos y contratos que no se pueden romper, el problema se parece más a uno de arquitectura que a uno de herramientas. Es el tipo de trabajo que abordo en una auditoría técnica: qué conocimiento está escrito y cuál vive solo en la cabeza de tres personas, qué contratos mienten, y en qué orden conviene ordenarlo para que automatizar compense.

Fuentes

• GitHub Docs — Instrucciones personalizadas del repositorio Rutas exactas de copilot-instructions.md y de las instrucciones por patrón. Respalda la sección 5.
• GitHub Docs — Sobre el agente de codificación Funcionamiento, entorno de ejecución y límites declarados. Respalda las secciones 2 y 7.
• GitHub Docs — Administración de Copilot Políticas, exclusión de contenido y registros de auditoría: los mecanismos que evalúa la sección 2.
• AGENTS.md Convenio abierto para describir el proyecto a herramientas de IA sin atarlo a un proveedor.
• OpenAPI Specification Define con precisión qué se puede declarar en un contrato y, por tanto, qué se puede verificar.
• Atlassian swagger-request-validator Validación de peticiones y respuestas contra un contrato OpenAPI, con integración para MockMvc y REST Assured.
• OpenAPI Generator — Generador Spring Generación de interfaces de servidor desde el contrato, para quien quiera llevar el ejemplo de la sección 6 más lejos.
• Becker et al. — Measuring the Impact of Early-2025 AI on Experienced Open-Source Developer Productivity (METR) Ensayo aleatorizado sobre desarrolladores expertos en repositorios propios: mayor tiempo de finalización con IA, frente a una percepción de mejora. Alcance limitado a ese perfil y a las herramientas de principios de 2025.
• Peng et al. — The Impact of AI on Developer Productivity: Evidence from GitHub Copilot Experimento controlado sobre una tarea acotada y nueva, con mejora sustancial. Es el extremo opuesto del anterior y describe un escenario distinto.
• DORA — Investigación sobre rendimiento de entrega Marco para medir el proceso de entrega sobre indicadores de resultado en lugar de sobre actividad.

Continúa en este blog

• Arquitectura Hexagonal desde cero Cómo aislar el dominio para que el adaptador REST del ejemplo pueda cambiar sin arrastrar las reglas de negocio.
• AI Act: qué cambia de verdad para las empresas La capa de cumplimiento normativo que acompaña al gobierno de la sección 2.
• Inteligencia Artificial empresarial Adopción de IA en plataformas enterprise: arquitectura, gobierno y cumplimiento.
• Auditoría técnica El servicio que instancia este método sobre una plataforma concreta.