Parte 2: CLAUDE.md, Hooks y Skills — Tres Capas

Escribes "nunca usar doc.save() — siempre usar findByIdAndUpdate()" en tu CLAUDE.md. Claude lo sigue. Durante semanas, cada actualización de Mongoose en tu base de código usa operaciones atómicas. Empiezas a confiar.

Entonces un viernes por la tarde, lanzas un subagente para manejar una migración de datos compleja. El subagente está trabajando con una docena de archivos, manejando cambios de esquema y transformaciones de datos. Enterrado en el octavo archivo, usa silenciosamente doc.save(). Sin ceremonia. Sin explicación. Solo una llamada a método que introduce una condición de carrera que no encontrarás hasta el lunes por la mañana, después de que dos usuarios reporten datos corruptos.

La regla estaba ahí. Claude simplemente... no la siguió.

Esto no es una historia de fracaso. Es una historia de calibración. CLAUDE.md era la herramienta correcta para el 95% de los casos. Para ese último 5%, necesitabas algo más fuerte.

La Parte 1 mapeó todo el stack de extensiones. Ahora vamos a profundizar en las tres capas del "cerebro interno" — CLAUDE.md, hooks y skills — y la pregunta que realmente importa: ¿cuándo es cada una lo suficientemente confiable para apostar?

¿Qué es CLAUDE.md y qué va en él?

CLAUDE.md es un archivo markdown en la raíz de tu proyecto que Claude lee al inicio de cada sesión. Se carga automáticamente, no requiere invocación, y moldea cada acción que Claude toma. Piensa en él como la constitución de tu proyecto: corta, con opiniones, no negociable. Los mejores tienen menos de 80 líneas — todo lo demás va en reglas con alcance o skills.

La analogía a la que siempre vuelvo: es el documento de onboarding que le darías a un nuevo desarrollador el primer día. No la documentación completa — solo las cosas críticas que necesita para no romper nada.

Qué pertenece a CLAUDE.md

Los mejores archivos CLAUDE.md comparten un patrón: son cortos, estructurados y con opiniones. Responden cinco preguntas:

1. ¿Qué es este proyecto? — Stack tecnológico, arquitectura, patrones clave.
2. ¿Cuáles son las reglas estrictas? — Cosas que nunca deben pasar.
3. ¿Cómo ejecuto las cosas? — Comandos de build, test, deploy.
4. ¿Cuáles son las trampas? — Errores no obvios que cuestan tiempo.
5. ¿Dónde busco más? — Links a documentación detallada.

Aquí hay una versión recortada de un CLAUDE.md real de un monorepo NestJS en producción:

# CLAUDE.md
 
## What Is This
NestJS + MongoDB + Firebase Auth monorepo. Port 3100.
All workflows go through Makefile targets — run `make help`.
 
## Hard Rules
- NO .env files (secrets via Doppler)
- NO `doc.save()` — always `findByIdAndUpdate()`
- NO `console.log` — use NestJS Logger
- NO direct DB queries without workspaceId scoping
- Never push to main (always PR)
 
