Cómo construir tu primer agente en Claude Code (paso a paso, sin saber programar)

La barrera para construir tu primer agente no es técnica. Es otra. Cuando instalé Claude Code por primera vez hace más de un año, lo que me bloqueó no fue la instalación. Fue no saber qué decirle. El software funcionaba. Yo no tenía claro qué quería que hiciera.

Eso es lo que este artículo resuelve. No el paso técnico, que es trivial. El paso conceptual: qué tienes que decidir antes de escribir una sola línea de instrucciones, y cómo estructurarlo para que el agente funcione de verdad y no sea un experimento que abandones a la semana.

Sin saber programar. En serio, no como descargo de responsabilidad. Lo que vas a escribir son instrucciones en lenguaje natural. Claude Code gestiona la parte técnica. Tú defines el qué. Él resuelve el cómo.

Paso 1: Instalar Claude Code y activar la licencia

Claude Code funciona en terminal. Necesitas Node.js instalado en tu máquina. Si estás en Windows, funciona perfectamente con WSL2 o directamente desde la terminal de PowerShell o CMD.

La instalación es un único comando en terminal. Una vez instalado, lo conectas con tu cuenta de Anthropic mediante otro comando que abre el navegador para autenticarte. El proceso completo lleva menos de cinco minutos.

Para usarlo de forma real necesitas una licencia de Claude. Los precios actuales están en la web de Anthropic y varían según el plan (individual o equipos). Una vez autenticado, entras en la carpeta donde quieras trabajar y lanzas Claude Code desde la terminal.

Verás el cursor esperando. El agente está activo. Aún no sabe nada sobre qué debe hacer. Para eso existe el paso 2.

Paso 2: Crear el CLAUDE.md — el archivo que lo cambia todo

El error que veo casi siempre en el primer CLAUDE.md es que no existe. La persona instala Claude Code, empieza a usarlo, y trabaja en modo conversacional sin instrucciones persistentes. Funciona para cosas puntuales. Para un agente que hace algo concreto y lo hace bien de forma consistente, necesitas el CLAUDE.md.

El CLAUDE.md es el archivo de instrucciones permanentes del agente. Se lee automáticamente cada vez que Claude Code se inicia en esa carpeta. Es lo que convierte una herramienta de IA genérica en un agente especializado en tu dominio, con tus reglas, con tus restricciones y con tus formatos de salida.

No es código. Es un archivo de texto con extensión .md (Markdown) que escribes tú en lenguaje normal.

Créalo en la raíz de tu carpeta de proyecto con cualquier editor de texto. Lo que escribas ahí es lo que el agente tendrá como contexto permanente desde el primer momento de cada sesión.

Paso 3: La anatomía de un CLAUDE.md que funciona

Un CLAUDE.md tiene seis secciones. No todas son obligatorias desde el principio, pero conocerlas te ayuda a decidir qué incluir y qué omitir en la primera versión.

Identidad del agente

Quién es el agente, en una o dos frases. No «eres un asistente útil». Eso no sirve. Algo concreto: qué rol tiene, en qué contexto opera, a quién ayuda.

Dominio

De qué temas y tareas se ocupa. Igual de importante: de qué NO se ocupa. El límite del dominio es lo que evita que el agente intente hacer todo y termine haciendo nada bien.

Principios operativos

Cómo trabaja. Qué estándares de calidad aplica. Qué prioriza cuando hay que elegir. Estos principios son los que distinguen un agente que produce resultados útiles de uno que produce resultados genéricos.

Restricciones

Lo que nunca hace. Qué tipo de contenido no genera. Qué decisiones no toma sin confirmación humana. Las restricciones son seguridad: definen dónde el agente se detiene y pide instrucciones en lugar de seguir solo.

Herramientas disponibles (MCPs)

Qué integraciones tiene el agente. Si puede leer desde Google Drive, si puede escribir en Notion, si tiene acceso a una base de datos. Esta sección la ampliamos en el paso 4.

Formato de salida

Cómo entrega los resultados. Lista, tabla, párrafo, JSON, correo formateado. Sin esta sección, el agente decide el formato él solo y no siempre elige el que mejor te funciona a ti.

Qué tiene un CLAUDE.md que funciona

Un CLAUDE.md efectivo define el rol con precisión, pone límites explícitos, y especifica el formato de salida. Un directivo que lo lea entiende exactamente qué hace el agente y qué no hace. Eso es lo que diferencia un CLAUDE.md que funciona en producción de uno que produce resultados inconsistentes.

