Cómo aprovechar todas las funciones de Claude Code

 (blog.sshh.io)
84 puntos por GN⁺ 2025-11-03 | 2 comentarios | Compartir por WhatsApp
  • Claude Code se usa ampliamente tanto en proyectos personales como en entornos de monorepo empresariales, y se organiza la forma real de usar sus componentes clave y funciones avanzadas
  • La clave para operar agentes de forma efectiva no está en el estilo de salida ni en la UI, sino en la calidad del PR final, y la meta es una delegación estilo “configurar y olvidarse” (shoot and forget)
  • El centro de la base de código es el archivo CLAUDE.md, que funciona como una “constitución” que define las reglas de comportamiento del agente y cómo usar las herramientas
  • Funciones como gestión de contexto, comandos slash, subagentes, Hooks y GitHub Action (GHA) elevan el nivel de colaboración y automatización
  • Se distingue la relación entre Skills y MCP (Model Context Protocol) para enfatizar una estructura de agentes flexible y centrada en scripting
  • Se ofrece una guía práctica para expandir Claude Code más allá de una simple herramienta CLI y convertirlo en una infraestructura de desarrollo con IA de nivel empresarial
  • Uso muchísimo Claude Code
    • En proyectos de hobby lo ejecuto varias veces por semana en una VM, usando --dangerously-skip-permissions para convertir ideas en código al instante
    • En el trabajo, el equipo construye reglas y herramientas para AI IDE, y nuestro equipo de ingeniería consume miles de millones de tokens al mes solo en generación de código
  • El mercado de agentes CLI está saturado con Claude Code, Gemini CLI, Cursor y Codex CLI, pero la competencia real es entre Anthropic y OpenAI
    • Pero al hablar con desarrolladores, la elección de herramientas depende de factores superficiales
      • Como una implementación de función “con suerte” o el “vibe” de un system prompt preferido
    • A estas alturas, todas estas herramientas son bastante buenas
  • Algunos incluso se enfocan demasiado en el estilo de salida o la UI
    • Adulaciones como "you're absolutely right!" no son un bug especialmente relevante
    • Más bien son señal de que el usuario está demasiado metido en el loop
  • Mi filosofía central de uso es "Shoot and Forget"
    • El flujo es: delegar, configurar el contexto, ejecutar la tarea
    • La herramienta se juzga por el PR final, evaluando el resultado y no el proceso para llegar ahí
  • Este texto es una reflexión sobre todo el ecosistema basada en mi experiencia usando Claude Code durante los últimos meses
    • Casi todas las funciones que uso (y las que no uso)
    • El archivo básico CLAUDE.md
    • Comandos slash personalizados
    • El poderoso mundo de los Subagents, Hooks y GitHub Actions
  • Como el texto es bastante largo, se recomienda usarlo más como referencia que leerlo completo

CLAUDE.md: la constitución del agente

  • El CLAUDE.md raíz es la principal fuente de verdad del agente sobre cómo funciona el repositorio
    • Proyecto de hobby: dejar que Claude lo escriba libremente como quiera
    • Monorepo empresarial: gestión estricta en unas 13 KB (puede crecer hasta 25 KB)
    • Solo se documentan herramientas usadas por más del 30% de los ingenieros
    • Se asigna un máximo de tokens a la documentación de cada herramienta interna (como si se “vendiera espacio publicitario”)
    • Si no puedes explicar la herramienta de forma concisa, CLAUDE.md todavía no está listo

  • Consejos y antipatrones comunes

    • Empieza con guardrails, no con un manual: comienza con documentación pequeña basada en lo que Claude suele hacer mal
    • No documentes archivos con @
      • Si mencionas con @ documentación extensa de otro lugar, el archivo completo se incrusta en la ventana de contexto en cada ejecución y se vuelve enorme
      • Si solo mencionas la ruta, Claude tiende a ignorarla
      • Hay que “sugerirle” al agente por qué y cuándo debe leer el archivo
      • Ejemplo: "consulta path/to/docs.md para resolución avanzada de problemas en usos complejos o si aparece FooBarError"
    • No digas solo lo que “nunca” debe hacer
      • Evita restricciones negativas como "nunca uses el flag --foo-bar"
      • Si el agente cree que necesita usar ese flag, se queda bloqueado
      • Siempre ofrece una alternativa
    • Usa CLAUDE.md como función forzadora
      • Si un comando CLI es complejo y verboso, no escribas un párrafo explicándolo (parche para un problema humano)
      • En su lugar, crea un wrapper bash simple con una API clara e intuitiva y documenta el wrapper
      • Mantener CLAUDE.md lo más corto posible es una excelente función forzadora para simplificar la base de código y las herramientas internas

  • Estructura de ejemplo

    # Monorepo  