## Quick Commands
```bash
make backend           # Start all services
make dev-health        # Check service health
make api-get ENDPOINT=/api/v1/agents  # Test endpoints

Architecture

Gotchas

• After git pull: make rebuild-packages && make backend
• Use .id not ._id in JSON responses
• 404/401/500 = FAILURE (never rationalize away)

Detailed Docs

• Architecture
• Service Contracts
• Database Schemas

 
Nota lo que no está ahí: sin explicaciones en prosa, sin discusiones de casos límite, sin detalles de implementación. Es conciso, escaneable y cabe en una pantalla.
 
### El techo aproximado de instrucciones
 
Aquí está la parte que no está en la documentación: en mi experiencia, Claude puede seguir de manera confiable aproximadamente 150-200 instrucciones totales entre su system prompt y CLAUDE.md combinados. Esto no es un límite estricto de la API — es una observación práctica de ejecutar esto en cientos de sesiones. El system prompt ya usa aproximadamente 50 de esos espacios. Eso te deja aproximadamente 100-150 instrucciones efectivas antes de que el cumplimiento empiece a caer.
 
"Instrucciones" no significa líneas de texto. Significa reglas discretas que Claude necesita rastrear. "Usar findByIdAndUpdate()" es una instrucción. Un párrafo explicando por qué, con tres ejemplos y dos excepciones, sigue siendo aproximadamente una instrucción — pero es una difusa que compite por atención con todo lo demás.
 
Cuando tu CLAUDE.md crece más allá de este umbral, algo sutil sucede. Claude no lanza un error. No te advierte que está ignorando reglas. Simplemente empieza... a olvidar ocasionalmente algunas de ellas. No las mismas cada vez. No de forma predecible. Solo las suficientes para hacerte cuestionar si la regla existe.
 
He visto archivos CLAUDE.md de más de 800 líneas. Los equipos que los escribieron pensaban que estaban siendo exhaustivos. En la práctica, Claude seguía quizá el 60% de las instrucciones — y el equipo no tenía idea de cuál 40% estaba siendo descartado silenciosamente.
 
### Reglas con alcance: la vía de escape
 
La solución al exceso de CLAUDE.md no es "escribir menos reglas." Son las reglas con alcance. Estos son archivos markdown en `.claude/rules/` con frontmatter que le dice a Claude cuándo cargarlos:
 
```markdown
---
globs:
  - "services/**/*.ts"
  - "packages/nestjs-common/**"
---
 
# Backend Services Rules
 
## Module Structure
Every service has an AppModule that imports shared modules:
- InfrastructureModule.forRoot() — Config + MongoDB + Redis
- AuthModule.forRoot() — Global auth guard
- HealthModule.forRoot() — Health endpoints
 
## Mongoose Patterns
- workspaceId on every schema, always indexed
- Use virtualIdPlugin for .id transformation
- findOneAndUpdate, never doc.save()
- Always scope queries by workspaceId
 
## DTO Rules
- class-validator + @ApiProperty on every field
- @ValidateNested() + @Type(() => NestedDto) for nested objects
- Extend PaginationDto for list endpoints

Cuando Claude abre un archivo que coincide con services/**/*.ts, este archivo de reglas se carga automáticamente. Cuando está trabajando en un componente de frontend, no. Las reglas de backend no compiten por atención durante el trabajo de frontend, y viceversa.

Aquí hay un directorio real de reglas con alcance de un proyecto en producción:

.claude/rules/
  backend-services.md     # globs: services/**/*.ts
  api-contracts.md        # globs: *.controller.ts, *.dto.ts
  frontend-apps.md        # globs: apps/**/*.tsx
  sdk-cli.md              # globs: packages/platform-sdk/**
  inter-service.md        # globs: **/clients/**, **/main.ts
  deploy-infra.md         # globs: make/**, Dockerfile*, fly.toml
  lessons-backend.md      # globs: services/**
  lessons-frontend.md     # globs: apps/**
  lessons-integration.md  # globs: packages/**

Cada archivo puede tener 100-200 líneas sin inflar CLAUDE.md. Y como solo se cargan cuando son relevantes, puedes tener orientación profunda y específica para cada área de tu base de código sin alcanzar el techo de instrucciones.

Mejores prácticas para CLAUDE.md

Después de ejecutar esta configuración en un monorepo de 17 servicios durante meses, esto es lo que he aprendido:

Mantén CLAUDE.md por debajo de 80 líneas. En serio. Usa viñetas, tablas y bloques de código. Sin párrafos en prosa. Si necesitas explicar por qué existe una regla, enlaza a un documento — no lo expliques en línea.

Las reglas estrictas van primero. Claude le da más peso al contenido cerca del inicio de CLAUDE.md. Tus reglas no negociables deberían estar en las primeras 20 líneas.

