Cómo planificar el uso de agentes de IA en desarrollo de software

Resumen rápido (lectores con prisa)

Qué es: Planning es el contrato operativo que define objetivos, constraints, convenciones y métricas para agentes de IA.

Cuándo usarlo: Antes de delegar tareas automatizadas o de permitir agentes a hacer commits/PRs.

Por qué importa: Evita decisiones ad-hoc del modelo, reduce variance y protege la arquitectura.

Cómo funciona: Documentos persistentes + sub-agents para investigación + slash commands + tests/verificación.

Planning (Planificación): documentos, contratos y el System Prompt persistente

Planear no es escribir un listado de features. Es crear el contrato que el agente deberá cumplir.

Estructura mínima de plan.md

Documentos Markdown como fuente de verdad. Crea plan.md, architecture.md, rules.md. Esos archivos son tu System Prompt persistente: contienen objetivos de negocio, constraints técnicas, convenciones de estilo, y métricas de aceptación (coverage, latencia, límites de tokens).

# Objetivo
- Migrar dashboard a Standalone Components (Angular 22)
# Constraints
- No tocar auth-service
- Coverage Vitest >= 90%
# Verificación
- vitest --coverage
- linter/eslint

Slash commands

Slash commands: define comandos reutilizables que encapsulen workflows estándar. Ejemplos: /investigate src/, /plan-migration --module dashboard, /task run-tests. Implementarlos reduce variance entre prompts y evita “ad-hoc prompts” que inducen errores.

No des todo el repo al agente principal. Haz que investigue sub-agents.

Sub-agents: investigación sin contaminar contexto

Definición

Meter cientos de archivos en el contexto degrada el razonamiento. Solución: sub-agents.

Sub-agent = proceso aislado que lee carpetas específicas, ejecuta análisis (dependencias, tree shakes, npm ls, hotspots de deuda técnica) y devuelve un resumen estructurado.

Resultado típico de sub-agent

Resultado típico de sub-agent:

• Lista de archivos críticos
• Dependencias vulnerables
• Tests flaky detectados
• Propuesta de subtareas

Ese resumen alimenta el plan sin hinchar la ventana de contexto del agente principal. Implementa sub-agents como funciones serverless o procesos MCP (Model Context Protocol — Model Context Protocol) que expongan solo lo necesario.

Implementation (Implementación): dividir para no quebrar

La implementación es donde la disciplina se mide en errores y tiempo.

Workflow por tarea

Divide el plan en tareas atómicas: “Implementar validación JWT en auth.service.ts” en vez de “Crear auth”.

1. /task [id] → agent genera cambios localmente.
2. Ejecutar tests unitarios (vitest) y linters.
3. Si todo OK → crear rama y PR con diff.
4. Si falla → el agent itera (máx N veces) o marca bloqueo para revisión humana.

Reglas imprescindibles

Reglas imprescindibles: límite de iteraciones por tarea (p.ej. 3), --safe por defecto en comandos destructivos y ejecución en contenedores/DevContainers.

Mantén trazabilidad: cada task debe registrar tokens consumidos, tiempo y resultado. Métricas simples que importan: tokens/tarea, tests rotos introducidos, tiempo humano por corrección.

Validation (Validación): automatización + juicio humano

Tests y revisiones automáticas

No hay merge sin validación. Tests automáticos primero: suites unitarias, E2E (Playwright), coverage thresholds.

Revisiones automáticas por IA: usa herramientas como CodeRabbit para revisar PRs. Estas herramientas detectan problemas de complejidad, seguridad y estilo antes de que pase a humano.

Revisión humana estratégica

Revisión humana estratégica: no valides línea por línea. Valida intención arquitectónica: ¿el cambio respeta architecture.md? ¿Introduce deuda oculta? ¿Hay trade-offs no documentados?

Documenta las excepciones. Cada PR debe contener la referencia al segmento de plan.md que motiva el cambio.

Patrones operativos y plantillas útiles

Slash command template

/task create
--id: migrate-dashboard-01
--scope: src/dashboard
--verify: vitest --coverage
--constraints: no-auth
--max-iter: 3

Sub-agent summary schema

{
  "files": [...],
  "hotspots": [...],
  "tests_flaky": [...],
  "recommendation": "split module, add tests"
}

Estas plantillas convierten la improvisación en procesos reproducibles.

Criterio para decidir si adoptar este flujo

Adóptalo si:

• Tienes stack moderno (TypeScript, Angular/React con tests).
• Puedes aislar ejecución (Docker, DevContainers).
• El equipo acepta medir: tokens por task, tests green rate.

No lo adoptes si:

• Tu repo es monolito sin tests.
• No puedes auditar secrets y gastos.
• No hay disciplina para documentar plan.md.

Gobernanza y métricas mínimas

Quota tokens por usuario/equipo (ej. $10–20/dev/día). Logs de sesión y transcripts almacenados. KPIs: tokens/tarea, %tasks auto-merged, tiempo humano por PR.

Planning (Planificación) no es burocracia; es el ancla. Divide, documenta y aísla. Usa sub-agents para investigar, slash commands para repetir y tests + CodeRabbit para validar. Hazlo bien y evitarás que tus agentes escriban código sin responder a tu arquitectura. Esto no acaba aquí: define tu primer plan.md hoy y convierte esa decisión en política de equipo.

Dominicode Labs

Para equipos interesados en explorar patrones operativos y sub-agents como prácticas reproducibles, una continuación lógica es revisar recursos y experimentos en Dominicode Labs. Estos recursos documentan plantillas y flujos que complementan la estrategia expuesta arriba.

FAQ

• ¿Qué debe contener exactamente plan.md?
• ¿Cómo funcionan los sub-agents sin filtrar contexto al agente principal?
• ¿Qué límites de iteración recomiendan por tarea?
• ¿Qué herramientas de review automático recomiendan?
• ¿Cómo se relaciona plan.md con el System Prompt persistente?
• ¿Qué métricas son imprescindibles para gobernanza?
• ¿Cuándo NO adoptar este flujo?