¿Qué hace sync-project-docs?
Audita y actualiza los archivos de contexto a nivel de proyecto de Claude Code. Actúa de forma autónoma para CLAUDE.md, skills y memoria; sugiere cambios en la configuración, ya que requieren autorización explícita del usuario.
Fase 1 — Orientar
Si el proyecto usa git:
git log --oneline -20
git status --short
Luego git diff HEAD~5 -- <archivos clave abajo> para ver cambios recientes en la infraestructura.
Si no hay repo git, lee la estructura del directorio y los archivos clave directamente.
Identifica cuáles de estos existen:
| Buscar | Ejemplos |
|---|---|
| Configuración de paquetes/dependencias | package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml, requirements.txt, Gemfile |
| Comandos | Makefile, justfile, scripts/, scripts de package.json, taskfile.yml |
| Infraestructura | docker-compose.yml, fly.toml, render.yaml, Procfile, vercel.json, k8s/ |
| Configuración de la aplicación | config.*, settings.*, config/, application.yml |
| Plantilla de entorno | .env.example, .env.template, .env.sample |
Objetivo: saber qué trabajo se ha realizado, qué está en curso y qué archivos clave han cambiado.
Fase 2 — Auditar y actualizar CLAUDE.md
Verifica todos los archivos de instrucciones a nivel de proyecto:
ls CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md .claude/rules/ 2>/dev/null
Si no existe CLAUDE.md: invoca la habilidad init en sub-skills/init/SKILL.md, luego continúa.
Si existe CLAUDE.md, léelo y verifica cada sección contra las fuentes de la Fase 1:
Comandos — compara con la fuente real de comandos. Corrige comandos modificados, añade los nuevos útiles, elimina los eliminados.
Arquitectura/estructura — compara los módulos y archivos clave descritos con lo que existe en disco. Añade nuevas incorporaciones; elimina elementos eliminados o renombrados.
Configuración/variables de entorno — compara con los archivos de configuración reales. Añade nuevas configuraciones relevantes en tiempo de ejecución; elimina o corrige las obsoletas.
Restricciones y dificultades — verifica si alguna restricción documentada ha sido resuelta por trabajo reciente.
Plantilla de entorno: verifica que liste todas las variables que requiere la configuración. Las variables faltantes aquí rompen configuraciones nuevas.
Referencias @import: busca líneas @ruta/al/archivo y verifica que cada archivo importado aún exista. Una importación faltante rompe silenciosamente la carga del contexto.
Tamaño: si el archivo supera las 200 líneas, márcalo: más allá de eso, la adherencia disminuye y el costo del contexto aumenta. Sugiere mover los detalles a archivos de temas en .claude/rules/.
.claude/rules/: si este directorio existe, verifica si algún archivo de reglas con ámbito de ruta hace referencia a comandos, nombres de módulos o rutas de archivos que ya no coinciden con la base de código actual. Corrige o marca los obsoletos.
CLAUDE.local.md: si existe, aplícale la misma revisión que a CLAUDE.md: es el suplemento personal ignorado por git y también puede quedar obsoleto.
Sé quirúrgico: actualiza lo que está obsoleto, deja el contenido preciso intacto. Será leído por una futura sesión de Claude.
Fase 3 — Auditar las skills del proyecto
ls .claude/skills/ 2>/dev/null
Lee cada skill. Dos categorías:
Skills acopladas a la infraestructura (ejecutar, desplegar, migrar, CI, integración) hacen referencia a cosas concretas: comandos, servicios, puertos, variables de entorno, rutas de archivos. Verifica cada una contra la Fase 1:
- ¿Siguen existiendo los comandos referenciados?
- ¿Los nombres de servicio, puertos y URLs siguen coincidiendo?
- ¿Las variables de entorno siguen existiendo en la configuración?
- ¿Las rutas de archivos y los nombres de módulos siguen siendo válidos?
Corrige pequeñas divergencias directamente. Para un retrabajo sustancial de una skill de ejecución/inicio (nueva secuencia de inicio, cambios importantes de servicio), pregunta primero:
"La skill de ejecución parece significativamente desactualizada. ¿Regenerar desde cero con
/run-skill-generator(puede perder dificultades personalizadas) o reescribir las secciones obsoletas manualmente?"
Si no existe una skill de ejecución y el inicio no es trivial: sugiere /run-skill-generator si está disponible, o /run como alternativa.
Skills de proceso/flujo de trabajo (plantillas de PR, estilo de confirmaciones): solo verifica si el registro de git sugiere que el proceso descrito cambió; de lo contrario, déjalas intactas.
Fase 4 — Memoria
La ruta de la memoria se deriva de la raíz del repo git (o pwd fuera de un repo):
REPO=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
echo "$HOME/.claude/projects/$(echo "$REPO" | sed 's|/|-|g')/memory/"
Si la memoria existe: invoca consolidate-memory.
Si no existe ninguna: pregunta antes de crear algo:
"Aún no existe memoria del proyecto. La memoria automática ya está activa, por lo que Claude la construirá con el tiempo, pero ¿quieres que la inicialice ahora con datos clave de esta base de código para que tu próxima sesión comience orientada de inmediato?"
Si la respuesta es sí: inicializa con datos no obvios que una sesión futura perdería tiempo en deducir:
- Restricciones sorprendentes (modelos de concurrencia, versiones fijas, valores predeterminados inesperados)
- Trabajo en curso actual y por qué
- Decisiones no obvias incorporadas en el código
Crea MEMORY.md como un índice conciso de una línea por entrada. Las notas detalladas van en archivos de temas separados (por ejemplo, architecture.md, constraints.md) — MEMORY.md se mantiene por debajo de 200 líneas para que quepa en la ventana de contexto de la sesión.
Fase 5 — Configuración
Verifica .claude/settings.json en busca de hooks obsoletos que hagan referencia a scripts o comandos que ya no existen.
Identifica comandos de solo lectura que aparecen constantemente (ejecutores de pruebas, linters, comprobaciones de estado, git log, git diff) y que sería seguro permitir sin preguntar.
No escribas en settings.json — preséntalos como sugerencias. Señala:
update-config: para agregar permisos, variables de entorno o corregir hooksfewer-permission-prompts: para descubrir permisos del historial de transcripciones real
Fase 6 — Compactar
Todos los hallazgos están ahora en disco. Antes de finalizar, recuerda al usuario que debe manejar el contexto ejecutando el comando /compact para empezar desde un estado limpio.
Resumen
Imprime un resumen de los cambios:
## Sincronización del proyecto completada
**CLAUDE.md**: <qué cambió, o "sin cambios necesarios">
**Skills**: <qué se actualizó, o "precisas">
**Memoria**: <consolidada / inicializada / "sin cambios">
**Sugerencias de configuración**: <permisos sugeridos, o "nada que añadir">
**Estado de git**: <archivos sin confirmar + trabajo en curso, una frase>
Ejecuta `git diff` para revisar los cambios en los archivos.