Enlaza, no incluyas. En lugar de poner toda tu documentación de arquitectura en CLAUDE.md, agrega un enlace: Ver [Architecture](docs/architecture/). Claude puede leer archivos enlazados cuando necesita el detalle.

Las tablas son mejores que la prosa. Compara "El agent-service corre en el puerto 8002 y maneja rutas para agentes y herramientas, mientras que el kb-service corre en el puerto 8990..." versus una tabla. Claude parsea tablas más rápido y con más precisión.

Prueba tus reglas. Periódicamente pídele a Claude que haga algo que viola una de tus reglas de CLAUDE.md. Si lo hace sin dudar, la regla no está aterrizando. Reescríbela, muévela más arriba, o promuévela a un hook.

¿Cómo los Hooks te dan 100% de cumplimiento?

Los Hooks son scripts de shell que se activan en eventos específicos de Claude Code, y son el único mecanismo que opera al 100% de confiabilidad. Se ejecutan fuera del ciclo de decisión de Claude — Claude no los interpreta, no los pesa contra el contexto, no los omite cuando está ocupado. Si el script sale con código 2, la acción está bloqueada de forma absoluta. Si genera un JSON pidiendo confirmación, el usuario recibe un prompt. De cualquier manera, Claude no puede anularlo.

Esto hace a los hooks fundamentalmente diferentes de todo lo demás en el stack de extensiones. CLAUDE.md es una sugerencia. Los Skills son una guía. Los Hooks son física.

El ciclo de vida de eventos

Claude Code define varios eventos de hook:

El crítico es PreToolUse. Se activa antes de cada comando bash, cada edición de archivo, cada operación de escritura. Y puede bloquear la acción completamente.

Ejemplo real: bloquear comandos peligrosos

Aquí hay un hook de producción que impide que Claude ejecute operaciones destructivas sin permiso explícito:

#!/bin/bash
# .claude/hooks/directory-permissions.sh
# Blocks dangerous git and deploy commands
#
# Exit codes:
#   0 (no output)  = allow the action
#   0 + JSON stdout with permissionDecision:"ask" = force user prompt
#   2 = hard block (cannot proceed even with user approval)
 
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
 
# No command = not a bash tool call, allow
[ -z "$COMMAND" ] && exit 0
 
REASON=""
 
# Block direct pushes
if echo "$COMMAND" | grep -qE 'git\s+push'; then
  REASON="Use /git-push skill instead of direct git push"
fi
 
# Block destructive git operations
if echo "$COMMAND" | grep -qE 'git\s+(reset\s+--hard|stash|rebase|clean\s+-f)'; then
  REASON="Destructive git operation — requires explicit user approval"
fi
 
# Block direct deploys
if echo "$COMMAND" | grep -qE '(fly\s+deploy|vercel\s+(--prod|deploy))'; then
  REASON="Use make deploy targets instead of direct CLI"
fi
 
# If we found a reason, force the user to confirm
if [ -n "$REASON" ]; then
  echo "{\"permissionDecision\":\"ask\",\"reason\":\"$REASON\"}"
  exit 0
fi
 
exit 0

Cuando Claude intenta ejecutar git push origin main, este hook lo captura y fuerza un prompt de confirmación al usuario. Cada vez. Sin excepciones. Sin "pero el contexto sugería..." Sin deriva probabilística. Si quieres un bloqueo absoluto en lugar de un prompt, usa exit 2.

Ejemplo real: ejecutor de tests pre-commit

#!/bin/bash
# .claude/hooks/pre-commit-tests.sh
# Runs relevant tests before allowing commits
 
INPUT=$(cat)
 
# Detect which services were modified
CHANGED=$(git diff --cached --name-only)
 
FAILED=0
 
