🌱 Empieza aquí · Guardián anti-cáncer de documentación

¿Alguna vez abriste una carpeta llena de archivos .md y no tenías idea de qué era cada uno? Sin título claro, sin saber si estaba vigente o viejo, sin fecha. Eso pasa cuando los documentos nacen sin metadata (una etiqueta al inicio que dice qué es, en qué estado está y de cuándo es). Con el tiempo esa carpeta se vuelve un basurero imposible de ordenar: a eso le decimos el "cáncer" de la documentación.

Esta semilla le pone un guardián a tu asistente. Cada vez que él va a crear un documento nuevo, revisa que traiga su etiqueta bien puesta. Si no, avisa (o lo bloquea, tú eliges). Así cada archivo nace ordenado y nunca más tienes carpetas que dan miedo.

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 guardián de documentación", "haz el setup de esto". Te entiende igual.

Para el asistente que siembra 🤖

Instala este hook (gancho de automatización) del evento PreToolUse con matcher Write. Se dispara justo antes de que escribas un archivo, valida el frontmatter de los .md nuevos, y en modo block puede rechazar la escritura. Sigue estos pasos y no inventes rutas: usa $HOME siempre. Este script necesita jq (procesador de JSON) instalado; si no está, avísale al usuario que lo instale (brew install jq en macOS, apt install jq en Linux).

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

Copia kernel/anti-cancer-guardrail.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/anti-cancer-guardrail.sh "$HOME/.claude/hooks/anti-cancer-guardrail.sh"
chmod +x "$HOME/.claude/hooks/anti-cancer-guardrail.sh"

Windows (Git Bash / WSL): misma ruta ~/.claude/hooks/. El script usa bash, jq, awk y grep; en Windows nativo sin bash no corre, avisa al usuario que necesita Git Bash o WSL.

2. Registra el hook en `settings.json`

Abre $HOME/.claude/settings.json (créalo si no existe) y agrega esta entrada dentro de hooks.PreToolUse. Si ya hay hooks de PreToolUse, suma este objeto al arreglo existente en lugar de reemplazarlo:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "bash $HOME/.claude/hooks/anti-cancer-guardrail.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

3. Elige el modo y ajusta la regla a ESTE sistema

Empieza siempre en modo warn (el default): así el guardián solo avisa y nunca bloquea trabajo mientras el usuario se acostumbra. Cuando ya confíe en la regla, puede subirlo a block exportando HOOK_MODE=block antes de que corra el hook, o poniendo ese valor por defecto en la parte superior del script.

Los valores por defecto son deliberadamente genéricos: exige los campos title, status y created, valida que created sea fecha ISO, y no valida ningún catálogo de estados (para no dar falsas alarmas). Toda la regla es configurable por variables de entorno; estas son todas las que entiende el script:

HOOK_MODE — warn (avisa, deja pasar · por defecto) o block (rechaza la creación).
GUARDRAIL_REQUIRED_FIELDS — campos de frontmatter obligatorios, separados por espacio (por defecto title status created).
GUARDRAIL_DATE_FIELD — qué campo debe ser fecha ISO YYYY-MM-DD (por defecto created; ponlo vacío para no validar fecha).
GUARDRAIL_STATUS_FIELD — nombre del campo de estado (por defecto status).
GUARDRAIL_STATUS_VALUES — lista de valores permitidos para el estado, separados por espacio (por defecto vacío = no validar; ej. borrador activo publicado archivado).
GUARDRAIL_EXEMPT_FILES — nombres de archivo exentos de la regla (por defecto README.md CHANGELOG.md LICENSE.md CONTRIBUTING.md INDEX.md CLAUDE.md AGENTS.md).
GUARDRAIL_EXEMPT_DIRS — subcadenas de ruta que se saltan (por defecto /node_modules/ /.git/ /.claude/).
GUARDRAIL_LOG_FILE — dónde se anota la bitácora del guardián.

Consejo: si el usuario ya tiene un catálogo de estados propio (por ejemplo borrador, activo, archivado), llena GUARDRAIL_STATUS_VALUES con esos valores para que el guardián también atrape estados escritos con typo.

4. Verificación post-siembra (obligatoria)

Corre esta prueba para confirmar que el guardián se dispara de verdad. Simula el evento de crear un .md sin frontmatter, en modo block:

printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/doc-prueba.md","content":"# Hola sin metadata"}}' \
  | HOOK_MODE=block bash "$HOME/.claude/hooks/anti-cancer-guardrail.sh"; echo "EXIT=$?"

Nota: usamos printf '%s' en lugar de echo a propósito. En algunas shells echo convierte \n en saltos de línea reales y eso rompería el JSON de prueba.

Salida esperada: una línea JSON que contiene "permissionDecision":"deny" y una razón que menciona el frontmatter faltante, terminada en EXIT=0 (en modo block el hook devuelve la decisión por stdout y sale con 0).

Ahora el caso feliz: un .md con frontmatter completo debe pasar sin ruido.

printf '%s' '{"tool_name":"Write","tool_input":{"file_path":"/tmp/doc-prueba.md","content":"---\ntitle: Prueba\nstatus: activo\ncreated: 2026-07-05\n---\n\n# Contenido"}}' \
  | HOOK_MODE=block bash "$HOME/.claude/hooks/anti-cancer-guardrail.sh"; echo "EXIT=$?"

Salida esperada: sin ninguna línea de decisión y EXIT=0 (pasó limpio).

Por último, confirma que el hook quedó registrado en settings.json:

grep -q 'anti-cancer-guardrail' "$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ó?

A partir de ahora, cada documento nuevo que cree tu asistente va a nacer con su etiqueta bien puesta: título, estado y fecha. Si por descuido intenta crear uno "pelón", el guardián le recuerda (o le impide) hacerlo. Con el tiempo lo vas a agradecer: abres cualquier carpeta y sabes de un vistazo qué es cada archivo, cuál está vigente y de cuándo es.

No tienes que hacer nada especial en el día a día. Solo vas a notar que tus carpetas de documentos dejan de convertirse en basureros. Eso es todo. 🌱