Recientemente, muchos amigos me han estado preguntando si podría publicar un tutorial para principiantes sobre Claude Code.
También quieren usar el producto Agent más potente del mundo.
En realidad, mucha gente no se da cuenta de que los productos Agent generalmente se componen de un framework Agent y un modelo. Los modelos de Claude son bloqueados con frecuencia en China y son muy difíciles de manejar; no tengo forma de enseñarles a todos cómo solucionarlo.
Pero Claude Code no será bloqueado ni dejará de funcionar porque en realidad es un framework Agent que se puede usar con cualquier modelo.
Aunque Anthropic puede ser bastante molesto con las constantes suspensiones de cuentas y la autenticación de identidad, aún tengo que admitir que el mejor framework Agent del mundo hoy en día es Claude Code.
Por eso siempre digo: si puedes hacerlo bien de una vez, hazlo. Sé que cosas como OpenClaw y Hermes Agent son muy populares ahora, pero sigo recomendando usar Claude Code. Incluso si no puedes usar los modelos nativos de Claude, combinarlo con un modelo doméstico aún da excelentes resultados.
Además, no tienes que preocuparte por suspensiones de cuentas, números de teléfono extranjeros, tarjetas Visa, ni siquiera por usar una VPN.
Así que hoy, aquí tienes un tutorial completo para principiantes de Claude Code desde cero. He preparado instrucciones para Windows y Mac, con y sin VPN, para que todos puedan seguir la parte que necesitan.
El siguiente proceso de instalación fue probado en cinco o seis computadoras durante todo un fin de semana por mí y mi equipo, mediante instalaciones y desinstalaciones repetidas.
Por ejemplo, en escenarios sin VPN, existen otros métodos de instalación como npm o el uso de fuentes espejo domésticas con curl. Estos métodos funcionan, pero no fueron lo suficientemente estables en diferentes computadoras en mis pruebas.
Así que finalmente, elegí el método que creo que es el más simple y con menos probabilidades de fallar incluso en una computadora muy "limpia".
Solo espero que todos puedan usar con éxito el framework Agent más potente del mundo siguiendo este artículo.
Explicaré cada paso de la manera más clara y detallada posible. Puede que sea un poco extenso, así que tengan paciencia.
Bien, comencemos.
I. Instalación de Claude Code
1. Mac
Primero veamos Mac. Los usuarios de Windows pueden saltarse esta parte y encontrar el tutorial de Windows más abajo.
Primero, busca la Terminal en tus Aplicaciones y ábrela.
Instalemos a nuestro protagonista de hoy, Claude Code.
Creé una cuenta de macOS completamente nueva para mi computadora, que es básicamente equivalente a una computadora limpia, para esta demostración.
Primero, hablemos del caso con VPN.
El comando es solo una línea:
Pega este comando en la terminal y presiona Enter.
Espera un momento y verás una instalación exitosa.
Aunque está instalado, es posible que te dé un aviso aquí.
Significa que Claude Code está instalado, pero la ubicación de instalación ~/.local/bin no se ha añadido a tu variable de entorno PATH, por lo que escribir claude directamente podría no encontrar el comando.
Dice que para solucionarlo, ejecutes el comando que se proporciona a continuación.
Si no lo entiendes, está bien. Solo haz lo que dice: copia ese largo comando echo que te dio en la terminal y ejecútalo.
Luego escribe claude --version. Si aparece un número de versión, la instalación fue exitosa.
La situación con VPN es muy simple, pero sé que muchos estudiantes no tienen una.
Entonces, si no tienes VPN, podemos instalarlo a través de Homebrew.
Homebrew es el gestor de paquetes por línea de comandos más popular en macOS. Te permite instalar, actualizar y desinstalar varios programas y herramientas de desarrollo con un solo comando.
Tomé prestada una computadora nueva de un colega; no tiene VPN y tiene un entorno muy limpio.
Primero instalemos brew. Puede parecer complicado, pero en realidad es muy simple si sigues los pasos.
Pega el siguiente comando en la línea de comandos y presiona Enter:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.shhttps://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh))"
Después del aviso, solo presiona Enter.
Luego se ejecutará por un tiempo.
Espera pacientemente unos minutos. Cuando termine y diga que la instalación fue exitosa, ya está.
A continuación, debemos añadir Homebrew a las variables de ruta para que la terminal pueda encontrar el comando cuando lo usemos.
Pega estas pocas líneas de comandos en la terminal y ejecútalas una vez.
Ahora podemos usar Homebrew para gestionar paquetes de Mac.
A continuación, usa el siguiente comando para instalar Claude Code. Debido a que el editor podría autoformatear algo de texto, copiar y pegar directamente podría causar errores. Escríbelo manualmente o pídele a Claude que corrija el formato antes de pegarlo en la terminal:
brew install --cask claude-code@latest
La velocidad de instalación aquí es un poco lenta; puedes tomarte un descanso y volver cuando termine.
Una vez que aparezca el mensaje de éxito, escribe claude en la terminal y verás el cangrejito.
Sin embargo, mostrará que no es utilizable por ahora. Puedes ignorar esto; te enseñaré cómo conectar un modelo en un momento.
Ahora que hemos cubierto Mac, hablemos de Windows por separado. Es ligeramente diferente. Los usuarios de Mac que hayan terminado pueden saltarse esta parte.
2. Windows
Ahora para Windows.
Usé una máquina Windows recién formateada para instalarlo.
Dado que Claude Code ejecuta comandos internamente usando Git Bash en Windows, debes instalar Git primero para usar Claude Code en Windows.
Entonces, paso uno: instalar Git.
Los amigos que ya lo tengan instalado pueden saltarse esto.
Usa WinGet para instalarlo. Este es el gestor de paquetes oficial de Windows, que se puede considerar como la versión de Windows de Homebrew.
Busca "Terminal" en la barra de tareas y ábrela.
Pega el siguiente comando en la terminal. La instalación será mucho más rápida si no usas una VPN aquí.
winget install Git.Git
Una vez que termine, mostrará una instalación exitosa.
Una vez instalado Git, como de costumbre, hablemos del caso con VPN.
Para los amigos con VPN, seguimos usando el comando de instalación nativo oficial.
Pega el comando en la terminal:
Espera un momento y se instalará.
Muy conveniente.
Si no tienes VPN, debemos usar WinGet para instalarlo.
Ejecuta este comando en la terminal:
winget install Anthropic.ClaudeCode
Después de que se instale correctamente, también puedes escribir claude para ver que se ha instalado.
En este punto, teóricamente, escribir claude en la terminal debería llevarte a la página de Claude Code.
Pero.
Solo hemos instalado el framework; aún no le hemos dado un "cerebro", por lo que no es utilizable.
A continuación, necesitamos conectar su cerebro.
II. Conexión del modelo
Si tienes una cuenta de Claude, solo inicia sesión directamente. No entraré en detalles aquí.
Porque teóricamente, si ya tienes una cuenta de Claude, no estarías leyendo este tutorial para principiantes...
Entonces, para asegurarme de que todos los amigos nacionales puedan usarlo, usaré el modelo doméstico GLM-5.1 como ejemplo.
GLM-5.1 es actualmente el modelo doméstico que he usado y que se siente más cercano a la experiencia de Claude Opus 4.6.
Por supuesto, si no captaron su plan de codificación, MiniMax M2.7 y K2.5 también son buenos. El código K2.6 debería salir pronto, y siento que Kimi también tendrá un gran avance; recomiendo estar atentos.
En cuanto a GLM-5.1, Zhipu oficial proporciona un comando de una línea para instalarlo, que es muy simple:
Sin embargo, para que sea más fácil para todos conectar otros modelos y cambiar libremente, te enseñaré un método más universal: usar CC Switch.
Nuevamente, dividido en Mac y Windows.
1. Mac
En Mac, la instalación es solo de dos comandos. El segundo comando también podría dar error si se copia y pega directamente debido al formato. Escríbelo manualmente o pídele a Claude que lo corrija antes de pegarlo:
brew tap farion1231/ccswitch
brew install --cask cc-switch
Pégalo en la terminal y presiona Enter.
Una vez instalado, ya está.
2. Windows
Para Windows, recomiendo descargar el paquete de instalación directamente desde el siguiente enlace:
https://github.com/farion1231/cc-switch/releases
Si no puedes acceder a GitHub, también he preparado un paquete de instalación local. Responde con "cc" en el fondo de la cuenta oficial y te enviará automáticamente el enlace de descarga.
Después de descargarlo, haz doble clic para ejecutarlo y puedes hacer clic en "Siguiente" hasta terminar la instalación.
Las operaciones posteriores son las mismas para Mac y Windows, así que no las separaré.
Después de la instalación, ábrelo.
Puedes ver que esta herramienta no es solo para Claude Code; Codex y Xiaolongxia también pueden usarla.
Como aún no lo hemos configurado, actualmente solo hay configuraciones oficiales del modelo Claude.
En la columna de Claude, haz clic en el signo más en la esquina superior derecha para añadir una nueva configuración de modelo.
Luego selecciona el modelo que deseas usar. Aquí elegí la versión doméstica de GLM.
A continuación, solo necesitas completar dos partes: la clave API (si no sabes qué es una clave API, puedes preguntarle a cualquier IA a la que tengas acceso y te ayudará) y la configuración del modelo. Todo lo demás se completará automáticamente.
Después de completarlo, haz clic en "Añadir" en la esquina inferior derecha.
Cambiará al modelo que configuramos.
En este punto, la instalación de Claude Code y la conexión de GLM-5.1 están completas.
III. Iniciar Claude Code
Vuelve a la terminal, escribe claude y presiona Enter.
Ahora puedes iniciar Claude Code normalmente.
Para el primer uso, habrá algunas configuraciones de inicialización.
Por ejemplo, el modo de color. Hay una vista previa del código debajo de los modos; elige según tu preferencia y presiona Enter.
Si quieres cambiarlo más tarde, ejecuta /theme dentro de Claude Code.
A continuación, el aviso de seguridad.
Dos puntos principales:
Uno es que Claude puede cometer errores. Debes revisar el código que genera y los comandos que quiere ejecutar antes de permitirlos.
Uno es que solo uses Claude Code en bases de código de confianza para evitar ataques de inyección de prompts.
Presiona Enter para ir al siguiente paso.
Pregunta si queremos usar la configuración de terminal de Claude Code.
Aquí, solo usa la configuración de terminal recomendada.
En realidad, quiere ayudarte a habilitar dos cosas:
Teclas de acceso directo para lograr saltos de línea en la terminal.
El otro es Visual Bell, un aviso visual.
Es decir, cuando Claude termine una tarea o necesite tu confirmación, la ventana de la terminal parpadeará y el icono del Dock saltará para recordártelo.
El último paso es confirmar si el directorio actual es de confianza.
Selecciona "Sí" y presiona Enter.
Finalmente hemos llegado a la interfaz de diálogo de Claude Code conectado a GLM-5.1.
Si quieres cambiar de modelo más tarde, configúralos en CC Switch y usa /model en Claude Code para cambiar.
En este punto, todas las operaciones de instalación y conexión están completas.
Para uso futuro, solo escribe claude en la terminal.
Recomiendo usar el siguiente comando, especialmente durante el desarrollo, de lo contrario, hacer clic en "Permitir" repetidamente te hará cuestionar tus decisiones de vida:
claude --dangerously-skip-permissions
Cuando lo iniciemos, debido al diseño del contexto, debemos iniciarlo en una carpeta para mantenerlo limitado y enfocado, en lugar de iniciar Claude Code directamente en el directorio raíz.
He dividido mis directorios; "Documentos" es donde hago creación de conocimiento.
También hay una carpeta "code", que contiene varios productos que he desarrollado yo mismo.
Iniciar Claude Code para una carpeta específica en la línea de comandos también es muy simple.
Es el comando cd, que es el mismo para Mac y Windows.
Por ejemplo, si quiero entrar en la carpeta "Base de conocimiento" para crear contenido:
Abre la terminal, escribe cd, luego recuerda presionar la barra espaciadora una vez, y luego arrastra tu carpeta directamente dentro.
Presiona Enter y habrás entrado en esa carpeta.
Luego usa el comando para iniciar Claude Code.
Entrarás en esa carpeta, y por defecto trabajará solo dentro de esa carpeta, leyendo todos los archivos dentro de ella.
Esto en realidad resulta en menos contaminación del contexto y más enfoque; en otras palabras, es más inteligente.
IV. Escribir CLAUDE.md
Después de aprender cómo iniciarlo, puedes comenzar oficialmente el diálogo y dejar que funcione.
Pero hay un estándar y un hábito muy importante que debes establecer antes de un uso profundo. No caigas en las viejas trampas en las que yo caí: define primero tu archivo CLAUDE.md.
En mi opinión, esto es incluso lo primero que debes hacer después de aprender a iniciar Claude Code.
Antes de entrar en el estilo de escritura específico, hablemos de qué es CLAUDE.md.
Esto no es solo un archivo; es un sistema de restricciones jerárquico de arriba hacia abajo.
Como esta imagen que usé antes.
Después de la instalación, las dos capas que debemos gestionar son el CLAUDE.md global y el CLAUDE.md del proyecto.
El CLAUDE.md global se coloca en el directorio raíz de Claude Code en el directorio de inicio del usuario: ~/.claude/CLAUDE.md.
Siempre que abras Claude Code, sin importar en qué proyecto entres, se cargará y seguirá automáticamente.
Esta es su especificación de nivel superior.
Resuelve problemas como quién eres, tus principios para hacer las cosas y cómo quieres que colabore contigo.
El CLAUDE.md a nivel de proyecto se coloca en el directorio raíz de cada proyecto: project_directory/CLAUDE.md.
Solo se carga cuando abres ese proyecto.
Resuelve el problema de cómo se debe hacer este proyecto específico y qué acuerdos especiales existen en este nivel.
Hablemos primero del CLAUDE.md global, que es lo primero que debe resolverse. Pero muchas personas no tienen claro qué escribir, cómo escribirlo, cuánto debe durar o dónde colocarlo. Para los no desarrolladores, compartiré mi experiencia.
En cuanto a la longitud, CLAUDE.md no es mejor si es más largo; al contrario, debe ser lo más conciso posible.
Si tu CLAUDE.md es demasiado largo, simplemente ignorará el contenido de la segunda mitad.
La línea roja específica es esta: más allá de 80 líneas, Claude comienza a omitir algo de contenido. Como máximo, nunca superes las 200 líneas.
En un artículo anterior, te mostré lo que contiene mi archivo CLAUDE.md global.
Basado en mi contenido, he iterado y preparado una plantilla para ti.
Contiene cosas que creo que un buen CLAUDE.md global debería tener.
Solo necesitas escribir tu propio contenido en la sección "Sobre mí"; el resto básicamente se puede reutilizar directamente.
Sobre mí [Tu nombre / identidad / antecedentes profesionales; si no eres programador, debes indicarlo]. Uso Claude Code para [Uso específico 1] y [Uso específico 2].
Principios de pensamiento: Todas las decisiones parten de la esencia del problema, no copies solo porque "es la convención". Vuelve al problema en sí: ¿Qué necesita resolverse? ¿Cuál es el camino más directo? ¿Cómo se diseñaría desde cero? No halagues. No elogies mis ideas, no digas "esta es una muy buena pregunta", no añadas "por supuesto" al principio. Dame juicios reales; si hay un problema con el plan, señálalo directamente. Si encuentras una mejor manera, dila directamente sin esperar a que te pregunte.
Restricciones primero: Ya sea un proyecto de desarrollo o un proyecto de gestión del conocimiento, el primer paso es siempre establecer reglas: escribe CLAUDE.md para nuevos proyectos primero, y define convenciones estructurales para nuevos directorios (qué va dónde, cómo nombrar, cuándo limpiar). No trabajes en un espacio de trabajo sin especificaciones. Para proyectos con especificaciones existentes, cumple estrictamente con los acuerdos en su CLAUDE.md. Al ajustar especificaciones, cambia primero el documento, luego la práctica, no al revés.
Estilo de comunicación - Por defecto en español, usa inglés para código, comandos y nombres de variables - Conclusión primero, luego razones, no prepares el terreno con antecedentes - Ante requisitos vagos, da primero el plan más razonable, luego pregunta si se necesitan ajustes - No preguntes "¿estás seguro de que quieres hacer esto?" a menos que se toquen las líneas rojas a continuación
Límites autónomos (Líneas rojas, debes preguntarme primero) Las siguientes operaciones deben detenerse y preguntarme incluso en modo de aceptación automática: - Eliminar archivos, directorios o historial de git - Modificar .env, claves, tokens, configuraciones de CI/CD - Cambios en el esquema de la base de datos o migraciones de datos - git push, git rebase, git reset --hard, force push - Instalar nuevas dependencias globales o modificar configuraciones del sistema - Publicación pública (npm publish, implementar en producción, publicar artículos, etc.)
Disciplina general de ingeniería - Ejecuta activamente la verificación después de los cambios (consulta el CLAUDE.md de cada proyecto para comandos específicos), no solo cambies sin verificar - No comentes errores ni añadas marcadores de omisión solo para que el código funcione; encuentra la causa raíz - Las claves, tokens y contraseñas no deben entrar en código, commits ni registros - Antes de cambios importantes, proporciona un plan en Modo Plan; solo procede después de mi confirmación
Un total de aproximadamente 30 líneas, divididas en seis partes.
Estos seis bloques tienen una característica común: son universales entre proyectos.
Una vez establecido el CLAUDE.md global, tenemos nuestras especificaciones de nivel superior.
En cuanto a la siguiente capa, el CLAUDE.md del proyecto.
Tómame como ejemplo.
Principalmente uso Claude Code para desarrollo y gestión del conocimiento.
Por ejemplo, hay un CLAUDE.md en mi directorio code/my. Su función es principalmente porque las cosas que suelo codificar en la carpeta my a menudo son desechables o experimentales, que en realidad son muy pequeñas, así que me da pereza crear una nueva carpeta dentro de my cada vez.
Así que mi práctica común actual es hacer cd directamente a la carpeta my para iniciar, y luego comenzar felizmente a exponer mis requisitos para que me ayude a codificar. Con este archivo CLAUDE.md, juzgará por sí mismo si esto es un producto nuevo. Si lo es, directamente me ayudará a crear una nueva carpeta para comenzar, por lo que toda la gestión de archivos se vuelve organizada.
Y ni siquiera tienes que escribir este archivo tú mismo. Solo abre esa carpeta y chatea con Claude Code. Discute directamente tus requisitos y las cosas que te importan con él, y deja que te escriba uno.
También he estado trabajando duro con mi Claude Code estos últimos días para establecer varias especificaciones y organizar los diversos "montones de mierda" de código que dejé antes.
Si no tienes nada en tu computadora en este momento, es aún más conveniente.
Esta es una de las razones por las que siempre he enfatizado las restricciones primero y las especificaciones primero.
Una vez que se establecen las restricciones, realmente puedes empezar a jugar.
En cuanto a habilidades, plugins, comandos comunes y funciones.
No me extenderé aquí. He escrito muchos artículos relacionados; los amigos interesados pueden buscar las palabras clave correspondientes.
Palabras finales
Finalmente he terminado este tutorial para principiantes de Claude Code que tanto tiempo llevaba pendiente.
Claude Code es la "herramienta de graduación" de la era actual de la IA que te recomiendo.
No necesitas usar todos esos Agents desordenados. Usa bien Claude Code y realmente sentirás cuál es el Agent más potente.
Espero que todos puedan crear felizmente.
Y hacer obras que te pertenezcan en esta era.
Tus propias obras.
