5.6 KiB
Snippet de actualización para methodology/PRINCIPLES.md
Este patch agrega una nueva sección al final del archivo, después del Principio 5 y de las relaciones entre principios.
Acción: agregar al final del archivo, como sección complementaria
Después de la sección "Cómo se relacionan los 5 principios", agregar:
Política de iniciativa agéntica
Política operativa que define cuándo un agente puede actuar proactivamente y cuándo debe consultar antes. Complementa el Principio 5 (humano como director).
El problema que resuelve
Los agentes producen mejor con libertad para optimizar lo local. Pero libertad sin límites lleva a:
- Cambios silenciosos que el humano descubre por casualidad
- Pérdida de gobernanza sobre el producto
- Erosión de la marca, arquitectura, o datos sin que nadie lo decida explícitamente
La política clasifica los cambios proactivos por impacto y define el comportamiento esperado en cada nivel.
Clasificación de impacto
Nivel 1 — Trivial
Definición: cambio interno no visible al usuario, reversible sin costo, sin efecto en datos o arquitectura.
Ejemplos:
- Renombrar una variable interna por claridad
- Reordenar imports
- Mejorar legibilidad de un comentario
- Extraer una función helper si se usa 3+ veces
Política: ejecutar libremente. Mencionar al final del reporte solo si fueron varios cambios acumulados.
Nivel 2 — Visible reversible
Definición: cambio visible al usuario final pero sin afectar marca, datos, ni arquitectura. Reversión cuesta minutos, no horas.
Ejemplos:
- Mejorar wording de un mensaje de error
- Ajustar padding o spacing en un componente
- Agregar un tooltip explicativo donde falta
- Reordenar columnas de una tabla para mejor lectura
Política: ejecutar y mencionar explícitamente en el reporte final como "decisión proactiva tomada — validar/revertir". El humano puede aprobar retroactivamente o pedir reversión.
Nivel 3 — De marca, arquitectura o datos
Definición: cambio que afecta identidad de marca, estructura del sistema, o información del usuario. Reversión cuesta horas o más.
Ejemplos:
- Agregar texto de marca al footer (ej. "Hecho desde Paraguay 🇵🇾")
- Cambiar colores que afectan la paleta visual del producto
- Agregar nuevas dependencias (npm packages, fonts, libs)
- Modificar estructura de datos persistidos (DB, IndexedDB)
- Cambiar flujos de navegación o jerarquía de información
- Agregar/quitar features no listadas en el brief
Política: NO ejecutar. Consultar antes de proceder. El reporte debe incluir:
PROPUESTA DE CAMBIO NIVEL 3 — requiere aprobación antes de implementar
Cambio sugerido: [descripción]
Justificación: [por qué el agente lo considera valioso]
Impacto: [qué afecta]
Alternativa si se rechaza: [qué hacer en lugar]
El humano decide explícitamente si proceder.
Casos límite
"Es trivial técnicamente pero visible para el usuario"
Sube a Nivel 2. La visibilidad es el criterio dominante.
"El brief no lo prohíbe explícitamente"
Irrelevante. El brief define el scope positivo (qué hacer), no negativo (todo lo demás). Cualquier cambio fuera del scope explícito se clasifica por impacto y se aplica la política.
"El cliente / usuario lo va a agradecer"
No es justificación para Nivel 3. La gratitud retroactiva no compensa el costo de la decisión unilateral. Si el cambio es bueno, sobrevive a la consulta previa.
"Es para arreglar un bug que descubrí"
Bugs reales se arreglan. Pero bugs cosméticos o de UX suelen ser Nivel 2 y se reportan, no se silencian. Bugs de datos o seguridad son Nivel 3 y se consultan si requieren cambio de modelo.
Cómo se aplica esta política en la práctica
Para el agente
Antes de hacer un cambio fuera del scope explícito del prompt:
- ¿Es trivial? → ejecutar
- ¿Es visible pero reversible? → ejecutar y reportar explícitamente
- ¿Afecta marca, arquitectura, datos? → consultar primero
Para el humano
Al revisar un reporte:
- Buscar la sección "Decisiones tomadas por iniciativa"
- Validar cada cambio Nivel 2 (aprobar o pedir reversión)
- Si hay propuesta Nivel 3, decidir antes de aprobar la etapa
- Si descubrís un cambio no reportado, es violación del patrón C.6 — registrar y discutir
Para el método
Esta política es viva. Si en práctica aparecen casos que no encajan claramente en los 3 niveles, documentar el caso y refinar la política. La política es herramienta, no dogma.
Cómo se relaciona con los 5 principios
- Principio 3 (Auditoría adversarial): la política le da al humano una sección concreta donde buscar cambios silenciosos.
- Principio 4 (Decisiones como contratos): los cambios Nivel 3 generan nuevas decisiones que se registran formalmente.
- Principio 5 (Humano director, no operador): la política preserva la autonomía agéntica útil sin perder gobernanza sobre el producto.
Aplicación en CLAUDE.md del producto
Para que un agente conozca y aplique esta política, agregar en CLAUDE.md del producto:
## Política de iniciativa proactiva
Cuando detectés una oportunidad de mejora fuera del scope del prompt actual:
- Cambios triviales (variables internas, reordenar imports): ejecutar
- Cambios visibles pero reversibles (wording, spacing, tooltips):
ejecutar y reportar explícitamente al final
- Cambios de marca, arquitectura o datos (paleta, dependencias,
estructura, features nuevas): CONSULTAR ANTES DE PROCEDER
Ver methodology/PRINCIPLES.md sección "Política de iniciativa agéntica"
para detalle completo.