Revisión de diseño

Una lista en orden para revisar el diseño de un agente antes de escribir código. Cada bloque depende del anterior: si uno falla, la revisión para ahí. Usa las otras seis plantillas como requisitos. También incluye una tabla de datos personales por país.
Copiá el bloque con el botón de la esquina, o abrí el archivo en GitHub.
# Revisión de diseño: [nombre del agente]

<!--
Cómo usar esta plantilla:
- Revisá el diseño antes de escribir código. Seguí el orden: cada bloque depende del anterior.
- Si un bloque falla, pará ahí. No sigas con el resto hasta resolverlo.
- Marcá [x] lo que se cumple. Si algo no se cumple, anotá por qué y quién lo resuelve.
-->

- Fecha: [AAAA-MM-DD]
- Autor del diseño: [nombre]
- Revisores: [nombres, con al menos una persona de seguridad]
- ADR: [link a adr-agente-o-no.md]

## 1. El problema

- [ ] Hay un ADR que descartó el flujo fijo con una razón concreta.
- [ ] El agente resuelve una sola tarea. La tarea está escrita en una oración.
- [ ] El agente tiene un dueño con nombre, responsable de que funcione.

## 2. Alcance y herramientas

- [ ] Las herramientas están listadas. Cada una hace una sola cosa. No hay una consola genérica.
- [ ] Las herramientas tienen parámetros que impiden errores comunes (por ejemplo, rutas absolutas, montos con tope).
- [ ] Hay un archivo de instrucciones con las reglas del dominio, los comandos y los límites.

## 3. Control del flujo

- [ ] El código controla el bucle. El modelo propone el siguiente paso y el código decide si corre.
- [ ] Hay un máximo de pasos por tarea: [n].
- [ ] Hay un presupuesto de tokens por tarea con corte automático: [n].
- [ ] El código detecta llamadas repetidas y corta el bucle.
- [ ] El estado se guarda en cada paso. Un reintento no empieza de cero.

## 4. Seguridad

- [ ] El mapa de amenazas está hecho: [link a mapa-de-amenazas.md].
- [ ] Ninguna sesión junta contenido no confiable, datos sensibles y acciones hacia afuera sin una persona que apruebe. Pedir una URL ya es una salida hacia afuera.
- [ ] El agente tiene una identidad propia, no la cuenta de una persona ni una cuenta compartida.
- [ ] Las credenciales del agente duran poco y tienen el mínimo alcance. Nunca superan los permisos del usuario al que atiende.
- [ ] En producción, el agente solo lee, salvo las acciones de la política.
- [ ] Los backups están en otra cuenta y otro volumen. El agente no los puede borrar.
- [ ] Los servidores MCP (Model Context Protocol, el estándar para conectar herramientas) están en un inventario, con versión fijada.

## 5. Acciones

- [ ] La política de acciones está hecha: [link a politica-de-acciones.md].
- [ ] Una acción que no está en la política pide confirmación.
- [ ] La aprobación queda atada a la acción exacta y la aplica el código, no el prompt.

## 6. Evaluación

- [ ] El plan de evaluación está hecho: [link a plan-de-evaluacion.md].
- [ ] Hay un criterio de salida con pass^k y un criterio de vuelta atrás.
- [ ] Durante las primeras [n] semanas, una persona revisa el 100 % de las respuestas.

## 7. Registro

- [ ] Cada acción queda registrada con lo que el agente vio, la herramienta, los parámetros y quién aprobó.
- [ ] El registro guarda la propuesta del agente y la autorización como eventos separados.
- [ ] El agente no puede borrar ni editar el registro.

## 8. Costo

- [ ] La ficha de costo está hecha: [link a ficha-de-costo.md].
- [ ] Hay un tope de gasto por día con alerta y corte. Quien lo levanta: [rol].

## 9. Personas y datos

- [ ] La persona sabe que habla con una IA desde la primera interacción, salvo que sea obvio. En la Unión Europea, esa obligación es del proveedor del sistema.
- [ ] Hay un camino visible para pasar a una persona.
- [ ] Para cada país con usuarios hay una base legal anotada (el motivo que la ley acepta para usar los datos). También hay una regla de minimización: usar solo los datos personales necesarios.
- [ ] Una persona puede revisar las decisiones con efecto significativo sobre alguien.
- [ ] Hay un contrato de tratamiento de datos con el proveedor del modelo.
- [ ] Sabemos cuántas aprobaciones por hora hace cada revisor. Ese número es sostenible: [n].

<!--
Datos personales por país. Revisá el estado de cada ley antes de usar esta tabla.
Los proyectos de ley de IA y las fechas de vigencia cambian rápido.
Borrá los países donde no tenés usuarios y agregá los que faltan.
-->

| País o región | Ley de datos personales | Base legal elegida | Aviso al usuario | Revisión de decisiones automatizadas |
|---|---|---|---|---|
| Unión Europea | RGPD | [...] | [...] | [qué garantías pide el RGPD en decisiones automatizadas con efectos significativos] |
| Brasil | LGPD | [...] | [...] | [art. 20 LGPD: derecho a pedir una revisión, no necesariamente humana] |
| México | LFPDPPP | [...] | [...] | [...] |
| Chile | Ley 21.719 (revisá la fecha de vigencia) | [...] | [...] | [...] |
| Colombia | Ley 1581 de 2012 | [...] | [...] | [...] |
| Argentina | Ley 25.326 | [...] | [...] | [...] |

A noviembre de 2026, ninguno de los cinco países de América Latina de la tabla tiene una ley de IA vigente. El riesgo legal hoy viene de sus leyes de datos personales.

## 10. Operación

- [ ] El runbook de incidentes está listo: [link a runbook-incidente-agente.md].
- [ ] Hay un interruptor para pasar a solo lectura y otro para apagar. Los probamos.
- [ ] Hay una persona de guardia que sabe usarlos.

## Resultado

- Decisión: [aprobado | aprobado con cambios | no aprobado]
- Cambios pedidos, con dueño y fecha: [...]

## Por qué está esto acá

- Una regla escrita en el prompt no es un control. Una base de producción se borró por un token (credencial) con demasiado alcance y backups en el mismo volumen: *An AI agent deleted our production database* (Hacker News, 2026).
- Un archivo de instrucciones, junto con la configuración del build, subió el éxito del agente de 38,1 % a 69 %. La revisión experta de cada cambio sostuvo la calidad: *Ten Months with Copilot Coding Agent in dotnet/runtime* (Stephen Toub, 2026).
- Muchas definiciones de herramientas gastan contexto y bajan la precisión. Cargá las herramientas cuando hacen falta: *Introducing advanced tool use on the Claude Developer Platform* (Anthropic, 2025).
- El proveedor de un sistema que habla con personas tiene que avisar que es una IA, salvo que sea obvio. Rige desde el 2 de agosto de 2026: *Article 50* de la Ley de IA de la UE (2024).
- El agente trata datos personales como cualquier sistema: necesita base legal y minimización. En Brasil, la persona puede pedir que se revise una decisión automatizada, y la ley no exige que la revise una persona: *Lei nº 13.853, de 8 de julho de 2019* (Câmara dos Deputados, 2019).