Source: https://aiprimetech.io/es/blog/claude-code-cli-guide/ Jun 19, 2026 · 6 min · Herramientas # Claude Code y la nueva ola de herramientas de programación con IA en la terminal A Por [AI Prime Tech](https://aiprimetech.io/es/) · Con asistencia de IA A las 2:13 a. m., vi cómo un agente de programación en terminal consumía 1.8 millones de tokens de entrada intentando «simplemente arreglar la prueba que fallaba». El error real era una discrepancia de tres líneas en el esquema. El agente no era torpe; sus límites estaban mal definidos. Seguía releyendo el repositorio, volviendo a ejecutar comandos de pruebas de amplio alcance, pegando enormes trazas de pila en el modelo y solicitando reescrituras de archivos completos cuando habría bastado con un diff preciso. Ese incidente cambió mi forma de ejecutar agentes de programación en la CLI. Herramientas como Claude Code, Aider, Cline y OpenCode no son simples chatbots con un botón de git diff . Son bucles de control impulsados por API que operan sobre tu shell, editor, sistema de archivos y, a veces, navegador. Pueden ser extremadamente productivos, especialmente con modelos potentes como Claude Opus 4.8, Sonnet 4.6, GPT-5.5, Gemini 3 y sistemas de contexto largo como Fable 5. También pueden consumir tokens silenciosamente a un ritmo que sorprende a los equipos acostumbrados a llamadas a la API de un solo turno. Este artículo ofrece una perspectiva práctica: qué hacen realmente los agentes de programación en terminal, cómo usan las API de modelos, por qué los bucles de agentes cambian la economía de los tokens y cómo los configuro para que una sesión larga siga siendo útil en lugar de convertirse en una costosa puesta en escena. ## Qué son realmente los agentes de programación en la CLI Un agente de programación en terminal suele combinar cinco elementos: - Un bucle de chat con un modelo de vanguardia o abierto - Un indexador de repositorios o una capa de descubrimiento de archivos - Una capa de ejecución de herramientas para comandos de shell y ediciones de archivos - Un mecanismo de aplicación de parches - Una capa de persistencia para el historial de conversación y el estado de la sesión La diferencia fundamental respecto al autocompletado es la autonomía. El autocompletado predice código en la posición del cursor. Un agente puede decidir inspeccionar archivos, ejecutar pruebas, modificar código, analizar fallos e iterar. Un bucle típico tiene este aspecto: ``` User task ↓ Agent builds prompt from instructions + repo context + prior messages ↓ Model proposes actions: read file, edit file, run command ↓ CLI executes allowed actions ↓ Results are added back into context ↓ Model plans next step ↓ Repeat until done or stopped ``` Ese bucle es lo que hace que estas herramientas parezcan potentes. También explica por qué el coste y la latencia se comportan de forma distinta al uso habitual de la API de «hacer una pregunta y obtener una respuesta». En la práctica, la mayoría de las sorpresas en los costes provienen del flujo de retroalimentación: las salidas de los comandos, el contenido de los archivos, los mensajes anteriores y los diffs se incluyen repetidamente en turnos posteriores. ## Claude Code, Aider, Cline y OpenCode: distintas formas del mismo patrón Las herramientas tienen estilos de interacción diferentes, pero el patrón de ingeniería básico es similar. | Herramienta | Interfaz principal | Fortaleza habitual | Riesgo de costes habitual | Claude Code | Agente nativo de terminal | Flujo de trabajo estrechamente integrado con la shell y el repositorio, con un sólido bucle de planificación y edición | Sesiones autónomas largas que acumulan contexto | Aider | Asistente de programación en pareja en la CLI con integración de Git | Edición centrada en diffs y selección explícita de archivos | Añadir demasiados archivos al contexto | Cline | Agente centrado en el editor | Integración con VS Code y uso visible de herramientas | Salidas extensas del terminal o del navegador que se incorporan al contexto | OpenCode | Flujo de trabajo de agente en terminal o editor | Flexibilidad de modelos y control del flujo de trabajo local | Proveedores mal configurados o exploraciones amplias del repositorio La distinción importante no es «cuál es más inteligente», sino cuánto contexto envía la herramienta, cómo selecciona los archivos, cómo resume el historial y cuánto control tienes sobre la ejecución de comandos de shell. Aider, por ejemplo, suele funcionar bien cuando añades deliberadamente los archivos relevantes. Claude Code tiene mayor autonomía y puede dar la sensación de ser un ingeniero sénior que se mueve por el repositorio, pero esa autonomía significa que debes definir cuidadosamente los permisos y el alcance. Cline resulta cómodo dentro del editor, especialmente cuando quieres observar las acciones, pero esa comodidad puede facilitar que apruebes demasiados pasos costosos. Los flujos de trabajo al estilo de OpenCode atraen a equipos que buscan flexibilidad de proveedores: Claude para tareas complejas de arquitectura, GPT para la implementación, Gemini para inspeccionar grandes volúmenes de contexto o modelos abiertos como Qwen, DeepSeek, Kimi, MiniMax y Llama para realizar ejecuciones locales o autoalojadas más económicas. ## Cómo usan estos agentes la API Una sola solicitud de «corrige este error» puede convertirse en decenas de llamadas a la API. Un cuerpo de solicitud simplificado para un paso del agente tiene este aspecto: ``` { "model": "claude-sonnet-4.6", "messages": [ { "role": "system", "content": "You are a coding agent. Follow repo instructions. Use tools safely." }, { "role": "user", "content": "Fix the failing invoice total test." }, { "role": "assistant", "content": "I will inspect the test and related invoice code." }, { "role": "tool", "name": "read_file", "content": "tests/test_invoice_totals.py contents..." } ], "tools": [ { "name": "read_file" }, { "name": "apply_patch" }, { "name": "run_shell" } ] } ``` Las implementaciones reales varían, pero el patrón es consistente: - La CLI recopila contexto. - El modelo decide la siguiente operación. - La CLI ejecuta la operación. - El resultado se devuelve al modelo. - El modelo continúa. Normalmente hay dos formas de exponer las herramientas. ### Protocolos de herramientas basados en texto Algunos agentes piden al modelo que genere texto estructurado: ``` RUN: pytest tests/test_invoice_totals.py -q ``` La CLI lo analiza y lo ejecuta. Esto es sencillo y portable, pero frágil. Si el modelo da un formato extraño al comando, el entorno de ejecución necesita medidas de protección. ### Llamadas nativas a funciones Otros agentes usan las llamadas a herramientas o funciones de la API del modelo. El modelo devuelve una invocación estructurada de una herramienta: ``` { "tool_name": "run_shell", "arguments": { "command": "pytest tests/test_invoice_totals.py -q", "timeout_seconds": 60 } } ``` Esto es más fácil de validar. El agente puede rechazar comandos que coincidan con patrones peligrosos, exigir aprobación para acceder a la red o restringir las escrituras al espacio de trabajo. En ambos diseños, la parte costosa no es el comando de shell. Es el prompt cada vez más grande que rodea al comando de shell. ## Por qué los bucles de agentes cambian los costes de los tokens Una integración habitual con una API podría enviar 2,000 tokens de entrada y recibir 500 tokens de salida. Una sesión de programación con un agente puede hacer lo siguiente: | Paso | Qué ocurre | Patrón de tokens de entrada | Patrón de tokens de salida | 1 | El usuario pide una corrección | Pequeño | Plan | 2 | El agente lee archivos | Mediano | Solicitud de herramienta | 3 | El agente edita código | Mediano-grande | Parche | 4 | Falla una prueba | Grande si se incluyen los registros completos | Diagnóstico | 5 | El agente lee más archivos | Mayor debido al historial | Solicitud de herramienta | 6 | El agente vuelve a intentarlo | Aún mayor | Parche | 7 | La ejecución completa de las pruebas falla en otra parte | Muy grande si se pega sin procesar | Resumen/clasificación de problemas El detalle que suele pasarse por alto: los tokens de entrada suelen predominar. Cada bucle puede reenviar las instrucciones del sistema, el historial de la conversación, los archivos seleccionados, las salidas de las herramientas y los resúmenes. Incluso con caché o compresión del contexto, las sesiones autónomas largas pueden resultar caras porque el modelo necesita suficiente información sobre el estado para evitar actuar a ciegas. Hay cuatro factores habituales que multiplican el consumo de tokens: - Contexto de archivos completos: enviar archivos de 900 líneas cuando solo importan dos funciones. - Salida de pruebas muy detallada: incluir advertencias de dependencias, barras de progreso y fallos no relacionados. - Exploraciones repetidas del repositorio: ejecutar find, tree, o rg de forma amplia y volver a incorporar la salida. - Historial de conversación sin límites: conservar cada intento fallido en lugar de resumir las decisiones. Lo que realmente ocurre en una sesión desordenada no es que «el agente razone más a fondo». A menudo, simplemente ve más contexto desactualizado. Más tokens pueden hacer que el modelo sea más lento y menos preciso si la información relevante queda enterrada. ## El modelo mental: presupuesto por bucle, no por prompt Cuando calculo el gasto, pienso en bucles. Una tarea pequeña y específica podría ser: ``` 8 turns × 12k input tokens average = 96k input tokens 8 turns × 1.5k output tokens average = 12k output tokens ``` Una tarea que se desvía del objetivo podría ser: ``` 35 turns × 55k input tokens average = 1.9M input tokens 35 turns × 3k output tokens average = 105k output tokens ``` El mismo prompt del usuario. Costes muy distintos. No necesitas precios exactos para entender la naturaleza del problema. Las sesiones con agentes escalan en función de: ``` total cost ≈ Σ(input_tokens_per_step × input_price) + Σ(output_tokens_per_step × output_price) + tool/runtime overhead ``` Los tokens de salida son visibles porque ves al agente escribir. Los tokens de entrada quedan ocultos porque la CLI los ensambla. Ese lado oculto es donde importa la disciplina presupuestaria. ## Elegir modelos para el trabajo con agentes Rara vez uso un solo modelo para todo. Para los agentes de terminal, la elección del modelo debe ajustarse a la fase: | Fase | Tipo de modelo más adecuado | Por qué | Exploración del repositorio | Modelo de contexto largo o modelo competente más económico | Requiere una lectura amplia, no ediciones perfectas | Decisión de arquitectura | Modelo con gran capacidad de razonamiento | Requiere criterio para evaluar ventajas e inconvenientes | Generación de parches | Modelo con gran capacidad de programación | Requiere diferencias de código precisas | Clasificación de fallos de pruebas | Modelo rápido de gama media | A menudo consiste en reconocer patrones | Refactorizaciones mecánicas | Modelo económico o abierto con medidas de protección | Trabajo repetitivo y verificable Una configuración práctica podría usar modelos de la clase Sonnet para la mayor parte de la programación, modelos de la clase Opus/GPT-5.5 para la depuración difícil o el diseño, modelos de contexto largo del estilo de Gemini/Fable para inspecciones extensas y modelos abiertos para refactorizaciones locales de tipo lint. Los nombres exactos cambiarán; el patrón se mantiene. Un error habitual es usar el modelo más caro durante todo el bucle. Ese modelo acaba consumiendo tokens de precio elevado para leer ruido relacionado con node_modules, advertencias de pruebas y archivos generados. Reserva el modelo más potente para las decisiones que realmente lo necesitan. ## Consejos de configuración que importan La mejor configuración no es «máxima autonomía». Es «respuesta rápida con permisos limitados». ### 1. Ignora los archivos generados y de terceros Todo agente de programación debería tener una lista de exclusión. Empieza por los mismos elementos que excluyes de las búsquedas y las revisiones: ``` node_modules/ dist/ build/ coverage/ .venv/ __pycache__/ target/ vendor/ *.lock *.min.js *.map ``` Normalmente no excluyo los archivos de bloqueo de forma global si la tarea implica resolver dependencias, pero sí los excluyo del contexto predeterminado. Se puede incorporar un archivo de bloqueo de forma explícita cuando sea necesario. ### 2. Usa comandos de prueba de alcance limitado No dejes que el agente ejecute por defecto toda la batería de pruebas en cada iteración. Dale una secuencia de comandos de alcance progresivo: ``` # First loop: fastest relevant test pytest tests/billing/test_invoice_totals.py -q # Second loop: nearby package pytest tests/billing -q # Final confidence check pytest -q ``` Para JavaScript o TypeScript: ``` pnpm test invoice-total.test.ts -- --runInBand pnpm lint src/billing pnpm test ``` No se trata solo del tiempo de ejecución. Las salidas más pequeñas implican prompts más pequeños en el siguiente bucle. ### 3. Limita la salida de los comandos Si tu agente admite límites de salida, úsalos. Si no, envuelve los comandos por tu cuenta: ``` pytest tests/billing -q 2>&1 | tail -120 ``` O para compilaciones con mucha salida: ``` pnpm test 2>&1 | grep -E "FAIL|Error|Expected|Received|at " | head -200 ``` Ten cuidado: el filtrado puede ocultar contexto útil. Lo uso después del primer fallo, no antes. Primero observa la naturaleza del fallo y luego limita las ejecuciones repetidas. ### 4. Pide diferencias de código, no reescrituras Para archivos grandes, indica al agente explícitamente: ``` Make the smallest safe patch. Do not rewrite unrelated functions. Show a concise diff summary before running tests. ``` Esto reduce el riesgo y normalmente reduce los tokens de salida. Más importante aún, mantiene la revisión del código manejable. ### 5. Separa la planificación de la ejecución Para cambios de cierta complejidad, suelo empezar con: ``` Inspect the relevant files and propose a plan. Do not edit yet. Limit repo inspection to payment, invoice, and tax modules unless needed. ``` Después apruebo el plan y dejo que lo implemente. Así se evita el fallo de «el agente edita antes de comprender». ## Controlar el gasto durante sesiones largas Las sesiones largas son donde los agentes CLI destacan y donde se vuelven peligrosos. Esta es la lista de comprobación que uso para controlar el gasto en el trabajo real: - Define un objetivo para la sesión: «Haz que test_invoice_rounding pase», en lugar de «arregla la facturación». - Especifica los archivos cuando sea posible: proporciona rutas exactas en lugar de pedir al agente que lo descubra todo. - Reinicia el contexto tras un cambio de rumbo: inicia una sesión nueva con un resumen cuando cambie la tarea. - Resume los fallos manualmente: pega las 30 líneas importantes, no un registro de 3,000 líneas. - Recurre a modelos más potentes de forma deliberada: usa un modelo más potente solo cuando haya un bloqueo claro. - Detente si se repiten los mismos ciclos: si el agente falla dos veces de la misma manera, intervén. Una buena instrucción para reiniciar la sesión sería esta: ``` We are fixing invoice rounding. Known facts: - Failure is in tests/billing/test_invoice_totals.py::test_round_half_even - Expected 10.24, actual 10.25 - Decimal quantization happens in src/billing/money.py - Tax calculation calls round_money() from src/billing/tax.py Continue from this summary. Inspect only those files first. ``` Esa instrucción puede resultar más económica y clara que arrastrar toda una conversación fallida. ## Claves de API, proveedores y enrutamiento La mayoría de los agentes CLI pueden comunicarse directamente con la API de un proveedor de modelos o a través de una pasarela compatible. Las principales cuestiones técnicas son: - Autenticación: dónde se almacenan las claves de API y si se filtran al historial de la shell o a los registros. - Enrutamiento de modelos: qué modelo se encarga de cada fase. - Límites de solicitudes: los ciclos de los agentes pueden generar ráfagas de solicitudes rápidamente. - Observabilidad: informes de tokens y costes por sesión. - Límites de los datos: si se puede enviar código a API externas. Una configuración mínima del entorno suele ser así: ``` export ANTHROPIC_API_KEY="..." export OPENAI_API_KEY="..." export GEMINI_API_KEY="..." ``` Para los equipos, prefiero un script contenedor que seleccione los modelos y registre el uso: ``` #!/usr/bin/env bash set -euo pipefail export AGENT_MODEL="${AGENT_MODEL:-sonnet}" export AGENT_MAX_OUTPUT_TOKENS="${AGENT_MAX_OUTPUT_TOKENS:-4096}" export AGENT_SESSION_BUDGET_USD="${AGENT_SESSION_BUDGET_USD:-10}" coding-agent "$@" ``` Si usas una pasarela con varios modelos, aquí puede resultar útil enrutar el tráfico de Claude, GPT, Gemini o modelos abiertos a través de una única interfaz. Lo importante no es la lista de logotipos, sino disponer de una contabilidad fiable del uso y de controles por modelo. ## Qué incluyo en las instrucciones del repositorio La mayoría de los agentes respetan algún tipo de archivo de instrucciones del repositorio. Mantengo el mío breve y operativo: ``` ## Agent Instructions - Prefer minimal diffs over rewrites. - Do not run full test suites until targeted tests pass. - Never edit generated files in `dist/`, `build/`, or `coverage/`. - Use `rg` for search. - Before large refactors, propose a plan and wait. - If a command emits more than 200 lines, rerun with a narrower command. ``` No es una cuestión de cortesía. Define cómo funciona el ciclo. El agente seguirá cometiendo errores, pero unas buenas instrucciones reducen el desperdicio recurrente. Un problema habitual: los archivos de instrucciones demasiado largos se convierten en ruido de fondo. Si las instrucciones de tu agente son 300 líneas sobre filosofía de estilo, el modelo puede pasar por alto las tres restricciones operativas que importan. Pon primero las reglas de mayor valor. ## Latencia: el otro coste Incluso cuando el gasto en tokens es aceptable, la latencia puede romper el ritmo de trabajo. La latencia de los agentes procede de: - Tiempo de inferencia del modelo - Tiempo de ejecución de las herramientas - Tiempo de indexación de archivos - Tiempo de ejecución de las pruebas - Pausas para la aprobación humana Para ciclos rápidos, optimizo el «tiempo hasta la siguiente observación útil». Una prueba específica de 15 segundos es mejor que una simulación completa de CI de 6 minutos. Un modelo más pequeño que identifica correctamente un error de sintaxis en 4 segundos es mejor que un modelo prémium que dedica 45 segundos a producir una explicación impecable. Las mejores sesiones se sienten como programación en pareja: ``` inspect → patch → targeted test → inspect failure → patch → targeted test → final suite ``` Las peores sesiones se sienten como una parodia de CI: ``` scan repo → edit many files → run everything → drown in logs → repeat ``` ## Limitaciones y modos de fallo Los agentes de terminal son útiles, pero no hacen magia. Tienen dificultades cuando: - El repositorio tiene dependencias ocultas en tiempo de ejecución que las pruebas no contemplan. - La tarea requiere criterio de producto en lugar de transformar código. - El error depende de servicios externos o de un estado inestable. - La base de código tiene abstracciones engañosas o documentación desactualizada. - El agente no puede ejecutar el comando de validación pertinente. También pueden producir correcciones plausibles pero erróneas. Esto es especialmente habitual cuando las pruebas son poco sólidas. Si el agente no puede verificar el comportamiento, trata su resultado como un parche sin revisar de un ingeniero júnior: potencialmente útil, pero nunca digno de confianza automática. La seguridad también importa. No des a un agente acceso sin restricciones a la shell en un repositorio sensible sin comprender el modelo de aprobación de la herramienta. «Ejecutar comandos» incluye la capacidad de mostrar variables de entorno, modificar archivos, instalar paquetes o acceder a la red, salvo que se impongan restricciones. ## Conclusiones prácticas - Trata las herramientas CLI de programación como ciclos de control impulsados por API, no como instrucciones aisladas. - Optimiza el coste reduciendo el número de ciclos y el tamaño del contexto, especialmente la salida de los comandos. - Usa modelos potentes para razonamientos difíciles, no para cada paso mecánico. - Mantén las instrucciones del repositorio breves, operativas y centradas en el comportamiento del agente. - Prioriza las pruebas específicas al principio y la validación más amplia al final. - Reinicia las sesiones largas con resúmenes concisos en lugar de arrastrar un historial obsoleto. - Vigila los tokens de entrada; son la fuente de costes oculta en la programación con agentes. - Detente e intervén cuando el agente repita la misma estrategia fallida. Claude Code, Aider, Cline y OpenCode forman parte de un cambio real: la asistencia para programar está pasando de motores de sugerencias a colaboradores que trabajan de forma nativa en el terminal. Los equipos que más se beneficien no serán los que simplemente «activen agentes». Serán los que diseñen el ciclo: contexto acotado, herramientas seguras, gasto observable y verificación en cada paso. [Programación](/es/blog/tag/coding/)[Claude](/es/blog/tag/claude/)[Agentes](/es/blog/tag/agents/) A [AI Prime Tech](https://aiprimetech.io/es/) AI Prime Tech publica este blog. Los artículos se redactan con asistencia de IA; comprueba los detalles específicos de cada versión, como los identificadores de modelos, los precios y los límites, en la documentación oficial antes de basarte en ellos. Obtén acceso más económico a la API de Claude Una sola clave de API para Claude Opus 5.5, Sonnet 5, Haiku 4.5 y Fable 5.1, además de GPT-6 modelos. Pago por uso, sin suscripción. [Obtén tu clave de API →](/register) AI Prime Tech es una pasarela de API independiente de terceros. Claude™ y Anthropic® son marcas comerciales de Anthropic, PBC. No se implica ninguna afiliación ni respaldo.