AI Coding Agents

1. Objetivos de la semana

2. Continuidad con el proyecto

employee-management/

Lo que ya tenemos

employee-management/
│
├── README.md
├── AGENTS.md
├── CONTRIBUTING.md
├── .env.example
│
├── docs/
│   ├── product.md
│   ├── architecture.md
│   ├── database.md
│   ├── api.md
│   ├── security.md
│   ├── testing.md
│   │
│   ├── requirements/
│   │   ├── US-001.md
│   │   └── US-002.md
│   │
│   └── decisions/
│       └── ADR-001.md
│
├── src/
├── tests/
└── scripts/

3. ¿Qué es un AI Coding Agent?

Un AI Coding Agent es un sistema que puede recibir un objetivo y utilizar herramientas para realizar tareas sobre un entorno de desarrollo.

Ejemplo simplificado

Usuario

"Implementa la creación de empleados"

        ↓

AGENTE

        ↓

Lee README
        ↓
Lee AGENTS.md
        ↓
Lee arquitectura
        ↓
Busca código existente
        ↓
Planifica
        ↓
Modifica archivos
        ↓
Ejecuta tests
        ↓
Analiza errores
        ↓
Corrige
        ↓
Entrega resultado

4. Chatbot vs AI Coding Agent

Analogía

5. Herramientas de un agente

Un agente puede disponer de diferentes herramientas. Las herramientas concretas dependen del producto que utilicemos.

read_file()
write_file()
edit_file()

search("EmployeeService")

npm test

git diff
git status

Principio importante

Más autonomía
      ↓
Más capacidad
      ↓
Más riesgo
      ↓
Necesidad de controles

6. El workflow AI-Native

7. Cómo diseñar una tarea para un agente

Una mala tarea

Haz el módulo de empleados.

Es demasiado ambigua.

Una tarea mejor

Implementa US-001.

Objetivo:
Permitir crear un empleado.

Antes de modificar código:

1. Lee AGENTS.md.
2. Lee docs/architecture.md.
3. Lee docs/database.md.
4. Revisa las entidades existentes.
5. Revisa los tests existentes.

No modifiques archivos todavía.

Primero:

- analiza la implementación;
- identifica archivos afectados;
- propone un plan;
- identifica posibles riesgos.

Espera aprobación antes de implementar.

8. Acceptance Criteria

Una tarea no debería definirse únicamente por lo que queremos construir. También debemos definir cómo sabremos que está terminada.

Ejemplo

US-001

Crear empleado.

Acceptance Criteria:

AC1
El usuario puede introducir nombre.

AC2
El usuario puede introducir email.

AC3
El email debe tener formato válido.

AC4
El email debe ser único.

AC5
No se permite crear empleados
sin nombre.

AC6
Se muestra un mensaje de error
cuando la operación falla.

AC7
La funcionalidad tiene tests.

AC8
Los tests existentes siguen pasando.

9. Planning antes de coding

Uno de los cambios más importantes en el desarrollo asistido por agentes es separar:

THINK

de

DO

Prompt de planificación

Quiero implementar US-001.

No modifiques ningún archivo.

Analiza el repositorio y prepara
un plan de implementación.

Incluye:

1. Archivos que habría que modificar.
2. Archivos que habría que crear.
3. Componentes existentes que podemos reutilizar.
4. Cambios de base de datos.
5. Cambios de API.
6. Cambios de frontend.
7. Tests necesarios.
8. Riesgos.
9. Dependencias.
10. Preguntas abiertas.

Después espera mi aprobación.

Resultado esperado

PLAN

1. Crear Employee entity.

2. Añadir migration.

3. Crear EmployeeRepository.

4. Crear EmployeeService.

5. Añadir endpoint POST /employees.

6. Añadir validación.

7. Crear UI form.

8. Crear unit tests.

9. Crear integration tests.

10. Actualizar docs/api.md.

10. Delegación progresiva

No conviene empezar dando al agente control total sobre el proyecto. Es mejor aumentar progresivamente su autonomía.

11. Code Review con IA

Una ventaja importante de trabajar con agentes es que podemos utilizar una segunda revisión.

Agente implementador

Implementa la funcionalidad.

Agente revisor

Actúa como Senior Code Reviewer.

Revisa los cambios realizados.

Comprueba:

- requisitos;
- arquitectura;
- seguridad;
- tests;
- errores;
- edge cases;
- duplicación;
- mantenibilidad.

