Escritos /
Axentes de código, o básico: Claude Code para profesionais sanitarios
Como traballa un axente de código como Claude Code e como mantelo baixo control, contado cun informe ficticio de HbA1c: regras, contexto, subaxentes, skills, privacidade e que modelo usar.
Un axente de código é un programa que non se limita a responder: le os teus ficheiros, escribe scripts, execútaos e mira o resultado, unha e outra vez, ata rematar a tarefa. Este titorial explica como funciona e como mantelo baixo control, para profesionais sanitarios que queren usalo cos seus propios datos.
Segue a parte básica do curso Claude Code 101 de Anthropic, cun só caso de principio a fin: un informe trimestral de HbA1c a partir de doce follas de analíticas. Os datos son ficticios. Conectar ferramentas externas (MCP) e as regras que se cumpren sempre (hooks) quedan para un segundo post, máis a fondo.






















Texto das diapositivas
- TUTORIAL · CLAUDE CODE 101, O BÁSICO · Axentes de código:o básico · Como traballa un axente como Claude Code e como mantelo baixo control, explicado para profesionais sanitarios. · José Manuel Ramírez Sánchez · jmramirez.engineer · novembro de 2026
- O CASO · Un informe trimestral de HbA1c · Un cartafol con analíticas anonimizadas e ficticias. Pedímoslle ao axente o informe do trimestre e facémolo sempre en catro pasos. · 1 · Explorar · Le o cartafol e describe os datos. Non cambia nada. · → · 2 · Planificar · Propón os pasos. Ti corríxelos e apróbalos. · → · 3 · Executar · Escribe e executa os scripts sobre copias. · → · 4 · Revisar · Comprobas o resultado. A responsabilidade é túa. · En Claude Code 101 este fluxo chámase explore → plan → code → commit. · Axentes de código: o básico · jmramirez.engineer
- 01 · FUNDAMENTOS · Que é un axente · Un chat · Contesta unha vez. Se algo falla, tes que decatarte ti. · Un axente · Repite un bucle ata cumprir o obxectivo: pensa, actúa cunha ferramenta e observa o resultado. · VoltaPensaActúaObserva 1Que ficheiros hai?ls datos/12 CSV de analíticas 2Únoos cun scriptpython unir.pyErro: non existe «Data» 3Corrixo o nome da columnapython unir.pytaboa_unida.csv creada Axentes de código: o básico · jmramirez.engineer
- 02 · FUNDAMENTOS · O cartafol de traballo · proxecto-hba1c/ · ├─ AGENTS.md regras · ├─ datos/ · │ ├─ orixinais/ non se tocan · │ └─ traballo/ copias · ├─ scripts/ · └─ resultados/ entrégase · É o escritorio do axente · Só ve o que hai dentro. Para ler ou escribir fóra, pídeche permiso. · O primeiro que le: AGENTS.md · E a estrutura dille que é cada cousa. · Orixinais á parte, copias para traballar, resultados á parte. · Axentes de código: o básico · jmramirez.engineer
- 02 · FUNDAMENTOS · Os modos de permisos · Shift+Tab cambia de modo en plena sesión. · ModoQue faiCando Pedir permisoPregunta antes de editar un ficheiro ou executar un comandoPor defecto, e sempre ao comezar Aceptar ediciónsEdita sen preguntar; os comandos aínda piden permisoCando xa aprobaches o plan Modo planSó le e propón un plan; non edita nadaAntes de tarefas con varios pasos Con datos clínicos, comeza pedindo permiso e le cada acción antes de aprobala. · Axentes de código: o básico · jmramirez.engineer
- 03 · REGRAS POR ESCRITO · AGENTS.md e a regra CURTO · Un ficheiro de texto coas regras do proxecto. Cárgase enteiro ao comezar cada sesión. · É contexto, non unha orde garantida: canto máis curto e concreto, mellor se segue. · Claude Code le CLAUDE.md e, se non existe, AGENTS.md. /init crea un inicial. · C · Concreto: instrucións que se poden comprobar · U · Útil: que facer, non a historia · R · Revisado: cada mes, borra o obsoleto · T · Tamaño: menos de 200 liñas · O · Ordenado: títulos claros; o específico, noutro ficheiro · Axentes de código: o básico · jmramirez.engineer
- 03 · EXEMPLO · Un AGENTS.md para o caso · # Proxecto HbA1c · ## Regras · - Responde en galego. · - Datas en AAAA-MM-DD. · - Non modifiques datos/orixinais/. · - Antes de borrar filas, pregunta. · ## Datos · - Anonimizados. Columnas: DATOS.md · ## Saídas · - Táboas e gráficas en resultados/. · ## Compact Instructions · - Conserva columnas e decisións. · De vago a concreto · VagoConcreto «Ordena ben os datos»Datas en AAAA-MM-DD «Ten coidado»Antes de borrar filas, pregunta «Sé breve»Respostas de menos de 10 liñas Nunca escribas aquí datos de pacientes nin contrasinais: o ficheiro envíase ao modelo en cada sesión. · Axentes de código: o básico · jmramirez.engineer
- 04 · CONTEXTO · A xanela de contexto · Todo o que o modelo ve á vez. Ten un tamaño fixo, medido en tokens. · Antes de compactar · 90 % · Despois de /compact · 28 % · Regras · Conversa · Ficheiros lidos · Resultados de comandos · Resumo · Consérvase: as regras enteiras, as túas peticións e o importante. · Pode perderse: instrucións longas do principio e resultados antigos. · Axentes de código: o básico · jmramirez.engineer · porcentaxes ilustrativas
- 05 · CONTEXTO · Memoria a curto e a longo prazo · O modelo non lembra nada entre sesións. O que perdura está en ficheiros. · MomentoXanela (curto prazo)AGENTS.md (longo prazo) Sesión 1«Pon as datas como AAAA-MM-DD»Sen cambios Sesión 1«Apúntao en AGENTS.md»+ Datas en AAAA-MM-DD /clearBaléirase por completoSegue igual Sesión 2Comeza baleiraCárgase: xa coñece o formato Se queres que o lembre mañá, escríbeo nun ficheiro. · Axentes de código: o básico · jmramirez.engineer
- 06 · CONTROLAR A SESIÓN · Cinco comandos básicos · ComandoQue faiCando /initMira o cartafol e crea un ficheiro de regras inicialAo comezar un proxecto /clearConversa nova; as regras seguen aíAo cambiar de tarefa /compactResume e libera xanela; podes dicir que conservarCando a xanela se enche /rewindVolve a un punto anterior: código, conversa ou ambosSe un paso sae mal /contextMostra que ocupa a xanelaSe parece ignorar unha regra Unha sesión por tarefa: /clear ao cambiar, /compact ao encherse, /rewind se algo falla. · Axentes de código: o básico · jmramirez.engineer
- 07 · CONTROLAR A SESIÓN · Atallos que aforran tempo e xanela · AtalloQue fai EscDetén o axente e conserva o feito; rediríxelo sen comezar de cero Shift+TabCambia de modo de permisos, incluído o modo plan @ficheiroSinala un ficheiro concreto: le só ese, non todo o cartafol /btwPregunta lateral que non entra no historial nin ocupa xanela claude --resumeRetoma unha sesión anterior; --continue abre a última Se tras dúas correccións segue fallando: /clear e escribe unha petición mellor. · Axentes de código: o básico · jmramirez.engineer
- O CASO, NUNHA SESIÓN · Explorar, planificar, executar, revisar · PasoQue pidesQue pasaQue fas Explorar«Le datos/traballo/ e describe as columnas. Non cambies nada.»Resume 12 CSVComprobas que entende os datos PlanificarShift+Tab, modo plan: «Propón como facer o informe»Plan de catro pasosCorríxelo e apróbalo Executar«Adiante co plan»Borra filas que non eran duplicados/rewind e «só duplicados exactos» ExecutarSegue coa gráficaA xanela chega ao 85 %/compact conserva as columnas Revisar«Compara os totais cos orixinais»CadranRevísalo ti e vai a resultados/ Axentes de código: o básico · jmramirez.engineer · datos ficticios
- 08 · DELEGAR · Subaxentes: axudantes con xanela propia · A túa conversa principal · 30 % · sen subaxentes, ~90 % · explorador-datos · → resumo · revisor-datas · → resumo · buscador-duplicados · → resumo · Como funciona: cada un le moito na súa xanela e á túa só chega un resumo. · Cando: tarefas que len moito. Para unha tarefa pequena non compensa. · Axentes de código: o básico · jmramirez.engineer · porcentaxes ilustrativas
- 08 · EXEMPLO · Un subaxente é un ficheiro .md · .claude/agents/revisor-datas.md · --- · name: revisor-datas · description: Revisa formatos · de data en datos/traballo/ · tools: Read, Grep · model: haiku · --- · Comproba que as datas están · en AAAA-MM-DD. Devolve un · resumo de 10 liñas como máximo. · Non modifiques ningún ficheiro. · CampoPara que descriptionCando delegar nel toolsQue pode facer: aquí, só ler e buscar modelUn modelo pequeno abonda para ler instruciónsQue facer e canto devolver Permisos mínimos: un revisor só precisa ler, non escribir. E pídelle sempre un resumo curto. · Axentes de código: o básico · jmramirez.engineer
- 09 · REUTILIZAR · Skills: receitas que se cargan á carta · Un cartafol cun SKILL.md e, se fai falta, scripts e modelos. Sempre á vista só está a súa descrición. · Ao comezar a sesión · 12 % · Ao pedir «fai o informe de HbA1c do trimestre» · 37 % · Regras · Descricións das skills · A skill en uso, enteira · informe-hba1c · en uso · limpar-datas · cartel-congreso · Axentes de código: o básico · jmramirez.engineer · porcentaxes ilustrativas
- 09 · EXEMPLO · Anatomía dunha skill · .claude/skills/informe-hba1c/ · ├─ SKILL.md · ├─ modelo.xlsx · └─ scripts/grafica.py · --- · name: informe-hba1c · description: Crea o informe · trimestral de HbA1c. Úsaa · se piden ese informe. · --- · 1. Le a táboa de resultados/. · 2. Calcula media e mediana. · 3. Executa scripts/grafica.py. · Onde viveQuen a usa ~/.claude/skills/Ti, en todos os teus proxectos .claude/skills/Quen traballe nese proxecto Actívase soa se a túa petición encaixa coa descrición, ou a man con /informe-hba1c. · SKILL.md curto: menos de 500 liñas; o detalle, en ficheiros á parte. · A descrición decídeo todo: di que fai e cando usala. · Axentes de código: o básico · jmramirez.engineer
- 08 + 09 · COMPARATIVA · AGENTS.md, skill ou subaxente? · PezaCando se cargaPara que serveExemplo AGENTS.mdSempre, enteiroRegras do proxecto«Datas en AAAA-MM-DD» SkillÁ carta, se encaixaUn procedemento repetibleO informe trimestral de HbA1c SubaxenteCando se lle delegaTraballo pesado á parte; devolve un resumoRevisar 40 CSV sen encher a túa xanela O que sempre vale, a AGENTS.md. O que fas ás veces, a unha skill. O que ensucia a xanela, a un subaxente. · Axentes de código: o básico · jmramirez.engineer
- 10 · ONDE CORRE · Local ou cloud · AspectoLocalCloud Onde correO teu ordenadorUnha máquina illada de Anthropic FicheirosOs teus, reaisUnha copia do teu repositorio de GitHub Portátil pechadoDetenseSegue traballando RevisiónVes cada cambio ao momentoRevisas ao rematar, tamén desde o móbil Ideal paraDatos e tarefas interactivasCódigo e tarefas longas Dispoñibilidade segundo versión e plan. Con configuracións HIPAA ou de retención cero, as sesións cloud poden non estar dispoñibles. · Axentes de código: o básico · jmramirez.engineer
- EN LOCAL E EN CLOUD · O que o axente le envíase ao modelo. · Anonimiza antes. Datos de pacientes: en local e anonimizados. En cloud, só código ou datos ficticios. · Axentes de código: o básico · jmramirez.engineer
- 11 · MODELOS · Que modelo usar: tres regras · 1 · O máis pequeno que resolva a tarefa · Comeza con Haiku ou Sonnet. Se falla dúas veces, sube a Opus ou Fable con /model. · 2 · Escribir custa máis que ler · En Claude, cada token de saída custa 5 veces un de entrada. Pide respostas curtas. · 3 · Non uses modelos antigos · Cada xeración dá máis por menos, e as antigas retíranse: un script cun modelo fixo deixa de funcionar. · A 11 de novembro de 2026: Haiku, Sonnet, Opus e Fable, de máis rápido a máis capaz. Prezos actuais en anthropic.com/pricing. · Axentes de código: o básico · jmramirez.engineer
- 11 · MODELOS · TERMÓMETRO · O caso HbA1c, co modelo que toca · 1 · EXPLORAR · Ler o cartafol e listar columnas (subaxente) · Claude: Haiku · Aberto: 1–8B · 2 · EXTRAER · Sacar a HbA1c de 200 informes · Claude: Haiku · Aberto: 1–8B · 3 · REDACTAR · Resumo do trimestre a partir da táboa · Claude: Sonnet · Aberto: 8–32B · 4 · EXECUTAR · Informe completo con scripts e gráficos · Claude: Opus ou Sonnet · Aberto: 70B+ · 5 · REVISAR · Sostéñense as conclusións? · Claude: Fable ou Opus · Aberto: 70B+, con dúbidas · E DESPOIS · A decisión clínica é túa: ningún nivel do termómetro chega aí. · Orientativo, a 11 de novembro de 2026 · aberto = en local, tamaño en parámetros · proba coa túa tarefa
- PRÁCTICA · Catro retos co cartafol de exemplo · axentes-practica/ · ├─ AGENTS.md · ├─ DATOS.md · ├─ datos/orixinais/ · ├─ datos/traballo/ · ├─ resultados/ · └─ .claude/ · ├─ agents/revisor-datas.md · └─ skills/informe-hba1c/ · 1 · Abre o cartafol con Claude Code e escribe /context. Cargouse AGENTS.md? · 2 · En modo plan, pide un plan para o informe. Corríxeo antes de aprobar. · 3 · Delega a revisión de datas no subaxente e compara a túa xanela antes e despois. · 4 · Lanza /informe-hba1c e comproba os totais fronte aos orixinais. · Datos 100 % ficticios · descarga en jmramirez.engineer · no teu ordenador
- RESUMO · Oito ideas para levar · 1 · Un axente actúa en bucle · Ti pos o obxectivo e revisas. · 2 · Cartafol ordenado e permisos · Orixinais á parte; aproba cada acción ao principio. · 3 · Un AGENTS.md CURTO · Regras comprobables, menos de 200 liñas. · 4 · A xanela é finita · O que debe perdurar, a un ficheiro. · 5 · Explorar, planificar, executar, revisar · Con /clear, /compact, /rewind e Esc a man. · 6 · Subaxentes e skills · O pesado delégase; o repetido reutilízase. · 7 · Anonimiza sempre · En local e en cloud, o que le vai ao modelo. · 8 · O modelo máis pequeno que sirva · E nunca un antigo. · Axentes de código: o básico · jmramirez.engineer · próximo: MCP e hooks
Todo o que hai aquí pódese practicar co cartafol de exemplo (12 KB, datos ficticios) no teu ordenador. Os retos están ao final.
1. Que é un axente
Un chat contesta unha vez: se algo falla, tes que decatarte ti. Un axente repite un bucle ata cumprir o obxectivo. Pensa que facer, actúa cunha ferramenta (lista un cartafol, executa un script) e observa o resultado. Se o script falla porque unha columna se chama data_extraccion en vez de data, o axente le o erro e corríxeo na volta seguinte.
Esa autonomía é o que o fai útil, e o que obriga a traballar con método. Cada tarefa deste titorial segue os mesmos catro pasos:
- Explorar. Le o cartafol e describe os datos. Non cambia nada.
- Planificar. Propón os pasos. Ti corríxelos e apróbalos.
- Executar. Escribe e executa os scripts, sempre sobre copias.
- Revisar. Comprobas o resultado. A responsabilidade é túa.
2. Cartafol ordenado e permisos
O axente traballa dentro dun cartafol, o seu escritorio: só ve o que hai dentro, e pide permiso para ler ou escribir fóra. Os orixinais, á parte; copias para traballar, e os resultados, á parte:
proxecto-hba1c/
├─ AGENTS.md regras
├─ datos/
│ ├─ orixinais/ non se tocan
│ └─ traballo/ copias
├─ scripts/
└─ resultados/ entrégase
Claude Code ten tres modos de permisos, que se cambian con Shift+Tab: pedir permiso antes de editar un ficheiro ou executar un comando (o modo por defecto), aceptar edicións e modo plan, no que só le e propón. Con datos clínicos, empeza pedindo permiso e le cada acción antes de aprobala.
3. As regras, por escrito: AGENTS.md
O axente non lembra nada entre sesións. O que ten que saber sempre vai nun ficheiro de texto na raíz do proxecto, que se carga enteiro ao comezar cada sesión. Claude Code le CLAUDE.md e, se non existe, AGENTS.md, o nome que usan tamén outros axentes; /init escribe unha primeira versión.
# Proxecto HbA1c
## Regras
- Responde en galego.
- Datas en AAAA-MM-DD.
- Non modifiques datos/orixinais/.
- Antes de borrar filas, pregunta.
## Datos
- Anonimizados. Columnas: DATOS.md
## Saídas
- Táboas e gráficas en resultados/.
## Compact Instructions
- Conserva columnas e decisións.
É contexto, non unha orde garantida, así que ten que ser CURTO: Concreto (regras que se poden comprobar: «datas en AAAA-MM-DD», non «ordena ben os datos»), Útil (que facer, non a historia), Revisado (cada mes, borra o obsoleto), de Tamaño contido (menos de 200 liñas) e Ordenado (títulos claros; o detalle, noutros ficheiros, como DATOS.md).
Nunca escribas nel datos de pacientes nin contrasinais: o ficheiro envíase ao modelo en cada sesión.
4. A xanela de contexto
A xanela é todo o que o modelo ve á vez: as regras, a conversa, os ficheiros que leu e os resultados dos seus comandos. Ten un tamaño fixo, medido en tokens. As túas mensaxes son o que menos ocupa; o que a enche son os ficheiros e os resultados longos.
Preto do límite, a conversa compáctase: resúmese para facer sitio. Podes pedilo con /compact conserva as columnas, ou faino o axente só. AGENTS.md segue enteiro; as instrucións longas dadas ao comezo do chat poden perderse. A regra é sinxela: se queres que o lembre mañá, escríbeo nun ficheiro. /context mostra que ocupa a xanela.
5. Controlar a sesión
Cinco comandos cobren case todo:
| Comando | Que fai | Cando |
|---|---|---|
/init | Mira o cartafol e crea un ficheiro de regras inicial | Ao comezar un proxecto |
/clear | Conversa nova; as regras seguen aí | Ao cambiar de tarefa |
/compact | Resume e libera xanela; podes dicir que conservar | Cando a xanela se enche |
/rewind | Volve a un punto anterior: código, conversa ou ambos | Se un paso sae mal |
/context | Mostra que ocupa a xanela | Se parece ignorar unha regra |
Esc detén o axente sen perder o feito, e @ficheiro sinala un ficheiro concreto para que non lea todo o cartafol. Se tras dúas correccións segue fallando, /clear e escribe unha petición mellor.
Este é o caso completo nunha sesión:
| Paso | Que pides | Que pasa | Que fas |
|---|---|---|---|
| Explorar | «Le datos/traballo/ e describe as columnas. Non cambies nada.» | Resume 12 CSV | Comprobas que entende os datos |
| Planificar | Shift+Tab, modo plan: «Propón como facer o informe» | Plan de catro pasos | Corríxelo e apróbalo |
| Executar | «Adiante co plan» | Borra filas que non eran duplicadas | /rewind e «só duplicados exactos» |
| Executar | Segue coa gráfica | A xanela chega ao 85 % | /compact conserva as columnas |
| Revisar | «Compara os totais cos orixinais» | Cadran | Revísalo ti e vai a resultados/ |
6. Delegar e reutilizar: subaxentes e skills
Un subaxente é un axudante con xanela propia. Le moito na súa xanela e á túa só chega un resumo. É un ficheiro Markdown en .claude/agents/:
---
name: revisor-datas
description: Revisa formatos de data en datos/traballo/
tools: Read, Grep
model: haiku
---
Comproba que as datas están en AAAA-MM-DD. Devolve un
resumo de 10 liñas como máximo. Non modifiques ningún ficheiro.
Dálle os permisos mínimos (un revisor só precisa ler) e pídelle un resumo curto. Para unha tarefa pequena non compensa.
Unha skill é unha receita que se carga á carta: un cartafol cun SKILL.md e, se fai falta, scripts e modelos. Sempre á vista só está a súa descrición; o resto cárgase cando a túa petición encaixa con ela, ou cando a chamas polo seu nome (/informe-hba1c). A descrición decide todo: di que fai e cando usala, e mantén SKILL.md por debaixo de 500 liñas.
O que sempre vale, a AGENTS.md. O que fas ás veces, a unha skill. O que ensucia a xanela, a un subaxente.
7. Local ou cloud, e privacidade
Claude Code pode correr no teu ordenador, cos teus ficheiros reais, ou na nube, nunha máquina illada cunha copia do teu repositorio, onde segue traballando co portátil pechado. O que non cambia é isto: o que o axente le envíase ao modelo, corra onde corra. Anonimiza antes. Con datos de pacientes: en local e anonimizados. En cloud, só código ou datos ficticios. Ante a dúbida, consulta co teu delegado de protección de datos.
8. Que modelo, para que tarefa
Os nomes e os prezos dos modelos cambian cada poucas semanas; o tipo de tarefa non. En vez dunha táboa de modelos, un termómetro: catro niveis de tarefa, cada un co modelo máis pequeno que adoita abondar. Para Claude dá a gama, porque Anthropic non publica cantos parámetros teñen os seus modelos. Para os modelos abertos que executas no teu ordenador dá o tamaño, que é público e decide se o modelo cabe no teu equipo.
Decisión clínica: ningún modelo substitúe o teu criterio.
Empeza abaixo. Sube un nivel só se falla dúas veces.
No caso Sacar o valor de HbA1c de 200 informes, ou describir as columnas dun cartafol (un subaxente lector).
Unha crenza que convén corrixir: os modelos pequenos non serven para conversar nin para preguntarlles datos, porque inventan. Serven para transformar o texto que ti lles dás: extraer, clasificar, normalizar. Unha mesma sesión pode mesturar niveis: un subaxente lector con Haiku mentres a conversa principal usa un modelo maior.
Tres regras que non caducan: usa o modelo máis pequeno que resolva a tarefa e sube con /model se falla dúas veces; pide respostas curtas, porque escribir custa máis que ler (en Claude, cada token de saída custa cinco veces un de entrada), e non uses modelos antigos, porque cada xeración dá máis por menos e as antigas retíranse. Os prezos actuais están en anthropic.com/pricing.
Práctica: catro retos
Descarga o cartafol de exemplo: doce CSV de analíticas de HbA1c ficticias de catro centros, o AGENTS.md de enriba, un dicionario de datos, o subaxente revisor-datas e a skill informe-hba1c. Ábreo con Claude Code no teu ordenador; non fai falta notebook nin servidor.
- Escribe
/context. Cargouse AGENTS.md? - En modo plan, pide un plan para o informe. Corríxeo antes de aprobalo. Os ficheiros non son todos iguais.
- Delega a revisión de datas no subaxente e compara a túa xanela antes e despois.
- Lanza
/informe-hba1ce comproba os totais fronte aos orixinais.
Se a terminal é nova para ti, o 10 % da terminal que che resolve o 90 % cobre o necesario para chegar ata aquí.