## Python  
- Always ...  
- Test with <command>  
... 10개 항목 ...  

## <Internal CLI Tool>  
... 80% 사용 사례에 집중한 10개 불릿 ...  
- <usage example>  
- Always ...  
- Never <x>, prefer <Y>  

복잡한 사용법이나 오류 시 path/to/<tool>_docs.md 참조
  • Se sincroniza con el archivo AGENTS.md para mantener compatibilidad con otros AI IDE que usan los ingenieros
  • Consejo adicional: consulta "AI Can't Read Your Docs", "AI-powered Software Engineering", "How Cursor (AI IDE) Works"

Compact, Context, Clear: gestión de la ventana de contexto

  • Usa el comando /context para revisar el uso de la ventana de 200k tokens
    • Incluso en Sonnet-1M, no está claro si toda la ventana de contexto se aprovecha de forma efectiva
    • Una sesión nueva en monorepo consume por defecto ~20k tokens (10%), y los 180k restantes se usan para cambios en curso (se agotan rápido)
  • Tres flujos de trabajo principales
    • /compact (evitar): la compresión automática es opaca, da errores y está poco optimizada, así que conviene evitarla lo más posible
    • /clear + /catchup (reinicio simple): forma básica de reiniciar; con /clear se limpia el estado y luego un /catchup personalizado lee todos los archivos modificados del branch de git
    • "Document & Clear" (reinicio complejo): para trabajo grande; Claude vuelca el plan y el progreso en un .md → /clear → en una sesión nueva se lee el .md y se continúa

Comandos slash personalizados

  • Los comandos slash son solo atajos simples para prompts frecuentes, ni más ni menos
  • Configuración mínima
    • /catchup: prompt para leer todos los archivos modificados del branch de git
    • /pr: helper para ordenar el código, hacer staging y preparar el PR
  • Una lista compleja de comandos personalizados es un antipatrón
    • La esencia de un agente como Claude: generar resultados útiles y combinables a partir de casi cualquier entrada en lenguaje natural
    • Obligar a ingenieros (o no ingenieros) a aprender una lista obligatoria de “comandos mágicos” para hacer tareas = fracaso
    • El objetivo es construir un agente con un CLAUDE.md más intuitivo y mejores herramientas

Subagent personalizado

  • En teoría, una función potente de gestión de contexto
    • Trabajo complejo: contexto de entrada de X tokens + contexto de trabajo de Y tokens + respuesta de Z tokens
    • N tareas = (X + Y + Z) * N tokens en la ventana principal
    • Solución con Subagent: delegar las tareas (X + Y) * N a un agente especializado y devolver solo la respuesta final de Z tokens
  • Dos problemas nuevos que crean los Subagent personalizados en la práctica
    • Gatekeeping de contexto: al crear un Subagent PythonTests, se oculta todo el contexto de pruebas al agente principal → imposible razonar de forma integral → se fuerza a llamar al Subagent para saber cómo verificar su propio código
    • Imposición de flujo de trabajo humano: se obliga a Claude a seguir un flujo de trabajo rígido definido por humanos → indicar cómo delegar = el mismo problema que el agente debería resolver

  • Personalmente prefiero la función Task(...)

    • Crear una copia de un agente de propósito general con la función integrada Task(...) de Claude
      • Colocar todo el contexto clave en CLAUDE.md
      • El agente principal decide cuándo y cómo delegar trabajo a su propia copia
      • Se mantienen las ventajas de ahorro de contexto del Subagent, pero se eliminan sus desventajas
      • El agente gestiona dinámicamente su propia orquestación
    • En "Building Multi-Agent Systems (Part 2)" se le da el nombre de arquitectura "Master-Clone"
      • La prefiero mucho más que el modelo "Lead-Specialist" que inducen los Subagent personalizados