La estructura mínima funcional: identidad concreta del agente, dominio explícito (qué sí hace y qué no), principios operativos, restricciones para los casos límite, y formato de salida. Esas seis secciones son suficientes para el primer agente.

El contenido concreto —qué tareas cubre, con qué criterios, en qué formato— es específico de cada empresa, cada departamento y cada operación. No hay un CLAUDE.md genérico que funcione bien para todo el mundo. Es lo que se trabaja en el curso: cada participante escribe el CLAUDE.md de sus propios agentes, con sus propios datos y su propia operación.

Paso 4: Conectar el primer MCP

MCP son las siglas de Model Context Protocol. Es el estándar que permite a Claude Code conectarse con herramientas externas: Google Drive, Notion, calendarios, bases de datos, APIs de empresa. Sin MCPs, el agente opera solo sobre los archivos que están en tu carpeta local. Con MCPs, tiene acceso a sistemas reales.

Para el primer agente, recomiendo empezar con Google Drive o Notion. Motivos concretos: son las integraciones con menor fricción técnica de configuración, están documentadas con ejemplos, y casi cualquier empresa ya los usa, lo que significa que el agente puede trabajar con documentos reales desde el primer día.

La configuración del MCP se hace en el archivo .mcp.json en la misma carpeta que el CLAUDE.md. Puedes leer el detalle de cómo conectar cada integración en el artículo sobre MCPs y herramientas de integración en Claude Code.

La idea clave para este paso: no necesitas conectar todo desde el principio. Un agente con un único MCP bien configurado es más útil que un agente con cinco MCPs mal definidos. Empieza por la herramienta donde ya tienes los documentos que quieres procesar. El agente crece desde ahí.

Paso 5: La primera tarea real — procesar un documento y extraer compromisos

La primera tarea tiene que ser algo que puedas verificar con tus propios ojos. No algo abstracto. No un experimento. Algo concreto: un documento que ya tienes, una salida que sabes cómo debería verse.

Ejemplo que funciona bien para empezar: las notas de tu última reunión importante. Tienes el documento. Sabes qué compromisos se acordaron porque estabas ahí. Puedes comparar lo que el agente extrae con lo que sabes tú que había.

Una vez que el agente está configurado con el CLAUDE.md del paso 3, le das la tarea en lenguaje natural: describirle el documento y pedirle que extraiga los compromisos según sus instrucciones.

Y entonces ocurre algo que muchos ven por primera vez y les cambia la perspectiva. El agente no simplemente ejecuta. Entra en un bucle que tiene cuatro fases:

Percibir: lee el documento. Lo analiza. Entiende el contexto, los participantes, el tipo de reunión.

Planificar: decide cómo abordarlo. Qué buscar primero. Qué criterios aplicar para distinguir un compromiso de una observación.

Actuar: ejecuta. Extrae, clasifica, formatea según las instrucciones del CLAUDE.md.

Evaluar: comprueba su propio resultado antes de entregártelo. Si algo no encaja con las instrucciones que le diste, itera.

Ves las cuatro fases en tiempo real en la terminal. Eso es lo que hace que Claude Code sea diferente de un prompt en un chat. No es una respuesta. Es un proceso.

Los errores que matan el primer agente

He visto fallar primeros agentes por las mismas razones repetidas. Cuatro en concreto. Si las evitas desde el principio, el agente funciona. Si no, acabas con algo que parece que funciona en el primer uso y se degrada a medida que encuentras casos que no contemplaste.

Instrucciones vagas en la identidad

«Eres un asistente útil y profesional.» No sirve. El agente no sabe qué es útil para ti, en qué contexto, con qué restricciones. Cuanto más genérico el CLAUDE.md, más genéricos e inconsistentes los resultados. La especificidad no es opcional en el primer CLAUDE.md: es lo que hace que el agente sea tuyo y no de nadie.

Sin límite de dominio

«Ayúdame con todo lo de mi departamento.» Sin saber exactamente qué es «todo», el agente interpreta en el momento, y no siempre bien. Definir qué no hace el agente es tan importante como definir qué hace. Los mejores CLAUDE.md tienen una sección explícita de «No haces:».

Sin criterios de éxito

Si no defines qué es un resultado correcto, el agente no puede evaluar su propio trabajo. Eso produce resultados que parecen razonables pero no son consistentes. «El resumen debe tener entre 5 y 10 puntos, ordenados por urgencia, sin repeticiones» es un criterio. «Dame un buen resumen» no lo es.

