🌱 Empieza aquí · Guardián de esquema de tu base de conocimiento

¿Tienes una carpeta donde guardas tu conocimiento —notas, wiki, bóveda, "segundo cerebro"— y quieres que cada archivo nazca bien puesto, con su título, su estado y su fecha en orden? Esta semilla instala un vigilante que revisa exactamente eso, pero solo dentro de esa carpeta. Si un archivo nuevo intenta colarse sin la metadata correcta, te avisa al momento (o, si lo pones estricto, ni lo deja crearse).

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 solo te pedirá un dato: cuál es la carpeta de tu base de conocimiento. 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 esquema", "haz el setup de esto". Te entiende igual.

Para el asistente que siembra 🤖

Instala este hook (gancho de automatización) del evento PreToolUse (antes de que la herramienta escriba). Vigila las escrituras de archivos .md y valida su frontmatter contra un esquema acotado a una sola carpeta. Sigue estos pasos y no inventes rutas: usa $HOME siempre.

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

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

Windows (Git Bash / WSL): misma ruta ~/.claude/hooks/. El script usa bash, jq y awk. jq no siempre viene preinstalado: si el usuario no lo tiene, indícale instalarlo (brew install jq en macOS, sudo apt install jq en Linux/WSL, o el binario de jq para Git Bash en Windows).

2. Pregunta al usuario cuál es su base de conocimiento

Este es el único dato que necesitas de él. Es la carpeta cuyos .md quieres vigilar (su wiki, sus notas, su bóveda). Guárdala; la usarás en el paso 3 como GUARD_SCOPE. Ejemplo de valor: $HOME/base-conocimiento o la ruta real que te diga.

Sin este dato, el hook queda en modo seguro y no valida nada (para no molestar por accidente en archivos que no son parte de su base de conocimiento).

3. 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 hooks existente en lugar de reemplazarlo. Sustituye la ruta de GUARD_SCOPE por la carpeta real que te dio el usuario en el paso 2:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "GUARD_SCOPE=\"$HOME/base-conocimiento\" GUARD_MODE=warn bash $HOME/.claude/hooks/guardrail-esquema.sh",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

Empieza siempre en GUARD_MODE=warn (avisa pero deja pasar). Cuando el usuario confíe en su esquema, cámbialo a GUARD_MODE=block para que rechace archivos mal formados.

4. (Opcional) Ajusta el esquema a ESTE usuario

El esquema por defecto pide title status created updated, con status limitado a draft,active,archived y las fechas en formato ISO. Si el usuario ocupa otros campos o valores, ajusta estas variables en el mismo command del paso 3 (todas opcionales):

GUARD_REQUIRED_FIELDS — campos obligatorios, separados por espacios. Ej. "title status created updated owner".
GUARD_DATE_FIELDS — campos que deben ir en fecha ISO. Ej. "created updated".
GUARD_ENUMS — campos de valor cerrado, formato campo:valor1,valor2, varios separados por espacios. Ej. "status:draft,active,archived tipo:nota,proyecto,decision".
GUARD_EXEMPT — archivos exentos por nombre (índices maestros, etc.). Ej. "INDEX.md README.md".
GUARD_LOG_FILE — ruta de un log opcional de lo validado.

5. Verificación post-siembra (obligatoria)

Comprueba que el guardián se dispara. Simula la creación de un .md mal formado (sin fecha) dentro de la carpeta vigilada, en modo block. Este comando arma la entrada del hook con jq (que ya es requisito del script), así el JSON siempre queda bien formado:

jq -n --arg fp "$HOME/base-conocimiento/prueba.md" \
  --arg c "$(printf '%s\n' '---' 'title: X' 'status: active' 'created: 2026-07-05' '---')" \
  '{tool_name:"Write",tool_input:{file_path:$fp,content:$c}}' \
  | GUARD_SCOPE="$HOME/base-conocimiento" GUARD_MODE=block bash "$HOME/.claude/hooks/guardrail-esquema.sh"; echo "EXIT=$?"

Salida esperada: un JSON con "permissionDecision": "deny" mencionando que falta el campo updated, y EXIT=0. (El rechazo viaja en el JSON, no en el código de salida.) Sustituye $HOME/base-conocimiento por la carpeta real si es otra.

Ahora el caso feliz (un .md bien formado, con todos los campos → deja pasar):

jq -n --arg fp "$HOME/base-conocimiento/prueba.md" \
  --arg c "$(printf '%s\n' '---' 'title: X' 'status: active' 'created: 2026-07-05' 'updated: 2026-07-05' '---')" \
  '{tool_name:"Write",tool_input:{file_path:$fp,content:$c}}' \
  | GUARD_SCOPE="$HOME/base-conocimiento" GUARD_MODE=block bash "$HOME/.claude/hooks/guardrail-esquema.sh"; echo "EXIT=$?"

Salida esperada: sin JSON de rechazo y EXIT=0.

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

grep -q 'guardrail-esquema' "$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, cada archivo nuevo que nazca dentro de tu base de conocimiento tendrá que traer su metadata bien puesta: su título, su estado válido y sus fechas en formato correcto. Si algo se sale del molde, lo sabrás al instante —y si lo dejaste en modo estricto, el archivo mal formado ni siquiera llega a crearse—.

No tienes que revisar nada a mano. Tu base de conocimiento se mantiene consistente sola, para que tus búsquedas, índices y filtros siempre cuadren. Eso es todo. 🌱