Resume, Continue, History

  • Uso básico
    • Uso con frecuencia claude --resume y claude --continue
    • Reinicio rápido de una terminal con errores o de una sesión vieja
    • Reanudar una sesión de hace varios días con claude --resume para resumir cómo superé un error específico → mejorar CLAUDE.md y las herramientas internas
  • Uso avanzado
    • Claude Code guarda el historial de todas las sesiones en ~/.claude/projects/
    • Tengo scripts que aprovechan los datos crudos del historial de sesiones
    • Ejecuto metaanálisis sobre los logs: busco excepciones comunes, solicitudes de permisos y patrones de error → mejoro el contexto dirigido al agente

Hooks

  • Críticos en repos empresariales: no los uso en proyectos hobby
  • Reglas determinísticas de tipo "must-do" que complementan las sugerencias "should-do" de CLAUDE.md
  • Dos tipos
    • Hook de bloqueo en la etapa de commit (Block-at-Submit): estrategia principal
      • Envolver todos los comandos Bash(git commit) con un Hook PreToolUse
      • Verificar el archivo /tmp/agent-pre-commit-pass (que el script de pruebas crea solo cuando todas las pruebas pasan)
      • Si el archivo no existe, se bloquea el commit → se obliga a Claude a entrar en un bucle de "probar-corregir" hasta que el build funcione
    • Hook de pista: Hook simple no bloqueante que da feedback de tipo "fire-and-forget" cuando el agente toma una opción subóptima
  • No uso deliberadamente Hooks de bloqueo en la etapa de escritura (Edit o Write)
    • Bloquear al agente a mitad del plan causa confusión o "frustración"
    • Es mucho más efectivo verificar el resultado final completado en la etapa de commit, después de terminar el trabajo

Modo de planificación

  • La planificación es esencial para cambios de funciones "grandes" con un AI IDE
  • Proyectos hobby: uso exclusivamente el modo de planificación integrado
    • Cómo alinearme antes de iniciar Claude
    • Definir cómo hacer el build y los "checkpoints de inspección" donde el trabajo debe detenerse y mostrar resultados
    • El uso regular construye una fuerte intuición sobre el contexto mínimo necesario para obtener un buen plan sin que Claude arruine la implementación
  • Monorepo empresarial: empecé a desplegar una herramienta de planificación personalizada basada en el SDK de Claude Code
    • Similar al modo de plan nativo, pero con prompts enfocados en alinear la salida con el formato de diseño técnico ya existente
    • Fuerza buenas prácticas internas por defecto (desde la estructura del código hasta privacidad de datos y seguridad)
    • Permite que un ingeniero haga el "vibe plan" de una nueva función como si fuera un arquitecto senior (al menos esa es la propuesta)

Skills

  • Coincido con Simon Willison: Skills es (probablemente) un negocio más grande que MCP
  • Evolución en 3 etapas del modelo mental de autonomía del agente
    • Single Prompt: darle todo el contexto al agente en un solo prompt gigante (frágil, no escala)
    • Tool Calling: el modelo de agente "clásico", creando herramientas manualmente y abstracciones de la realidad para el agente (mejoró, pero crea nuevas abstracciones y cuellos de botella de contexto)
    • Scripting: dar al agente acceso al entorno crudo (binarios, scripts, documentación) → el agente escribe código sobre la marcha para interactuar
  • Agent Skills es la siguiente función obvia: una formalización del producto de la capa de "Scripting"
  • Si preferiste CLI sobre MCP, ya obtuviste implícitamente las ventajas de Skills
    • El archivo SKILL.md es una forma más organizada, compartible y detectable de documentar esos CLI y scripts y exponerlos al agente
  • Skills son la abstracción correcta: formalizan un modelo de agente basado en "scripting" más sólido y flexible que el modelo rígido tipo API que representa MCP

