SDK de Claude Code

 (docs.anthropic.com)
1 puntos por GN⁺ 2025-05-20 | 1 comentarios | Compartir por WhatsApp
  • El SDK de Claude Code ofrece capacidades para integrar herramientas de programación impulsadas por IA en aplicaciones
  • Los desarrolladores pueden ejecutar Claude Code como un subproceso, con soporte prioritario para uso por línea de comandos
  • Incluye funciones de gestión de contexto conversacional, definición de prompts de sistema personalizados e integración con herramientas externas (MCP)
  • Permite usar diversos formatos de salida (texto, JSON, JSON en streaming) y opciones detalladas de CLI
  • Como caso real, muestra la posibilidad de integrarse en flujos de trabajo de desarrollo reales, como revisiones automáticas de código y creación de PR al vincularse con GitHub Actions

Introducción

El SDK de Claude Code es una herramienta de desarrollo de código abierto que permite integrar de forma programática las capacidades de Claude Code directamente en aplicaciones. El SDK ejecuta Claude Code como un proceso separado, lo que ofrece extensibilidad para incorporarlo en distintos flujos de trabajo de desarrollo, como asistentes de código impulsados por IA, herramientas de automatización y sistemas de revisión de código.

Por ahora, admite una interfaz basada en línea de comandos (CLI), y los SDK para TypeScript y Python estarán disponibles próximamente.

Uso básico del SDK

El SDK de Claude Code admite ejecución no conversacional (no interactiva). Por ejemplo, dentro del código de un programa se puede invocar Claude Code con argumentos de línea de comandos para obtener automáticamente la salida deseada.

Uso avanzado

Continuar sesiones de conversación de múltiples turnos

  • Al intercambiar varias rondas de conversación, ofrece una función para mantener y continuar el contexto de la conversación usando la sesión previa o un ID de sesión específico
  • Los desarrolladores pueden continuar la conversación desde la sesión más reciente o cargar una sesión determinada

Prompt de sistema personalizado

  • Es posible ajustar el comportamiento base de Claude con un prompt de sistema personalizado por el desarrollador
  • Se pueden adjuntar instrucciones adicionales al prompt de sistema predeterminado para cambiar la orientación de trabajo y el alcance de comportamiento del assistant

Configuración de MCP (Model Context Protocol)

  • MCP es un protocolo de integración con servidores externos para ampliar las capacidades de Claude Code
  • Mediante la bandera --mcp-config y un archivo de configuración JSON, se pueden agregar acceso a bases de datos, integración con APIs y herramientas personalizadas proporcionadas por servidores externos
  • Al usar herramientas MCP, solo deben poder utilizarse las herramientas autorizadas explícitamente (bandera --allowedTools), y el patrón del nombre tiene el formato mcp__<serverName>__<toolName>

Opciones de CLI disponibles

En el SDK de Claude Code se pueden usar diversas banderas de línea de comandos para configurar el entorno de ejecución.

  • --print, -p : ejecuta el modo no interactivo
  • --output-format : selecciona el formato de salida (texto, JSON, stream JSON, etc.)
  • --resume, -r : continúa la conversación con un ID de sesión específico
  • --continue, -c : continúa la sesión más reciente
  • --verbose : muestra registros detallados
  • --max-turns : limita el número máximo de rondas de conversación en modo no interactivo
  • --system-prompt : reemplaza el prompt de sistema
  • --append-system-prompt : agrega instrucciones adicionales al prompt de sistema
  • --allowedTools : especifica la lista de herramientas permitidas (incluidas las herramientas MCP)
  • --disallowedTools : especifica la lista de herramientas prohibidas
  • --mcp-config : carga el archivo de configuración del servidor MCP
  • --permission-prompt-tool : especifica la herramienta MCP para manejar prompts de permisos

Para conocer todas las opciones disponibles y ejemplos de uso, es necesario consultar la documentación oficial de CLI.

Formatos de salida

El SDK admite diversos formatos de salida.

Salida de texto (predeterminada)

  • Devuelve solo el texto de la respuesta

Salida JSON

  • Devuelve metadatos y datos estructurados, lo que facilita el parseo programático
  • Los mensajes de respuesta de la API siguen una estructura de tipos estricta, y en el futuro también se definirán tipos en formato JSON Schema

Salida JSON en streaming

  • Transmite cada mensaje en tiempo real por streaming
  • Durante el avance de la sesión de conversación, se envían objetos JSON separados en este orden: el mensaje de inicialización (init), los mensajes de usuario/assistant y, al final, el mensaje result con estadísticas

Esquema de mensajes

  • Los mensajes de respuesta de la API JSON se estructuran de acuerdo con un esquema preciso
  • Está previsto actualizar periódicamente el esquema y gestionarlo por versiones

Ejemplos

  • Integración con scripts simples
  • Procesamiento de archivos con Claude
  • Soporte para flujos de conversación complejos mediante gestión de sesiones