# If backend services changed, run type checks
if echo "$CHANGED" | grep -q "services/"; then
  echo "Running type check on backend services..." >&2
  npx tsc --noEmit --project tsconfig.json 2>/dev/null
  if [ $? -ne 0 ]; then
    echo "TypeScript type check failed" >&2
    FAILED=1
  fi
fi
 
# If SDK changed, build it
if echo "$CHANGED" | grep -q "packages/platform-sdk/"; then
  echo "Building SDK..." >&2
  make build-sdk 2>/dev/null
  if [ $? -ne 0 ]; then
    echo "SDK build failed" >&2
    FAILED=1
  fi
fi
 
# Exit 2 = hard block, commit cannot proceed
if [ $FAILED -ne 0 ]; then
  exit 2
fi
 
exit 0

Configurando Hooks

Los Hooks se definen en .claude/settings.json. Cada tipo de evento obtiene un array de matchers, y cada matcher tiene su propio array de hooks:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/directory-permissions.sh"
          }
        ]
      }
    ],
    "PreCommit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/pre-commit-tests.sh"
          }
        ]
      }
    ]
  }
}

El campo matcher controla qué herramienta activa el hook — "Bash" solo para comandos bash, "*" para todo. Los hooks deben ser rápidos. Un hook pre-commit que ejecute una suite completa de tests de 5 minutos dejará tu sesión paralizada. Mantén los hooks PreToolUse por debajo de 1 segundo. Mantén los hooks PreCommit por debajo de 30 segundos — ejecuta verificaciones específicas, no la suite completa.

La idea clave: "por favor no" vs. "no puedes"

Este es el modelo mental que cambió cómo pienso sobre la configuración de Claude:

CLAUDE.md dice "por favor no." Es una petición. Claude la pesa contra el contexto, instrucciones en competencia y la complejidad de la tarea actual. La mayoría de las veces cumple. A veces no.

Los Hooks dicen "no puedes." Son una pared. Claude no puede pesarlos contra nada. El script de shell se ejecuta, y si sale con código 2, la acción está bloqueada absolutamente. Si genera {"permissionDecision":"ask"}, el usuario recibe un prompt para confirmar. De cualquier manera, la opinión de Claude sobre el asunto es irrelevante.

Mapea tus reglas de acuerdo a esto. "Usar tokens de Tailwind en lugar de colores hex crudos" es un "por favor no" — ponlo en CLAUDE.md. "Nunca hacer push a main sin un PR" es un "no puedes" — aplícalo con un hook.

¿Qué son los Skills y cuándo deberías usarlos en lugar de reglas?

Los Skills son archivos markdown que le dan a Claude procedimientos paso a paso para tareas específicas. Se cargan bajo demanda cuando los invocas — /deploy, /commit, /review — y son procedimentales en lugar de declarativos. Las reglas dicen "nunca hacer X." Los Skills dicen "aquí está exactamente cómo hacer Y, paso a paso." Si alguna vez has deseado poder darle a Claude una receta en lugar de un reglamento, eso es lo que son los skills.

Cuando escribes /deploy en Claude Code, Claude lee el archivo del skill y sigue el procedimiento. Es la diferencia entre darle a alguien un manual de políticas y darle un checklist.

Anatomía de un Skill

Los Skills viven en .claude/commands/ (para comandos slash simples) o .claude/skills/<nombre>/SKILL.md (para definiciones más completas con allowed-tools). Aquí hay un skill de deploy real:

---
name: deploy
description: "Deploy services to staging or production with health checks and rollback"
allowed-tools: Bash(make:*), Bash(git:*), Bash(flyctl:*)
---
 
# Deploy Skill
 
## Usage
`/deploy <environment>` where environment is `staging` or `prod`
 
## Procedure
 
### Pre-deploy Checks
1. Run `make dev-health` to verify all local services are healthy
2. Run `git status` to ensure working tree is clean
3. Run `git log --oneline -5` to confirm the latest commits
4. Show the user what will be deployed and ASK for confirmation
 
