Ejecutor de Planes Fronterizos para OpenCode
Principio Fundamental
El plan fronterizo es una hipótesis sólida, no una verdad absoluta.
Ejecuta la intención del plan paso a paso, pero valida cada instrucción contra el repositorio real antes de editar código. Los planes de IA fronteriza fallan frecuentemente en: nombres de archivo inexistentes, importaciones inventadas, bibliotecas no disponibles, patrones que no coinciden con el repositorio, pruebas faltantes, arquitectura idealizada y ruptura de APIs internas.
Nunca agrupes cambios grandes. Nunca omitas la verificación. Nunca ocultes la incertidumbre. Nunca realices acciones destructivas sin aprobación explícita.
Cuándo Usarlo
- Recibes un plan de implementación detallado de varios pasos escrito por una IA fronteriza
- El plan tiene 3+ pasos distintos con rutas de archivo y patrones de código específicos
- Estás usando un modelo de codificación no fronterizo que se beneficia de la disciplina de ejecución
- El plan conlleva el riesgo de entrar en conflicto con la base de código real
NO lo uses para:
- Cambios de un solo archivo o correcciones triviales
- Planes con solo 1-2 pasos simples
- Planes que escribiste tú mismo durante la misma sesión
- Iteración rápida donde el usuario prioriza la velocidad sobre la seguridad
Flujo de Trabajo Principal
0. PREVUELO: Establecer la Línea Base del Repositorio
Antes de tocar cualquier archivo, comprende el estado del repositorio y detecta fallos preexistentes.
1. git status --short # ¿Está limpio el repositorio?
2. Inspeccionar package.json # Scripts disponibles, dependencias
3. Inspeccionar AGENTS.md, README.md # Convenciones del proyecto, comandos
4. Detectar comandos de verificación disponibles de los scripts de package.json
5. Ejecutar la verificación de línea base más económica si está disponible (lint o typecheck)
Si la línea base ya falla:
- Registra el fallo explícitamente: comando exacto, código de salida y resumen breve del error
- NO intentes una limpieza amplia ni corregir problemas no relacionados
- Continúa solo si el cambio planificado puede aislarse del fallo existente
- No atribuyas fallos preexistentes a tu implementación
Detección de estado peligroso:
- Si
git statusmuestra cambios no confirmados no relacionados con el plan, advierte al usuario - Si los archivos de bloqueo están modificados, advierte al usuario
- Si el repositorio está en un estado de conflicto/rebase, detente y pregunta
Recomendación de checkpoint:
- Si el repositorio está limpio antes de comenzar, recomienda crear un commit de checkpoint antes de la implementación
- NO crees commits a menos que el usuario lo solicite explícitamente
Auto-Confirmación y Auto-Push
La auto-confirmación y el auto-push están habilitados por defecto a menos que el usuario los deshabilite explícitamente.
El agente debe confirmar cada unidad lógica de trabajo verificada y subirla a la rama de trabajo remota activa para que el usuario pueda revisar el historial más tarde.
Antes de la implementación:
- identifica la rama actual;
- si estás en
main,master,production,releaseu otra rama protegida/principal, crea una nueva rama de trabajo inferida del plan; - si ya estás en una rama de trabajo, continúa allí;
- nunca hagas push directamente a ramas protegidas/principales.
Si hay cambios no confirmados preexistentes:
- no los incluyas automáticamente en los commits del agente;
- prepara solo los archivos relacionados con la unidad lógica actual;
- si los cambios del usuario y los cambios del agente no se pueden separar de forma segura, detente e informa del conflicto.
Confirma solo después de:
- que la unidad lógica esté completa;
- que la verificación pase;
- que el diff haya sido inspeccionado;
- que el commit tenga un propósito coherente.
Usa Commits Convencionales:
tipo(alcance): resumen imperativo conciso
Ejemplos:
feat(auth): añadir helper de validación de sesión
fix(api): manejar payload de webhook vacío
refactor(billing): extraer mapeador de facturas
test(auth): cubrir flujo de sesión expirada
1. ANALIZAR: Extraer y Verificar la Realidad del Plan
Lee el plan COMPLETO. Extrae los pasos ordenados. Para cada paso, realiza una verificación de realidad:
| Verificación | Pregunta |
|---|---|
| Archivos | ¿Existen los archivos referenciados en el repositorio? |
| Bibliotecas | ¿Están las bibliotecas referenciadas en package.json? |
| Patrones | ¿Tiene el repositorio ya una utilidad/componente equivalente? |
| Comandos | ¿Están disponibles los comandos de verificación del plan? |
| Dependencias | ¿Depende este paso de un paso anterior? |
| Riesgo | Bajo / Medio / Alto — ¿qué probabilidad hay de romper el comportamiento existente? |
Si un paso referencia archivos faltantes, bibliotecas inexistentes, patrones obsoletos o comandos no disponibles: adapta el paso antes de implementar, preservando la intención del plan.
2. SEGUIMIENTO: Crear un Rastreador de Progreso
Usa todowrite (la herramienta de lista de tareas de OpenCode) si está disponible.
Si todowrite no está disponible (por ejemplo, en subagentes donde está deshabilitado por defecto):
- Crea una lista de verificación markdown visible en tu respuesta
- Mantenla actualizada manualmente después de cada paso
- Úsala como fuente de verdad para el progreso
- NO finjas que la herramienta se usó si no fue así
Cada elemento debe incluir: la acción de implementación, el método de verificación y los archivos esperados que se tocarán.
3. IMPLEMENTAR: Un Paso a la Vez
Marca el paso actual como en_progreso. Implementa SOLO ese paso.
- Lee los archivos de destino antes de editarlos
- Sigue las convenciones existentes de la base de código (importaciones, nombres, patrones, arquitectura)
- Adapta el plan a la infraestructura existente (por ejemplo, si el plan dice "crear un componente toast" pero el proyecto usa Sonner, envuelve Sonner en lugar de construirlo desde cero)
- Haz el cambio coherente más pequeño
- NO implementes pasos futuros, pero ten en cuenta las dependencias posteriores al tomar decisiones de diseño
- NO realices limpieza, refactorización o formateo no relacionados
- NO instales dependencias a menos que se apruebe explícitamente
4. VERIFICAR: Verificación por Niveles
Después de cada paso, ejecuta la verificación significativa más estricta. No "lint de todo" cada vez.
| Tipo de Cambio | Verificación Mínima | Verificación Más Fuerte |
|---|---|---|
| Archivo/componente nuevo | lint o typecheck | typecheck afectado |
| Cambio de tipo/interfaz | typecheck | pruebas afectadas |
| Cambio de lógica/función | prueba unitaria específica | suite de pruebas completa |
| Cambio de API/servidor | prueba de integración específica | build + comprobación de endpoint |
| Cambio de UI | typecheck + build | comprobación visual/manual |
| Cambio de configuración/build | build | instalación/build limpia si es necesario |
| Cambio de base de datos/esquema | comando de simulación/verificación | aprobación del usuario requerida |
Si no existe una verificación automatizada para un paso: realiza una revisión manual y declara con precisión lo que comprobaste.
Si la verificación falla:
Primer fallo — corrige y vuelve a verificar:
- Corrige solo los errores causados por el paso actual
- NO corrijas errores preexistentes o no relacionados
- Vuelve a verificar inmediatamente
Fallos repetidos — no sigas parcheando a ciegas. Consulta "Manejo de Fallos Repetidos" a continuación.
Crítico: Nunca hagas que la verificación pase debilitando aserciones, eliminando pruebas, quitando comportamiento, cambiando APIs públicas, suprimiendo errores u ocultando fallos — a menos que el plan lo requiera explícitamente Y el usuario lo apruebe. Hacer que la alarma se detenga no es lo mismo que solucionar el problema.
5. DIFF: Inspeccionar los Cambios
Después de que la verificación pase, inspecciona lo que realmente cambió:
git diff --stat # ¿Qué archivos cambiaron?
git diff # Cuando el diff es lo suficientemente pequeño para revisar
Confirma:
- Solo cambiaron los archivos esperados
- No ocurrió ningún formateo no relacionado
- No cambiaron los archivos de bloqueo (a menos que fuera intencional)
- No se editaron archivos generados accidentalmente
- No se introdujeron secretos, rutas locales o registros de depuración
- No se eliminó código accidentalmente
Si el diff excede el alcance esperado, detente y corrige antes de continuar.
6. CONFIRMAR: Marcar como Completado
Solo cuando la implementación, la verificación Y la inspección del diff estén limpias:
- Marca el paso como
completado - Resume lo que cambió en una oración
- Marca el siguiente paso como
en_progreso
7. FINAL: Verificación Completa + Informe
Después de todos los pasos:
- Ejecuta la comprobación razonable más sólida: lint + typecheck + build + pruebas (usando los comandos del proyecto)
- Informa: pasos completados, archivos cambiados, resultados de verificación, adaptaciones realizadas, fallos preexistentes (si los hay), cualquier cosa que requiera revisión del usuario
Manejo de Fallos Repetidos
Si la verificación falla repetidamente por la misma razón subyacente, no continúes aplicando pequeñas correcciones ciegas. El objetivo es detectar si estás aprendiendo algo nuevo entre intentos o simplemente dando palos de ciego.
Cuando un paso falla varias veces:
- Deja de parchear. Deja de hacer pequeños ajustes y volver a ejecutar.
- Vuelve a leer la salida del error cuidadosamente. El stacktrace completo, no solo la primera línea.
- Inspecciona el diff y el código circundante.
git diff, lee tipos, interfaces y funciones relacionados. - Reevalúa la suposición original. ¿Es correcta la estrategia de implementación actual?
- Clasifica el fallo:
- ¿Suposición incorrecta sobre la base de código?
- ¿Desajuste del repositorio (plan vs realidad)?
- ¿Abstracción incorrecta elegida?
- ¿Incompatibilidad de interfaz o tipo?
- ¿Dependencia faltante?
- ¿Artefactos generados obsoletos?
- ¿Problema preexistente no relacionado con tu cambio?
- ¿El propio comando de verificación está mal configurado?
- Formula una hipótesis genuinamente nueva. Solo vuelve a intentarlo cuando tengas una.
- Considera reducir el alcance. ¿Se puede dividir el paso en partes más pequeñas para aislar el fallo?
Regla crítica: No repitas la misma estrategia de corrección a menos que se haya descubierto nueva información a partir de:
- Registros
- Trazas de pila
- Diffs
- Pruebas
- Inspección del repositorio
- Documentación
Si no surge una nueva estrategia después de múltiples intentos, detente e informa claramente del bloqueador:
Bloqueador:
- comando de verificación: `npm run build`
- archivo fallido: `src/app/page.tsx`
- hipótesis de la causa raíz: componente del servidor React importando hook solo del cliente
- estrategias intentadas:
1. mover importación al componente del cliente
2. aislar el hook en un archivo separado
3. verificar patrones existentes en el repositorio
- razón para detenerse:
no hay un patrón consistente en el repositorio para resolver el límite de manera segura
- probable siguiente acción:
revisión del usuario o aclaración arquitectónica
Un informe de bloqueador claro siempre es mejor que repetir "sigue fallando" mientras se adivina.
Adaptando Planes al Código Existente
Los planes de IA fronteriza frecuentemente entran en conflicto con la base de código real. Cuando esto sucede:
- Identifica el conflicto — "El plan dice
import { X } from 'librería-no-instalada'pero no está en package.json" - Adapta, no ignores — Usa la infraestructura existente para que coincida con la intención del plan
- Explica la adaptación — Una oración sobre lo que cambiaste y por qué
- Preserva la interfaz del plan — Si el plan exporta
useToast(), tu adaptación aún debe exportaruseToast(), incluso si los detalles internos difieren
Reglas críticas:
- NO crees nuevas abstracciones si el repositorio ya tiene una primitiva equivalente
- NO instales nuevas dependencias a menos que el plan lo requiera explícitamente Y el usuario lo apruebe
- NO cambies la arquitectura o los patrones sin justificación
Prohibido Sin Aprobación Explícita del Usuario
Estos comandos requieren que el usuario diga "sí" antes de ejecutarlos:
Destructivos:
rm -rfgit reset --hardgit clean -fdgit push --force
Instalación (cambia archivos de bloqueo):
npm installpnpm installyarn installbun installnpm audit fix
Base de datos / Infraestructura:
prisma migrateprisma db pushsupabase db pushdocker compose down -v
Configuración:
- Cambiar archivos
.env - Modificar la configuración global de herramientas
- Ejecutar comandos de implementación/despublicación
Cambios masivos:
- Formateo amplio (prettier/eslint --fix en todo el repositorio)
- Buscar y reemplazar en muchos archivos sin revisión
Si no estás seguro de si un comando es seguro, pregunta antes de ejecutarlo.
Errores Comunes
| Error | Realidad |
|---|---|
| "La IA fronteriza lo dijo, así que debe ser correcto" | Los planes fronterizos son hipótesis. Valida contra el repositorio real. |
| "Verificaré todo al final" | Los errores se acumulan. Verifica cada paso con la granularidad adecuada. |
| "Ya leí el plan, puedo implementarlo todo a la vez" | Implementación por lotes = errores por lotes + depuración más difícil. |
| "Arreglaré los errores de lint preexistentes ya que estoy aquí" | La limpieza no relacionada enmascara lo que tus cambios realmente hicieron. No lo hagas. |
| "Este paso es simple, no necesito comprobar git diff" | Las ediciones simples pueden eliminar código accidentalmente o formatear archivos no deseados. |
| "Instalaré la biblioteca faltante que referencia el plan" | Pregunta primero. La biblioteca puede estar intencionalmente ausente o no aprobada. |
| "npm run build es la única verificación que importa" | Build es lento y amplio. Usa lint/typecheck para pasos intermedios. |
| "Si falla, solo ajustaré y volveré a ejecutar hasta que pase" | Parchear a ciegas sin nueva información es dar palos de ciego. Vuelve a leer los errores. Formula una nueva hipótesis primero. |
| "El mismo error otra vez, probemos con otro cambio pequeño" | Mismo error + misma estrategia = mismo resultado. Cambia la estrategia, no el parche. |
Señales de Alerta — DETENTE y Reevalúa
- "Verificaré después del siguiente paso también" — Verifica AHORA.
- "El plan fronterizo sabe más que el repositorio" — El repositorio es la fuente de verdad.
- "Esta biblioteca no está instalada pero el plan la necesita" — Pregunta al usuario. No instales en silencio.
- "El diff es más grande de lo esperado pero probablemente esté bien" — Inspecciona y explica antes de continuar.
- "Agruparé los pasos 2 y 3 ya que están relacionados" — Un paso = un ciclo de verificar + diff.
- "Errores de lint preexistentes, déjame arreglarlos primero" — No es tu trabajo. Regístralos. Mantente enfocado.
- "Déjame formatear este archivo mientras lo edito" — Cambio separado = paso separado. No mezcles.
- "Sigue fallando, probemos con otra solución rápida" — Deja de parchear. Vuelve a leer el error. Formula una nueva hipótesis primero.
- "El mismo error 3 veces, un ajuste más podría funcionar" — Mismo error + misma estrategia = dar palos de ciego. Cambia la estrategia o informa del bloqueador.
- "Simplemente reescribiré todo y veré si eso lo soluciona" — Tirar el trabajo sin entender por qué falló no enseña nada. Diagnostica primero.
- "El usuario tiene prisa, me saltaré la comprobación del diff" — 5 segundos de
git diff --statprevienen horas de depuración.
Referencia Rápida
| Fase | Acción | Herramienta |
|---|---|---|
| Prevuelo | git status, detectar comandos, verificación de línea base | Bash |
| Analizar + Verificación de Realidad | Leer plan, validar cada paso contra el repositorio | Leer + Glob |
| Seguimiento | Crear lista de verificación | todowrite o markdown |
| Implementación | Leer archivo de destino, hacer el cambio más pequeño | Editar |
| Verificación | Ejecutar lint/typecheck/prueba según el cambio | Bash |
| Inspección de Diff | git diff --stat + git diff | Bash |
| Confirmación | Marcar paso, pasar al siguiente | todowrite o markdown |
| Final | lint + typecheck + build + pruebas + informe | Bash |