Mantenimiento programado

Propósito

Lanzar al agente con regularidad en pasadas que buscan deriva en el código, la documentación y el propio entorno del agente, reconstruyen modelos de comportamiento ocultos y devuelven el resultado en forma de PR pequeños, descripciones de modelos o tickets. Cada pasada tiene su propia frecuencia, su propio alcance y su propia forma de ejecución: en la nube, en local o contigo.

También conocido como

Garbage collection, doc gardening, maintenance routines, tareas periódicas, pasadas de higiene.

Problema

Los agentes escriben decenas de miles de líneas a la semana. La revisión de cada PR solo comprueba su diff. Si tres PR se desvían un poco del estándar, cada uno en un sitio distinto, ninguna revisión lo nota, y al cabo de un mes la desviación se convierte en la nueva norma que el agente sigue copiando.

Junto con el código envejece todo lo que ayuda al agente a trabajar. El glosario no conoce los modelos nuevos, en AGENTS.md se acumulan reglas que ya no cambian nada, el skill que arranca la aplicación apunta a un script borrado, la lista de permisos no para de crecer y en la memoria privada del agente se depositan hechos del proyecto que no están en el repositorio. Cada uno de estos detalles le cuesta al agente llamadas extra y errores en cada sesión siguiente.

Una limpieza puntual «cuando la cosa se ponga fea» no funciona: para entonces la deriva ya se ha extendido por el código, y arreglarla se convierte en una refactorización grande y arriesgada. Una limpieza manual semanal tampoco escala: el equipo le dedica un día y aun así no alcanza el volumen.

Solución

Cuando hay mucho código de agentes, todo deriva a la vez: la arquitectura, los límites entre capas, el glosario, el cumplimiento de los estándares, las instrucciones para los propios agentes. Empieza con una frecuencia semanal para revisar estándares, simplificación, seguridad y glosario. Alterna las pasadas sobre modelos ocultos y arquitectura entre las áreas donde más cuesta hacer cambios. Las instrucciones, los skills, los ADR y los ajustes del agente cambian más despacio, así que una revisión mensual es un buen punto de partida. Ajusta la frecuencia según la utilidad de los hallazgos y la capacidad del equipo para revisar los resultados.

Cada pasada mira una parte concreta: los cambios de la semana, un directorio, una capa o un concepto del dominio. Una pasada por todo el repositorio de golpe da un informe superficial.

Descubrir el modelo y cambiar el código son pasadas distintas. Primero recibes una descripción del comportamiento existente con referencias al código y dudas; después eliges un cambio. El resultado puede ser una corrección pequeña, un modelo aceptado o un ticket con una pregunta sobre el dominio. Si no hay nada que cambiar, esa es la conclusión. Exigir un PR tras cada ejecución fomenta modificaciones innecesarias.

Aplica el flujo de refactorización al cambio elegido: comprueba el comportamiento actual antes y después de editar. Las pasadas programadas complementan las pequeñas mejoras durante las tareas habituales.

Aparte de las pasadas programadas, mantén una revisión por evento. La retrospectiva de una sesión sirve justo después de un trabajo que salió mal, mientras aún recuerdas qué falló. Una semana después ya no queda nada que revisar.

Estructura

El diagrama muestra las tres formas de ejecución y adónde llega el resultado de cada una.

Las pasadas en segundo plano trabajan sin ti. Configura el resultado esperado: un PR con cambios, una descripción del modelo o tickets con hallazgos comprobados. Revisa el resultado tras la ejecución; también es válido no encontrar nada. Los hallazgos semanales sugieren un área para la sesión de arquitectura. Lanza la retrospectiva después de una sesión difícil; las pasadas locales mantienen la herramienta.

Participantes / Componentes

• El calendario lanza las pasadas con la frecuencia fijada y guarda sus prompts.
• El punto de referencia fija el rango: una etiqueta de la última ejecución o una fecha.
• Una pasada comprueba un área en busca de un tipo de deriva.
• La referencia describe la norma: estándares de código, glosario, ADR, AGENTS.md.
• El resultado convierte los hallazgos en PR, descripciones de modelos o tickets y separa el comportamiento confirmado de las suposiciones.
• Tú aceptas los cambios, eliges el área para la sesión de arquitectura y respondes a las preguntas de la retrospectiva.

