← Volver al Blog

Los 7 archivos que Claude Code lee antes de escribir código — checklist de context engineering en 5 minutos

/ 12 min de lectura / claude-code · context-engineering · ai-agent · checklist

Cuando ejecutas claude en la terminal, hay 7 archivos que se leen antes de que el agente escriba una sola línea. Si no los conoces, tu agente está trabajando con contexto que tú no elegiste. Este checklist toma 5 minutos y sirve para saber exactamente qué está leyendo Claude Code y qué no debería estar leyendo.

Antes de entrar en materia, una aclaración rápida: hay otro artículo mío que habla de “arquitectura de 7 archivos” para dar memoria persistente a un agente. Ese va de dónde guardar recuerdos entre sesiones. Este va de qué carga Claude Code al arrancar. Son 7 archivos distintos con el mismo número por coincidencia. No los mezcles.

Los 7 archivos que se cargan al arrancar

Flujo de arranque de Claude Code: 7 archivos que se leen

Según los docs oficiales de Anthropic para julio de 2026, la carga es en este orden:

  1. ~/.claude/CLAUDE.md: instrucciones globales del usuario
  2. ./CLAUDE.md: instrucciones del proyecto (versionado con git)
  3. ./CLAUDE.local.md: sobreescrituras locales (fuera de git)
  4. ~/.claude/settings.json: permisos y variables globales
  5. .claude/settings.local.json: permisos y variables del proyecto
  6. .claude/hooks/: scripts que se ejecutan en eventos
  7. .claude/skills/: habilidades reutilizables invocables

Cada archivo tiene un rol distinto y una precedencia distinta. Confundir los roles es el error más común: gente que mete permisos en el CLAUDE.md (no se leen), o que pone secretos en settings.json versionado (se filtran al equipo).

Los 7 archivos, uno por uno

1. ~/.claude/CLAUDE.md

Qué debe contener: tus preferencias personales de estilo, herramientas que usas siempre, atajos de tu terminal. Cosas que aplican a todos tus proyectos.

Qué NO debe contener: información específica de un cliente, secretos, rutas absolutas que solo existen en tu computadora del trabajo.

Regla dura: menos de 200 líneas. Si crece más, Claude Code lo recorta y no sabes qué quedó afuera.

2. ./CLAUDE.md del proyecto

Qué debe contener: stack técnico, convenciones del equipo, “cosas que no hay que hacer” en este repo, comandos de build. Todo lo que un miembro nuevo del equipo necesitaría saber.

Qué NO debe contener: credenciales, rutas de tu computadora personal, decisiones que aún están en discusión.

Regla dura: este archivo se versiona con git. Todo lo que escribas ahí lo va a leer cualquier persona del equipo que ejecute Claude Code. Trátalo como documentación pública del proyecto.

3. ./CLAUDE.local.md

Qué debe contener: tus rutas locales (~/Downloads/data/), notas sobre bugs que estás depurando, información sensible del cliente que no debe ir al repo.

Qué NO debe contener: convenciones del equipo (van en ./CLAUDE.md), preferencias personales generales (van en ~/.claude/CLAUDE.md).

Regla dura: este archivo debe estar en .gitignore. Verifícalo hoy. Si se sube por error, es una filtración de datos.

4. ~/.claude/settings.json

Qué debe contener: permisos que aplican en todos tus proyectos (permitir git status, bloquear rm -rf /), variables de entorno globales, el model que quieres por defecto.

Qué NO debe contener: permisos específicos de un proyecto (van en .claude/settings.local.json), tokens de API (deben ir en .env o en un secret manager).

Regla dura: revisa permissions.deny cada 2 semanas. Es tu red de seguridad contra “el agente borró la base de producción”.

5. .claude/settings.local.json

Qué debe contener: permisos y hooks específicos de este proyecto. Por ejemplo, permitir npm run migrate solo en este repo, o registrar un hook que valide migraciones.

Qué NO debe contener: credenciales, endpoints con tokens embebidos. Este archivo también puede terminar en git si no configuras .gitignore correctamente.