### Deploy to Staging
1. Run `make deploy-staging`
2. Wait for deploy to complete (check output for errors)
3. Run `make dashboard-staging` to verify staging health
4. Report results to user
 
### Deploy to Production
1. REQUIRE explicit user confirmation with the phrase "yes, deploy to prod"
2. Run `make deploy-prod`
3. Run `make dashboard-prod` to verify production health
4. Post to #all-6fs Slack channel with deploy summary
5. Report results to user
 
### Rollback
If any health check fails after deploy:
1. Alert the user immediately
2. Show the failing health checks
3. Ask if they want to rollback
4. If yes: `fly releases -a chanl-platform` then deploy previous image

Nota la estructura: una descripción que le dice a Claude cuándo este skill es relevante, luego pasos explícitos. Sin ambigüedad sobre qué hacer o en qué orden.

Skills vs. CLAUDE.md: cuándo usar cuál

La distinción se reduce a una pregunta: ¿es esto un hecho o un procedimiento?

Si pones procedimientos en CLAUDE.md, lo inflas. Si pones hechos en skills, Claude solo los ve cuando el skill se invoca. Empareja el contenido con el contenedor.

Ejemplo real: un skill de flujo de commit

---
description: Review changes, write commit message, and commit
allowed-tools: Bash(git:*)
---
 
# Commit Skill
 
## Steps
 
1. **Diff Review**: Run `git diff --staged` and `git status` in parallel
2. **Analyze Changes**: Summarize what changed and why
3. **Recent History**: Run `git log --oneline -5` to match commit style
4. **Draft Message**: Write a conventional commit message:
   - `feat:` for new features
   - `fix:` for bug fixes
   - `refactor:` for code changes that don't add features or fix bugs
   - Focus on "why" not "what"
5. **Commit**: Create the commit using a HEREDOC for the message
6. **Verify**: Run `git status` to confirm clean state
 
## Rules
- NEVER amend existing commits unless explicitly asked
- NEVER use --no-verify
- If pre-commit hook fails, fix the issue and create a NEW commit
- Stage specific files, not `git add -A`

Este es un procedimiento que Claude sigue paso a paso. Poner estas 20 líneas de flujo de trabajo en CLAUDE.md desperdiciaría espacios de instrucciones en algo que Claude solo necesita durante los commits.

Ejemplo real: un skill de code review

---
name: review
description: "Review session work against the active plan"
allowed-tools: Bash(make:*), Bash(npx:*), Read
---
 
# Review Skill
 
## Procedure
 
1. **Load Context**: Read the active plan from the task list
2. **Check Each Task**: For every task in the plan:
   - Is the implementation complete?
   - Do the acceptance criteria pass?
   - Were tests written/updated?
3. **Run Verification**:
   - `make dev-health` if services were modified
   - Type check: `npx tsc --noEmit`
   - Run relevant use case tests
4. **Cross-Project Consistency**:
   - Do SDK types match API response shapes?
   - Do UI hooks use the correct SDK methods?
5. **Report**: Summary with verdict (COMPLETED / NEEDS WORK)

La naturaleza probabilística de los Skills

Los Skills tienen una brecha de confiabilidad que es importante entender. A diferencia de los hooks (100% de cumplimiento), los skills dependen de que Claude decida seguir el procedimiento tal como está escrito. La mayoría de las veces lo hace. Pero cuando la tarea es compleja, cuando hay prioridades en competencia, o cuando un subagente está ejecutando el skill en un contexto restringido, se pueden omitir pasos.

He visto a Claude omitir el paso 4 ("pedir confirmación") en un skill de deploy porque el contexto previo de la conversación implicaba fuertemente que el usuario quería hacer deploy. Claude estaba siendo servicial. También estaba siendo peligroso.

La mitigación: para pasos de alto riesgo, empareja el skill con un hook. El skill de deploy dice "pedir confirmación." El hook PreToolUse bloquea fly deploy si no ha visto un patrón de confirmación en la conversación reciente. Cinturón y tirantes.