Cuándo aplicarlo

• Los agentes escriben más código del que el equipo puede leer con atención.
• El proyecto tiene una referencia con la que comparar: estándares, un glosario, ADR.
• Sobre el repositorio trabajan varias personas o varias sesiones en paralelo.
• El proyecto ya ha acumulado un entorno para el agente: instrucciones, skills, hooks, permisos.

En un proyecto pequeño con un solo desarrollador y cambios poco frecuentes, basta con una retrospectiva tras las sesiones fallidas y una pasada mensual por las instrucciones.

Consecuencias y compromisos

• ➕ La deriva se corrige en pasos pequeños mientras todavía es local.
• ➕ Las instrucciones y los skills siguen siendo cortos y corresponden al trabajo real.
• ➕ Las pasadas en segundo plano no te quitan tiempo hasta la revisión.
• ➖ Los PR semanales también hay que leerlos; si se acumulan, las pasadas pierden su sentido.
• ➖ Un agente en segundo plano se equivoca como cualquier otro, así que sus PR pasan por la revisión normal.
• ➖ Las pasadas cuestan tokens y límites de uso, sobre todo en rangos grandes.
• ➖ El calendario envejece junto con el proyecto y también necesita revisión.

Implementación

Las pasadas semanales por el código pueden ser tareas en la nube. Pide un PR pequeño para las correcciones, o una descripción con referencias al código y preguntas abiertas para descubrir modelos ocultos. Realiza la arquitectura, la discusión de reglas dudosas, las retrospectivas y el mantenimiento en una sesión interactiva. Indica el periodo, por ejemplo «de la última semana»; para un recorrido sucesivo puedes guardar el commit revisado de la ejecución anterior. Elige el siguiente rango tras revisar el resultado y ten en cuenta los tickets abiertos para evitar propuestas repetidas. Revisa cada mes la utilidad de las pasadas.

Pasadas que no dependen del agente

Algunas pasadas usan skills de Matt Pocock; otras son prompts normales. Para los skills, instala el paquete por uno de los métodos de su perfil y ejecuta una vez /setup-matt-pocock-skills. Los ejemplos nombran las rutinas; la invocación depende del agente. Los comandos integrados están en bloques separados después del enfoque común.

Retrospectiva

Es el skill retro de la sección de ingeniería del paquete (código fuente). El modelo no lo invoca por su cuenta; solo lo lanzas tú.

El skill carga writing-for-agents como guía de estilo y lee la transcripción de la sesión, por defecto la actual. Busca mejoras en siete categorías: navegación por el proyecto, comprobaciones automáticas, estándares de revisión, AGENTS.md, economía de llamadas, reglas que no cambian nada y acceso a la información. Propone detectar una infracción mecánica con un linter, un hook o CI, y anotar en los estándares solo lo que requiere criterio. Presenta los candidatos por gravedad y no cambia nada por sí mismo.

Lánzalo justo después de una sesión en la que el agente se atascó: muchas correcciones, una vuelta atrás, una búsqueda larga, un error repetido. Implementa las propuestas aceptadas en esa misma sesión.

Ejemplo

/retro

Revisión de estándares

Es el skill code-review del paquete (código fuente).

El skill toma el diff desde un punto de referencia (git diff <punto>...HEAD) y encuentra los documentos con estándares, como CODING_STANDARDS.md y CONTRIBUTING.md. Luego lanza dos subagentes en paralelo: uno contrasta el diff con los estándares del proyecto y con una lista base de code smells de Refactoring de Fowler, el otro lo contrasta con la tarea de origen. Para una pasada programada basta con la primera parte. Las infracciones se dividen en graves y discutibles, cada una con un enlace a la regla.

Lánzalo cada semana como tarea en la nube, una tarea por cada área grande.

Ejemplo

/code-review de la última semana

Refactorización

Cada semana, elige un área activa y un tipo de dificultad: una regla repetida, estados poco claros, abstracciones innecesarias o ramas obsoletas. Alterna las áreas y ten en cuenta los tickets abiertos. Refactorización explica las peticiones concretas, la investigación del modelo y las comprobaciones antes y después del cambio.

