492 lines
23 KiB
Markdown
492 lines
23 KiB
Markdown
# Patrones operativos
|
|
|
|
> Aplicaciones concretas de los 5 principios. Estructurados por categoría operativa.
|
|
>
|
|
> Estado de cada patrón: **propuesto** (validado en 1 proyecto) o **estable** (validado en 2+ proyectos).
|
|
>
|
|
> A la fecha, todos los patrones aquí son propuestos. Caso de validación: InQ ROI Sprint 1.5.
|
|
|
|
---
|
|
|
|
## Categoría A — Disciplina antes de codear
|
|
|
|
### A.1 Brief versionado antes que código
|
|
**Estado:** propuesto · **Deriva de:** Principio 1
|
|
|
|
Todo sprint o cambio mayor arranca con un brief en `sprints/sprint-N/BRIEF.md` antes de pedirle algo a un agente. El brief define alcance, decisiones tomadas, criterios de éxito y lo que NO entra.
|
|
|
|
**Indicador de aplicación correcta:** podés iniciar una sesión nueva con Claude Code pasándole solo el path del brief y CLAUDE.md, sin contexto adicional, y empieza a trabajar correctamente.
|
|
|
|
**Indicador de violación:** el agente te hace preguntas que ya están respondidas en otro lugar (o peor, no las hace y asume).
|
|
|
|
---
|
|
|
|
### A.2 Mockup como contrato visual
|
|
**Estado:** propuesto · **Deriva de:** Principio 1
|
|
|
|
Si el cambio es visual, antes de implementarlo se construye un mockup interactivo (HTML, Figma, Visualizer) que el humano aprueba. El mockup es el contrato: el agente lo replica, no lo interpreta libremente.
|
|
|
|
**Indicador de aplicación correcta:** cuando ves el output del agente, podés compararlo lado a lado con el mockup y la diferencia es marginal.
|
|
|
|
**Indicador de violación:** llegás a Etapa N de un rediseño visual y descubrís que el output "no tiene nada que ver" con lo que esperabas.
|
|
|
|
---
|
|
|
|
### A.3 Roadmap explícito antes de arrancar
|
|
**Estado:** propuesto · **Deriva de:** Principios 1 y 4
|
|
|
|
Todo sprint con más de 3 etapas tiene un roadmap explícito desde el inicio. Cada etapa tiene **expectativa calibrada** de qué cambia y qué NO cambia respecto a la anterior.
|
|
|
|
**Indicador de aplicación correcta:** después de cada checkpoint, el resultado coincide con lo que esperabas ver, no te sorprende ni para bien ni para mal.
|
|
|
|
**Indicador de violación:** te sorprende negativamente un output intermedio porque pensabas que ya tenía X feature que en realidad está agendado 3 etapas después.
|
|
|
|
---
|
|
|
|
## Categoría B — Operación con agentes
|
|
|
|
### B.1 Prompt como artefacto del repo
|
|
**Estado:** propuesto · **Deriva de:** Principios 4 y 5
|
|
|
|
Cada etapa de trabajo agéntico tiene su prompt en `sprints/sprint-N/ETAPA_X_PROMPT.md`, versionado. El chat con el agente es **puente** entre el prompt y el reporte, no contenedor de la decisión.
|
|
|
|
**Por qué:** los prompts en archivo son auditables, editables antes de ejecutar, replicables, y no se pierden al cerrar la sesión.
|
|
|
|
**Estructura mínima de un prompt de etapa:**
|
|
1. Objetivo
|
|
2. Pre-requisitos / contexto previo
|
|
3. Decisiones ya tomadas (no consultar de nuevo)
|
|
4. Tareas concretas
|
|
5. Entregables (DoD checklist)
|
|
6. Qué reportar al final
|
|
7. Qué NO hacer en esta etapa
|
|
|
|
---
|
|
|
|
### B.2 Mensaje inicial corto, contexto en archivos
|
|
**Estado:** propuesto · **Deriva de:** Principio 5
|
|
|
|
El mensaje al agente al arrancar una sesión es de 3-5 párrafos, NO el prompt entero pegado. Estructura:
|
|
1. "Procedé con etapa X"
|
|
2. Archivos a leer en orden
|
|
3. Confirmaciones que esperás antes de que empiece
|
|
4. Restricción de alcance ("no avances a Y sin OK")
|
|
|
|
**Por qué:** el contexto en archivos sobrevive a la sesión, queda versionado, y el agente lo consulta cuando lo necesita en vez de tenerlo permanentemente en ventana.
|
|
|
|
---
|
|
|
|
### B.3 Decisiones tomadas como sección explícita
|
|
**Estado:** propuesto · **Deriva de:** Principio 4
|
|
|
|
En cada prompt de etapa, incluir sección "DECISIONES YA TOMADAS — no consultar de nuevo" con las definiciones cerradas. Esto impide que el agente vuelva a preguntar lo ya resuelto.
|
|
|
|
**Ejemplo:**
|
|
```
|
|
DECISIONES YA TOMADAS (no consultar de nuevo)
|
|
- Payback negativo → "Sin payback (costo aumenta)"
|
|
- Caracteres compactos: "<" y "~"
|
|
- Pluralización: siempre plural ("1.0 meses")
|
|
```
|
|
|
|
---
|
|
|
|
### B.4 Reglas no negociables en CLAUDE.md
|
|
**Estado:** propuesto · **Deriva de:** Principio 4
|
|
|
|
Las reglas que aplican a TODO el proyecto van en `CLAUDE.md`, no solo en briefs específicos. El agente carga CLAUDE.md en cada sesión nueva por defecto.
|
|
|
|
**Ejemplo de qué va ahí:**
|
|
- Reglas de marca (cómo se escribe el nombre, qué colores)
|
|
- Restricciones de comportamiento (qué no decir, qué no asumir)
|
|
- Verificaciones obligatorias pre-entrega
|
|
|
|
---
|
|
|
|
## Categoría C — Validación de output
|
|
|
|
### C.1 Validación visual mandatoria del artefacto final
|
|
**Estado:** propuesto · **Deriva de:** Principio 2
|
|
|
|
Si el output de la etapa es un artefacto visible (PDF, screenshot, página renderizada, documento), el humano lo abre con sus ojos antes del OK. Tests verdes no es suficiente.
|
|
|
|
**Tooling sugerido:**
|
|
- PDFs/imágenes: Preview en Mac, visor PDF en Linux
|
|
- Páginas web: dev server en navegador
|
|
- Documentos: editor que renderice (no solo source)
|
|
|
|
**Cuándo evolucionar este patrón:** ver methodology/AUTOMATION_STRATEGY.md.
|
|
La validación visual humana es Fase 1. Puede complementarse con agentes
|
|
auditores (Fase 3) pero NO se reemplaza completamente hasta que el
|
|
equipo desarrolle criterio adversarial maduro.
|
|
|
|
---
|
|
|
|
### C.2 Validación programática antes de declarar completado (agente)
|
|
**Estado:** propuesto · **Deriva de:** Principios 2 y 3
|
|
|
|
Antes de declarar una etapa completada, el agente debe ejecutar validaciones programáticas, no solo confiar en tests unitarios. Para outputs visuales:
|
|
- Análisis de píxeles (¿están los colores esperados?)
|
|
- Text extraction (¿están las palabras clave?)
|
|
- Tamaño de archivo (¿es razonable?)
|
|
- Cantidad de páginas (¿coincide con el diseño?)
|
|
|
|
**Por qué:** un test unitario puede pasar mientras el output final está roto. La validación programática del artefacto cierra ese gap.
|
|
|
|
---
|
|
|
|
### C.3 Auditoría adversarial al reporte
|
|
**Estado:** propuesto · **Deriva de:** Principio 3
|
|
|
|
Cuando llega un reporte de agente "todo OK", aplicar 3 preguntas:
|
|
1. ¿Los números reportados cuadran si recalculo o pido dump?
|
|
2. ¿El artefacto es el que pedí?
|
|
3. ¿Lo que no menciona podría ser relevante?
|
|
|
|
**Casos típicos de detección:**
|
|
- PDF de 36 KB con 4 páginas (es muy poco → algo no se renderizó)
|
|
- KPI con valor "0.0 meses" (numéricamente correcto pero confuso)
|
|
- Reporte que dice "PDF generado" sin abrir el PDF generado
|
|
|
|
---
|
|
|
|
### C.4 Reporte con datos concretos, no descripciones (agente)
|
|
**Estado:** propuesto · **Deriva de:** Principio 3
|
|
|
|
Los reportes del agente deben incluir métricas concretas, no descripciones genéricas.
|
|
|
|
**Mal reporte:** "PDF generado correctamente, contiene todo lo esperado."
|
|
|
|
**Buen reporte:**
|
|
```
|
|
PDF generado: 78 KB, 4 páginas
|
|
- Página 1: KPI Hero + 4 cards secundarios + top 3 ahorros
|
|
- Página 2: tabla con 11 filas + footer
|
|
- Página 3: 3 secciones (composición, trayectoria, transparencia)
|
|
- Página 4: nota metodológica
|
|
Análisis de píxeles del heatmap: verde 36.329px, ámbar 3.889px, rojo 3.713px
|
|
Text extraction confirma palabras clave: "InQ ROI", "Powered by InQuality", "Payback"
|
|
```
|
|
|
|
### C.5 Validaciones programáticas explícitas en el prompt
|
|
**Estado:** propuesto · **Deriva de:** Principios 2 y 5
|
|
|
|
Cada prompt de etapa incluye una sección **"Validaciones automatizadas mandatorias"** con criterios objetivos verificables por código que el agente debe ejecutar antes de declarar terminada la etapa o usar `present_files`.
|
|
|
|
**Por qué:** documenta explícitamente qué se va a auto-validar, hace transferible el conocimiento operativo al equipo, captura el aprendizaje sobre qué problemas son recurrentes y vale la pena chequear automáticamente.
|
|
|
|
**Cómo se aplica:**
|
|
|
|
```markdown
|
|
## Validaciones automatizadas mandatorias
|
|
|
|
Antes de present_files, ejecutá y confirmá:
|
|
|
|
PDFs:
|
|
- pdf-parse confirma palabras clave esperadas: [lista]
|
|
- pdf-parse rechaza términos prohibidos: [lista]
|
|
- Cada página entre [N-M] KB
|
|
- Cantidad de páginas == [N exacto]
|
|
|
|
Tests:
|
|
- Tests previos verdes (>= [N])
|
|
- Tests nuevos verdes
|
|
|
|
Build:
|
|
- npm run build limpio
|
|
- Sin warnings TS ni lint nuevos
|
|
```
|
|
|
|
**Indicador de aplicación correcta:** los problemas que ya cazaste manualmente en sprints anteriores aparecen como validación automatizada en sprints siguientes. Aprendizaje acumulativo.
|
|
|
|
**Indicador de violación:** el agente declara etapa terminada y vos cazás el mismo tipo de problema que ya cazaste 3 etapas atrás. Significa que el aprendizaje no se está capturando como validación.
|
|
|
|
**Relación con otros patrones:**
|
|
- Extiende **C.2** (validación programática) haciéndola explícita en el prompt
|
|
- No reemplaza **C.1** (validación visual humana) — son complementarias
|
|
- Es Fase 2 del roadmap de `AUTOMATION_STRATEGY.md`
|
|
|
|
### C.6 Iniciativa agéntica con consulta clasificada por impacto
|
|
**Estado:** propuesto · **Deriva de:** Principios 3, 4 y 5
|
|
|
|
Cuando el agente detecta una oportunidad de mejora **fuera del scope del prompt**, debe clasificar el impacto del cambio antes de proceder y actuar según la política definida en `PRINCIPLES.md` sección "Política de iniciativa agéntica".
|
|
|
|
**Niveles de impacto:**
|
|
|
|
1. **Trivial** (cambio interno, no visible al usuario, reversible sin costo)
|
|
→ ejecutar y reportar al final como "decisión menor tomada"
|
|
|
|
2. **Visible reversible** (cambio visible al usuario pero sin afectar marca, datos, ni arquitectura)
|
|
→ ejecutar, **mencionar explícitamente en el reporte final** como "decisión proactiva, validar/revertir"
|
|
|
|
3. **De marca, arquitectura o datos** (cambio que afecta identidad, estructura, o información del usuario)
|
|
→ **NO ejecutar**. Consultar antes de proceder.
|
|
|
|
**Por qué:** los agentes producen mejor cuando tienen libertad para optimizar lo local. Pero esa libertad sin límites lleva a cambios silenciosos que el humano descubre por casualidad. Una clasificación explícita preserva la velocidad agéntica sin perder gobernanza.
|
|
|
|
**Caso real:** InQ ROI Sprint 1.5 Etapa 3. Claude Code agregó "Hecho desde Paraguay 🇵🇾" al footer del web app sin estar en el brief. El cambio era razonable, alineado con identidad de marca, pero **el humano lo descubrió revisando screenshots**, no porque se reportara. Decisión retroactiva: mantener, pero documentar el patrón para que en el futuro este tipo de cambios (impacto nivel 3, afecta marca) sean consulta previa, no decisión unilateral.
|
|
|
|
**Indicador de aplicación correcta:**
|
|
- El reporte final del agente tiene una sección explícita "Decisiones tomadas por iniciativa" listando cambios fuera del scope
|
|
- Los cambios nivel 3 no se ejecutan sin consulta previa documentada
|
|
- El humano puede aprobar o revertir cambios nivel 2 sin tener que reconstruir contexto
|
|
|
|
**Indicador de violación:**
|
|
- Descubrir cambios en el output que no están ni en el prompt ni en el reporte
|
|
- Cambios de marca, arquitectura o datos ejecutados sin consulta previa
|
|
- "Pequeñas mejoras de UX" agregadas en silencio que cambian el comportamiento del producto
|
|
|
|
**Relación con otros patrones:**
|
|
- Complementa **E.2** (Hallazgos no esperados) — pero E.2 es para descubrimientos pasivos (cosas que el agente notó), C.6 es para decisiones activas (cosas que el agente hizo).
|
|
- Refuerza **C.3** (Auditoría adversarial) — provee al humano una sección concreta donde buscar cambios silenciosos.
|
|
|
|
## Refinamiento — criterios explícitos de clasificación (aprendizajes de Sprint 1.5)
|
|
|
|
Durante Sprint 1.5 InQ ROI se detectaron dos casos de mala clasificación de impacto. A partir de esos casos, se refinaron los criterios para distinguir entre Niveles 1, 2 y 3:
|
|
|
|
### Reglas de clasificación (en orden de evaluación)
|
|
|
|
Evaluar en este orden estricto. El primer criterio que aplique determina el nivel — no seguir evaluando los siguientes.
|
|
|
|
**1. ¿El cambio resuelve un ítem listado en `TECH_DEBT.md`, `BACKLOG.md`, o archivos de planificación?**
|
|
→ Nivel 3 (consulta previa). Sin importar el tamaño técnico.
|
|
|
|
**Justificación:** ítems en archivos de planificación son decisiones del director sobre cuándo trabajarlos. El agente no puede promover ítems al sprint en curso por iniciativa.
|
|
|
|
**2. ¿El cambio choca con una restricción explícita del prompt de la etapa?**
|
|
→ Nivel 3 (consulta previa). Sin excepciones.
|
|
|
|
Ejemplo de restricciones explícitas:
|
|
- "NO entra: X" en sección de alcance
|
|
- "NO tocar Y" en reglas operativas
|
|
- "X está agendado para Etapa Z" en decisiones tomadas
|
|
|
|
**3. ¿El cambio modifica paginación, layout, cantidad de archivos generados, o estructura de salida?**
|
|
→ Nivel 2 mínimo. Reportar.
|
|
|
|
**4. ¿El cambio es visible al usuario final (texto en interfaz, color, posición de elemento, contenido de PDF)?**
|
|
→ Nivel 2 mínimo. Reportar.
|
|
|
|
**5. ¿El cambio afecta marca, identidad, dependencias, o configuración del producto?**
|
|
→ Nivel 3 (consulta previa).
|
|
|
|
**6. Si nada de lo anterior aplica → Nivel 1**
|
|
|
|
Ejemplos válidos de Nivel 1:
|
|
- Renombrar variable interna por claridad
|
|
- Reordenar imports
|
|
- Mejorar comentario de código
|
|
- Extraer función helper usada en múltiples lugares
|
|
- Eliminar código muerto evidente (sin riesgo de uso futuro)
|
|
- Limpiar artefactos accidentales del refactor (variables `void` no usadas)
|
|
|
|
### Argumentos que NO son justificación válida para Nivel 1
|
|
|
|
El agente puede invocar argumentos que parecen razonables pero violan los criterios de arriba:
|
|
|
|
- **"Es mejora de legibilidad"** → si afecta contenido visible, es Nivel 2 mínimo
|
|
- **"Es consistencia con etapa anterior"** → verificar si la etapa anterior fue autorizada o si también es adelanto silencioso (ver AP.8)
|
|
- **"Es trivial de revertir"** → la reversibilidad NO es criterio de clasificación. Cambios reversibles también pueden ser Nivel 3.
|
|
- **"Resuelve un bug menor"** → si el bug está documentado en TECH_DEBT.md, es Nivel 3
|
|
- **"Es lo que el usuario esperaría"** → eso es asumir. La política existe para no asumir.
|
|
|
|
### Casos reales documentados (Sprint 1.5 InQ ROI)
|
|
|
|
**Caso 1 (Etapa 5):** compactación de páginas reportada como Nivel 1.
|
|
- Realidad: Nivel 2 mínimo (modificó paginación visible)
|
|
- Resultado: nota metodológica truncada, descubierto en validación visual
|
|
- Lección: paginación es estructura de salida, criterio 3 aplica
|
|
|
|
**Caso 2 (Etapa 7-8):** reescritura de fórmulas Σ → "SUM" reportada inicialmente sin clasificación, después como Nivel 1.
|
|
- Realidad: Nivel 3 (resolvía ítem de TECH_DEBT.md sobre Unicode roto)
|
|
- Resultado: aceptado retroactivamente porque resultó ser solución correcta para el dominio, pero el patrón quedó como anti-patrón AP.8
|
|
- Lección: ítem en TECH_DEBT.md activa criterio 1 directo, sin importar el tamaño
|
|
|
|
### Implicancia para CLAUDE.md del proyecto
|
|
|
|
En el `CLAUDE.md` de cada proyecto, agregar a la sección "Política de iniciativa proactiva":
|
|
|
|
```
|
|
Antes de aplicar un cambio fuera del scope explícito del prompt actual:
|
|
|
|
1. Verificá si el cambio está listado en TECH_DEBT.md, BACKLOG.md, o
|
|
archivos de planificación equivalentes. Si está, es Nivel 3 — consultá.
|
|
|
|
2. Verificá si el cambio choca con una restricción explícita del prompt
|
|
("NO entra", "NO tocar", "está agendado para Etapa X"). Si choca,
|
|
es Nivel 3 — consultá.
|
|
|
|
3. Verificá si el cambio modifica paginación, layout, estructura de
|
|
salida, contenido visible. Si lo hace, es Nivel 2 mínimo — reportá.
|
|
|
|
4. Solo si nada de lo anterior aplica, ejecutá como Nivel 1.
|
|
|
|
Argumentos NO válidos para evitar la consulta:
|
|
- "Es mejora de legibilidad"
|
|
- "Es consistencia con etapa anterior" (verificar si esa etapa fue
|
|
autorizada o también fue adelanto silencioso)
|
|
- "Es trivial de revertir"
|
|
- "Resuelve un bug menor"
|
|
```
|
|
|
|
---
|
|
|
|
## Categoría D — Estructura del repo
|
|
|
|
### D.1 Carpeta `sprints/` para activos de planificación
|
|
**Estado:** propuesto · **Deriva de:** Principio 4
|
|
|
|
Cada sprint tiene su carpeta `sprints/sprint-N/` con todos sus artefactos:
|
|
- `BRIEF.md`
|
|
- `ETAPA_X_PROMPT.md` (uno por etapa)
|
|
- `ETAPA_X_REPORT.md` (opcional, reporte del agente capturado)
|
|
- `etapa-X-audit.md` (cuando aplica)
|
|
- `screenshots/` con evidencia visual
|
|
|
|
**Por qué:** en 6 meses, abrir esa carpeta te da el historial completo de cómo se construyó el sprint. Sin esto, el conocimiento queda en commits + memoria, que es frágil.
|
|
|
|
---
|
|
|
|
### D.2 Carpeta `methodology/` para el método en sí
|
|
**Estado:** propuesto · **Deriva de:** Principio 4
|
|
|
|
El método de trabajo vive en `methodology/`, separado del producto. Esto permite que el método evolucione independiente de cualquier producto específico.
|
|
|
|
---
|
|
|
|
### D.3 ADRs para decisiones arquitectónicas
|
|
**Estado:** propuesto · **Deriva de:** Principio 4
|
|
|
|
Las decisiones arquitectónicas importantes se registran como ADR (Architectural Decision Record) en `ARCHITECTURE.md` o `docs/adr/`. Estructura mínima:
|
|
- Contexto (qué problema teníamos)
|
|
- Decisión (qué elegimos)
|
|
- Alternativas consideradas
|
|
- Consecuencias (qué implica)
|
|
|
|
---
|
|
|
|
### D.4 Permisos del agente versionados en `.claude/`
|
|
**Estado:** propuesto · **Deriva de:** Principios 4 y 5
|
|
|
|
Las decisiones sobre qué comandos puede ejecutar el agente sin consultar al humano se versionan en archivos de configuración del repo. Esto evita dos extremos: la fricción de aprobar cada comando manualmente, y el bypass total que abre la puerta a acciones no intencionadas.
|
|
|
|
**Estructura recomendada:**
|
|
|
|
```
|
|
repo/
|
|
└── .claude/
|
|
├── settings.json ← commitable: deny patterns críticos
|
|
└── settings.local.json ← gitignored: allow personales del dev
|
|
```
|
|
|
|
**Reglas:**
|
|
|
|
1. **`settings.json` es del proyecto** — contiene patrones `deny` (comandos peligrosos prohibidos para todos: `rm -rf /`, `git push --force`, `npm publish`, etc.). Se comitea al repo.
|
|
|
|
2. **`settings.local.json` es del desarrollador** — contiene patrones `allow` personales (cada uno decide qué comandos pre-aprueba). Va en `.gitignore`. Cuando un dev nuevo arranca, **debe construir su propio** archivo siguiendo el template, no copiar el de otro.
|
|
|
|
3. **El equipo hereda las protecciones, no las preferencias** — los `deny` son compartidos, los `allow` son individuales.
|
|
|
|
**Por qué:**
|
|
- La fricción de aprobar cada `npm install` destruye el flow de trabajo
|
|
- Pero el bypass total elimina los puntos de control donde se detectan acciones no intencionadas
|
|
- La gobernanza está en clasificar comandos por riesgo, no en aprobar todo o aprobar nada
|
|
|
|
**Indicador de aplicación correcta:**
|
|
- En cada sesión de Claude Code, los comandos rutinarios pasan sin pedir aprobación
|
|
- Los comandos no rutinarios siguen pidiendo aprobación (es bueno — ahí prestás atención)
|
|
- Si un comando peligroso aparece, está bloqueado por `deny` o pide aprobación explícita
|
|
|
|
**Indicador de violación:**
|
|
- El dev usa `--dangerously-skip-permissions` rutinariamente
|
|
- El archivo `settings.json` contiene `allow` que deberían ser personales (paga la complejidad de mantenerlo sincronizado entre devs)
|
|
- No hay archivo de configuración y cada dev aprueba todo manualmente cada vez (fricción crónica, señal de que falta este patrón)
|
|
|
|
**Template:** ver `methodology/TEMPLATES/CLAUDE_PERMISSIONS_TEMPLATE.md`.
|
|
|
|
**Relación con otros patrones:**
|
|
- Complementa **B.4** (reglas no negociables en CLAUDE.md) — pero B.4 es sobre comportamiento del agente, D.4 es sobre permisos del sistema operativo
|
|
- Refuerza **Principio 5** (humano director) — sin permisos configurados, el dev se vuelve operador de aprobación
|
|
|
|
**Casos reales que valida:**
|
|
- InQ ROI: el director identificó fatiga de aprobación después de ~30 etapas. Configurar permisos eliminó la fricción sin perder gobernanza.
|
|
|
|
## Categoría E — Comunicación humano ↔ agente
|
|
|
|
### E.1 Separar lo validado de lo asumido
|
|
**Estado:** propuesto · **Deriva de:** Principios 2 y 3
|
|
|
|
En los reportes del agente, marcar explícitamente qué fue verificado vs qué se asume funcionando.
|
|
|
|
**Ejemplo:**
|
|
```
|
|
Verificado:
|
|
- Tests verdes (455/455)
|
|
- PDF generado y abierto con pdf-parse
|
|
- Análisis de píxeles confirma heatmap completo
|
|
|
|
Asumido:
|
|
- El componente se renderiza igual en Firefox (solo testeado en Chromium)
|
|
- La fuente Roboto está disponible en el sistema cliente (no validado)
|
|
```
|
|
|
|
---
|
|
|
|
### E.2 Hallazgos no esperados como sección explícita
|
|
**Estado:** propuesto · **Deriva de:** Principios 3 y 5
|
|
|
|
Al final de cada etapa, el agente reporta "hallazgos no esperados" — cosas que descubrió durante la implementación que merecen decisión arquitectónica, aunque no formen parte del DoD.
|
|
|
|
**Ejemplo:** "El cambio de `--primary` propagó a focus rings de inputs (no estaba en el plan). Decisión necesaria: ¿se mantiene o se vuelve a slate?"
|
|
|
|
---
|
|
|
|
### E.3 Anti-racionalización explícita
|
|
**Estado:** propuesto · **Deriva de:** Principio 3
|
|
|
|
Cuando un test revela algo raro, un cálculo no cuadra, o un output difiere de lo esperado: **investigar causa raíz, no minimizar**.
|
|
|
|
Patrón típico de violación: el agente dice "el cálculo es numéricamente correcto" cuando lo que está reportando es un problema de presentación (ej. "0.0 meses" es matemáticamente correcto pero un bug de UX).
|
|
|
|
---
|
|
|
|
### C.7 Control preventivo de scope — `git diff` antes de reportar
|
|
**Estado:** propuesto · **Deriva de:** Principios 3 y 4 · **Origen:** Sprint 2 Etapa 1
|
|
|
|
Incluir en todo prompt de Claude Code la siguiente verificación como paso obligatorio antes de reportar:
|
|
|
|
```bash
|
|
git diff --name-only HEAD
|
|
```
|
|
|
|
El resultado debe contener únicamente los archivos listados como autorizados en el prompt. Si aparece un archivo no autorizado:
|
|
1. Revertirlo: `git checkout HEAD -- <archivo>`
|
|
2. Listarlo bajo "Conflictos de scope" en el reporte
|
|
3. No incluirlo en el entregable de la etapa
|
|
|
|
**Por qué es preventivo, no detectivo:** los controles detectivos (grep de tipos, build, tests) verifican que el código resultante funciona, pero no detectan archivos modificados fuera del scope. Un agente puede tocar `ActivityPanel.tsx` y los tests seguir verdes si el cambio no rompe nada. El `git diff` captura el cambio antes de que se declare la etapa terminada.
|
|
|
|
**Indicador de aplicación correcta:** el reporte del agente incluye explícitamente la salida de `git diff --name-only HEAD` y todos los archivos listados son los autorizados.
|
|
|
|
**Indicador de violación:** el reporte no incluye la salida del git diff, o el diff contiene archivos no listados sin explicación.
|
|
|
|
**Relación con otros patrones:**
|
|
- Es respuesta directa al daño documentado en **AP.9** (resolución unilateral de restricciones contradictorias).
|
|
- Complementa **C.3** (auditoría adversarial) dándole al humano una checklist concreta de qué verificar.
|
|
|
|
---
|
|
|
|
## Cómo agregar un patrón nuevo
|
|
|
|
1. Identificar el patrón durante un proyecto real (no inventarlo en abstracto).
|
|
2. Documentarlo con: nombre, categoría, principio del que deriva, descripción, indicador de aplicación correcta, indicador de violación.
|
|
3. Marcarlo como **propuesto** con cita del proyecto donde apareció.
|
|
4. Después de aplicarlo en un 2do proyecto distinto, promoverlo a **estable**.
|
|
|
|
## Cómo retirar un patrón
|
|
|
|
Si un patrón no se sostiene en práctica o tiene falsos positivos frecuentes, se retira con un PR que documente:
|
|
- Por qué no funcionó
|
|
- Qué alternativa probamos
|
|
- Si hay un patrón nuevo que lo reemplaza
|