136 lines
5.6 KiB
Markdown
136 lines
5.6 KiB
Markdown
# 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:
|
|
1. ¿Es trivial? → ejecutar
|
|
2. ¿Es visible pero reversible? → ejecutar y reportar explícitamente
|
|
3. ¿Afecta marca, arquitectura, datos? → consultar primero
|
|
|
|
### Para el humano
|
|
Al revisar un reporte:
|
|
1. Buscar la sección "Decisiones tomadas por iniciativa"
|
|
2. Validar cada cambio Nivel 2 (aprobar o pedir reversión)
|
|
3. Si hay propuesta Nivel 3, decidir antes de aprobar la etapa
|
|
4. 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:
|
|
|
|
```markdown
|
|
## 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.
|
|
```
|