¿Qué tan confiable es cada capa, realmente?

Diferentes mecanismos de cumplimiento tienen diferentes niveles de confiabilidad, y necesitas diseñar en torno a eso. Nadie te dice esto de entrada, pero es lo más importante que debes entender sobre la configuración de Claude.

Esta no es una medición precisa — está calibrada a partir del uso real en cientos de sesiones. El patrón es consistente: instrucciones más cortas, más específicas y más prominentemente ubicadas se siguen con mayor confiabilidad.

Mapeando reglas a la capa correcta

Usa este framework de decisión:

¿Reglas de seguridad? Hooks. Si violar la regla podría causar pérdida de datos, brechas de seguridad o incidentes en producción, necesita cumplimiento del 100%. Ponle un hook. "Nunca hacer push a main" es un hook. "Nunca hacer deploy sin confirmación" es un hook. "Nunca ejecutar DROP TABLE" es absolutamente un hook.

¿Patrones y convenciones de código? CLAUDE.md o reglas con alcance. "Usar findByIdAndUpdate" es una regla de CLAUDE.md. Está bien al ~85% de confiabilidad porque el 15% de falla es algo que se captura en code review, no un incidente de producción. "Cada campo de DTO necesita @ApiProperty" va en una regla con alcance para archivos *.dto.ts. (Para gestionar los prompts e instrucciones que usan tus agentes en producción, el mismo principio aplica — las restricciones críticas se aplican, las convenciones se sugieren.)

¿Flujos de trabajo complejos de múltiples pasos? Skills. Procedimientos de deploy, flujos de commit, checklists de code review — cualquier cosa con más de 3 pasos secuenciales es un skill. Claude sigue procedimientos mejor cuando están estructurados como pasos numerados explícitos en lugar de incrustados en un muro de reglas.

¿Preferencias simples? CLAUDE.md. "Usar tabular-nums en números" y "máximo 3 pesos de fuente" están bien como reglas de CLAUDE.md. Si Claude ocasionalmente usa font-bold en lugar de font-semibold, el mundo no se acaba.

Lo que nunca deberías hacer es poner una regla de seguridad solo en CLAUDE.md y confiar en ella. Si "nunca exponer API keys en logs" es solo una instrucción de CLAUDE.md, estás a una sesión compleja de debugging de que un subagente imprima credenciales en la terminal. Ponle un hook.

¿Cómo se ve un directorio .claude/ de producción?

Aquí está la estructura real de directorios de un monorepo NestJS de 17 servicios que ha estado ejecutando esta configuración durante meses. El tuyo se verá diferente, pero la forma es la misma: settings para hooks, commands para skills, rules para orientación específica por contexto.

.claude/
  settings.json          # Hooks, permissions, preferences
  commands/              # Slash-command skills (/deploy, /commit, /review)
    deploy.md
    commit.md
    review.md
    plan.md
    board.md
  rules/                 # Scoped rules (auto-loaded by file pattern)
    backend-services.md  # globs: services/**/*.ts
    api-contracts.md     # globs: *.controller.ts, *.dto.ts
    frontend-apps.md     # globs: apps/**/*.tsx
    sdk-cli.md           # globs: packages/platform-sdk/**
    deploy-infra.md      # globs: make/**, Dockerfile*
    lessons-backend.md   # globs: services/**
    lessons-frontend.md  # globs: apps/**
  hooks/                 # Shell scripts for deterministic enforcement
    directory-permissions.sh
    pre-commit-tests.sh
CLAUDE.md                # Top-level constitution (root of repo)

La jerarquía: usuario, proyecto, workspace

La configuración se carga en capas, con cada nivel sobreescribiendo el anterior:

Nivel de usuario (~/.claude/CLAUDE.md, ~/.claude/settings.json): Preferencias personales que aplican en todos lados. Tu estilo preferido de commit, hooks globales, herramientas que siempre quieres disponibles. Esto no se commitea al control de versiones.