Regla dura: si contiene algo específico de tu computadora, pertenece a .gitignore. Si contiene algo del proyecto que todo el equipo necesita, versiónalo (y quita cualquier secreto).

6. .claude/hooks/

Qué debe contener: scripts que se ejecutan en eventos como PreToolUse, PostToolUse, Stop. Por ejemplo, un hook que corre pnpm typecheck después de editar un archivo .ts.

Qué NO debe contener: lógica compleja que debería ir en tu pipeline de CI. Los hooks son para señales rápidas al agente, no para reemplazar tu CI.

Regla dura: cada hook debe terminar en menos de 5 segundos. Si tarda más, el agente se queda esperando y el flujo se degrada rápido.

7. .claude/skills/

Qué debe contener: habilidades reutilizables invocables con /nombre-habilidad. Cada carpeta con un SKILL.md que declare el propósito y los archivos que carga.

Qué NO debe contener: habilidades que nunca usas. Cada SKILL.md se lee al arrancar y consume contexto. Las habilidades muertas envenenan el arranque.

Regla dura: haz una purga trimestral. Si no invocaste una habilidad en 3 meses, borra la carpeta.

Checklist de 5 minutos

Ejecuta esto en tu terminal ahora mismo:

# ¿existe cada archivo? ¿qué tamaño tiene?
ls -la ~/.claude/CLAUDE.md ~/.claude/settings.json 2>/dev/null
ls -la ./CLAUDE.md ./CLAUDE.local.md .claude/settings.local.json 2>/dev/null
ls -d .claude/hooks .claude/skills 2>/dev/null

# ¿CLAUDE.local.md está en .gitignore?
grep -c "CLAUDE.local.md" .gitignore

# ¿tienes permisos "deny" globales?
python3 -c "import json; d=json.load(open('$HOME/.claude/settings.json'));\
  print('deny rules:', len(d.get('permissions',{}).get('deny',[])))"

# ¿cuántas habilidades tienes cargadas?
ls .claude/skills/ 2>/dev/null | wc -l
ls ~/.claude/skills/ 2>/dev/null | wc -l

Con esos 4 comandos ya sabes:

  • Cuáles de los 7 archivos existen en tu proyecto (los que no existen, Claude Code los ignora sin avisar).
  • Si tu archivo local está protegido de git (el bug de filtración más común).
  • Si tienes al menos alguna regla de bloqueo global (0 reglas = el agente puede ejecutar cualquier cosa).
  • Cuántas habilidades están consumiendo contexto solo por existir.

Si cualquiera de esos valores te sorprende, ya encontraste el trabajo de los próximos 30 minutos.

¿Por qué esto se llama context engineering?

Prompt engineering es lo que le dices al modelo esta vez. Context engineering es el ambiente que el modelo ve antes de que le digas nada. Los 7 archivos son literalmente el ambiente. Auditar esos archivos es a un agente de IA lo que auditar variables de entorno es a un contenedor de Docker: sin ese paso, no sabes con qué está trabajando el sistema.

Si LLMO (Large Language Model Optimization) es exponer tu sitio a la IA externa, context engineering es exponer tus archivos a la IA interna. Ambas disciplinas comparten el mismo principio: hazte cargo de lo que la IA lee, porque si no lo controlas tú, lo controla el proveedor por default.

Recursos

Cierre

  • Claude Code lee 7 archivos al arrancar. Si no los conoces, tu agente lee lo que decidió Anthropic, no lo que decidiste tú.
  • El error más común es meter secretos en settings.json versionado. Sepáralos con .local.json y .gitignore.
  • El segundo error más común es dejar habilidades muertas en .claude/skills/. Purga trimestral.
  • El checklist entero cabe en 4 comandos de terminal y toma 5 minutos.

Si quieres profundizar en la disciplina completa de context engineering, dejé el material largo en Ingeniería de Contexto en la Práctica.

ken imoto · WebRTC & Voice AI engineer · kenimoto.dev

Artículos relacionados

Ver todos los artículos →