MCP (Model Context Protocol)

  • Que existan Skills no significa que MCP esté muerto (ver "Everything Wrong with MCP")
  • Problema anterior: mucha gente construyó MCP horribles y pesados en contexto, con decenas de herramientas que espejan una REST API (read_thing_a(), read_thing_b(), update_thing_c())
  • El modelo de "Scripting" (formalizado con Skills) es una mejor forma, pero necesita una manera segura de acceder al entorno → ese es el nuevo rol, más enfocado, de MCP

  • Nuevo rol de MCP: gateway de datos

    • En lugar de APIs infladas, un gateway simple y seguro que ofrece unas pocas herramientas potentes de alto nivel
      • download_raw_data(filters…)
      • take_sensitive_gated_action(args…)
      • execute_code_in_environment_with_state(code…)
    • El rol de MCP: gestionar autenticación, networking y límites de seguridad, y luego no estorbar, en vez de abstraer la realidad para el agente
      • Proporciona un punto de entrada para el agente → el agente hace el trabajo real con scripting y contexto en markdown
    • El único MCP que uso actualmente: Playwright (tiene sentido porque es un entorno complejo y con estado)
      • Todas las herramientas sin estado (Jira, AWS, GitHub) se migran a CLI simples

Claude Code SDK

  • Claude Code no es solo una CLI interactiva, sino también un SDK potente para crear agentes completamente nuevos tanto para tareas de programación como no técnicas
  • En la mayoría de los nuevos proyectos personales, empiezo a usarlo como framework base de agentes en lugar de herramientas como LangChain/CrewAI
  • Tres formas principales de uso
    • Scripting paralelo a gran escala: no usar chat interactivo durante refactorizaciones grandes, correcciones de bugs o migraciones
      • Escribir scripts bash simples que llamen en paralelo a claude -p &quot;in /pathA change all refs from foo to bar&quot;
      • Mucho más escalable y controlable que hacer que un agente principal administre decenas de tareas de subagentes
    • Construcción de herramientas internas de chat: perfecto para envolver procesos complejos en una interfaz de chat simple para usuarios no técnicos
      • Ej.: un instalador que, cuando hay un error, recurre a Claude Code SDK para resolver el problema del usuario
      • Ej.: una herramienta interna tipo "v0-at-home" para que el equipo de diseño pueda vibe-codear mockups de frontend con el framework UI interno de la empresa (garantiza alta fidelidad de la idea y permite un uso más directo en código frontend de producción)
    • Prototipado rápido de agentes: el caso de uso más común, y no solo para programación
      • Cuando hay una idea para una tarea de agente (por ejemplo, un "agente de investigación de amenazas" usando una CLI personalizada o MCP)
      • Construir y probar rápidamente el prototipo con Claude Code SDK antes de hacer commit del scaffolding completo del despliegue

Claude Code GitHub Action (GHA)

  • Una de mis funciones favoritas y más subestimadas: el concepto es simple (ejecutar Claude Code en GHA), pero esa simplicidad es la fuente de su poder
  • Similar al agente en segundo plano de Cursor o a la UI web administrada de Codex, pero mucho más personalizable
    • Control total del contenedor y del entorno → mejor acceso a los datos
    • Controles de sandboxing y auditoría mucho más potentes que en otros productos
    • Soporta todas las funciones avanzadas como Hooks y MCP

  • Casos de uso

    • Construir una herramienta personalizada de "PR desde cualquier lugar"
      • Se puede disparar un PR desde Slack, Jira e incluso alertas de CloudWatch
      • GHA devuelve un PR completamente probado después de corregir el bug o agregar la funcionalidad
    • Flywheel impulsado por datos
      • Los logs de GHA = logs completos del agente
      • Revisar periódicamente los logs a nivel empresa: detectar errores comunes, fallas de bash y prácticas de ingeniería desalineadas
      • Flywheel: bug → mejoras en CLAUDE.md/CLI → mejor agente
      • $ query-claude-gha-logs --since 5d | claude -p &quot;see what the other claudes were getting stuck on and fix it, then put up a PR&quot;