Mejores prácticas

  1. Usar el formato de salida JSON para parsear respuestas
  2. Manejo de errores: revisar el código de salida y el stream de errores
  3. Gestión de sesiones: mantener el contexto en conversaciones de múltiples rondas
  4. Considerar timeouts: asegurar la estabilidad en trabajos de larga duración
  5. Ajustar el intervalo entre solicitudes: evitar llamadas excesivas y mantener la estabilidad del servicio

Casos de uso reales

El SDK de Claude Code ofrece funciones potentes de automatización e integración en entornos reales de desarrollo.

  • Como ejemplo representativo, al combinarse con GitHub Actions puede automatizar por completo flujos de trabajo de desarrollo como revisión automática de código, creación de PR y clasificación de issues

Lecturas relacionadas

1 comentarios

 
GN⁺ 2025-05-20
Opiniones de Hacker News

  • Quiero destacar que la dirección que busca Claude Code es exactamente la forma de filosofía "unix toolish" que yo quería en una herramienta de programación basada en agentes. He usado Claude Code desde la vista previa pública inicial y he visto su evolución. Creo que el "estándar de oro" para un agente de programación es un nivel en el que puedas ingresar una solicitud de funcionalidad, por ejemplo un ticket de Jira, y recibir un PR para revisarlo y dar feedback tú mismo. Veo una limitación en Cursor, windsurf y similares porque son editores locales y no se pueden integrar a entornos de CI. Si quieres optimizar un codebase para IA (MCP, reglas, etc.), quiero enfatizar que deberías apuntar a una tecnología que también pueda usarse en modo headless. Claude Code se puede usar de forma simple junto con herramientas de automatización, así que ahora es mi referencia base cuando pienso en agentes de programación. Pienso algo similar del paquete npm de Codex. Como contexto, yo ayudo a configurar este tipo de entornos óptimos, así que inevitablemente puedo tener una visión favorable hacia herramientas que sean fáciles de configurar

    • El "estado final dorado" que yo quiero es estar en el centro de una sala rodeado de agentes de IA, por ejemplo agentes de IA que escriben código, hacen diseño y ejecutan pruebas. Yo estaría en medio, casi sin tocar el teclado, dando dirección, criterios estéticos y guías solo mediante conversación. Espero con ganas ese futuro

    • Quiero mencionar que Anthropic anunció hoy una función parecida en beta. Quiero compartir la documentación relacionada. https://docs.anthropic.com/en/docs/claude-code/github-actions

    • El "estado final dorado" de un agente de programación, para mí, es usar un agente de programación libre y de código abierto que pueda ejecutarse libremente en mi computadora o donde yo quiera. Así como se siente absurdo imaginar pagar cada vez que ejecutas comandos como ls, ps o kill en la terminal, creo que con los LLM pasa lo mismo. No digo que haya que "prohibir" los LLM propietarios, pero me gustaría que las personas a las que llaman hackers en este campo usaran herramientas de código abierto como herramienta principal

    • Señalaste que Cursor, windsurf y similares son editores locales y por eso son difíciles de usar en CI, pero yo intenté esto con la combinación de Cursor y MCP. Me funcionó bien durante todo un día, pero pronto me topé con el rate limit y terminé en el modelo más lento y más tonto. También lo intenté con Claude, pero al poco tiempo igual agoté el límite. Además, solo como un 25% de los PR quedan en un nivel de "listo para usar" y muchas veces es más rápido hacerlo yo mismo que averiguar en qué se equivocó la IA

    • Pienso que esa automatización basada en CI ya se puede hacer. Si registras Aider CLI como GitHub Action para que se ejecute automáticamente cuando se crea un issue, esa estructura ya es posible hoy

  • Claude Code es mi forma favorita de usar un LLM para programar. Pero creo que lo que realmente hace falta es una versión open source de Claude Code. Necesitamos un entorno donde puedas aplicar el modelo que quieras y comparar directamente las respuestas de distintos modelos. Siento que otras alternativas como Aider no dan una experiencia al nivel de Claude Code. Es predecible que Anthropic no quiera este enfoque porque debilita su foso defensivo. Pero desde la perspectiva del consumidor, yo quiero usar el mejor modelo y no quiero quedar atado a un solo ecosistema. Supongo que ese es el mayor miedo desde la perspectiva de los proveedores de LLM

    • OpenAI codex es el open source más cercano a lo que mencionas. Puedes usar modelos del proveedor que quieras. Por ahora está por debajo de Claude Code, pero creo que pronto lo alcanzará. https://github.com/openai/codex/tree/main

    • Puedes implementar hasta cierto punto el entorno que quieres usando Claude Code como servidor MCP

  • Aider ya venía ofreciendo soporte para Python y shell scripting desde hace bastante tiempo. Recientemente también hicieron un screencast que incluye un aide de bash scripting ad hoc como parte del proceso de añadir soporte para 130 lenguajes de programación nuevos. Podrás sentir de primera mano lo potente que es este enfoque de estilo scripting. https://aider.chat/docs/scripting.html, https://aider.chat/docs/recordings/tree-sitter-language-pack.html

    • Aider me encanta. MCPs también tendrá soporte pronto y ya lo están probando en la rama de desarrollo. Si esto sale bien, el desarrollo end-to-end real con PR, tickets, etc., usando solo modelos en los que confías, de verdad se vuelve posible

    • Me pregunto si Aider podrá llegar a un nivel en el que me guste tanto como Claude Code. Me gusta la UX de Claude Code, pero no lo uso porque prefiero Gemini 2.5 Pro. Más que funciones como hacer commits, lo atractivo es que la UX es buena. Me gustaría saber qué opinan de eso

    • Creo que Aider podría crecer muchísimo si deja más pulido el workflow de integración con GitHub Actions. Si solo agregando un archivo al repo puedes hablar con el modelo que quieras mediante issues, sería enorme

  • Quiero compartir contexto adicional que el propio equipo de Claude Code dio directamente. http://latent.space/p/claude-code Resumiendo lo principal: los empleados de Anthropic usan Claude ilimitado por un promedio de 6 dólares al día. Un Claude Code headless, como una utilidad de "linux" para CI, resulta muy atractivo. También existe la orientación hacia una plataforma de usuario extensible. El roadmap a futuro incluye sandboxing, branching y funciones de planning. También está previsto sonnet 3.7 como modelo agentic persistente

    • Mencionaste "empleados de Anthropic usan Claude ilimitado por un promedio de $6/día", pero en el artículo también se dice que algún ingeniero llegó a gastar $1,000 en un solo día. Más que el promedio, me da curiosidad ver la distribución, como P50, P75 y P95

    • Me ha pasado varias veces que con solo usar Claude Code unas 2 horas ya se me van más de 20 dólares. Para proyectos personales es demasiado caro, así que simplemente no puedo usarlo

    • Escuché hace poco el pódcast de latent space y de verdad me pareció muy entretenido. Hay muy pocas personas o pódcasts que mantengan un SNR tan alto y al mismo tiempo produzcan contenido público de tan alta productividad de forma constante. Es impresionante sostener este nivel de producción pública mientras además llevan varios negocios. Ojalá más gente pudiera experimentar este gradiente de productividad. Él comparte su fórmula, pero seguirla uno mismo no es nada fácil

  • Si yo hiciera un asistente de código con IA, jamás lo ataría a un proveedor específico de foundation models. Para que eso tenga sentido como estrategia, tendría que darse una situación en la que los efectos del modelo ya casi hubieran llegado a su techo, el rendimiento fuera prácticamente igual entre todos y solo quedaran pequeñas diferencias al nivel de SDK con el que ya estás familiarizado

    • Creo que en realidad el lock-in no es tan fuerte, porque al final solo cambian los comandos o los argumentos. Todo termina siendo una función de entrada y salida, así que basta con sustituir o envolver las partes necesarias. No hay una complejidad estructural grande

    • En este momento, creo que Claude Code sí está funcionando como diferenciador en el mercado de programación basada en agentes. Estoy desarrollando directamente un AI code assistant y Claude Code es la primera integración que intentaría. Siento que todavía no es momento de preocuparse por el lock-in al principio. Hay que elegir lo mejor y empezar a construir principalmente sobre eso

  • Quiero enfatizar que Claude Code ya podía usarse en modo non-interactive, así que era fácil integrarlo con otras aplicaciones como una utilidad de línea de comandos de UNIX. Este SDK nuevo también parece soportar solo uso por línea de comandos, así que no me queda claro qué cambia esencialmente respecto a lo que ya existía. Me pregunto qué punto se me está escapando

  • Cito los términos de uso de Anthropic: "prohíbe desarrollar, entrenar o revender cualquier producto o servicio que compita con la inteligencia general". Si prácticamente todo software entra en la categoría de competir con la "inteligencia general", ¿eso no significaría que, bajo una interpretación estricta, no se podría usar para nada? Creo que este tipo de lenguaje legal es demasiado ambiguo para aplicarse de verdad. Se supone que eres dueño de los resultados de la IA, pero que no compitan con la inteligencia general; me pregunto por qué lo prohíben de una forma tan amplia. ¿Solo significa que la responsabilidad legal recae en el usuario? Me deja muchas dudas

    • Esto es lo que pasa cuando los abogados redactan las reglas como quieren

  • Me da muchísimo gusto que la GitHub Action recién agregada coincida exactamente con la función que estaba buscando. https://docs.anthropic.com/en/docs/claude-code/github-action... Pero parece que por ahora no hay forma de usarla vinculada al plan Max de Claude Code. La estructura solo pide una api key, así que es un poco decepcionante

  • Quiero enfatizar que especialmente la integración con GitHub Actions y con issue/PR es justo la función que he querido todo este tiempo. https://docs.anthropic.com/en/docs/claude-code/github-action...

  • Definitivamente pienso probarlo cuando empiece el soporte de Claude a través de copilot. Por políticas de la empresa, todavía no podemos usar otras herramientas fuera de esa opción