Todas las guías técnicas
Estándar de ingeniería · Agentes de codificación

Comienzo de un proyecto con IA

Lo que tu equipo necesita tener listo antes de que un agente escriba la primera línea: requerimientos no funcionales definidos, entorno en contenedores, el ciclo Orquestador–Implementador–Auditor, un ambiente seguro y controles en cada paso hacia producción.

01

Reglas base para iniciar

Antes de que un agente genere o modifique código, tu equipo deja claras unas cuantas reglas. Así el agente acelera el trabajo sin tomar decisiones que le corresponden a las personas. A lo largo de la guía, la marca DEV señala lo que sólo hace o decide alguien del equipo.

  • Tu equipo define los requerimientos no funcionales en la plantilla; el agente no los decide
  • Cada tarea pasa por Orquestador → Implementador → Auditor, y el Auditor revisa sin heredar el contexto del autor
  • Un gateway con DLP controla qué sale hacia los modelos, y los secretos de producción nunca llegan al agente
  • Commit, push, solicitud de cambios (PR) y merge pasan por los mismos controles que usa todo el equipo
  • Una tarea sólo se da por terminada cuando sus pruebas corrieron y pasaron
02

Flujo por fases

Las decisiones clave siguen un orden y ninguna se salta. Dentro de cada fase, la implementación puede repetirse tantas veces como haga falta cuando las pruebas o la revisión encuentran algo por corregir.

Antes de escribir código · DEV

Plantilla y requerimientos no funcionales

Los requerimientos no funcionales (NFR) son lo que el sistema debe cumplir además de sus funciones. Tu equipo los fija en la plantilla al crear el repositorio; el agente construye sobre esa base y no la cambia.
  • Seguridad: prácticas de OWASP, autenticación y autorización, cifrado y un modelo de amenazas inicial.
  • Desempeño: objetivos de servicio (SLO), tiempos de respuesta esperados y límites de recursos.
  • Arquitectura: capas, límites entre dominios (bounded contexts) y registros de decisiones de arquitectura (ADR).
  • Observabilidad: logs estructurados, trazas y métricas.
Entorno de desarrollo

Infraestructura en contenedores

  • Crear: una estructura inicial reproducible con Compose o Devcontainer; el entorno viene definido por la plantilla.
  • Ejecutar: servicios aislados, redes internas y volúmenes temporales para los datos de prueba.
  • Probar y cerrar: pruebas unitarias, de integración y de contratos dentro del contenedor, hasta cumplir la definición de terminado (DoD).
Controles de seguridad

Gateway · DLP · Escaneo local · Secretos

  • Gateway hacia los modelos: todas las peticiones a proveedores de IA y agentes (Cursor, Claude Code, etc.) pasan por un punto que aplica las políticas de prevención de fuga de datos (DLP).
  • Gitleaks (o equivalente): impide que archivos .env o secretos entren al espacio de trabajo y al historial desde el pre-commit.
  • Secretos por ambiente: sólo en desarrollo, QA y pruebas. Producción queda fuera del alcance del agente.
Ciclo de ejecución

Orquestador + Implementador + Auditor

El Orquestador decide cuántos intentos tiene cada fase y cómo reporta el Auditor: hallazgo por hallazgo o en un inventario completo con plan de corrección. El Auditor trabaja en un subagente aparte, sin el razonamiento del Implementador. En una migración, al ciclo se suma la Fuente de verdad después de inventariar las reglas de negocio.
Puertas de control

Commit · Push · Solicitud de cambios (PR) · Merge

En cada paso hacia producción se revisan privacidad, seguridad y la misma definición de terminado del ciclo (pruebas, patrones y arquitectura). Los controles comunes de cada puerta están en Control de versiones y ciclo de cambios.
03

Infraestructura básica del proyecto

Tu entorno debe permitir crear, ejecutar y probar todo dentro de contenedores, hasta cerrar cada tarea con evidencia. Los controles comunes están en Estándares de ingeniería para trabajar con agentes.

Crear

Devcontainer o Compose

La imagen base la fija la plantilla y los servicios que dependen de ella tienen versión. El equipo cuenta con comandos conocidos como make test y make lint.
Ejecutar

Aislamiento

Cada tarea del agente trabaja en su propia rama o worktree, sin acceso a secretos de producción y en redes internas, sin salida libre a internet.
Probar y cerrar

Pruebas como puerta

Pruebas unitarias y de integración con datos de prueba separados. Un resultado que siempre se repite igual es la evidencia de que la tarea está lista.
04

Ciclo Orquestador → Implementador → Auditor

Todo empieza con una persona del equipo (DEV), que describe la tarea en un prompt. A partir de ahí corre el ciclo de agentes, y el Auditor siempre revisa con un contexto limpio.

01Coordinación

Orquestador

Define el plan, asigna el trabajo y decide si los hallazgos requieren otro intento.

02Ejecución

Implementador

Construye dentro de la arquitectura acordada y entrega código y pruebas verificables.

03Revisión

Auditor

Revisa en contexto limpio contra los criterios de aceptación y reporta evidencia o hallazgos.

Si hay hallazgos, el Orquestador decide el siguiente intento
La tarea termina cuando el Auditor verifica el resultado y se cumplen los criterios acordados.
Lo escribe una persona · DEV

Prompt de tarea

Aquí tu equipo dice qué hay que hacer. Es la entrada humana al ciclo.

