🌱 Empieza aquí · Guarda-JSON

Esta semilla le pone a tu asistente un guardia para tus archivos JSON. Cada vez que termina de escribir o editar uno de esos archivos (los .json, muy comunes para configuraciones), revisa que la sintaxis quedó bien. Si se le coló un error —una coma de más, una llave sin cerrar, unas comillas mal puestas— le avisa en el momento para que lo arregle, en vez de que el error aparezca horas después rompiendo algo.

¿Qué es un JSON? Es un formato de texto muy usado para guardar configuraciones y datos (piensa en el "archivo de ajustes" de muchos programas). Tiene reglas estrictas: un solo signo fuera de lugar lo deja "roto", y cuando eso pasa el programa que lo usa deja de funcionar sin decir por qué. Este guardia caza ese error apenas ocurre.

Para instalarla

Abre esta carpeta con Claude Code o Cowork y dile a tu asistente:

"Siembra esta semilla 🌱"

Con eso basta de tu parte. Tu asistente hace todo lo técnico y al final te dice cómo comprobar que quedó funcionando. Vas a ver algunas palabras en inglés en la pantalla; ni caso, él te guía.

¿Otras formas de pedírselo? "instala esta semilla", "pon a funcionar el guardia de JSON", "haz el setup de esto". Te entiende igual.

Para el asistente que siembra 🤖

Instala este hook (gancho de automatización) del evento PostToolUse (justo DESPUÉS de que el asistente usa una herramienta de escritura). Se usa PostToolUse a propósito: el validador necesita el archivo ya escrito en disco para revisarlo. Sigue estos pasos y no inventes rutas: usa $HOME siempre.

Antes de empezar — compatibilidad: esta semilla funciona en Claude Code y Cowork, que comparten el mecanismo de hooks vía settings.json. No aplica a Codex, que usa otro modelo de configuración de hooks. Si estás sembrando en Codex, avísale a la persona que esta semilla no es compatible con su plataforma y no sigas con los pasos de abajo.

1. Copia el script del kernel (el corazón de la semilla)

Copia kernel/validate-json.sh a la carpeta de hooks del usuario y dale permiso de ejecución.

Claude Code / Cowork (macOS o Linux):

mkdir -p "$HOME/.claude/hooks"
cp kernel/validate-json.sh "$HOME/.claude/hooks/validate-json.sh"
chmod +x "$HOME/.claude/hooks/validate-json.sh"

Windows (Git Bash / WSL): misma ruta ~/.claude/hooks/. El script usa bash, jq y un validador de JSON (python3, o en su defecto python, o en su defecto jq). jq no viene por defecto en Windows: si no está, instálalo (por ejemplo con winget install jqlang.jq) o avísale al usuario. En macOS jq se instala con brew install jq; en Linux con el gestor de paquetes de la distribución. python3 normalmente ya está presente.

2. Registra el hook en `settings.json`

Abre $HOME/.claude/settings.json (créalo si no existe) y agrega esta entrada dentro de hooks.PostToolUse. Si ya hay hooks de PostToolUse, suma este objeto al arreglo existente en lugar de reemplazarlo. El matcher limita el hook a las herramientas de escritura, para que no corra de más:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "bash $HOME/.claude/hooks/validate-json.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

3. (Opcional) Ajusta el comportamiento con variables de entorno

De fábrica el guardia valida solo los .json, salta dependencias y archivos autogenerados, y le pasa el error al asistente para que lo corrija. Todo eso se puede cambiar (todas las variables son opcionales):

JSON_GUARD_EXTENSIONS — qué extensiones validar, separadas por espacio o coma (por defecto .json).
JSON_GUARD_SKIP — fragmentos de ruta a SALTAR, separados por coma (por defecto /node_modules/,/.git/,package-lock.json,yarn.lock,pnpm-lock.yaml, es decir dependencias y archivos que nadie edita a mano).
JSON_GUARD_SOFT — pon 1 para modo suave: cuando el JSON esté roto solo imprime una nota y termina normal (exit 0), sin pasarle el error al asistente como algo a corregir. Por defecto es 0 (le pasa el error para que lo arregle en el momento).

Nota: los archivos .jsonc (JSON con comentarios) se saltan siempre, porque los comentarios no son JSON estricto y un validador los marcaría como rotos sin estarlo.

4. Verificación post-siembra (obligatoria)

Comprueba que el guardia atrapa un JSON roto y deja pasar uno bueno.

a) Caso con JSON roto (espera un aviso 🔴 y EXIT=2):

printf '{bad,,}' > /tmp/roto.json
printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/roto.json"}}' \
  | bash "$HOME/.claude/hooks/validate-json.sh"; echo "EXIT=$?"

Salida esperada: un bloque 🔴 GUARDA-JSON … con el error de sintaxis y EXIT=2.

b) Caso con JSON bueno (espera SIN aviso y EXIT=0):

printf '{"ok":true}' > /tmp/bien.json
printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/bien.json"}}' \
  | bash "$HOME/.claude/hooks/validate-json.sh"; echo "EXIT=$?"

Salida esperada: sin avisos y EXIT=0.

c) Confirma que el hook quedó registrado en settings.json:

grep -q 'validate-json' "$HOME/.claude/settings.json" && echo 'REGISTRADO'

Salida esperada: REGISTRADO.

Cuando las tres pruebas den lo esperado, avísale al usuario que ya quedó y explícale en una línea qué gana con esto.

✅ ¿Cómo sé que funcionó?

De ahora en adelante, cuando tu asistente escriba o edite un archivo de configuración .json, si se le escapa un error de sintaxis lo va a notar en el acto y lo corregirá antes de decirte que terminó. Se acabaron las configuraciones que "no sabes por qué dejaron de jalar": el guardia las caza en el momento exacto en que se rompen, cuando el arreglo cuesta segundos.

No tienes que hacer nada especial en el día a día. Solo vas a notar que tus archivos JSON llegan bien formados. Eso es todo. 🌱