HugAI
.dev
CONSEJOS
Artículos
Agendar
EN
Consejos // Claude en la práctica
Tips para trabajar mejor con Claude
Un tip corto por vez, con un ejemplo para copiar. Recórrelos al azar o busca el que necesitas.
×
Todos los tips
Las reglas del equipo van en el CLAUDE.md del proyecto
Si tus convenciones están en ~/.claude/CLAUDE.md, la persona que se suma al equipo no las recibe: pasalas al CLAUDE.md del repo.
Volcá hallazgos a un scratchpad en investigaciones largas
Pedile a Claude que anote los hallazgos en un archivo y, si el contexto se degrada o abrís otra sesión, lo lee en vez de re-investigar.
Revisá con una sesión distinta a la que escribió el código
La sesión que generó el código conserva su razonamiento y le cuesta cuestionarlo: abrí una instancia nueva para revisar y detectás más.
En CI, corré Claude Code en modo -p con salida JSON
Con claude -p el pipeline no queda esperando input y, con salida JSON, podés parsear el resultado para comentar el PR.
El loop del agente termina por stop_reason, no por el texto
Seguí iterando mientras stop_reason sea tool_use y cortá en end_turn; buscar la palabra "listo" en la respuesta es frágil.
El resultado de una tool viaja en un mensaje con rol user
No existe un rol "tool": el resultado se devuelve como bloque tool_result dentro de un mensaje user.
tool_choice: auto, any o una herramienta forzada
Si necesitás salida estructurada garantizada o un primer paso fijo, no dejes que Claude elija entre responder en texto o llamar una tool.
Campos required solo si el dato siempre está en la fuente
Un campo obligatorio que el documento no trae empuja a Claude a inventar el valor: hacelo nullable y sumá un enum "unclear".
Batch si nadie espera la respuesta; sincrónica si alguien sí
Un reporte nocturno o una auditoría semanal van a Batch y salen más baratos; un chequeo pre-merge necesita la API sincrónica.
En una tool MCP, "sin resultados" no es lo mismo que "falló"
Si una búsqueda que falló devuelve una lista vacía, el agente concluye que no hay datos y no reintenta; separá los dos casos.
Si Claude ignora tu tool MCP, reforzá su descripción
Con una descripción pobre, el agente prefiere Grep o Read; decile qué datos únicos aporta tu herramienta y cuándo conviene.
Skill con context: fork para que no ensucie tu sesión
Si un skill genera mucha salida (análisis, exploración), ejecutalo en un subagente aislado y en tu sesión queda solo el resumen.
En revisiones, definí qué marcar y qué no marcar
Un criterio categórico baja los falsos positivos mucho más que una instrucción general de prudencia.
Ejemplos con justificación aclaran los casos grises
Para pedidos ambiguos, un ejemplo con su porqué le muestra a Claude cuándo actuar y cuándo escalar, mejor que otro párrafo de reglas.
Si la validación falla, reintentá con el error concreto
Devolvele a Claude el documento, su extracción anterior y el error exacto: corrige fallos de formato y cuentas, pero no inventa lo que falta.
PR grande: revisá por archivo y después las relaciones
Un solo prompt con 14 archivos diluye la atención; una pasada por archivo más una de integración da análisis parejo.
Un subagente no hereda tu contexto: pasáselo en el prompt
Lo que el coordinador sabe no llega solo al subagente; incluí documento, hallazgos previos y formato de salida en la instrucción.
Cada subagente con 4 o 5 herramientas, no con las 18
Cuantas más herramientas ajenas a su rol tiene un agente, peor las elige; dale solo las de su especialidad.
Si el orden de las tools importa, imponelo con código
Bloqueá process_refund hasta que get_customer haya devuelto un ID verificado: el prompt cumple casi siempre, el hook cumple siempre.
Escalá a una persona por reglas claras, no por el enojo
El tono del cliente y la autoevaluación de confianza del modelo no predicen qué casos son difíciles; las reglas explícitas sí.
Si repetís el mismo contexto, armá un Project
Si cada semana pegás el mismo párrafo de contexto en un chat nuevo, ese trabajo ya necesita un Project.
Usá Artifacts cuando el resultado es un entregable
Si lo que pedís es un documento, tabla o código para refinar y reutilizar, pedilo como Artifact y no como respuesta en el chat.
Pedí que calcule con Code Execution, no de cabeza
Para cualquier cifra que vayas a reportar, hacé que Claude corra el cálculo en código en vez de estimarlo en prosa.
Incognito no vuelve seguros los datos regulados
Incognito evita que algo quede en historial y Memory, pero no confirma que ese dato pueda subirse a Claude.
Si Claude se olvida de tus reglas, reiniciá con resumen
Cuando una sesión larga empieza a ignorar tus instrucciones iniciales, no repitas el prompt: resumí y abrí un chat nuevo.
Un Project por cliente para que no se mezclen datos
La Memory acotada a cada Project evita que el contexto del cliente A aparezca en una charla del cliente B.
Regla, referencia o procedimiento: cada uno en su lugar
Las reglas de comportamiento van en instrucciones, los datos en la base de conocimiento y los procedimientos en una Skill.
Instrucciones del Project que dos personas lean igual
Una instrucción vaga como 'sé profesional' falla en silencio; una medible cambia de verdad la salida.
Auditá tu Project una vez por mes
Si un Project empieza a dar resultados raros sin error visible, probablemente tenga instrucciones, archivos o memorias viejas.
Antes de enviar: rol, contexto, tarea, límites, formato
Repasá cinco componentes antes de mandar un prompt importante y te ahorrás varias rondas de corrección.
Partí los pedidos grandes en pasos con resultado revisable
Un pedido de varias etapas en un solo prompt sale superficial; en pasos ordenados podés corregir antes de seguir.
Si la salida falla, corregí solo el componente culpable
Leé la salida como diagnóstico: genérica es poco contexto, largo o tono equivocado es un límite que faltó.
Para brainstorm, aflojá las restricciones
Sobreespecificar mata la variedad: dale el objetivo y un par de guardrails, pedí volumen y recién después filtrá.
Autorizá a Claude a decir 'no sé'
Si aclarás que admitir incertidumbre es válido, Claude tiene menos tentación de rellenar huecos con datos inventados.
En documentos largos, pedí las citas antes del análisis
Si Claude extrae primero las frases relevantes, su razonamiento queda anclado al texto y los errores se ven.
Una cifra muy precisa y sin fuente es sospechosa
Claude escribe con la misma seguridad cuando acierta y cuando inventa, así que la precisión sin cita es una señal de alerta.
Tratá una Skill como software que instalás
Antes de activar una Skill de terceros, revisá quién la publicó, a qué podría acceder y si el alcance es proporcional.
Si corregís lo mismo cada semana, mandalo a configuración
Una corrección que repetís a mano se rediscute cada vez; guardala como instrucción o Skill y desaparece el costo.
Diagnosticá en orden antes de culpar al modelo
Si el resultado decepciona, revisá primero el prompt, después el largo del chat, luego feature y modelo, y al final la configuración.
Delegá cada paso según reversibilidad y riesgo
Mapeá un flujo paso por paso y decidí qué hace Claude, qué hace una persona y qué hacen juntos.
Equipo en Claude Code: baseline común y un champion por área
Si cada dev configura Claude Code a su manera, la config se dispersa; arrancá con un baseline compartido y habilitá primero a un champion por equipo.
Checklist de 4 dimensiones antes de mergear código de IA
Código generado que 'parece bien' y pasa los tests puede igual filtrar datos: un checklist explícito convierte la buena intención en una compuerta repetible.
RAG para documentos estables, tool call para datos vivos
Si el dato cambia entre reindexados (stock, saldo, estado de un pedido), el RAG responde seguro pero desactualizado: ahí corresponde una llamada a una tool.
Poné lo fijo primero en el prompt o el caché nunca pega
El caché de prompts funciona sobre un prefijo estable: si el contenido variable va arriba, el prefijo cambia en cada request y no ahorrás nada.
Prompt que no entra ≠ respuesta truncada por la ventana
Un prompt que no entra se rechaza antes de generar; uno que entra pero choca con el techo de la ventana corta la salida: se diagnostican distinto.
Evals: código para lo objetivo, juez para lo interpretativo
Validar formato o datos contra una fuente se resuelve con checks automáticos; tono o calidad de razonamiento necesitan un juez basado en modelo.
Antes de un A/B, definí métrica primaria y tamaño de muestra
Comparar 50 sesiones contra 50 es una confirmación, no un test: sin métrica fijada de antemano siempre vas a encontrar un 'ganador'.
Redactá la PII antes de armar el prompt, no después
Si un dato sensible entra al prompt, queda expuesto en los logs de requests de tu aplicación; limpiarlo a posteriori es de lo más caro de arreglar.
En multi-tenant, una API key por tenant
Con una sola key compartida, cuando salta el rate limit del org se ve el pico pero no quién lo causó, y todos los clientes lo sufren.
Skills en equipo: elegí la vía según la gobernanza
Hay cuatro formas de repartir una skill y cambian en gobernanza: no es lo mismo subirla a la organización que empaquetarla en un plugin.
Claude puede equivocarse con el mismo tono seguro de siempre
Nombres, fechas, citas y estadísticas son lo más riesgoso: verificalos con una fuente en vez de confiar en cómo suena la respuesta.
Entry point, interfaz de build y ruta: 3 decisiones
Claude.ai o Claude Code (entrada), API o Agent SDK (build) y Bedrock/Vertex/Foundry (ruta) se eligen con criterios y stakeholders distintos.
Una regla que debe cumplirse siempre, fuera del modelo
Un umbral de negocio (ej. reclamos de más de 5.000 van a un senior) es mejor en tu motor de reglas o SQL: Claude acierta casi siempre, no siempre.
Decidí qué pasa cuando tu guardrail falla: ¿pasa o bloquea?
Si el servicio de screening da error y nadie definió el comportamiento, el código casi siempre deja pasar el request sin protección.
Autorizá acciones con side effects con reglas deterministas
Un modelo puede clasificar un input dudoso, pero permitir un reembolso o un envío tiene que ser una decisión que puedas probar y reproducir.
Cada obligación de compliance: control, dueño y evidencia
HIPAA, GDPR o FedRAMP dicen qué debe cumplirse, no cómo: el revisor pide ver el control funcionando, no solo el diseño.
El sesgo entra por 4 puntos que podés inspeccionar
Corpus de retrieval, framing del prompt, ejemplos few-shot y ruteo posterior: si ninguno está instrumentado, no vas a ver un trato desigual.
En discovery, 'seamless' es una pista, no un requisito
Palabras como simple, rápido o intuitivo esconden restricciones: preguntá qué haría que NO lo fuera y escribilo antes de seguir.
Presentá un tradeoff con 4 preguntas (incluida revertir)
La pregunta que casi todos se saltean ('¿y si lo elegimos ahora y hay que revertirlo?') es la que cambia la reunión.
Runbook: síntoma → causa de arquitectura → primera acción
Enseñarle al equipo el camino del síntoma a la causa reduce tu carga futura; arreglar el incidente vos solo la repite.
Elegí el scope de config preguntando quién es el dueño
Antes de tocar un settings, decidí quién controla la regla y a quién afecta: el scope correcto sale solo.
Reglas del equipo en settings.json, pruebas tuyas en .local
Lo que tiene que valer para todo el equipo va en .claude/settings.json (en git); lo que solo anda en tu máquina, en settings.local.json.
CLAUDE.local.md y @imports: contexto sin ensuciar el repo
Las notas personales van en CLAUDE.local.md y los documentos largos se referencian con @ruta, en vez de pegarlos en el CLAUDE.md del proyecto.
Si una regla es obligatoria, no la dejes solo en CLAUDE.md
CLAUDE.md se carga como contexto, no como configuración que se hace cumplir: para lo innegociable usá hooks o managed settings.
Prompt repetido más de 2 veces: hacelo slash command
Un archivo .md en .claude/commands/ se convierte en un comando que todo el equipo puede invocar igual, sin rearmar el prompt.
Output styles: cambiá cómo habla Claude, no lo que sabe
CLAUDE.md define el conocimiento del proyecto; un output style cambia el tono y el formato con que Claude te responde.
Los hooks reciben JSON por stdin: parsealo con jq
Para loguear o formatear tras cada tool call con un hook PostToolUse, leé los datos de stdin con jq: variables como $TOOL_INPUT no existen.
claude -p: Claude Code en scripts, con tools acotadas
Agregar -p convierte a Claude Code en un comando no interactivo que recibe el prompt, ejecuta y termina: ideal para scripts y CI.
Salida JSON para otros sistemas: el schema va en el prompt
--output-format json devuelve JSON, pero la estructura esperada la definís vos en el prompt, y conviene validarla en el pipeline.
--bare: mismo resultado en CI en cualquier máquina
Un pipeline que depende de la config de cada developer da resultados distintos; --bare la deja afuera.
Subagentes o instancias paralelas: devuelven vs. entregan
Un subagente le devuelve resultados al agente principal; las instancias paralelas son sesiones independientes que no se comunican.
Proxy corporativo: apuntá al CA, nunca apagues el TLS
Si ves 'self-signed certificate in chain', el proxy funciona como debe: la solución es darle a Claude Code el CA de la empresa.
Bloqueá el login con API key para que todo pase por SSO
Con forceLoginMethod en managed settings, nadie esquiva el SSO ni la auditoría iniciando sesión con una API key.
Cerrá la clase de riesgo MCP con una sola clave
allowManagedMcpServersOnly bloquea todo servidor MCP que no haya definido el admin, sin ir servidor por servidor.
Skills: la referencia larga va en archivos aparte
Un SKILL.md corto con un enlace a la referencia pesada no consume contexto en las tareas que no la necesitan.
Si un Skill se equivoca siempre igual, sumá una regla
Un error repetido de un Skill se arregla con una instrucción específica en el SKILL.md, no borrándolo ni apilando ejemplos.
OTel dice qué se ejecutó; Compliance API, qué se dijo
Tres fuentes, tres preguntas: logs de auditoría (eventos de admin), Compliance API (conversaciones) y OpenTelemetry (herramientas ejecutadas).
¿Sugerencias 'medio fuera de lugar'? Revisá el CLAUDE.md
Si las respuestas de Claude Code no son erróneas sino desalineadas con el código actual, lo más probable es un CLAUDE.md viejo.
Plan mode: que Claude Code explore antes de tocar nada
Si el código es desconocido o el cambio es delicado, dejá a Claude Code en modo plan y evitás ediciones que no pediste.
Una deny rule le gana a cualquier permission mode
Cambiar de modo no protege tus archivos sensibles; una deny rule sí, porque se aplica aunque el modo auto-apruebe todo.
Mantené CLAUDE.md corto o las reglas se diluyen
Un CLAUDE.md de cientos de líneas hace que Claude ignore justo la regla que importaba; dejá solo lo que cambia su comportamiento.
Reglas por carpeta: .claude/rules con paths en frontmatter
Guía que solo aplica a una parte del repo no tiene por qué cargarse en cada sesión; limitala con un glob.
Hooks PreToolUse: una guardia que se cumple siempre
Una instrucción en CLAUDE.md se sigue casi siempre; un hook PreToolUse que sale con código 2 bloquea la acción todas las veces.
No testees el texto exacto de una respuesta de Claude
El mismo prompt puede dar redacciones distintas y todas correctas; asertá propiedades (campo presente, valor en rango), no strings.
Con thinking + tools, devolvé los bloques thinking sin tocar
Si en un loop de tools borrás o editás el bloque thinking para ahorrar contexto, la próxima request falla por la firma.
Activá el razonamiento solo donde cambia la respuesta
Los tokens de thinking se cobran como output: en clasificación o extracción pagás de más sin ganar precisión.
Cada tool necesita una frase de cuándo NO usarla
Si dos tools dicen 'buscá información', Claude no puede distinguirlas; una condición de exclusión suele arreglar la selección errónea.
Streaming: que se corte el stream no es mensaje completo
Un turno armado desde un stream cortado puede dejar un tool_use truncado en el historial y romper la request siguiente.
Antes de reintentar, preguntate: ¿esperar lo arregla?
Un 429 se reintenta con backoff; un 400 no. Reintentar errores terminales solo gasta tu presupuesto de reintentos.
Si una tool falla, devolvele el error a Claude con is_error
Un resultado vacío se toma como dato válido; con is_error en true Claude sabe que falló y puede cambiar de plan.
Sacá el formato del prompt y ponelo en un JSON schema
Pedir 'devolvé solo JSON' funciona hasta que aparece un caso que no probaste; structured outputs lo restringe en la generación.
MCP: stdio para lo local, HTTP para lo compartido
Un servidor stdio en .mcp.json parece compartido pero no lo es; el equipo necesita HTTP y scope de proyecto.
En un skill, la description es el criterio de carga
Claude carga un skill comparando tu pedido con su description: si es vaga, no se carga en ningún runtime.
Tu skill no carga en el Agent SDK: revisá settingSources
Un skill que anda en Claude Code puede no hacer nada en el SDK si nunca indicaste de qué fuentes cargar la configuración.
Un plugin se instala en todos pero rompe fuera de tu PC
Una ruta absoluta o una variable de entorno sin documentar hacen que la instalación funcione y la ejecución falle en el resto del equipo.
Si el prompt falla, diagnosticá el tipo de falla primero
Reformular rara vez arregla un prompt: cada tipo de falla señala una técnica distinta que falta.
Dos ejemplos en XML fijan el formato mejor que otro párrafo
Si el formato de salida se te desarma, mostrá uno o dos pares entrada-salida correctos en vez de describirlo más.
Lo que el agente lee es dato, no instrucciones
Una instrucción oculta en una página o documento puede influir en el agente; la defensa real es limitar lo que puede hacer.
Inicio
CV
Proyectos
Contacto
Consejos