Nivel de proyecto (.claude/ en la raíz del repo): Convenciones del equipo commiteadas a git. Cuando alguien clona el repo, obtiene las mismas reglas, skills y hooks. Aquí es donde vive el 90% de tu configuración.

CLAUDE.md: Puede existir en ambos niveles. El CLAUDE.md del proyecto contiene reglas específicas del repo. Un CLAUDE.md a nivel de usuario podría contener "siempre usar atajos de vim" o "preferir explicaciones concisas."

La decisión de diseño clave: todo en .claude/ se commitea. Cada miembro del equipo ejecuta con las mismas barreras de protección. Las preferencias personales se quedan en ~/.claude/. Si alguien del equipo le gusta usar emoji en mensajes de commit, eso es su ~/.claude/CLAUDE.md — no el del proyecto.

settings.json: el panorama completo

Aquí hay un settings.json realista de producción:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/directory-permissions.sh"
          }
        ]
      }
    ],
    "PreCommit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/pre-commit-tests.sh"
          }
        ]
      }
    ]
  },
  "permissions": {
    "allow": [
      "Bash(make *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "Bash(npm run *)",
      "Bash(npx tsc *)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(curl * | bash)"
    ]
  }
}

El bloque permissions es una capa de defensa secundaria. allow lista los comandos que Claude puede ejecutar sin preguntar. deny bloquea comandos directamente. Pero hay una sutileza: los hooks se ejecutan en un punto diferente del pipeline que los permisos. Si necesitas cumplimiento real, los hooks son la respuesta. Los permisos son una capa de conveniencia para reducir prompts de confirmación, no un límite de seguridad.

¿Cuáles son los errores de configuración más comunes?

Todos estos me costaron tiempo real de debugging. Cada uno de ellos se sentía obvio en retrospectiva.

Trampa 1: CLAUDE.md de más de 500 líneas

Una vez tuve un CLAUDE.md de más de 500 líneas, cubriendo cada convención, cada patrón, cada trampa para un monorepo de 17 servicios. Se sentía completo. En la práctica, Claude seguía alrededor del 60% de las reglas. El otro 40% variaba aleatoriamente entre sesiones.

La solución: extraje todo en reglas con alcance y skills. CLAUDE.md bajó a 70 líneas. Las reglas estrictas fueron al inicio. Todo lo demás se movió a .claude/rules/ con los globs apropiados. El cumplimiento de reglas saltó del 60% a aproximadamente el 90%.

La lección: CLAUDE.md no es una wiki. Es una constitución. Mantenlo lo suficientemente corto para que cada línea importe.

Trampa 2: Skills sin descripciones claras

Mis primeros skills tenían descripciones como "Ayudante de deploy" y "Herramienta de commit." Claude raramente los invocaba. Cuando cambié las descripciones a "Deploy services to staging or production with health checks and rollback" y "Review staged changes, write conventional commit message, verify clean state," las tasas de invocación se duplicaron.

Claude usa la descripción para decidir relevancia. Descripciones vagas significan que el skill compite pobremente contra el razonamiento integrado de Claude. Sé específico sobre qué hace el skill y cuándo es útil.

Trampa 3: Hooks que son demasiado lentos

Escribí un hook PreToolUse que ejecutaba un escaneo de seguridad completo en cada comando bash. Tardaba 3-4 segundos por comando. En una sesión donde Claude ejecuta más de 50 comandos, eso agregaba 2-3 minutos de tiempo muerto. El flujo de trabajo se sentía lento y sin respuesta.

La regla: los hooks PreToolUse deben terminar en menos de 1 segundo. Si necesitas una verificación más larga, muévela a PreCommit (que se ejecuta con menos frecuencia) o ejecútala asíncronamente y reporta resultados.

Trampa 4: reglas sobre herramientas en CLAUDE.md

