Guía · Intermedio · 11 min
Trabajar bien con un agente de código: dividir tareas, revisar, probar y controlar los costos
Para trabajar con un agente de código, defina la tarea, divida los cambios, revise las diferencias y ejecute pruebas para controlar la calidad y los costos.
Para trabajar bien con un agente de código, asígnele una tarea que pueda comprobar, limite su alcance y revise los cambios y las pruebas antes de aceptarlos. Controle los costos teniendo en cuenta tanto el gasto como el tiempo humano necesario para validar un cambio, y defina de antemano cuándo debe detenerse el trabajo.
Preparar un entorno cuyo estado conozca
Los requisitos previos son sencillos: un proyecto con copia de seguridad y control de versiones, un entorno de desarrollo operativo, instrucciones para ejecutarlo y una persona capaz de validar el resultado. Antes de modificar nada, identifique los archivos que ya tienen cambios, las pruebas disponibles y los errores conocidos. De lo contrario, podría atribuir al agente un defecto anterior o permitir que sobrescriba su trabajo.
Trabaje en una rama específica o en una copia aislada. Conserve un punto de partida recuperable y utilice datos ficticios cuando la aplicación maneje información sensible. Una rama separa los cambios, pero no protege los archivos accesibles, las credenciales presentes en el equipo ni los servicios a los que se puede conectar.
Conceda los permisos necesarios para la tarea: consultar el proyecto, modificar determinados archivos y ejecutar las comprobaciones previstas. El acceso a producción, a la facturación y a los secretos requiere un tratamiento separado. La guía para proteger un agente de IA explica estos límites.
Este método es válido con independencia del producto que elija en el directorio de agentes de IA. También exige distinguir las funciones anunciadas de las que están disponibles en su entorno. Para entender el ciclo de lectura, modificación y ejecución, consulte el artículo sobre el funcionamiento de los agentes de código.
1. Convertir una petición en un acuerdo de trabajo
Una petición como «mejore el inicio de sesión» deja abiertas las cuestiones esenciales: qué falla, a qué usuario le ocurre, en qué circunstancias y cuál es el resultado esperado. Empiece por describir un comportamiento observable. Si se trata de corregir un error, indique los pasos para reproducirlo y lo que debería suceder en su lugar.
El acuerdo de trabajo debe precisar:
- el resultado esperado y los casos cuyo comportamiento debe mantenerse;
- los archivos o módulos que probablemente estén implicados;
- las restricciones técnicas y los cambios excluidos;
- las comprobaciones necesarias para aceptar el resultado;
- las situaciones que obligan a detenerse y solicitar una decisión.
Distinga lo que sabe de lo que supone. El nombre de un archivo puede orientar la búsqueda sin convertirse en una obligación. Una restricción de compatibilidad, en cambio, debe quedar explícita.
Este es un ejemplo ficticio de instrucción que puede adaptar a su proyecto:
Objetivo: conservar los filtros activos al recargar
la página de búsqueda.
Comportamiento esperado:
- Los filtros válidos se recuperan desde la dirección.
- Los valores desconocidos se ignoran.
- Si no hay filtros, se mantiene el comportamiento actual.
Alcance:
- Reutilizar los mecanismos existentes.
- No añadir dependencias.
- No modificar la autenticación.
Comprobación:
- Cubrir la recuperación y los valores no válidos.
- Comprobar la recarga en el navegador.
Detención:
- Informar de cualquier incompatibilidad con el enrutamiento existente.Las convenciones permanentes del repositorio deben mantenerse separadas de esta petición puntual. La guía para redactar las instrucciones de un agente explica cómo evitar que se repitan reglas contradictorias en cada sesión.
2. Dividir el trabajo en cambios que pueda revisar
Un bloque de trabajo adecuado responde a una intención coherente: corregir una validación, añadir un comportamiento o sustituir un mecanismo concreto. Dividir solo por tamaño de archivo puede separar artificialmente el código de sus pruebas. En el extremo contrario, reunir una funcionalidad, una reorganización y una actualización de dependencias dificulta localizar los errores.
Cuando un cambio afecta a varias partes del sistema, empiece por un recorrido funcional acotado: una entrada, su procesamiento y un resultado visible. Amplíelo después a los demás casos. Cada bloque debe poder explicarse, comprobarse y, si hace falta, retirarse sin deshacer todo el trabajo.
| Criterio | Tarea bien delimitada | Tarea que conviene dividir |
|---|---|---|
| Objetivo | Un comportamiento observable | Varios objetivos independientes |
| Validación | Criterios de aceptación explícitos | Impresión general de mejora |
| Revisión | Una intención fácil de seguir | Mezcla de cambios sin relación |
| Dependencias | Interfaces conocidas | Decisiones estructurales aún pendientes |
| Reversión | Efectos identificables | Consecuencias difíciles de separar |
El límite útil depende de su capacidad para revisar el resultado. Un pequeño cambio en los permisos puede exigir más atención que un cambio de nombres que afecte a muchos archivos.
La división también sirve para repartir el trabajo. No ponga a varios agentes a trabajar sobre los mismos archivos sin coordinación. Las tareas independientes pueden avanzar por separado, pero alguien debe comprobar sus interfaces y cómo encajan entre sí. La ejecución en paralelo no elimina los conflictos ni el costo de integración.
3. Pedir una exploración antes de autorizar cambios
Si la tarea es ambigua, pida primero una exploración limitada: puntos de entrada, convenciones existentes, pruebas relacionadas y dependencias afectadas. Solicite referencias a los archivos consultados. Un plan convincente que no se apoye en el repositorio puede partir de una arquitectura imaginaria.
El plan debe identificar los cambios previstos, explicar por qué son necesarios y describir cómo se comprobarán. También debe señalar las incógnitas: reglas de negocio que no están documentadas, una prueba que no se puede ejecutar o una compatibilidad que no está clara.
La documentación de buenas prácticas de Claude Code recomienda, entre otras cosas, explorar antes de implementar y establecer criterios de comprobación precisos. Tanto con Claude Code como con otros agentes, estas recomendaciones deben adaptarse a la complejidad del cambio.
Una corrección evidente no necesita una larga fase de planificación. Puede autorizar directamente un cambio localizado, acompañado de una comprobación proporcional. Reserve la discusión previa para las decisiones que afectan a la arquitectura, los datos o el comportamiento del producto.
A continuación, aporte un contexto seleccionado: el escenario que reproduce el problema, los archivos pertinentes y los mensajes de error útiles. La ventana de contexto es la cantidad de información que el modelo puede procesar en una interacción; llenarla de registros sin relación dificulta el seguimiento de la tarea. Pida una búsqueda dirigida antes de proporcionar todo el repositorio.
4. Establecer puntos de control durante la ejecución
Autorice al agente a continuar con las operaciones reversibles necesarias dentro del alcance acordado. Pedir confirmación para cada lectura o corrección menor retrasa el trabajo sin ayudarle a decidir. Sitúe las aprobaciones en los puntos donde cambian las consecuencias.
Añadir una dependencia, realizar una migración destructiva, acceder a la red de forma imprevista o modificar permisos requiere una explicación antes de ejecutarse. El agente debe presentar el motivo, el impacto y las alternativas. Así podrá aprobar una acción concreta.
Defina también cuándo debe detenerse el agente durante las correcciones:
- se repite el mismo fallo sin información nueva;
- el cambio supera el alcance aceptado;
- falta una decisión de negocio;
- el entorno impide realizar las comprobaciones;
- se alcanza el presupuesto acordado.
Pida un informe basado en observaciones: archivos modificados, comprobaciones ejecutadas, resultado obtenido y bloqueos. Una declaración de éxito no constituye una prueba.
Por último, los archivos y las páginas consultados pueden contener instrucciones maliciosas. Una inyección de instrucciones puede intentar desviar al agente de su objetivo. La documentación de seguridad de Claude Code describe este riesgo y las protecciones asociadas. Trate el contenido externo como datos y examine cualquier petición inusual de acceso o envío de información.
5. Revisar las diferencias antes de leer el resumen
Empiece por la lista completa de archivos afectados, incluidos los nuevos. Compruebe después que cada cambio contribuye a la tarea. Las limpiezas adicionales, los cambios de nombres y los ajustes de formato pueden ocultar la corrección que interesa revisar.
En un proyecto que utilice Git, estos comandos permiten examinar los cambios en archivos bajo seguimiento y, después, los preparados en el área de preparación:
git diff --stat
git diff
git diff --cachedLa documentación oficial de git diff detalla qué comparaciones se realizan. Estas vistas no constituyen, por sí solas, un inventario de los archivos sin seguimiento: compruebe también el estado del repositorio con su herramienta habitual.
Revise primero el comportamiento de negocio: condiciones, valores predeterminados, permisos y casos límite. Examine después los efectos técnicos: errores ocultos, llamadas adicionales, nuevas dependencias, registros que contengan datos sensibles o cambios de configuración.
No se limite a las líneas añadidas. Lea el código que las rodea y los puntos desde los que se llama a las funciones afectadas. Una función correcta por separado puede incumplir una convención implícita o trasladar una responsabilidad al lugar equivocado.
El resumen del agente sirve, al final, para comparar su intención con el resultado. Cualquier diferencia requiere una explicación. Una revisión asistida puede buscar un defecto concreto, como un fallo en el control de permisos, pero sigue siendo una ayuda: usted debe poder justificar por qué acepta el cambio.
6. Probar el comportamiento, los límites y las regresiones
Las pruebas deben comprobar lo acordado para la tarea. Una prueba que reproduce exactamente la implementación puede pasar aunque el requisito se haya interpretado mal. Describa las entradas, las salidas esperadas y las situaciones problemáticas con independencia de la solución propuesta.
Para corregir un error, busque una evidencia de que existía: una prueba que falla antes del cambio, una reproducción manual o un registro que permita analizarlo. Compruebe después que la corrección resuelve el defecto sin eliminar el control que lo detectaba.
| Comprobación | Qué aporta | Cuál es su límite |
|---|---|---|
| Análisis estático y comprobación de tipos | Coherencia de determinadas construcciones | No valida las necesidades de negocio |
| Prueba unitaria | Comportamiento de una unidad aislada | Depende de las suposiciones y las simulaciones |
| Prueba de integración | Funcionamiento entre componentes | Requiere un entorno representativo |
| Prueba de extremo a extremo | Comportamiento visible de un recorrido | No cubre todas las situaciones |
| Comprobación manual dirigida | Evaluación visual o funcional | Es poco sistemática |
Empiece por las comprobaciones más cercanas al cambio y amplíelas según su impacto y las exigencias del proyecto. Un cambio en la autenticación requiere comprobar que se deniega el acceso cuando corresponde. Una interfaz también exige revisar el uso del teclado, los errores y los estados sin contenido.
La documentación de GitHub sobre el uso responsable de agentes señala las limitaciones del código generado y la necesidad de revisarlo y probarlo. Distinga siempre entre las comprobaciones superadas, las fallidas y las que no se han ejecutado. Si el entorno está incompleto, debe indicarse en la entrega.
7. Controlar el costo por cambio aceptado
El costo que conviene medir incluye el consumo del modelo, las herramientas de pago, el entorno de ejecución y el tiempo humano dedicado a definir, revisar y corregir la tarea. Una tarea barata en consumo de API puede exigir muchas horas de corrección manual. A la inversa, una investigación más profunda puede evitar cambios innecesarios.
Antes de empezar, establezca unos límites acordes con lo que está en juego. Distinga el presupuesto económico, el tiempo máximo y las condiciones para continuar. Pedir por escrito que se respete un límite no garantiza que se aplique: utilice los topes técnicos disponibles y compruebe cómo funcionan.
La facturación depende de la forma de acceso. Una suscripción, el consumo de API y los créditos adicionales no se pueden comparar directamente. Consulte las condiciones de su plan en lugar de deducir el costo de una tarea solo a partir de la cuota mensual.
En una API, los tokens de entrada y salida contribuyen a la factura según las tarifas aplicables. La caché y otros conceptos que puedan existir deben contabilizarse por separado. La calculadora de precios de LLM ayuda a preparar una estimación; los datos de facturación permiten contrastarla con el uso real.
Lleve un registro por tarea: gasto observado, tiempo de revisión, resultado aceptado o descartado y trabajo adicional necesario. Para distinguir las partidas del presupuesto, consulte también el artículo sobre el costo real de un agente de IA.
8. Reducir los ciclos innecesarios sin debilitar las comprobaciones
La primera forma de ahorrar consiste en reducir la incertidumbre evitable: un entorno preparado, un error reproducible y un resultado esperado explícito. Pedir varias correcciones vagas de forma sucesiva puede consumir presupuesto sin aportar un diagnóstico.
Elija el nivel de capacidad según la dificultad. Una operación mecánica bien definida y un problema ambiguo de arquitectura no requieren la misma investigación. Aun así, compruebe el resultado con sus propias tareas: un modelo más barato por llamada puede acabar costando más si obliga a repetir el trabajo.
La documentación sobre gestión de costos de Claude Code presenta, entre otros aspectos, el seguimiento del consumo y el control del contexto. Como parte de su método, conserve la información útil para decidir y evite volver a enviar salidas voluminosas que no tengan relación con el fallo.
Después de una prueba fallida, pida una hipótesis y la siguiente observación que permita confirmarla. Si el agente alterna entre soluciones que ya ha intentado, interrumpa la ejecución. Retome el trabajo desde un estado conocido y con un diagnóstico más acotado.
Para una nueva sesión, prepare una nota de continuidad: objetivo, estado del trabajo, intentos fallidos y comprobaciones pendientes. Esa nota debe remitir a los archivos y resultados conservados. La guía para reducir el costo de un agente de IA profundiza en la elección del modelo, la caché y los presupuestos.
Problemas frecuentes: identificar la causa antes de volver a intentarlo
El agente modifica demasiados archivos. Compruebe si la necesidad exige realmente ese alcance. Pídale que separe los cambios necesarios de las mejoras adicionales. Si ya no puede relacionar cada modificación con un criterio de aceptación, reduzca el bloque de trabajo antes de continuar.
Las pruebas pasan, pero el resultado es incorrecto. Vuelva al escenario del usuario y a las expectativas iniciales. Examine las simulaciones, las aserciones demasiado generales y los casos excluidos. Añada una comprobación del comportamiento que falta, en lugar de limitarse a pedir más pruebas.
El agente quiere desactivar un control. Pídale que explique el fallo observado y el motivo del cambio. Relajar una validación, ignorar un error o modificar una prueba para que pase requiere una justificación independiente del resultado que se pretende obtener.
El entorno bloquea el trabajo. Separe el defecto del producto del problema de instalación o acceso. Que falte una clave o que un servicio no esté disponible no justifica modificar la lógica de negocio. Conserve el mensaje de error e indique con precisión qué comprobación no se puede realizar.
La factura aumenta sin que haya avances. Busque lecturas repetidas, salidas demasiado largas, exploraciones redundantes y correcciones que vuelven al mismo punto. Detenga la sesión si ninguna información nueva reduce la incertidumbre. Documentar el abandono puede ser preferible a continuar sin una hipótesis verificable.
Entregar con evidencias y un plan de reversión
Una entrega debe explicar el problema corregido, el comportamiento obtenido y las limitaciones pendientes. Adjunte las comprobaciones ejecutadas y sus resultados. Si el cambio es visible, añada una captura de pantalla o describa el recorrido verificado; si afecta a una interfaz técnica, aporte un ejemplo de entrada y salida.
Compruebe que las evidencias corresponden al estado final. Si se han modificado archivos después de las pruebas, identifique las comprobaciones afectadas y vuelva a ejecutar aquellas cuyo resultado ya no sea representativo. Evite presentar una comprobación anterior como validación del código entregado.
Aceptar el código y desplegarlo son decisiones distintas. Una migración de datos, una publicación o un cambio de configuración necesita sus propias condiciones de ejecución. La reversión debe contemplar los efectos externos: volver a una versión anterior del código no restaura automáticamente los datos.
Antes de aceptar el bloque de trabajo:
- El resultado cumple los criterios de aceptación.
- Cada archivo modificado tiene una justificación.
- Se han revisado el comportamiento y los casos límite.
- Las comprobaciones corresponden al estado final.
- Se indican las comprobaciones que no se han podido realizar.
- No se han añadido secretos ni accesos imprevistos.
- Se han registrado el costo y las correcciones adicionales necesarias.
- Se comprenden los efectos del despliegue y el plan de reversión.
Así dispondrá de un cambio que puede explicar, comprobar y mantener. Ese nivel de control permite delegar de forma útil la siguiente tarea.
Páginas relacionadas
Preguntas frecuentes
¿Es necesario saber programar para usar un agente de código?
Puede pedirle que produzca un prototipo sin dominar todo el lenguaje. Sin embargo, para aceptar un cambio en una aplicación en uso, necesita poder comprobar su comportamiento y comprender los riesgos técnicos. Recurra a una persona con los conocimientos necesarios cuando esa comprobación supere los suyos.
¿Cómo saber si una tarea es demasiado grande para un agente?
Intente describir con precisión qué comprobará antes de aceptar el resultado. Si la descripción mezcla varias funciones independientes o exige revisar áreas que no domina, reduzca el alcance. La capacidad de revisión humana marca un límite práctico.
¿Se puede dejar que un agente de código trabaje sin supervisión?
Depende de los permisos concedidos y de las posibles consecuencias. Una búsqueda en una copia aislada del proyecto requiere menos control que una migración de datos o un despliegue. Defina cuándo debe detenerse y mantenga una aprobación explícita para las acciones sensibles.
¿Una suscripción basta para limitar el gasto?
Revise las condiciones de su plan y la configuración de facturación. Los créditos adicionales, una clave de API o los servicios externos pueden tener presupuestos separados. Una instrucción escrita en la conversación no sustituye un límite técnico.
¿Conviene pedir a un segundo agente que revise el código?
Una segunda revisión puede detectar defectos, sobre todo si recibe una instrucción concreta y un contexto independiente. También puede repetir las mismas suposiciones equivocadas. Trate sus observaciones como indicios que debe comprobar, junto con las pruebas y la revisión humana.