El alcance es parte de la respuesta

El problema

Un equipo descubre una instrucción de prompt efectiva — "ejecuta siempre el linter antes de finalizar una edición" — y la incluye en el CLAUDE.md raíz del proyecto. Tres semanas después, un desarrollador que trabaja en un script aislado sin dependencias de linter configuradas observa cómo Claude intenta ejecutar repetidamente un binario inexistente en ese contexto. La instrucción era acertada. El ámbito de configuración era erróneo.

Este es el error más común en la configuración de Claude Code: tratar cada instrucción como si debiera aplicarse en todas partes, todo el tiempo. Los escenarios del examen evalúan precisamente este criterio — no solo saber que CLAUDE.md existe, sino decidir dónde debe residir cada instrucción, comando o regla.

Cuatro ámbitos concéntricos, cuatro respuestas arquitectónicas

Claude Code presenta una jerarquía de configuración con ámbitos concéntricos, donde cada nivel responde a una necesidad organizativa diferente:

• Usuario (~/.claude/): "¿es una preferencia individual que deseo activa en todos los proyectos en los que trabajo?" Los atajos personales y preferencias del desarrollador residen aquí.
• Proyecto (.claude/ en el repositorio, versionado): "¿es una convención de equipo que cualquier colaborador de este repositorio debe seguir?" El CLAUDE.md de proyecto, los comandos compartidos y las Skills del equipo pertenecen aquí.
• Reglas específicas de ruta (archivos Markdown en .claude/rules/ con un patrón glob paths en el frontmatter YAML): "¿esta regla aplica estrictamente cuando se modifica un subdirectorio o patrón de archivos específico?" La regla de linting del ejemplo inicial debió ser una regla con paths: ["src/api/**"], no una línea global en el CLAUDE.md raíz.
• Ámbito de sesión o efímero: directivas válidas únicamente para el turno o tarea activa que no deben perdurar más allá de la interacción inmediata.

La pregunta que resuelve la mayoría de los escenarios no es "¿esta instrucción es útil?" — casi siempre lo es. Es: "¿esta instrucción es válida en todos los ámbitos donde será procesada?" Una regla útil en un ámbito incorrecto constituye un fallo de configuración.

Skills: ámbito de ejecución y contratos estructurales

Una Skill (.claude/skills/<nombre>/SKILL.md) formaliza la lógica de configuración en un paquete modular y reutilizable. El frontmatter YAML de una Skill define propiedades arquitectónicas clave:

• context: fork: la Skill se ejecuta en una ventana de contexto aislada, evitando que el razonamiento exploratorio contamine la sesión principal.
• allowed-tools: la Skill queda estrictamente restringida a las herramientas listadas, independientemente de los permisos más amplios de la sesión que la invocó.
• argument-hint: documenta los formatos de parámetros esperados, reduciendo la ambigüedad en las invocaciones.

Un antipatrón frecuente es tratar allowed-tools como documentación informal en lugar de como un límite de control de acceso. Una Skill de revisión de código que incluye Bash en allowed-tools sin necesidad operativa expande la superficie de riesgo. Pregúntate siempre: "¿qué herramientas requiere esta Skill para cumplir su contrato?", no "¿cuáles sería cómodo tener disponibles?".

CI headless: salidas estructuradas sobre prosa de terminal

Ejecutar Claude Code de forma no interactiva en canalizaciones de CI (-p o --print con --output-format json) transforma la naturaleza de la ejecución: no hay un operador humano en el bucle para interpretar matices de texto. Esto implica dos requisitos de diseño:

1. La salida debe estar estructurada como JSON legible por máquina para que herramientas automatizadas o bots de revisión tomen decisiones de compuerta (gating).
2. Una ejecución desatendida que modifica código de producción sin verificación independiente representa un riesgo severo. El patrón maduro utiliza dos fases: una que genera los cambios y otra de revisión independiente — en una sesión limpia, sin el sesgo del contexto generativo — que evalúa la evidencia empírica antes de aprobar fusiones.

El distractor clásico en los escenarios propone que el CI headless es autosuficiente sin revisión independiente porque "--output-format json ya garantiza la calidad". El formato estructurado asegura que la salida es parseable. No garantiza que sea correcta.

Ponlo en práctica

En el laboratorio de esta lección auditarás un conjunto de directivas distribuidas en distintos ámbitos (usuario, proyecto y reglas de ruta), reclasificando cada una a su nivel adecuado (promoviendo, degradando o convirtiéndola en regla basada en paths).