Documentación de Claude Code CLI: lo que dicen los manuales oficiales, lo que omiten y lo que uso a diario
El análisis de un desarrollador sobre la documentación de claude code CLI de Anthropic. Cinco lagunas que encontré esta semana, la anatomía de ~/.claude/ que los manuales no explican bien y una comparativa entre la teoría y la práctica en Mac y VPS Linux.
Nota del traductor: Este artículo fue traducido con asistencia de IA y revisado por Jim Liu (desarrollador independiente en Sídney) para corregir terminología y mejorar fluidez. Si encuentras errores o expresiones poco naturales, escríbeme. Versión original en inglés: English.
Documentación de Claude Code CLI — Una lectura para desarrolladores en activo
- La documentación oficial de Claude Code CLI de Anthropic se encuentra en
code.claude.com/docs/en/— incluye guía rápida, referencia de CLI, comandos, costes y una sección de "skills" en crecimiento. Son precisas, pero también incompletas en varios aspectos que los desarrolladores encuentran en su primera semana. - Los cinco vacíos reales que tuve que llenar fuera de la documentación: el parseo de argumentos en comandos de barra (slash commands), códigos de salida de hooks, ciclo de vida del servidor MCP al reiniciar, frontmatter de skills que realmente cargue y cómo interactúan los estilos de salida con las reglas del proyecto.
- El tema oculto: el directorio
~/.claude/en sí. La documentación describe cada pieza de forma aislada; nadie dibuja el mapa de cómo encajancommands/,skills/,hooks/,mcp/ysettings.json. Yo lo dibujaré a continuación. - Veredicto de configuración: la guía rápida oficial es precisa para la instalación y una primera conversación. Después de eso, planea leer las notas de lanzamiento en GitHub y al menos una guía de la comunidad; la documentación suele ir una semana por detrás del comportamiento real en cuanto a nuevas funciones.
Tabla de contenidos
- Cómo uso Claude Code (Configuración real)
- Lo que la documentación oficial cubre bien
- Cinco vacíos en la documentación que encontré esta semana
- Anatomía de ~/.claude/ — El mapa que la documentación no dibuja
- Documentación vs. Uso Real — Comparación honesta
- Ruta de cinco pasos: de la Guía Rápida al uso diario
- Preguntas frecuentes (FAQ)
Cómo uso Claude Code (Configuración real)
Soy Jim, un desarrollador independiente en Sídney que gestiona cinco sitios en Cloudflare Workers + un par de VPS de Postgres. Claude Code es la CLI que tengo abierta en un panel de mi terminal cada día de trabajo. Mi configuración: claude-code en macOS (MacBook Pro M2, shell fish) además del mismo binario en un VPS Ubuntu de Hostinger para scripts en producción. Ambos autenticados con la misma cuenta de Anthropic.
No uso la aplicación de escritorio. Para mí, la clave es que la CLI esté vinculada a una shell real para que el agente lea los mismos archivos que lee git.
Esta semana cerré deliberadamente todas las pestañas del navegador que apuntaban a la documentación y trabajé solo con claude code --help y lo que tenía en ~/.claude/. Los cinco vacíos a continuación son los que me obligaron a reabrir la documentación — solo para descubrir que la respuesta tampoco estaba allí.
Lo que la documentación oficial cubre bien
Hay que reconocer los méritos. La documentación de Anthropic en code.claude.com/docs/en/ clava lo siguiente:
- Instalación y autenticación. La instalación por npm, el flujo de
claude auth login, la distinción entre clave API y suscripción — todo impecable. - Referencia de flags de la CLI.
--print,--continue,--resume,--allowedTools,--mcp-config— información precisa y actualizada a las pocas semanas de lanzarse nuevos flags. - Costes y límites de uso. La página
/docs/en/costses honesta sobre los límites de sesión y cómo funcionan los planes Pro / Max. - La primera conversación. La guía rápida realmente te guía para hacer algo útil, no solo para configurar algo.
Si empiezas desde cero, la documentación te permite tener tu primera conversación útil en quince minutos. Es un estándar real y lo cumplen.
Cinco vacíos en la documentación que encontré esta semana
Vacío uno — Martes: parseo de argumentos en comandos de barra. Quería un comando /deploy que tomara un slug de sitio y ejecutara el comando de wrangler adecuado. La documentación muestra que los comandos de barra viven en ~/.claude/commands/*.md y aceptan $ARGUMENTS, pero no dice cómo parsear múltiples argumentos posicionales. Tuve que leer el repositorio de otro desarrollador en GitHub para descubrir que tienes que dividir $ARGUMENTS tú mismo con herramientas de shell; no hay un $1 $2 integrado. Me costó unos veinte minutos. La solución: ahora uso read -r sitio resto <<< "$ARGUMENTS" en el cuerpo del comando.
Vacío dos — Miércoles: semántica de los códigos de salida de hooks. Configuré un hook PreToolUse para bloquear git push --force. La documentación dice: "un código de salida distinto de cero bloquea la llamada a la herramienta". Lo que no dice es que el código de salida 2 es el que envía el stderr del hook al modelo para que este entienda por qué fue bloqueado. El código de salida 1 simplemente detiene la herramienta con un error genérico y Claude intenta otra cosa. Perdí quince minutos preguntándome por qué mi advertencia de "no hacer force-push a main" nunca llegaba al agente hasta que comparé mi código con otro hook que sí funcionaba.
Vacío tres — Miércoles tarde: ciclo de vida del servidor MCP al reiniciar la shell. Tengo un servidor MCP personalizado para la base de datos Postgres de OpenAI Tools Hub. Tras iniciar una nueva sesión de terminal, claude code a veces lanzaba el servidor MCP dos veces. La documentación describe cómo registrar un servidor MCP en .mcp.json, pero no dice nada sobre cómo funciona el ciclo de vida entre sesiones o cómo detectar un proceso huérfano. La respuesta honesta (sacada de un issue en GitHub): la CLI no reutiliza un servidor de larga duración entre sesiones; cada sesión inicia el suyo propio. Si ves dos, generalmente significa que hay un proceso colgante de un cierre inesperado anterior. La solución: pkill -f "node mi-mcp-server" antes de cada sesión, o usar un trap EXIT en tu lanzador.
Vacío cuatro — Jueves: frontmatter de skills que realmente cargue. Las "skills" son una función reciente y la documentación en /docs/en/skills describe el frontmatter YAML (name, description). Lo que no enfatiza es lo estricto que es el cargador. Un espacio al final en el campo name, una comilla tipográfica en lugar de una recta, o un campo tags con una estructura incorrecta hace que la skill se ignore silenciosamente — sin advertencias, simplemente no aparece. Perdí una hora con una skill que no cargaba hasta que copié byte por byte el frontmatter de una skill que sabía que funcionaba.
Vacío cinco — Viernes: cómo interactúan los estilos de salida con CLAUDE.md. Los estilos de salida (~/.claude/output-styles/*.md) y los archivos CLAUDE.md locales del proyecto inyectan contexto al sistema. La documentación cubre cada uno por separado, pero en ningún lugar se explica la precedencia. Por ensayo y error: el archivo CLAUDE.md del proyecto gana cuando ambos contienen reglas en conflicto, pero el estilo de salida sigue afectando al formato (longitud, encabezados). Si quieres un estilo de salida estricto de "respuestas de una sola línea" para anular una regla de proyecto que dice "siempre muestra resúmenes de TODO", no puedes — el archivo del proyecto gana en el contenido, el estilo solo afecta a la forma.
Anatomía de ~/.claude/ — El mapa que la documentación no dibuja
Tras unos meses de uso diario, así es como se ve mi directorio. La documentación describe cada subdirectorio en su propia página; nadie dibuja el árbol completo.
| Ruta | Qué contiene | Cuándo se carga |
|---|---|---|
~/.claude/settings.json | Permisos, hooks, configs de MCP (nivel de usuario) | En cada sesión |
~/.claude/CLAUDE.md | Reglas globales personales | En cada sesión |
~/.claude/commands/*.md | Comandos de barra personales | Al ejecutar / |
~/.claude/skills/ | Skills personales (invocadas automáticamente) | Cuando el modelo lo considera relevante |
~/.claude/output-styles/*.md | Reglas personales de estilo de salida | Cuando se activan por nombre |
~/.claude/hooks/*.sh (referenciados en settings.json) | Hooks pre/post herramientas | Alrededor de las llamadas a herramientas |
./.claude/ en cualquier proyecto | Misma estructura, alcance de proyecto, sobrepone al usuario | Cuando el CWD está dentro del proyecto |
./.mcp.json | Registro de servidor MCP del proyecto | Al iniciar sesión en ese directorio |
./CLAUDE.md | Reglas del proyecto — gana al nivel de usuario en contenido | Al iniciar sesión en ese directorio |
Las dos reglas que desearía que la documentación mencionara de entrada: los archivos de proyecto se superponen a los de usuario (el proyecto gana en caso de conflicto de contenido), y las skills se invocan automáticamente, mientras que los comandos son explícitos. El modelo mental que se deriva de estas dos reglas es suficiente para deducir el resto a partir de la documentación de referencia.
Para una lectura más profunda sobre qué poner en commands/ y skills/, mi guía de campo de skills para Claude Code detalla las que realmente utilizo.
Documentación vs. Uso Real — Comparación honesta
Comparación (⚖️): dónde dedicar tu tiempo de lectura en cada área.
| Tema | Profundidad en docs oficiales | Profundidad necesaria en el mundo real |
|---|---|---|
| Instalación + primera charla | Excelente | Lee la documentación y listo. |
| Referencia de flags de CLI | Excelente | Lee la documentación y listo. |
| Comandos de barra | Superficial | Lee las docs + mira un repo de la comunidad con comandos complejos. |
| Hooks | Menciona códigos de salida, no explica la semántica | Lee las docs + lee el código de un hook que funcione. |
| Skills | Formato descrito, omite casos borde | Copia un SKILL.md que funcione byte por byte la primera vez. |
| MCP | Cubre la configuración, no el ciclo de vida | Lee las docs + busca 2-3 issues en GitHub sobre tu caso. |
| Estilos de salida | Qué son, no cómo se combinan | Ensayo y error en un proyecto de prueba. |
| Costes y límites | Honesta y actualizada | Lee la documentación y listo. |
Mantengo abiertas tanto la documentación de Anthropic como la guía de extensiones de la comunidad al mismo tiempo. Cubren frentes distintos.
Ruta de cinco pasos: de la Guía Rápida al uso diario
Guía operativa (🧭):
- Sigue la guía rápida oficial. No te la saltes; el flujo de instalación y autenticación es preciso y rápido.
- Escribe tu propio comando de barra. Un
/git-statusque ejecutegit statusy lo resuma es suficiente. Hacerlo te enseñará que$ARGUMENTSes una sola cadena, no una lista, y que debes parsearla tú mismo. - Instala un servidor MCP. El MCP
filesystemde Anthropic es el más sencillo para empezar. Observa el log de la sesión para ver cuándo se inicia y cuándo muere. - Añade un
./CLAUDE.mda tu proyecto principal con tres reglas. Verifica que anula la regla correspondiente a nivel de usuario. Ahora entiendes la precedencia. - Adopta una skill de la comunidad de un repositorio público, copia el
SKILL.mdíntegramente, cambia una línea y observa cómo carga. Después de esto, la documentación tendrá sentido como referencia en lugar de como tutorial.
Para una visión más amplia de cómo se compara Claude Code con el lado del IDE, mi post Claude Code vs Cursor explica cuándo usar cada uno.
Preguntas frecuentes (FAQ)
¿Dónde está la documentación oficial de Claude Code CLI?
En code.claude.com/docs/en/ — encontrarás la guía rápida, referencia de CLI, comandos, costes, skills y hooks. Las páginas de referencia son las que se mantienen más actualizadas.
¿Es precisa la documentación? Para instalación, autenticación, flags de CLI y costes: sí. Para las áreas de personalización (comandos, hooks, skills, MCP, estilos de salida): es precisa pero superficial. Planea complementarla con un recurso de la comunidad por cada área.
¿Cuánto tarda la documentación en reflejar nuevas funciones? Aproximadamente una semana, según mi experiencia. Los nuevos flags llegan primero al binario, luego a las notas de lanzamiento en GitHub y, por último, a la web. Si una función es demasiado nueva para la web, búscala en los issues de GitHub.
¿Dónde buscar cuando la documentación oficial no tiene la respuesta?
En este orden: los issues de GitHub de anthropics/claude-code, la pestaña de discusiones de ese mismo repositorio y guías de la comunidad bien seleccionadas. Evita vídeos de YouTube de hace cinco meses; este campo evoluciona demasiado rápido.
¿Puedo ejecutar la CLI sin conexión (offline)? No. Incluso con un servidor MCP local haciendo el trabajo, el agente llama a la API de Anthropic en cada turno. No hay opción de modelo local a fecha de abril de 2026.
¿Funciona Claude Code en Windows? Sí, a través de WSL2 o directamente en PowerShell. La documentación cubre ambos. WSL2 es el camino más fluido; PowerShell ocasionalmente tiene reglas de entrecomillado diferentes en los comandos de barra que la documentación sí advierte.
Cómo verifiqué la cobertura de la documentación
Leí la documentación oficial en code.claude.com/docs/en/ entre el 25 y el 27 de abril de 2026, revisando desde la guía rápida hasta las skills y MCP. Los cinco vacíos provienen de mis propias notas de sesión (21-25 de abril) — cinco momentos reales en los que necesité algo que la documentación no ofrecía. La anatomía del directorio proviene de ejecutar find ~/.claude -maxdepth 3 en mi propia máquina y find ./.claude -maxdepth 3 en tres de mis proyectos.
Si la documentación cambia después de la publicación de este post, este artículo recibirá una marca de dateModified y se actualizará la sección correspondiente. No prometo actualizar cada micro-revisión; solo cambios sustanciales.
Sobre el autor
Jim Liu — desarrollador independiente en Sídney que gestiona OpenAI Tools Hub, LowRiskTradeSmart y otros tres sitios de nicho usando Cloudflare + Next.js. Escribo sobre las herramientas CLI por las que realmente pago y uso a diario. Sin contenido patrocinado; si una herramienta deja de valer la pena, actualizo o elimino el post.
Perspectiva LATAM y España
Para los desarrolladores en España y Latinoamérica, el acceso a Claude Code CLI presenta matices operativos cruciales que no siempre aparecen en los tutoriales anglosajones. Aunque la herramienta es accesible globalmente, la gestión de créditos de API sigue siendo el principal obstáculo en regiones con restricciones cambiarias, como Argentina, donde las tarjetas locales suelen presentar fricciones al procesar pagos internacionales en dólares. En el ecosistema de startups de Ciudad de México, Bogotá o Madrid, esta CLI se está posicionando no solo como un asistente de código, sino como un motor para automatizar la modernización de sistemas legacy en consultoras tecnológicas. Mientras que alternativas como Cursor dominan el aspecto visual del desarrollo, los equipos locales están adoptando Claude Code para flujos de CI/CD y "scripts" de mantenimiento debido a su precisión en el razonamiento lógico. Un caso de uso emergente es el cumplimiento de normativas de privacidad locales, donde la capacidad de la herramienta para auditar código bajo marcos regulatorios específicos (como el RGPD) ofrece una ventaja competitiva real.