Qué debe decir

  • Objetivo: qué problema se resuelve y para quién.
  • Alcance: módulos, pantallas o archivos incluidos, y lo que queda fuera.
  • Criterios de aceptación: cómo se comprueba que quedó completa, alineados con la definición de terminado.
  • Restricciones: requerimientos de la plantilla que no se pueden romper, dependencias y riesgos.
  • Contexto útil: enlaces a ADR, tickets o diseños. Nunca secretos.
Coordinación

Orquestador

Decide cuántos intentos hay, cómo trabaja el Implementador y cómo reporta el Auditor.

Su prompt debe incluir

  • Intentos por fase: cuántas vueltas Implementador ↔ Auditor se permiten antes de pedir ayuda al equipo.
  • Forma de reportar: hallazgo por hallazgo o un inventario completo con plan de corrección.
  • Cómo arranca el Implementador: contexto, worktree y herramientas que puede usar.
  • Cuándo se cierra: la tarea termina sólo si el Auditor la aprueba contra la especificación original, no contra el relato del Implementador.
  • Memoria en archivos: PLAN.md y la evidencia guardados en el repositorio, no sólo en el chat.
Construcción

Implementador

Construye con la arquitectura, los patrones, la seguridad, la CI/CD, los secretos, la definición de terminado y la lista de cambios ya definidos.

Su prompt debe incluir

  • La arquitectura y los patrones del marco de trabajo (framework) definidos en la plantilla.
  • Las prácticas de escalabilidad y seguridad ya fijadas, para que no las invente en la corrida.
  • La integración y el despliegue continuos: flujos, puertas de control y artefactos.
  • El ambiente, los secretos y las variables, sin acceso a producción.
  • La definición de terminado: pruebas unitarias, de integración y datos de prueba separados.
  • La lista de cambios: qué crear, modificar, corregir o eliminar.
Revisión con contexto limpio

Auditor

Revisa pruebas, código y evidencia sin heredar el razonamiento de quien construyó.

Su prompt debe incluir

  • La definición de terminado como una lista de verificación independiente.
  • Los resultados de las pruebas: logs, cobertura y fallos que se puedan reproducir.
  • La revisión de código: seguridad, patrones, estilo y arquitectura.
  • Lo necesario para reintentar: qué falta, dónde y cómo reproducirlo.
  • Un veredicto claro de cumple o no cumple, sin ambigüedades.

El ciclo de trabajo

  1. 00
    Prompt de tarea · DEV

    Una persona del equipo describe la tarea.

  2. 01
    Orquestar

    Plan, intentos y forma de reportar.

  3. 02
    Implementar

    Código y pruebas dentro del contenedor.

  4. 03
    Auditar

    Revisión sin el sesgo de quien construyó.

  5. 04
    Decisión · DEV

    Aprobar, reintentar o llevarlo al equipo.

El Auditor no comparte contexto ni cadena de razonamiento con el Implementador; así se evita la autoconfirmación.

05

Ambiente seguro desde el primer día

Las capas de seguridad son las mismas en cualquier proyecto y están explicadas en Estándares · Seguridad, datos y secretos. En un proyecto nuevo, tu equipo las deja activas antes del primer prompt.

  • Gateway hacia los modelos y agentes configurado para el equipo

    Con la política de DLP, la lista de modelos y herramientas permitidos, y el registro de prompts que se acordó con el cliente.

  • Gitleaks o equivalente activo desde el primer commit

    Revisión en el pre-commit y en la CI. En el repositorio sólo existe .env.example, sin valores reales.

  • Secretos por ambiente sólo para desarrollo, QA y pruebas

    Producción nunca se configura a través del agente; queda detrás de flujos de despliegue con aprobación humana.

06

La plantilla como base del código generado

Seguridad, desempeño y arquitectura se deciden antes de empezar, para que el agente no tenga que adivinarlos.

Qué incluye la plantilla

Base técnica

  • ADR y políticas del proyecto (seguridad, logs y manejo de errores).
  • Estructura de módulos, capas y contratos.
  • Lint, análisis estático de seguridad (SAST), estructura inicial de pruebas y CI base.
  • Prompts base de cada rol del ciclo, versionados en el repositorio.
  • Devcontainer y scripts de verificación.
Qué hace el agente

Implementar dentro de esos límites

  • Implementa los requisitos funcionales dentro de la plantilla.
  • Amplía las pruebas según la definición de terminado.
  • No cambia autenticación, límites de desempeño ni arquitectura sin un ADR aprobado por una persona.
07

Prácticas comunes

Las nueve prácticas que sostienen la calidad son las mismas en proyectos nuevos y en migraciones. Las explicamos con ejemplos en Estándares · Prácticas para sostener calidad.

08

Checklist de arranque

Repasa estos puntos con tu equipo antes de que un agente genere código en un proyecto nuevo.

  • Plantilla con requerimientos no funcionales, ADR, CI, lint y los prompts de cada rol versionados
  • Devcontainer o Compose listo para crear, ejecutar y probar
  • Gateway hacia los modelos con DLP activo para el equipo
  • Gitleaks o equivalente en el pre-commit y en la CI
  • Secretos sólo en desarrollo, QA y pruebas; producción bloqueada
  • Ciclo de agentes configurado, con intentos y forma de reportar
  • Controles de auditoría en commit, push, PR y merge
  • `PLAN.md` y evidencia en cada corrida; nada se da por terminado sin pruebas en verde
Sigue explorando