No modifiques archivos.

Devuelve los problemas encontrados
ordenados por severidad.

Agent A
   ↓
Implementación
   ↓
Agent B
   ↓
Review
   ↓
Human
   ↓
Approval

12. Qué hacer cuando el agente se equivoca

Error típico

Agente:

"He terminado."

Desarrollador:

npm test

Result:

7 tests failed.

La respuesta incorrecta sería:

"Arregla todo."

Es demasiado vaga.

Mejor enfoque

Los tests han fallado.

Analiza primero los errores.

No modifiques archivos todavía.

Para cada fallo:

1. Explica la causa.
2. Indica qué archivo está implicado.
3. Explica la solución propuesta.
4. Indica si puede existir una regresión.

Después espera aprobación.

Principio

Error
 ↓
Diagnóstico
 ↓
Hipótesis
 ↓
Plan
 ↓
Cambio
 ↓
Test
 ↓
Validación

13. Seguridad al utilizar agentes

Ejemplos de operaciones peligrosas

DROP DATABASE

rm -rf ...

DELETE FROM ...

git push --force

rotación de credenciales

modificación de producción

14. Proyecto práctico

Fase 1 — Preparación

Antes de empezar:

git status

git branch

Comprueba que no tienes cambios pendientes.

Fase 2 — Planning

Pide al agente:

Lee:

AGENTS.md

docs/product.md

docs/architecture.md

docs/database.md

docs/api.md

docs/requirements/US-001.md

No modifiques ningún archivo.

Analiza cómo implementar US-001.

Quiero:

- plan;
- archivos afectados;
- dependencias;
- riesgos;
- tests necesarios.

Espera mi aprobación.

Fase 3 — Revisión humana

Comprueba:

• ¿El agente entendió correctamente el requisito?
• ¿Ha identificado los archivos adecuados?
• ¿Está respetando la arquitectura?
• ¿Está reutilizando componentes?
• ¿Hay cambios innecesarios?
• ¿Hay riesgos?

Fase 4 — Implementación

Una vez aprobado:

Implementa el plan aprobado.

Respeta:

- AGENTS.md;
- architecture.md;
- security.md;
- acceptance criteria.

No introduzcas dependencias
sin justificación.

Implementa tests.

No modifiques funcionalidades
fuera del alcance de US-001.

Fase 5 — Tests

El agente debe ejecutar los tests relevantes.

Fase 6 — Review

Pide al agente que revise su propio trabajo:

Revisa tu implementación.

Comprueba:

1. Acceptance criteria.
2. Tests.
3. Seguridad.
4. Arquitectura.
5. Edge cases.
6. Código duplicado.
7. Documentación.

No realices cambios.

Devuelve los problemas encontrados.

Fase 7 — Auditoría final

Finalmente pregunta:

Compara la implementación actual
con docs/requirements/US-001.md.

Dime:

- qué requisitos están cubiertos;
- cuáles no;
- qué supuestos has realizado;
- qué riesgos quedan;
- qué debería revisarse manualmente.

15. Ejercicios prácticos

Haz el login.

Implementa US-XXX — Autenticación.

Antes de modificar:

1. Lee AGENTS.md.
2. Lee security.md.
3. Lee architecture.md.
4. Analiza autenticación existente.
5. Revisa tests.

Primero crea un plan.

No modifiques archivos
hasta que el plan sea aprobado.

Acceptance criteria:

- usuario válido puede autenticarse;
- credenciales incorrectas son rechazadas;
- no se almacenan contraseñas en texto plano;
- errores no revelan información sensible;
- existen tests.

"Permite eliminar empleados."

16. Reto avanzado

docs/ai-development-workflow.md

Objetivo

Al terminar, otro desarrollador debería poder seguir el mismo workflow sin preguntarte cómo utilizar la IA.

17. Test de evaluación

18. Recursos externos

19. Checklist de Week 09

20. Métrica de aprendizaje

21. Conclusión

ANTES

"IA, escribe este código."


AHORA

"Este es el objetivo.

Este es el contexto.

Estas son las restricciones.

Estos son los criterios de aceptación.

Analiza.

Planifica.

Implementa.

Testea.

Valida.

Explícame el resultado."

Requirement

      ↓

Database

      ↓

Backend

      ↓

API

      ↓

Frontend

      ↓

Tests

      ↓

Documentation