settings.json

  • Ciertas configuraciones son esenciales tanto para proyectos personales como para el trabajo
  • HTTPS_PROXY/HTTP_PROXY: para depuración
    • Inspeccionar tráfico en bruto para ver el prompt exacto que Claude está enviando
    • Para agentes en segundo plano, es una herramienta potente de sandboxing de red granular
  • MCP_TOOL_TIMEOUT/BASH_MAX_TIMEOUT_MS: aumentar los valores
    • Se prefiere ejecutar comandos largos y complejos; el timeout por defecto suele ser demasiado conservador
    • No está claro si sigue siendo necesario después de los trabajos bash en segundo plano, pero se mantiene por si acaso
  • ANTHROPIC_API_KEY: usar una clave de API enterprise en el trabajo (mediante apiKeyHelper)
    • Cambiar del licenciamiento "por asiento" al precio "basado en uso" (un modelo mucho mejor para esta forma de trabajar)
    • Considerar la enorme diferencia en uso entre desarrolladores (se ha visto una diferencia de 1:100 entre ingenieros)
    • Los ingenieros pueden experimentar con scripts LLM que no sean Claude Code usando una sola cuenta enterprise
  • &quot;permissions&quot;: auditar periódicamente por cuenta propia la lista de comandos que Claude tiene permitido ejecutar automáticamente

Cierre

  • Es mucho contenido, pero espero que sea útil
  • Si todavía no usas agentes basados en CLI como Claude Code o Codex CLI, deberías hacerlo
  • Casi no hay buenas guías sobre estas funciones avanzadas, y la única forma de aprender es meterse de lleno

Lecturas relacionadas

