Escritos /
Agentes de código, lo básico: Claude Code para profesionales sanitarios
Cómo trabaja un agente de código como Claude Code y cómo mantenerlo bajo control, contado con un informe ficticio de HbA1c: reglas, contexto, subagentes, skills, privacidad y qué modelo usar.
Un agente de código es un programa que no se limita a responder: lee tus archivos, escribe scripts, los ejecuta y mira el resultado, una y otra vez, hasta terminar la tarea. Este tutorial explica cómo funciona y cómo mantenerlo bajo control, para profesionales sanitarios que quieren usarlo con sus propios datos.
Sigue la parte básica del curso Claude Code 101 de Anthropic, con un solo caso de principio a fin: un informe trimestral de HbA1c a partir de doce hojas de analíticas. Los datos son ficticios. Conectar herramientas externas (MCP) y las reglas que se cumplen siempre (hooks) quedan para un segundo post, más a fondo.






















Texto de las diapositivas
- TUTORIAL · CLAUDE CODE 101, LO BÁSICO · Agentes de código:lo básico · Cómo trabaja un agente como Claude Code y cómo mantenerlo bajo control, explicado para profesionales sanitarios. · José Manuel Ramírez Sánchez · jmramirez.engineer · noviembre de 2026
- EL CASO · Un informe trimestral de HbA1c · Una carpeta con analíticas anonimizadas y ficticias. Pedimos al agente el informe del trimestre y lo hacemos siempre en cuatro pasos. · 1 · Explorar · Lee la carpeta y describe los datos. No cambia nada. · → · 2 · Planificar · Propone los pasos. Tú los corriges y apruebas. · → · 3 · Ejecutar · Escribe y ejecuta los scripts sobre copias. · → · 4 · Revisar · Compruebas el resultado. La responsabilidad es tuya. · En Claude Code 101 este flujo se llama explore → plan → code → commit. · Agentes de código: lo básico · jmramirez.engineer
- 01 · FUNDAMENTOS · Qué es un agente · Un chat · Contesta una vez. Si algo falla, tienes que darte cuenta tú. · Un agente · Repite un bucle hasta cumplir el objetivo: piensa, actúa con una herramienta y observa el resultado. · VueltaPiensaActúaObserva 1¿Qué archivos hay?ls datos/12 CSV de analíticas 2Los uno con un scriptpython unir.pyError: no existe «Fecha» 3Corrijo el nombre de la columnapython unir.pytabla_unida.csv creada Agentes de código: lo básico · jmramirez.engineer
- 02 · FUNDAMENTOS · La carpeta de trabajo · proyecto-hba1c/ · ├─ AGENTS.md reglas · ├─ datos/ · │ ├─ originales/ no se tocan · │ └─ trabajo/ copias · ├─ scripts/ · └─ resultados/ se entrega · Es el escritorio del agente · Solo ve lo que hay dentro. Para leer o escribir fuera, te pide permiso. · Lo primero que lee: AGENTS.md · Y la estructura le dice qué es cada cosa. · Originales aparte, copias para trabajar, resultados aparte. · Agentes de código: lo básico · jmramirez.engineer
- 02 · FUNDAMENTOS · Los modos de permisos · Shift+Tab cambia de modo en mitad de la sesión. · ModoQué haceCuándo Pedir permisoPregunta antes de editar un archivo o ejecutar un comandoPor defecto, y siempre al empezar Aceptar edicionesEdita sin preguntar; los comandos aún piden permisoCuando ya has aprobado el plan Modo planSolo lee y propone un plan; no edita nadaAntes de tareas con varios pasos Con datos clínicos, empieza pidiendo permiso y lee cada acción antes de aprobarla. · Agentes de código: lo básico · jmramirez.engineer
- 03 · REGLAS POR ESCRITO · AGENTS.md y la regla CORTO · Un archivo de texto con las reglas del proyecto. Se carga entero al empezar cada sesión. · Es contexto, no una orden garantizada: cuanto más corto y concreto, mejor se sigue. · Claude Code lee CLAUDE.md y, si no existe, AGENTS.md. /init crea uno inicial. · C · Concreto: instrucciones que se pueden comprobar · O · Operativo: qué hacer, no la historia · R · Revisado: cada mes, borra lo obsoleto · T · Tamaño: menos de 200 líneas · O · Ordenado: títulos claros; lo específico, en otro archivo · Agentes de código: lo básico · jmramirez.engineer
- 03 · EJEMPLO · Un AGENTS.md para el caso · # Proyecto HbA1c · ## Reglas · - Responde en español. · - Fechas en AAAA-MM-DD. · - No modifiques datos/originales/. · - Antes de borrar filas, pregunta. · ## Datos · - Anonimizados. Columnas: DATOS.md · ## Salidas · - Tablas y gráficas en resultados/. · ## Compact Instructions · - Conserva columnas y decisiones. · De vago a concreto · VagoConcreto «Ordena bien los datos»Fechas en AAAA-MM-DD «Ten cuidado»Antes de borrar filas, pregunta «Sé breve»Respuestas de menos de 10 líneas Nunca escribas aquí datos de pacientes ni contraseñas: el archivo se envía al modelo en cada sesión. · Agentes de código: lo básico · jmramirez.engineer
- 04 · CONTEXTO · La ventana de contexto · Todo lo que el modelo ve a la vez. Tiene un tamaño fijo, medido en tokens. · Antes de compactar · 90 % · Después de /compact · 28 % · Reglas · Conversación · Archivos leídos · Resultados de comandos · Resumen · Se conserva: las reglas enteras, tus peticiones y lo importante. · Puede perderse: instrucciones largas del principio y resultados antiguos. · Agentes de código: lo básico · jmramirez.engineer · porcentajes ilustrativos
- 05 · CONTEXTO · Memoria a corto y a largo plazo · El modelo no recuerda nada entre sesiones. Lo que perdura está en archivos. · MomentoVentana (corto plazo)AGENTS.md (largo plazo) Sesión 1«Pon las fechas como AAAA-MM-DD»Sin cambios Sesión 1«Apúntalo en AGENTS.md»+ Fechas en AAAA-MM-DD /clearSe vacía por completoSigue igual Sesión 2Empieza vacíaSe carga: ya conoce el formato Si quieres que lo recuerde mañana, escríbelo en un archivo. · Agentes de código: lo básico · jmramirez.engineer
- 06 · CONTROLAR LA SESIÓN · Cinco comandos básicos · ComandoQué haceCuándo /initMira la carpeta y crea un archivo de reglas inicialAl empezar un proyecto /clearConversación nueva; las reglas siguen ahíAl cambiar de tarea /compactResume y libera ventana; puedes decir qué conservarCuando la ventana se llena /rewindVuelve a un punto anterior: código, conversación o ambosSi un paso sale mal /contextMuestra qué ocupa la ventanaSi parece ignorar una regla Una sesión por tarea: /clear al cambiar, /compact al llenarse, /rewind si algo falla. · Agentes de código: lo básico · jmramirez.engineer
- 07 · CONTROLAR LA SESIÓN · Atajos que ahorran tiempo y ventana · AtajoQué hace EscDetiene al agente y conserva lo hecho; lo rediriges sin empezar de cero Shift+TabCambia de modo de permisos, incluido el modo plan @archivoSeñala un archivo concreto: lee solo ese, no toda la carpeta /btwPregunta lateral que no entra en el historial ni ocupa ventana claude --resumeRetoma una sesión anterior; --continue abre la última Si tras dos correcciones sigue fallando: /clear y escribe una petición mejor. · Agentes de código: lo básico · jmramirez.engineer
- EL CASO, EN UNA SESIÓN · Explorar, planificar, ejecutar, revisar · PasoQué pidesQué pasaQué haces Explorar«Lee datos/trabajo/ y describe las columnas. No cambies nada.»Resume 12 CSVCompruebas que entiende los datos PlanificarShift+Tab, modo plan: «Propón cómo hacer el informe»Plan de cuatro pasosLo corriges y lo apruebas Ejecutar«Adelante con el plan»Borra filas que no eran duplicados/rewind y «solo duplicados exactos» EjecutarSigue con la gráficaLa ventana llega al 85 %/compact conserva las columnas Revisar«Compara los totales con los originales»CuadranLo revisas tú y va a resultados/ Agentes de código: lo básico · jmramirez.engineer · datos ficticios
- 08 · DELEGAR · Subagentes: ayudantes con ventana propia · Tu conversación principal · 30 % · sin subagentes, ~90 % · explorador-datos · → resumen · revisor-fechas · → resumen · buscador-duplicados · → resumen · Cómo funciona: cada uno lee mucho en su ventana y a la tuya solo llega un resumen. · Cuándo: tareas que leen mucho. Para una tarea pequeña no compensa. · Agentes de código: lo básico · jmramirez.engineer · porcentajes ilustrativos
- 08 · EJEMPLO · Un subagente es un archivo .md · .claude/agents/revisor-fechas.md · --- · name: revisor-fechas · description: Revisa formatos · de fecha en datos/trabajo/ · tools: Read, Grep · model: haiku · --- · Comprueba que las fechas están · en AAAA-MM-DD. Devuelve un · resumen de 10 líneas como máximo. · No modifiques ningún archivo. · CampoPara qué descriptionCuándo delegar en él toolsQué puede hacer: aquí, solo leer y buscar modelUn modelo pequeño basta para leer instruccionesQué hacer y cuánto devolver Permisos mínimos: un revisor solo necesita leer, no escribir. Y pídele siempre un resumen corto. · Agentes de código: lo básico · jmramirez.engineer
- 09 · REUTILIZAR · Skills: recetas que se cargan a la carta · Una carpeta con un SKILL.md y, si hace falta, scripts y plantillas. Siempre a la vista solo está su descripción. · Al empezar la sesión · 12 % · Al pedir «haz el informe de HbA1c del trimestre» · 37 % · Reglas · Descripciones de las skills · La skill en uso, entera · informe-hba1c · en uso · limpiar-fechas · cartel-congreso · Agentes de código: lo básico · jmramirez.engineer · porcentajes ilustrativos
- 09 · EJEMPLO · Anatomía de una skill · .claude/skills/informe-hba1c/ · ├─ SKILL.md · ├─ plantilla.xlsx · └─ scripts/grafica.py · --- · name: informe-hba1c · description: Crea el informe · trimestral de HbA1c. Úsala · si piden ese informe. · --- · 1. Lee la tabla de resultados/. · 2. Calcula media y mediana. · 3. Ejecuta scripts/grafica.py. · Dónde viveQuién la usa ~/.claude/skills/Tú, en todos tus proyectos .claude/skills/Quien trabaje en ese proyecto Se activa sola si tu petición encaja con la descripción, o a mano con /informe-hba1c. · SKILL.md corto: menos de 500 líneas; el detalle, en archivos aparte. · La descripción lo decide todo: di qué hace y cuándo usarla. · Agentes de código: lo básico · jmramirez.engineer
- 08 + 09 · COMPARATIVA · ¿AGENTS.md, skill o subagente? · PiezaCuándo se cargaPara qué sirveEjemplo AGENTS.mdSiempre, enteroReglas del proyecto«Fechas en AAAA-MM-DD» SkillA la carta, si encajaUn procedimiento repetibleEl informe trimestral de HbA1c SubagenteCuando se le delegaTrabajo pesado aparte; devuelve un resumenRevisar 40 CSV sin llenar tu ventana Lo que siempre vale, a AGENTS.md. Lo que haces a veces, a una skill. Lo que ensucia la ventana, a un subagente. · Agentes de código: lo básico · jmramirez.engineer
- 10 · DÓNDE CORRE · Local o cloud · AspectoLocalCloud Dónde correTu ordenadorUna máquina aislada de Anthropic ArchivosLos tuyos, realesUna copia de tu repositorio de GitHub Portátil cerradoSe detieneSigue trabajando RevisiónVes cada cambio al momentoRevisas al terminar, también desde el móvil Ideal paraDatos y tareas interactivasCódigo y tareas largas Disponibilidad según versión y plan. Con configuraciones HIPAA o de retención cero, las sesiones cloud pueden no estar disponibles. · Agentes de código: lo básico · jmramirez.engineer
- EN LOCAL Y EN CLOUD · Lo que el agente lee se envía al modelo. · Anonimiza antes. Datos de pacientes: en local y anonimizados. En cloud, solo código o datos ficticios. · Agentes de código: lo básico · jmramirez.engineer
- 11 · MODELOS · Qué modelo usar: tres reglas · 1 · El más pequeño que resuelva la tarea · Empieza con Haiku o Sonnet. Si falla dos veces, sube a Opus o Fable con /model. · 2 · Escribir cuesta más que leer · En Claude, cada token de salida cuesta 5 veces uno de entrada. Pide respuestas cortas. · 3 · No uses modelos antiguos · Cada generación da más por menos, y las antiguas se retiran: un script con un modelo fijo deja de funcionar. · A 11 de noviembre de 2026: Haiku, Sonnet, Opus y Fable, de más rápido a más capaz. Precios actuales en anthropic.com/pricing. · Agentes de código: lo básico · jmramirez.engineer
- 11 · MODELOS · TERMÓMETRO · El caso HbA1c, con el modelo que toca · 1 · EXPLORAR · Leer la carpeta y listar columnas (subagente) · Claude: Haiku · Abierto: 1–8B · 2 · EXTRAER · Sacar la HbA1c de 200 informes · Claude: Haiku · Abierto: 1–8B · 3 · REDACTAR · Resumen del trimestre a partir de la tabla · Claude: Sonnet · Abierto: 8–32B · 4 · EJECUTAR · Informe completo con scripts y gráficos · Claude: Opus o Sonnet · Abierto: 70B+ · 5 · REVISAR · ¿Se sostienen las conclusiones? · Claude: Fable u Opus · Abierto: 70B+, con dudas · Y DESPUÉS · La decisión clínica es tuya: ningún nivel del termómetro llega ahí. · Orientativo, a 11 de noviembre de 2026 · abierto = en local, tamaño en parámetros · prueba con tu tarea
- PRÁCTICA · Cuatro retos con la carpeta de ejemplo · agentes-practica/ · ├─ AGENTS.md · ├─ DATOS.md · ├─ datos/originales/ · ├─ datos/trabajo/ · ├─ resultados/ · └─ .claude/ · ├─ agents/revisor-fechas.md · └─ skills/informe-hba1c/ · 1 · Abre la carpeta con Claude Code y escribe /context. ¿Se cargó AGENTS.md? · 2 · En modo plan, pide un plan para el informe. Corrígelo antes de aprobar. · 3 · Delega la revisión de fechas en el subagente y compara tu ventana antes y después. · 4 · Lanza /informe-hba1c y comprueba los totales frente a los originales. · Datos 100 % ficticios · descarga en jmramirez.engineer · en tu ordenador
- RESUMEN · Ocho ideas para llevarse · 1 · Un agente actúa en bucle · Tú pones el objetivo y revisas. · 2 · Carpeta ordenada y permisos · Originales aparte; aprueba cada acción al principio. · 3 · Un AGENTS.md CORTO · Reglas comprobables, menos de 200 líneas. · 4 · La ventana es finita · Lo que debe perdurar, a un archivo. · 5 · Explorar, planificar, ejecutar, revisar · Con /clear, /compact, /rewind y Esc a mano. · 6 · Subagentes y skills · Lo pesado se delega; lo repetido se reutiliza. · 7 · Anonimiza siempre · En local y en cloud, lo que lee va al modelo. · 8 · El modelo más pequeño que sirva · Y nunca uno antiguo. · Agentes de código: lo básico · jmramirez.engineer · próximo: MCP y hooks
Todo lo que hay aquí se puede practicar con la carpeta de ejemplo (12 KB, datos ficticios) en tu ordenador. Los retos están al final.
1. Qué es un agente
Un chat contesta una vez: si algo falla, tienes que darte cuenta tú. Un agente repite un bucle hasta cumplir el objetivo. Piensa qué hacer, actúa con una herramienta (lista una carpeta, ejecuta un script) y observa el resultado. Si el script falla porque una columna se llama fecha_extraccion en vez de fecha, el agente lee el error y lo corrige en la vuelta siguiente.
Esa autonomía es lo que lo hace útil, y lo que obliga a trabajar con método. Cada tarea de este tutorial sigue los mismos cuatro pasos:
- Explorar. Lee la carpeta y describe los datos. No cambia nada.
- Planificar. Propone los pasos. Tú los corriges y los apruebas.
- Ejecutar. Escribe y ejecuta los scripts, siempre sobre copias.
- Revisar. Compruebas el resultado. La responsabilidad es tuya.
2. Carpeta ordenada y permisos
El agente trabaja dentro de una carpeta, su escritorio: solo ve lo que hay dentro, y pide permiso para leer o escribir fuera. Los originales, aparte; copias para trabajar, y los resultados, aparte:
proyecto-hba1c/
├─ AGENTS.md reglas
├─ datos/
│ ├─ originales/ no se tocan
│ └─ trabajo/ copias
├─ scripts/
└─ resultados/ se entrega
Claude Code tiene tres modos de permisos, que se cambian con Shift+Tab: pedir permiso antes de editar un archivo o ejecutar un comando (el modo por defecto), aceptar ediciones y modo plan, en el que solo lee y propone. Con datos clínicos, empieza pidiendo permiso y lee cada acción antes de aprobarla.
3. Las reglas, por escrito: AGENTS.md
El agente no recuerda nada entre sesiones. Lo que tiene que saber siempre va en un archivo de texto en la raíz del proyecto, que se carga entero al empezar cada sesión. Claude Code lee CLAUDE.md y, si no existe, AGENTS.md, el nombre que usan también otros agentes; /init escribe una primera versión.
# Proyecto HbA1c
## Reglas
- Responde en español.
- Fechas en AAAA-MM-DD.
- No modifiques datos/originales/.
- Antes de borrar filas, pregunta.
## Datos
- Anonimizados. Columnas: DATOS.md
## Salidas
- Tablas y gráficas en resultados/.
## Compact Instructions
- Conserva columnas y decisiones.
Es contexto, no una orden garantizada, así que tiene que ser CORTO: Concreto (reglas que se pueden comprobar: «fechas en AAAA-MM-DD», no «ordena bien los datos»), Operativo (qué hacer, no la historia), Revisado (cada mes, borra lo obsoleto), de Tamaño contenido (menos de 200 líneas) y Ordenado (títulos claros; el detalle, en otros archivos, como DATOS.md).
Nunca escribas en él datos de pacientes ni contraseñas: el archivo se envía al modelo en cada sesión.
4. La ventana de contexto
La ventana es todo lo que el modelo ve a la vez: las reglas, la conversación, los archivos que ha leído y los resultados de sus comandos. Tiene un tamaño fijo, medido en tokens. Tus mensajes son lo que menos ocupa; lo que la llena son los archivos y los resultados largos.
Cerca del límite, la conversación se compacta: se resume para hacer sitio. Puedes pedirlo con /compact conserva las columnas, o lo hace el agente solo. AGENTS.md sigue entero; las instrucciones largas dichas al principio del chat pueden perderse. La regla es sencilla: si quieres que lo recuerde mañana, escríbelo en un archivo. /context muestra qué ocupa la ventana.
5. Controlar la sesión
Cinco comandos cubren casi todo:
| Comando | Qué hace | Cuándo |
|---|---|---|
/init | Mira la carpeta y crea un archivo de reglas inicial | Al empezar un proyecto |
/clear | Conversación nueva; las reglas siguen ahí | Al cambiar de tarea |
/compact | Resume y libera ventana; puedes decir qué conservar | Cuando la ventana se llena |
/rewind | Vuelve a un punto anterior: código, conversación o ambos | Si un paso sale mal |
/context | Muestra qué ocupa la ventana | Si parece ignorar una regla |
Esc detiene al agente sin perder lo hecho, y @archivo señala un archivo concreto para que no lea toda la carpeta. Si tras dos correcciones sigue fallando, /clear y escribe una petición mejor.
Este es el caso completo en una sesión:
| Paso | Qué pides | Qué pasa | Qué haces |
|---|---|---|---|
| Explorar | «Lee datos/trabajo/ y describe las columnas. No cambies nada.» | Resume 12 CSV | Compruebas que entiende los datos |
| Planificar | Shift+Tab, modo plan: «Propón cómo hacer el informe» | Plan de cuatro pasos | Lo corriges y lo apruebas |
| Ejecutar | «Adelante con el plan» | Borra filas que no eran duplicadas | /rewind y «solo duplicados exactos» |
| Ejecutar | Sigue con la gráfica | La ventana llega al 85 % | /compact conserva las columnas |
| Revisar | «Compara los totales con los originales» | Cuadran | Lo revisas tú y va a resultados/ |
6. Delegar y reutilizar: subagentes y skills
Un subagente es un ayudante con ventana propia. Lee mucho en su ventana y a la tuya solo llega un resumen. Es un archivo Markdown en .claude/agents/:
---
name: revisor-fechas
description: Revisa formatos de fecha en datos/trabajo/
tools: Read, Grep
model: haiku
---
Comprueba que las fechas están en AAAA-MM-DD. Devuelve un
resumen de 10 líneas como máximo. No modifiques ningún archivo.
Dale los permisos mínimos (un revisor solo necesita leer) y pídele un resumen corto. Para una tarea pequeña no compensa.
Una skill es una receta que se carga a la carta: una carpeta con un SKILL.md y, si hace falta, scripts y plantillas. Siempre a la vista solo está su descripción; el resto se carga cuando tu petición encaja con ella, o cuando la llamas por su nombre (/informe-hba1c). La descripción lo decide todo: di qué hace y cuándo usarla, y mantén SKILL.md por debajo de 500 líneas.
Lo que siempre vale, a AGENTS.md. Lo que haces a veces, a una skill. Lo que ensucia la ventana, a un subagente.
7. Local o cloud, y privacidad
Claude Code puede correr en tu ordenador, con tus archivos reales, o en la nube, en una máquina aislada con una copia de tu repositorio, donde sigue trabajando con el portátil cerrado. Lo que no cambia es esto: lo que el agente lee se envía al modelo, corra donde corra. Anonimiza antes. Con datos de pacientes: en local y anonimizados. En cloud, solo código o datos ficticios. Ante la duda, consulta a tu delegado de protección de datos.
8. Qué modelo, para qué tarea
Los nombres y los precios de los modelos cambian cada pocas semanas; el tipo de tarea no. En vez de una tabla de modelos, un termómetro: cuatro niveles de tarea, cada uno con el modelo más pequeño que suele bastar. Para Claude da la gama, porque Anthropic no publica cuántos parámetros tienen sus modelos. Para los modelos abiertos que ejecutas en tu ordenador da el tamaño, que es público y decide si el modelo cabe en tu equipo.
Decisión clínica: ningún modelo sustituye tu criterio.
Empieza abajo. Sube un nivel solo si falla dos veces.
En el caso Sacar el valor de HbA1c de 200 informes, o describir las columnas de una carpeta (un subagente lector).
Una creencia que conviene corregir: los modelos pequeños no sirven para charlar ni para preguntarles datos, porque inventan. Sirven para transformar el texto que tú les das: extraer, clasificar, normalizar. Una misma sesión puede mezclar niveles: un subagente lector con Haiku mientras la conversación principal usa un modelo mayor.
Tres reglas que no caducan: usa el modelo más pequeño que resuelva la tarea y sube con /model si falla dos veces; pide respuestas cortas, porque escribir cuesta más que leer (en Claude, cada token de salida cuesta cinco veces uno de entrada), y no uses modelos antiguos, porque cada generación da más por menos y las antiguas se retiran. Los precios actuales están en anthropic.com/pricing.
Práctica: cuatro retos
Descarga la carpeta de ejemplo: doce CSV de analíticas de HbA1c ficticias de cuatro centros, el AGENTS.md de arriba, un diccionario de datos, el subagente revisor-fechas y la skill informe-hba1c. Ábrela con Claude Code en tu ordenador; no hace falta notebook ni servidor.
- Escribe
/context. ¿Se cargó AGENTS.md? - En modo plan, pide un plan para el informe. Corrígelo antes de aprobarlo. Los archivos no son todos iguales.
- Delega la revisión de fechas en el subagente y compara tu ventana antes y después.
- Lanza
/informe-hba1cy comprueba los totales frente a los originales.
Si la terminal es nueva para ti, el 10 % de la terminal que te resuelve el 90 % cubre lo necesario para llegar hasta aquí.