Revisión de seguridad

Un prompt normal. El agente lee los cambios del periodo y revisa los sitios donde un error sale más caro: autorización, pagos, subida de archivos y llamadas a API externas.

Lánzalo cada semana como tarea en la nube sobre la rama principal.

Ejemplo

Revisa si hay vulnerabilidades en los cambios de la última semana

Comprobación del glosario

Es el skill domain-modeling del paquete (código fuente).

El skill contrasta los términos del código y de la conversación con GLOSSARY.md y señala las contradicciones: el glosario llama a un concepto de una manera y el código de otra, o el código se comporta distinto de lo descrito. Un término resuelto lo anota en el glosario enseguida. GLOSSARY.md sigue siendo solo un diccionario, sin detalles de implementación. El skill está pensado para una conversación contigo; en una tarea en la nube no hay a quién preguntar, así que los términos dudosos van a la descripción del PR.

Lánzalo cada semana como tarea en la nube.

Ejemplo

/domain-modeling de la última semana

Arquitectura

Cada semana, dedica una sesión conjunta a un área elegida según los hallazgos semanales. Trabaja con el agente cuando la decisión exija aclarar el dominio o comparar interfaces. Refactorización describe el uso de improve-codebase-architecture y el paso a tickets.

Instrucciones para agentes

Es el skill writing-for-agents del paquete (código fuente).

Es una referencia sobre cómo escribir documentos para un agente. Trata los punteros de contexto, las dos cargas (sobre el contexto del agente y sobre la atención de la persona), el orden de pasos y referencia, los criterios de finalización y la fuente única de verdad. Con él se ven los duplicados entre archivos, los documentos hinchados y las prohibiciones que atraen la atención hacia lo prohibido más de lo que la apartan.

Lánzalo cada mes.

Ejemplo

/writing-for-agents revisa la documentación

Tus propios skills

Tus propios skills se revisan con el mismo writing-for-agents; para los skills trata además el frontmatter y la forma de invocación. La descripción de un skill debe nombrar los casos en que hace falta, y cada paso debe terminar en un criterio comprobable.

Lánzalo cada mes.

Ejemplo

/writing-for-agents revisa los skills

ADR

Los ADR se revisan con el mismo domain-modeling. El skill lee docs/adr, contrasta las decisiones con el código y con ADR posteriores, y pone estados y enlaces.

Lánzalo cada mes.

Ejemplo

/domain-modeling revisa los ADR

Memoria del agente

No hay comando propio; basta un prompt normal. El agente lee su memoria sobre el proyecto, lleva al repositorio los hechos sobre el código y los comandos y deja en la memoria solo cómo trabajar contigo. Dónde vive la memoria y cómo se limpia sola depende del agente y se describe en su bloque. Si desactivaste la memoria en el proyecto, como aconseja «Memoria privada», la pasada hace falta una sola vez, antes de desactivarla.

Lánzalo cada mes, en local.

Ejemplo

Limpia tu memoria de este proyecto

Claude Code

Este bloque se comprobó con Claude Code 2.1.316 y la referencia de comandos el 2026-10-31. El mantenimiento de instalación y memoria se ejecuta en local. /schedule inicia tareas en la nube; la revisión también tiene el modo en la nube /code-review ultra.

Calendario: /schedule

/schedule es un comando integrado, también /routines (documentación).

El comando crea una tarea en la nube conversando contigo: aclara el calendario, el repositorio y la petición. Normalmente parte de la rama por defecto; los eventos de PR y los ajustes explícitos pueden cambiarla. El resultado puede ser un informe, comentario o PR. Si necesitas un PR, indícalo al configurar la tarea y comprueba el resultado. Las ramas nuevas suelen llevar el prefijo claude/; la transcripción en claude.ai muestra la ejecución.

Ejemplo

/schedule cada lunes /code-review de la última semana

Revisión: /code-review y /review

Claude Code tiene un skill integrado /code-review que busca errores de corrección. Un skill del proyecto con el mismo nombre, como code-review del paquete de Matt Pocock, lo sustituye, y el integrado sigue disponible como /review (documentación).