Sin instrucciones para los casos límite

¿Qué hace el agente cuando el documento está incompleto? ¿Cuando hay información contradictoria? ¿Cuando no entiende un término técnico de tu sector? Sin instrucciones explícitas para estos casos, el agente elige. A veces bien, a veces no. La sección de restricciones del CLAUDE.md es donde defines el comportamiento en los bordes.

El CLAUDE.md es el activo que construyes

Cuando alguien me pregunta qué es lo más importante para construir un agente que funcione, la respuesta siempre es la misma: el CLAUDE.md. No el modelo de IA. No la herramienta técnica. Las instrucciones.

Un CLAUDE.md bien escrito para tu departamento contiene conocimiento que tardas años en acumular: cómo opera tu equipo, qué es urgente y qué no, qué formato funciona para tu empresa, qué decisiones son del agente y cuáles las toma siempre un humano. Ese conocimiento, formalizado en instrucciones claras, es lo que convierte el agente en algo útil y consistente.

El CLAUDE.md también mejora. Cada vez que el agente produce un resultado que no es el que querías, actualizas una línea. Añades una restricción. Aclaras un criterio. Con tres o cuatro iteraciones en casos reales, tienes un agente que funciona de forma fiable para tu caso de uso concreto.

Y eso, el proceso de escribir, usar, corregir y refinar el CLAUDE.md, es exactamente lo que se trabaja en el curso de un día. Cada participante sale con el CLAUDE.md de sus propios departamentos, no con un ejemplo genérico. Porque el valor no está en el template. Está en que sea tuyo.

Si quieres entender antes qué es exactamente un agente de IA y en qué se diferencia de un chatbot, te recomiendo leer primero el artículo sobre qué es un agente de IA y en qué se diferencia de un chatbot. Es el contexto que hace que todo lo anterior tenga más sentido.

Preguntas frecuentes

¿Cuánto cuesta la licencia de Claude Code?

Claude Code en sí es gratuito: es una herramienta de línea de comandos de Anthropic que se instala sin coste. Lo que tiene coste es el acceso al modelo de IA que hay detrás. Anthropic ofrece diferentes planes según el uso: individual, equipos y acceso directo a la API con pago por uso para automatizaciones de alto volumen. Los precios actuales y las diferencias entre planes están en la web de Anthropic.

¿Funciona en Windows?

Sí. Claude Code funciona en Windows de tres formas: mediante WSL2 (Windows Subsystem for Linux), que es la opción recomendada para mayor compatibilidad; directamente desde PowerShell con Node.js instalado; o desde el terminal integrado de VS Code. En la práctica, la mayoría de los directivos que han pasado por el curso lo han instalado en Windows sin incidencias. El proceso no requiere ningún conocimiento técnico más allá de ejecutar dos comandos en terminal.

¿Necesito saber programar para construir un agente?

No. Lo que describes en el CLAUDE.md son instrucciones en español. No hay sintaxis de programación, no hay código. Claude Code interpreta el lenguaje natural y decide cómo ejecutar lo que le pides. Donde sí puede aparecer algo técnico es en la configuración de algunos MCPs, pero incluso ahí las guías oficiales son suficientemente claras y no requieren conocimientos previos. La parte más exigente no es técnica: es saber qué quieres que haga el agente con suficiente precisión para escribirlo de forma que él lo entienda siempre igual.

¿Cuánto tiempo lleva tener el primer agente funcionando?

Si tienes claro el dominio del agente, entre dos y cuatro horas para la primera versión funcional. Eso incluye instalación, CLAUDE.md inicial, primera prueba con un documento real y primeras correcciones. Lo que tarda más no es la parte técnica sino la parte conceptual: decidir exactamente qué hace el agente, qué no hace, y cómo debe formatear los resultados. Una vez tienes eso claro por escrito, la implementación es rápida.

¿Puedo construir agentes para varios departamentos?

Sí, y es lo habitual. Cada departamento tiene su propia carpeta con su propio CLAUDE.md. El agente de marketing no tiene por qué conocer las instrucciones del agente de legal, y viceversa. La separación por carpetas también es separación de contexto: el agente solo conoce lo que está en su CLAUDE.md y en los archivos de su directorio. Esto es una ventaja de seguridad y también de rendimiento: agentes más focalizados producen resultados más consistentes.