Tenía reglas en CLAUDE.md sobre cómo usar herramientas y MCP servers específicos. "Al usar la herramienta de deploy, siempre verificar staging primero." Claude seguía esto quizá el 60% de las veces porque la instrucción estaba desconectada del contexto donde importaba.

La solución: instrucciones específicas de herramientas van en skills, no en CLAUDE.md. El skill /deploy incluye "verificar staging primero" como paso 1. Cuando Claude está ejecutando el skill de deploy, esa instrucción está justo frente a él, no compitiendo con 100 otras reglas.

Trampa 5: no usar reglas con alcance para orientación específica por contexto

Al principio, tenía reglas de CSS de frontend en el CLAUDE.md principal: "usar tokens semánticos, no colores crudos" y "spacing en grid de 8pt." Estas reglas se cargaban durante el trabajo de backend también, desperdiciando espacios de instrucciones. Peor aún, las reglas específicas de backend a veces se depriorizaban por el ruido del frontend.

Las reglas con alcance resolvieron esto completamente. Las reglas de frontend solo se cargan al tocar archivos .tsx. Las reglas de backend solo se cargan al tocar archivos .ts de servicios. Cada contexto obtiene atención completa a sus reglas específicas sin contaminación cruzada.

Trampa 6: confiar en CLAUDE.md para la seguridad de subagentes

La trampa más peligrosa: asumir que los subagentes heredan CLAUDE.md con la misma fidelidad que el hilo principal. No lo hacen. Los subagentes operan en contextos restringidos con sus propios presupuestos de instrucciones. Una regla que se sigue de manera confiable en el hilo principal puede ser descartada por un subagente trabajando bajo presión de contexto pesada.

Para cualquier cosa crítica de seguridad que los subagentes puedan encontrar, usa hooks. El hook se ejecuta sin importar qué hilo desencadene la acción.

Armando todo

Las tres capas se complementan porque son buenas en cosas diferentes. CLAUDE.md maneja la amplitud, los hooks manejan el cumplimiento y los skills manejan la complejidad procedimental. Aquí está el panorama completo:

El principio de diseño: confía en cada capa para lo que es buena, y compensa lo que no es.

CLAUDE.md maneja la amplitud — las 100 convenciones en las que tu equipo está de acuerdo. La mayoría se siguen. Las que no, se capturan en code review por humanos que también conocen las convenciones.

Los Hooks manejan la profundidad en la ruta crítica — las 5-10 reglas donde una violación significa daño real. Nunca fallan.

Los Skills manejan la complejidad — los flujos de trabajo de múltiples pasos que son demasiado procedimentales para reglas y demasiado importantes para dejar al razonamiento improvisado.

Juntos, te dan un sistema donde los agentes de IA trabajan dentro de barreras de protección — lo suficientemente confiable para producción, lo suficientemente flexible para el trabajo diario, lo suficientemente transparente para depurar cuando algo sale mal.

Si estás empezando: escribe un CLAUDE.md de 50 líneas hoy. Agrega un hook que bloquee tu operación más peligrosa. Crea un skill para tu flujo de trabajo más común. Esa base te servirá mejor que un CLAUDE.md de 500 líneas jamás podría.

A continuación: la Parte 3 cruza el límite del cerebro interno de Claude a sus capacidades externas — MCP servers, connectors y Claude Apps. Y la Parte 4 compone todas estas capas en un recorrido real de producción.

Esta es la Parte 2 de una serie de cuatro partes. Empieza con la Parte 1: El Modelo Mental si aún no la has leído. Para inmersiones profundas relacionadas, ve Construye Tu Propio Sistema de Herramientas para Agentes de IA y Sistemas Multi-Agente: Orquestación desde Cero.

Aprende IA Agéntica

Una lección por semana: técnicas prácticas para construir, probar y lanzar agentes IA. Desde ingeniería de prompts hasta monitoreo en producción. Aprende haciendo.

Subscribe

500+ ingenieros suscritos