Ejemplo

/review

Simplificación

Elige un área activa para cada tarea periódica. Refactorización explica el skill integrado /simplify y la validación del resultado; aquí configura el calendario y comprueba que se revisen los resultados antes de la siguiente ejecución.

Ejemplo

/schedule cada lunes /simplify app/services

Seguridad: /security-review

/security-review es un comando integrado (referencia de comandos, código fuente). Las comprobaciones del plugin instalado Security Guidance son un mecanismo aparte.

El comando toma el diff entre la rama actual y la rama por defecto de origin y busca inyecciones, fallos de autorización y fugas de datos. No acepta un rango de commits, así que se ejecuta en una rama antes de fusionar, y la pasada semanal por la rama principal sigue siendo un prompt normal del bloque común.

Ejemplo

/security-review

Memoria

La memoria automática vive en ~/.claude/projects/<proyecto>/memory; /memory muestra las entradas y controla su activación (documentación). Son notas personales de la herramienta. Durante el mantenimiento mensual, lleva las reglas comprobadas del equipo a AGENTS.md mediante revisión; no esperes que el procesamiento en segundo plano actualice por sí solo el repositorio.

Permisos: /fewer-permission-prompts

/fewer-permission-prompts es un skill integrado.

El skill lee las transcripciones de las sesiones, reúne las llamadas frecuentes de solo lectura a Bash y MCP y propone una lista por prioridad. Cuando das tu conformidad, las añade a la lista compartida de permisos del proyecto, que se sube con el código.

Lánzalo cada mes.

Ejemplo

/fewer-permission-prompts

Estado de la instalación: /doctor

/doctor es un skill integrado.

El skill comprueba la instalación, la versión, los ajustes, los plugins, los servidores MCP y los hooks. Evalúa los cambios propuestos de permisos aparte del diagnóstico. Revisa AGENTS.md con writing-for-agents: contrasta los comandos con el proyecto, elimina duplicados y comprueba el resultado con tareas reales.

Lánzalo cada mes, después de /fewer-permission-prompts.

Ejemplo

/doctor

Skills: /skill-doctor

/skill-doctor es un comando integrado disponible desde la versión 2.1.252 (documentación). El informe requiere acceso a la descarga de feature flags; el comando no está disponible mediante Remote Control.

El informe muestra el coste en contexto y el uso de los skills admitidos; excluye los integrados y corporativos. Claude Code carga skills del proyecto, del usuario, de plugins y de otras fuentes admitidas. En instalaciones editables, comprueba .claude/skills/ o los enlaces a archivos compartidos; en instalaciones por plugin, comprueba el plugin.

Lánzalo cada mes.

Ejemplo

/skill-doctor

Arranque de la aplicación: /run-skill-generator

/run-skill-generator es un skill integrado.

El skill escribe un skill del proyecto que enseña a /run y /verify a compilar, arrancar y comprobar tu aplicación desde un entorno limpio. Si el skill guardado deja de funcionar, /run propone actualizarlo. Claude edita el archivo solo cuando una ejecución salió mal.

Lánzalo cada mes y cada vez que /run avise de que el skill está obsoleto.

Ejemplo

/run-skill-generator

Codex

Este bloque se comprobó con Codex CLI 0.166.0 y la documentación de learn.chatgpt.com el 2026-10-31.

Calendario: Scheduled tasks y codex-action

Scheduled tasks crea tareas recurrentes en la aplicación y en ChatGPT/Work en la web cuando la función está disponible (documentación). openai/codex-action ejecuta Codex en GitHub Actions (documentación, código fuente).

Una tarea local trabaja en un proyecto o worktree separado; el ordenador y la aplicación deben estar encendidos. Una tarea web usa los archivos, skills, plugins y herramientas conectadas disponibles, sin acceso directo a una carpeta local. Las tareas trabajan sin tu presencia: comprueba antes los permisos y la sandbox. La Action ejecuta codex exec por eventos de GitHub, incluido cron, sin depender de tu máquina. Crear un PR requiere un paso aparte.