2 comentarios

 
GN⁺ 2025-11-03
Opiniones en Hacker News

  • Estamos sincronizando los archivos con AGENTS.md para mantener compatibilidad con otros IDE de IA
    Al investigar recientemente, vimos que la forma recomendada por Anthropic es poner solo una línea con @AGENTS.md en el archivo CLAUDE.md, y dejar el contenido real en AGENTS.md
    Documentación relacionada: Claude Code Best Practices

    • Creo que, para alinearnos con el estándar, habría que renombrar CLAUDE.md a AGENTS.md
    • Nosotros usamos AGENTS.md con un enlace simbólico hacia CLAUDE.md y funciona bien
    • Me parece una forma más limpia de hacerlo
    • Me pregunto si usar enlaces simbólicos será una buena idea
    • En mi experiencia, Claude y otros agentes en realidad no leen AGENTS.md ni CLAUDE.md a menos que se les indique explícitamente en cada sesión

  • Me gustó mucho esta parte del artículo sobre MCP
    Me parece acertada la idea de que “MCP no debería ser una API compleja, sino una puerta de enlace simple que gestione autenticación, red y límites de seguridad, y luego se quite del camino”
    Artículo relacionado

    • Cuando salió MCP por primera vez no imaginaba este caso de uso, pero ahora se siente que Claude quiere más scripting de datos que múltiples ‘herramientas’. Mi papel es solo entregarle bien los datos
    • Mi MCP consiste en un solo intérprete de código. Últimamente estoy probando un MCP proxy que permite llamar a MCP desde dentro del intérprete de código
      Aun así, casi no uso MCP. Ojalá se enfocaran más en la parte de autenticación (auth)
      Enlace de referencia: post en X
    • Si usas MCP como API gateway interno, funciona de esta manera. En la práctica se parece a OpenAPI, pero optimizado un poco más para el razonamiento de los LLM

  • Es una lástima que un artículo de 3000 palabras se vea como “demasiado largo y solo para consulta”
    Me gustaría ver una versión aún más extensa con ejemplos reales

    • Últimamente soy pesimista sobre cuánto está dispuesta a leer la gente
    • Yo también tenía expectativas, pero me decepcionó un poco lo limitado del contenido. Aun así, saqué algunos puntos útiles

  • Estoy usando una rutina de reinicio simple con /clear y /catchup para reiniciar el estado de Claude y hacer que vuelva a leer los archivos modificados
    Probablemente pronto el comando /compact termine cumpliendo ese papel

    • Por la latencia de /compact, casi no se puede usar
      Aunque muestre “0% context remaining”, en realidad alrededor de un 30% queda reservado para la compresión
      Y aun así, como la mitad de las veces la compresión falla o choca con límites de la API

  • También está bueno usar Claude Code para mejorar su propia configuración
    Recomiendo cambiar a modo plan y usar este prompt:
    “Lee este documento (How I use every Claude Code feature) y dime cómo mejorar mi configuración de Claude Code”

  • Dejé de mantener CLAUDE.md porque Claude ni siquiera sigue bien instrucciones simples que están ahí
    Por ejemplo, aunque le diga que nombre los scripts generados como <foo>.aigen.ts, ignora eso la mitad de las veces
    Así que lo termino resolviendo metiendo el contexto directamente en el prompt cada vez
    ¿Soy el único al que le pasa esto?

    • Mi CLAUDE.md es bastante largo, pero casi siempre lo sigue bien. Cuando lo ignora, lo cambio con énfasis en MAYÚSCULAS tipo “IMPORTANT! ALWAYS DO …” y así funciona bien el 95% de las veces
      He visto resultados parecidos en varios proyectos
    • Mi experiencia fue la misma. Eso sí, ya me rendí, así que no sé si mejoró en la versión más reciente
    • Entre los Claudemasters esto ya es un problema conocido

  • Decían que “si no estás usando un agente basado en CLI, deberías hacerlo”, pero me pregunto si de verdad es mejor que la app de Cursor
    Cursor es cómodo porque puedes seleccionar una parte específica del código y con Cmd-L decir “arregla esta parte”
    Enviar fragmentos de código por CLI parece un poco engorroso

    • Yo uso Claude y Codex en VS Code, y el flujo de dar instrucciones directamente sobre el código seleccionado funciona bastante bien
    • Me da mejores resultados usar Codex + GPT5 o Claude Code CLI directamente que Cursor. Da la impresión de que Cursor ajusta para reducir el tamaño de salida y ahorrar tokens
    • Yo también empecé con Cursor, pasé por un esquema híbrido y al final me cambié por completo al CLI
      Tanto la UX liviana como la eficiencia son mejores. Claude funciona mejor en CC
    • Claude reconoce automáticamente las líneas de código seleccionadas en VS Code
    • También puedes seleccionar varios archivos a la vez para darles foco, y ejecutar comandos del PATH (como gh)

  • Al leer la frase “Claude Code no es un simple CLI, sino un SDK con el que puedes crear nuevos agentes”, sentí cansancio porque sonaba como prosa escrita por IA
    Me dio la impresión de que no respetaba al lector

    • Yo también tenía un rechazo instintivo a los textos generados por IA, pero últimamente trato de juzgar el contenido en sí
      En este caso me parece un buen ejemplo porque se nota que el autor lo leyó y lo editó personalmente
      En cambio, copiar y pegar salida de IA tal cual sí merece críticas
    • Me vino a la mente la frase “Internet está muerto. Larga vida a Internet”
    • Nadie te obligó a leerlo, así que no entiendo por qué te resultó ofensivo
      A mí, al contrario, me hizo sentir respetado y lo leí hasta el final

  • Estas herramientas son interesantes, pero me preocupa que la industria otra vez se esté enfocando en la tecnología en sí y no en el cliente
    (Me recuerda al ensayo de Paul Graham “Top idea in your mind”)

    • Sí. Las herramientas de programación basadas en LLM sirven para métricas corporativas como velocidad y reducción de costos, pero lo que el cliente quiere son funciones y estabilidad
      Si el producto se hace rápido y barato pero queda lleno de bugs, no sirve de nada
      Con la IA pasa lo mismo: los CEO la ven solo como una forma de recortar personal, pero la tecnología todavía no está al nivel de dar beneficios reales al cliente
      Los chatbots de IA solo logran molestar más a los clientes
    • Me pregunto qué significa exactamente “cliente”. Yo uso estas herramientas para entender mejor a los clientes

  • La velocidad a la que está avanzando Claude Code es sorprendentemente rápida
    Sigue mejorando tanto que cada semana hay algo nuevo que aprender

    • Viendo el uso de CPU y memoria, tampoco es tan sorprendente
      Si pudiera agregar funciones sin volver lenta mi M4 Mac (64GB RAM), eso sí sería verdadera magia
 
hyeonseokoh94 2025-11-05

Está bueno, pero..