El plugin de seguridad de Claude Code no conoce las reglas de tu repo. Enséñaselas.

TL;DR Crea .claude/claude-security-guidance.md y escribe en lenguaje natural las reglas de seguridad de tu repo: "no registres customer_id en logs", "toda ruta /admin llama a require_role". El plugin security-guidance lo carga como contexto en sus revisiones con modelo (la de fin de turno y la de commit), y empieza a marcar violaciones que el checklist genérico no tenía forma de conocer. Ojo: es guía aditiva, no un muro. No bloquea nada.

El plugin security-guidance revisa el código de Claude en tres capas. Dos usan el modelo (una al final de cada turno, otra en cada commit) y comparan tu diff contra un checklist de vulnerabilidades de fábrica: inyección, deserialización insegura, SSRF, criptografía débil. Ese checklist es genérico. No sabe nada de tu repo: ni que ahí nunca se loguea el customer_id, ni que toda ruta de admin pasa por un guard. Eso se lo escribes tú, en .claude/claude-security-guidance.md.

El archivo: tu modelo de amenazas en lenguaje natural

No es configuración con schema. Es texto plano, reglas que le dictarías a un revisor humano nuevo en el equipo:

# Guía de seguridad de este repo  (.claude/claude-security-guidance.md)

- No registres `customer_id` ni `account_number` en logs de nivel INFO o superior.
- Toda ruta bajo `/admin` debe llamar a `require_role("admin")` antes de tocar la base de datos.
- Compara tokens con `crypto.timingSafeEqual`, nunca con `===`.

Las revisiones con modelo cargan esto junto al checklist de fábrica. A partir de ahí, si Claude escribe un log.info(customer_id), la revisión de fin de turno lo marca como hallazgo y Claude lo corrige en la misma sesión, aunque "no loguear customer_id" no sea una vulnerabilidad que ningún checklist genérico pudiera adivinar.

Qué capa lo lee (y cuál no)

El plugin tiene tres capas. Esta guía la leen solo las dos que usan el modelo:

La capa por edición es un match de texto sin modelo, y se extiende con otro archivo, .claude/security-patterns.yaml (su propio tip). Esta guía en Markdown es la de criterio: la lee el modelo, no un regex.

Dónde lo pones

Se busca en tres sitios, y se cargan y concatenan todos los que existan (usuario, luego proyecto, luego local), con un tope combinado de 8 KB:

El de proyecto es el importante: lo commiteas y todo el equipo hereda el mismo modelo de amenazas. El revisor de cada uno pasa a conocer las reglas de la casa sin que nadie las repita.

Cuidado: es guía, no un muro

Esto es lo que la documentación deja claro y conviene no olvidar:

• Es aditiva y no bloquea. Suma contexto al checklist, no lo sustituye. Ninguna capa corta la edición ni el commit: el hallazgo le llega a Claude como instrucción para arreglarlo, y el modelo puede fallar.
• No sirve para silenciar. Una regla que diga "ignora los SSRF" no suprime esos hallazgos. La guía solo suma, nunca resta.
• Si necesitas bloqueo duro, esto no es el sitio: usa un hook que corte la edición, o un check en CI.
• Las revisiones con modelo gastan tokens (Opus 4.7 por defecto). La capa por edición, la de security-patterns.yaml, es la gratis.

Referencia

Documentación oficial: Add guidance for the model-backed reviews

Requisitos

• El plugin security-guidance instalado (CLI v2.1.144+).
• Un repositorio git (las revisiones de turno y commit diffean contra git).
• Autenticación de Anthropic activa: sin ella, las capas con modelo se saltan y solo corre el match por edición.