Ejemplo en la aplicación

En la vista Scheduled, crea una tarea con un calendario y un prompt:

$code-review de la última semana

Ejemplo en GitHub Actions

Pide a Codex que cree el workflow; el archivo llega al repositorio mediante la revisión normal.

Crea un GitHub Actions semanal: codex-action ejecuta $code-review y abre un PR

Revisión: codex review y @codex review

codex review es un comando integrado de la CLI; /review hace lo mismo en la TUI (documentación). Codex toma sus reglas de revisión de la sección ## Code Review Rules de AGENTS.md, así que ahí conviene tener el enlace a los estándares del proyecto. La revisión automática de PR en GitHub (@codex review) mira un solo PR e informa solo de problemas graves, así que no sustituye a la pasada semanal.

Ejemplo

codex review --base main

Pasada por el código

Repite una pasada probada según un calendario, alternando áreas y guardando el punto de partida tras la revisión. Refactorización explica la petición normal y cómo empaquetar el procedimiento como un skill propio.

En la aplicación, crea una tarea semanal con esta petición y revisa el primer resultado antes de las ejecuciones periódicas.

Ejemplo

Cada lunes, simplifica el código de pagos modificado durante la última semana

Seguridad: @codex security review

Security Review requiere acceso a la función, un espacio de trabajo configurado y un repositorio en la nube conectado (configuración). En la fecha de comprobación admite Enterprise, Business, Edu y Pro; no está disponible en Plus. En un repositorio configurado, el comentario @codex security review inicia la comprobación del PR; el informe completo aparece en Security Report de la tarea. Codex Security permite comprobaciones más amplias.

Ejemplo

@codex security review

Memoria: Memories

Las Memories están desactivadas por defecto (documentación). Si las activaste, las entradas viven en ~/.codex/memories/ y se generan a partir de sesiones anteriores. La documentación desaconseja editarlas a mano, así que en la pasada mensual los hechos del proyecto van a AGENTS.md y en un proyecto de equipo conviene pedir a Codex que desactive Memories (ver «Memoria privada»).

Permisos: archivos .rules

La sandbox limita el sistema de archivos y la red, la política de aprobación decide cuándo hace falta tu conformidad, y las reglas experimentales .rules deciden qué comandos ejecuta Codex fuera de la sandbox directamente, preguntando o nunca (reglas, sandbox). Gana la regla coincidente más estricta.

Cuando aceptas permitir siempre un prefijo de comando, Codex guarda una regla en tus reglas personales; una aprobación puntual no crea ninguna. Una vez al mes, pide a Codex que repase esas reglas: que lleve las compartidas a las reglas del repositorio y borre las que sobran.

Ejemplo

Limpia mis reglas de comandos, lleva las compartidas al repo

Estado de la instalación: codex doctor

codex doctor es un comando integrado de la CLI (documentación).

El comando comprueba la instalación, la configuración, la autenticación, el entorno de ejecución, Git y el terminal. En la TUI, /debug-config muestra las capas de configuración, y /hooks muestra los hooks y permite confiar en ellos o desactivarlos (documentación).

Lánzalo cada mes.

Ejemplo

codex doctor

Tamaño de AGENTS.md

Codex carga las instrucciones hasta un límite, 32 KiB por defecto (documentación).

Comprueba cuánto pesan las instrucciones aplicables al directorio de trabajo y si llegan al límite. Si hay muchos archivos, verifica que las reglas necesarias llegaron al contexto; que el archivo exista no demuestra que se haya cargado. Combina esta comprobación con writing-for-agents.

Ejemplo

Suma cuánto pesan todos los AGENTS.md juntos

Skills

Codex lee .agents/skills/ directamente y puede desactivar skills concretos (documentación).

Pregunta a Codex qué skills no has usado y pídele que desactive los que sobran. La estimación se basa en las sesiones conservadas, pero la falta de registros no demuestra que un skill no se usara: ten en cuenta la retención y la fuente del historial.

Lánzalo cada mes.

Ejemplo

¿Qué skills no he usado en el último mes?

Arranque de la aplicación

