freeze

Descripción general de la habilidad freeze

Qué hace freeze

freeze es una habilidad de contención que restringe las ediciones de archivos a un solo directorio durante la sesión. Bloquea Edit y Write fuera de la ruta permitida, así que resulta útil cuando quieres que un agente de automatización de flujos de trabajo se mantenga dentro de un módulo, una carpeta de una funcionalidad o un entorno aislado de depuración. Si necesitas la freeze skill para evitar cambios accidentales de gran alcance, esta es la opción adecuada.

Quién debería instalarla

Instala freeze si con frecuencia le pides a un agente que depure, refactorice o corrija código dentro de un alcance reducido y no quieres que “ayude” tocando archivos no relacionados. Es especialmente valiosa para mantenedores, revisores y cualquier persona que trabaje en una base de código mixta o delicada, donde los límites de edición importan más que la autonomía amplia.

En qué se diferencia

La gran diferencia está en la ejecución, no en la recomendación. freeze usa un hook previo a la herramienta para denegar ediciones fuera del directorio elegido, algo más sólido que un prompt que solo pide al modelo que se mantenga enfocado. Eso hace que la guía de freeze sea útil para una contención real, especialmente en sesiones donde cualquier desvío accidental saldría caro.

Cómo usar la habilidad freeze

Instala e inicializa el límite

Para freeze install, añade la habilidad a tu entorno con el gestor de habilidades del repositorio y después elige el directorio que quieres bloquear. El flujo de configuración de la habilidad es interactivo porque la ruta permitida depende de la sesión. En la práctica, debes estar listo para responder: “¿Qué directorio debe congelarse?” con una ruta precisa, no con una zona vaga como “el backend”.

Lee primero estos archivos

Empieza con SKILL.md para entender el flujo de control y luego revisa bin/check-freeze.sh para ver cómo se aplica el límite. Si vas a adaptar la habilidad, consulta también SKILL.md.tmpl para entender la estructura generada. Estos archivos te dicen qué permite realmente el uso de freeze, qué se bloquea y dónde el análisis de rutas puede fallar o ser más permisivo.

Da a la habilidad un prompt preciso

La mejor entrada combina una tarea concreta con un límite claro. Por ejemplo: “Congela las ediciones en apps/payments y corrige ahí los tests unitarios que fallan sin cambiar las librerías compartidas.” Eso es mejor que “depura esta app”, porque freeze necesita un directorio objetivo y una tarea que quepa dentro de él. Cuanto más exacto sea el alcance, menos probable será que el agente pida excepciones.

Consejos prácticos de flujo de trabajo

Usa freeze cuando la primera pasada deba ser quirúrgica: localizar el error, aplicar el parche dentro de una carpeta y verificar sin ampliar el alcance. Si la tarea realmente requiere cambios entre varios directorios, no la fuerces a entrar en freeze; amplía la ruta permitida o usa otro flujo de trabajo. La habilidad funciona mejor cuando el conjunto de cambios solicitado está naturalmente acotado y la estructura del repositorio es clara.

Preguntas frecuentes sobre la habilidad freeze

¿freeze es solo para depuración?

No. La depuración es un uso común, pero la freeze skill también ayuda con refactors acotados, aislamiento de funcionalidades y ediciones seguras para revisión. La pregunta clave es si quieres que el agente permanezca dentro de un solo directorio mientras trabaja.

¿En qué se diferencia de un prompt normal?

Un prompt normal depende de que el modelo siga las instrucciones. freeze añade ejecución mediante hooks, así que las ediciones fuera de alcance se bloquean aunque el modelo intente hacerlas. Eso lo hace más fiable para trabajos de automatización de flujos de trabajo donde las barreras de seguridad importan.

¿freeze es apto para principiantes?

Sí, siempre que el usuario pueda nombrar un directorio con seguridad. El error más común al empezar es elegir un límite demasiado amplio o demasiado estrecho. Si el directorio es ambiguo, la sesión puede quedarse atascada mientras aclaras el alcance.

¿Cuándo no debería usar freeze?

No lo uses cuando la tarea deba abarcar varios módulos, configuraciones compartidas o formato a nivel de todo el repositorio. En esos casos, la restricción puede ralentizar el trabajo o provocar acciones bloqueadas innecesarias. freeze es mejor cuando el límite es una decisión real, no solo una preferencia.

Cómo mejorar la habilidad freeze

Haz explícito el límite

La mayor mejora de calidad viene de nombrar juntos el directorio exacto y el resultado esperado. Una buena instrucción se parece a esto: “Congela las ediciones en services/auth y actualiza el flujo de renovación de tokens sin tocar shared/.” Una instrucción débil como “arregla auth” obliga a adivinar y aumenta la probabilidad de ediciones bloqueadas o incompletas.

Incluye archivos, síntomas y límites

Para usar mejor freeze, indica el archivo que falla, el comportamiento observado y cualquier archivo que esté fuera de límites. Ejemplo: “Edita solo apps/admin; el error está en src/table.ts; no cambies los contratos de API.” Eso ayuda al agente a mantenerse dentro de la zona congelada sin dejar de resolver el problema real.

Vigila el desajuste del límite

El fallo más habitual es una tarea que en secreto necesita un alcance más amplio del que permite el directorio congelado. Si el agente sigue topándose con escrituras denegadas, normalmente la solución es ampliar el límite o dividir la tarea en etapas. Eso es una ventaja, no un defecto: freeze te está diciendo que el plan y el alcance no coinciden.

Itera después de la primera pasada

Después de la primera salida, revisa si la solución dependía de supuestos fuera de la ruta congelada. Si fue así, ajusta el prompt añadiendo una o dos restricciones concretas: directorio objetivo, tipos de archivo permitidos y qué debe permanecer intacto. Para obtener los mejores resultados con la freeze skill, itera aclarando el alcance, no pidiendo más creatividad.