Los scripts de preparación y las acciones para arrancar la aplicación se configuran en Local environments (documentación). Una vez al mes, ejecuta la preparación en un worktree limpio y comprueba que la aplicación arranca desde cero.

Ejemplo

El proyecto recibe unas veinte mil líneas a la semana, los estándares están en CODING_STANDARDS.md y el código está organizado por capas en app/. Cada lunes una tarea en la nube se ejecuta con este prompt:

/code-review de la última semana

En este ejemplo didáctico, la revisión encuentra dos servicios que acceden a la base de datos saltándose los repositorios. Aceptas un PR pequeño tras comprobarlo. Una regla poco clara en pagos lleva a dedicar la siguiente sesión a su investigación y refactorización.

La duda sobre los estados queda en un ticket. La siguiente pasada semanal lo tiene en cuenta y busca discrepancias nuevas desde el commit guardado. Un mes después, ves que los informes de un directorio ya no ofrecen hallazgos útiles y cambias de área. Reduce la frecuencia si el equipo no da abasto para revisar los resultados.

Antipatrones y errores comunes

• Una pasada por todo el repositorio. El agente mira un poco de todo y solo encuentra lo evidente. Fija un alcance.
• Un único PR grande. Las correcciones de todas las áreas en un solo PR no se pueden revisar, se aplaza, y la siguiente pasada encuentra lo mismo.
• Hallazgos sin revisión. Los informes se acumulan y las siguientes ejecuciones los repiten. Una descripción del modelo aceptada es útil; un informe sin leer no ayuda.
• Refactorizar por obligación. El agente edita para producir un PR semanal. Admite la conclusión de que no hay nada que cambiar.
• Una retrospectiva de memoria. Revisar sesiones de hace una semana depende de lo que ya nadie recuerda.
• Confiar en la revisión de cada PR. La revisión automática de PR detecta errores en un diff, pero no una desviación que se acumula a lo largo de muchos PR.
• Mantenimiento de la herramienta mezclado con el proyecto. Los cambios de permisos y memoria personales acaban en un PR del equipo o, al revés, las reglas del equipo se quedan en ajustes personales.
• Un calendario que nadie revisa. Las pasadas que llevan tiempo sin encontrar nada siguen gastando límites, y la gente deja de leer sus PR.

Usos conocidos

• OpenAI describe en Harness engineering tareas de Codex en segundo plano que, con una frecuencia regular, buscan desviaciones de los «principios de oro», actualizan las calificaciones de calidad por dominio y capa, y abren PR de refactorización concretos. Un agente aparte de doc-gardening busca documentación obsoleta. Antes el equipo dedicaba cada viernes a la limpieza, y eso no escalaba.
• Los skills de Matt Pocock ofrecen pasadas listas para ejecutar con regularidad: retro, code-review, domain-modeling, writing-for-agents, improve-codebase-architecture.
• Claude Code incluye las comprobaciones de entorno integradas /doctor, /skill-doctor y /fewer-permission-prompts, y /schedule ejecuta tareas en la nube según un calendario.
• Codex da, en la documentación de Scheduled tasks, un ejemplo de tarea que repasa sesiones anteriores y mejora los skills.

Patrones relacionados

• Refactorización explica la investigación del modelo, la elección del cambio y las comprobaciones de conservación del comportamiento.
• Memoria del proyecto describe el archivo de instrucciones que la pasada mensual mantiene corto.
• Memoria hinchada muestra en qué se convierten las instrucciones sin una limpieza regular.
• Vocabulario del dominio fija la referencia para la comprobación semanal del glosario.
• Skills empaquetan las pasadas para que puedan ejecutarse según un calendario.
• Escritor y revisor separa la escritura de la revisión; la revisión programada de estándares trabaja a escala de semana, no de un PR.
• Límites ejecutables reciben nuevas comprobaciones de las retrospectivas y limitan las tareas en segundo plano a un sandbox.
• Diseña dos veces ayuda a comparar representaciones del modelo elegido.
• Bucle de retroalimentación aporta una comprobación de que la refactorización conserva el comportamiento.
• Tickets trazadores convierten la mejora elegida en pasos verificables; un cambio amplio de interfaz requiere expand–contract.