Introducción: El agente que todos quieren, sin la exageración
Lo que ocurre con los agentes de codificación es que la mayoría intenta ser tu jefe, tu copiloto y tu terapeuta, para luego olvidarse de simplemente escribir el código. El plan de juego es el siguiente: añadir una docena de almacenes de vectores, espolvorear un poco de polvo mágico de orquestación, atar un navegador y luego darlo por terminado. Se ve bien en la demostración. También se desmorona en el segundo en que le pides que arregle una prueba de integración inestable a las 4:52 p.m. de un viernes.
Construir un agente de codificación ligero con Claude 4.5 es, sorpresa, en realidad sencillo si dejas de perseguir el sueño de un mayordomo de software universal y simplemente construyes una herramienta que lee código, planifica, edita, ejecuta y repite. Sin sermones sobre "la IA reemplazando a los desarrolladores". Sin tuberías de Rube Goldberg. Solo un bucle ajustado que hace las cosas obvias, bien.
Esta es una guía práctica para llegar allí sin arrastrar a todo un departamento de operaciones de IA. Usaremos Claude 4.5 para el cerebro, un sistema de archivos y un shell para las manos, y una pequeña memoria para el enfoque a corto plazo. Eso es todo. Ligero significa que puedes entenderlo de una sentada, ejecutarlo localmente y confiar en él porque cada paso es inspeccionable. Lo cual, si has usado algo en este espacio últimamente, es casi subversivo.
Por qué Claude 4.5 funciona para un agente mínimo
Claude 4.5 tiene el temperamento que realmente quieres para el código: cuidadoso con el seguimiento de las instrucciones, sorprendentemente decente en la lectura de diffs y no demasiado ansioso por alucinar frameworks que no pediste. El modelo es competente en el razonamiento paso a paso sin exigir una novela de prompt completa. Esa combinación, razonamiento más moderación, lo hace ideal para un bucle de agente de codificación:
- Observar: Leer los archivos actuales, los registros de errores y las pruebas.
- Planificar: Proponer ediciones concretas con justificación.
- Actuar: Aplicar parches a los archivos, ejecutar comandos.
- Reflexionar: Evaluar la salida, iterar o detener.
Puedes atornillar esto a cualquier repositorio y obtener valor en una tarde. El truco es resistir la tentación de convertirlo en una "plataforma de IA". Si mantienes el agente ligero, Claude 4.5 hace el trabajo pesado sin interponerse en tu camino.
La arquitectura ligera: Cinco piezas, sin drama
Aquí está toda la pila que necesitas:
- Bucle central: Un proceso que llama a Claude 4.5 e interpreta sus mensajes de uso de herramientas.
- Herramientas: Un conjunto pequeño: read_file, write_file, list_dir, run_tests (o run_cmd), search_code.
- Constructor de contexto: Ensamblar un prompt corto y preciso con metadatos del repositorio y diffs recientes.
- Memoria a corto plazo: Una ventana de conversación continua más un bloc de notas explícito para el plan y las restricciones.
- Barandillas: Límites de tokens, tiempo y escritura de archivos; un modo de prueba en seco; y instantáneas de reversión.
Eso es todo. Puedes ejecutarlo sin cabeza en un terminal o envolverlo en una interfaz de usuario mínima si es necesario. La razón por la que esto funciona es aburrida: cada acción se observa y se puede verificar. El agente propone un cambio, muestra el diff, ejecuta las pruebas, lee la salida y continúa o se detiene. No hay misterio en el medio.
Cómo construir el agente (sin perder la trama)
Paso 1: Definir el contrato: Prompt y herramientas
Tu agente es tan bueno como su contrato con el modelo. Mantén el prompt del sistema corto, estricto e implacablemente práctico.
Prompt del sistema, destilado:
- Eres un agente de codificación. Tu trabajo es hacer pequeños cambios correctos en el repositorio para satisfacer una tarea del usuario.
- Piensa en voz alta en un bloc de notas oculto; expón solo planes y diffs al usuario.
- Prefiere diffs mínimos, pruebas de funcionamiento y progreso incremental.
- En caso de duda, propone un experimento y ejecútalo.
- Nunca fabriques archivos o comandos: enumera y lee antes de editar.
Esquema de herramientas (no le des muchas vueltas):
- read_file(path, offset?, length?)
- write_file(path, content, create_if_missing=false)
- run_cmd(command, timeout=60, cwd=repo_root)
- search_code(query, path=repo_root, max_results=50)
Extras opcionales: git_diff y git_revert(sha) si quieres reversiones manos libres. Puedes omitir un almacén de vectores; la mayoría de las tareas útiles dependen de un puñado de archivos en la memoria de trabajo más una búsqueda rápida.
Paso 2: Mantener el contexto ligero
El relleno de contexto es el culto al cargo del diseño de agentes. No vuelques todo tu monorepositorio en el prompt. En su lugar:
- Resumen del repositorio: Resumen de una párrafo del README; puntos de entrada; comando del ejecutor de pruebas.
- Archivos activos: Solo los archivos que el agente planea tocar: léelos en fragmentos según sea necesario.
- Tarea: El objetivo del usuario, expresado de forma concisa: "Corregir la prueba fallida FooTest.test_bar en tests/foo_test.py".
- Restricciones: Límites de tiempo de ejecución, lista blanca de escritura de archivos, reglas de estilo y expectativas de versionado semántico si corresponde.
- Historial reciente: Los dos últimos diffs y sus resultados de prueba. Nada más.
Claude 4.5 es perfectamente capaz de obtener más contexto cuando lo necesita a través de search_code y read_file. Dale el mapa, no el territorio.
Paso 3: El bucle (Observar → Planificar → Actuar → Reflexionar)
- Observar: Comienza enumerando los directorios, leyendo la prueba fallida, el código bajo prueba y el registro de errores. Pídele a Claude que resuma los síntomas del fallo en dos o tres viñetas.
- Planificar: Haz que Claude proponga un plan con:
- Archivos para inspeccionar o editar
- Diffs mínimos para intentar
- Un comando de prueba para validar
- Actuar: Aplica el diff propuesto a través de write_file. Muestra el diff textualmente. Ejecuta las pruebas.
- Reflexionar: Introduce stdout/stderr de nuevo. Pregúntale a Claude: ¿proceder, retroceder o detener? Si el plan cambia, requiere una justificación de una frase que haga referencia a la salida real.
- Salir: Detente cuando las pruebas pasen, o después de N iteraciones, lo que ocurra primero.
Esto es una programación en pareja glorificada donde realmente mantienes la honestidad del emparejamiento.
Paso 4: Barandillas que te salvan el fin de semana
- Lista blanca de escritura: Solo permite escrituras dentro de src/, lib/ o rutas aprobadas explícitamente.
- Límite de tamaño de diff: Limita las ediciones a 200–500 líneas por paso. Si es más grande, divídelo en subpasos.
- Lista blanca de comandos permitidos: ejecutores de pruebas, linters y algunos scripts de desarrollo. Prohíbe la red. Quieres reproducibilidad, no curl del salvaje oeste.
- Tiempo de espera y reintentos: Tiempos de espera cortos, un reintento máximo: los bucles de reejecución interminables son donde los agentes van a morir.
- Modo de prueba en seco: Imprime los diffs propuestos pero no escribas. Genial para la revisión de código.
Claude 4.5 se apegará a las reglas si las haces explícitas. Si no lo haces, no te sorprendas cuando intente "ayudar" reorganizando todo tu repositorio para que se ajuste a alguna publicación de blog de 2017.
Paso 5: Memoria que es realmente útil
La memoria a corto plazo resuelve el 80% del problema. Mantén:
- Un bloc de notas para la hipótesis y el plan actuales.
- Una lista de archivos tocados en esta sesión.
- Las dos últimas salidas de comando.
Eso es suficiente para que Claude 4.5 razone coherentemente. La memoria a largo plazo, los registros de tareas, las incrustaciones, pueden ser útiles para bases de código recurrentes, pero trátala como un aditivo opcional. Si tu agente no puede corregir una prueba sin un índice vectorial de 500 MB, no es un agente, es una dependencia.
El esquema de implementación mínima
En términos de pseudocódigo, puedes implementar este agente en un par de cientos de líneas:
- initialize: carga los metadatos del repositorio, las restricciones y el cliente del modelo
- observe: lee las pruebas fallidas, los archivos, los registros
- plan = model.propose_plan(context)
- while not done and steps < MAX:
- diff = model.propose_patch(plan)
- show(diff); maybe approve
- out = run_cmd(plan.test_cmd)
- reflect = model.evaluate(out)
- if reflect == pass: done = true
- else if reflect == rollback: git_revert(last_commit)
- else: plan = model.revise_plan(out)
Notarás las partes faltantes: no hay agentes que administren agentes, ni "delegados", ni "modelo de planificación" y "modelo de ejecución" separados. Claude 4.5 puede hacer ambos trabajos bien si no lo saboteas con un aparato de Rube Goldberg.
Prompts que no se esfuerzan demasiado
Los prompts malos intentan ser inteligentes. Los buenos prompts son aburridos y específicos. Aquí hay un esqueleto sensato para tu bloque de instrucciones central:
- Objetivo: Indica la tarea de codificación exacta y los criterios de éxito.
- Contexto: Estructura del proyecto, puntos de entrada y comando de prueba.
- Restricciones: Lista blanca de escritura, límite de tamaño de diff, sin red.
- Preferencias de estilo: Versión de idioma, formateador, reglas de linter.
- Proceso: Observar → Planificar → Actuar → Reflexionar; mostrar diffs; ejecutar pruebas; iterar hasta N pasos; detener cuando las pruebas pasen.
Claude 4.5, con esta estructura, no necesitará un escenario de juego de roles de 100 líneas. Simplemente funciona.
Ejemplo práctico: Corregir una prueba fallida
Digamos que una prueba está fallando en tests/time_test.py porque parse_time("09:00") devuelve 5400 en lugar de 32400. El bucle del agente debería verse así:
- Observar: Leer time.py y time_test.py; ejecutar pytest -k parse_time.
- Planificar: Hipótesis: error de cálculo de segundos frente a minutos; proponer la edición de parse_time; añadir un caso límite de unidad.
- Actuar: Aplicar el parche a parse_time, añadir una prueba para las horas con ceros iniciales; ejecutar pruebas.
- Reflexionar: Si las pruebas aún fallan, leer el error, ajustar las matemáticas o la expresión regular, volver a ejecutar.
El parche exitoso mínimo podría ser un cambio de dos líneas. Ese es el punto. Ediciones pequeñas, ciclos rápidos, progreso real.
Dónde la ligereza vence al fregadero de la cocina
- Latencia: Un modelo, un bucle, sin sobrecarga de orquestación.
- Transparencia: Cada paso es auditable. Puedes diferenciarlo, puedes revertirlo, puedes volver a ejecutarlo.
- Control: Las barandillas mantienen el daño local. El agente no puede desviarse hacia tu infraestructura.
- Costo: Menos llamadas, menos contexto, tokens predecibles.
- UX: Lo entiendes. Tus compañeros de equipo lo entienden. Tu futuro yo no te odiará.
Y las concesiones:
- Amplitud: Un agente de codificación ligero no refactorizará tu monorepositorio de cinco idiomas en una sola pasada. Tampoco debería hacerlo.
- Iniciativa: No inventará hojas de ruta de varias semanas. Tú le das tareas.
- Estatalidad: Sin una gran capa de memoria, olvida la historia distante por diseño. Eso es una característica hasta que es un error.
El punto óptimo de Claude 4.5 para los agentes de codificación
Claude 4.5 brilla en:
- Leer y razonar sobre diffs y registros.
- Producir cambios de código coherentes y mínimos.
- Seguir las restricciones y ser explícito sobre la incertidumbre.
Es menos bueno en:
- Adivinar el comportamiento de la API que no puede leer.
- Coreografía pesada de herramientas (no es necesario aquí).
- Refactorizaciones largas de varios archivos sin que un humano guíe los pasos.
Ese último punto es importante. La mejor manera de obtener resultados sólidos no es hacer que el agente sea más grande, es hacer que la tarea sea más pequeña. Usa tu cerebro para el alcance y Claude 4.5 para la ejecución dentro de ese alcance.
Una palabra sobre la integración de IDE
Resiste la tentación de integrar esto directamente en un panel de IDE con cincuenta conmutadores. Un bucle basado en terminal con diffs de texto sin formato es más fácil de confiar y depurar. Si quieres un aditivo de editor, mantenlo tonto:
- Comandos para iniciar/detener el bucle.
- Mostrar diffs en una vista dividida.
- Prompt de aprobación para escrituras (opcional pero prudente).
Puedes integrar más tarde. Primero, haz que funcione.
Sider.AI, usado con moderación, realmente ayuda Si quieres un entorno pragmático para ejecutar este tipo de bucle sin reinventar el andamiaje, Sider.AI realmente funciona, al menos cuando lo usas para lo que es bueno. Mantiene la conversación y los diffs ordenados, te permite ejecutar comandos y no te obliga a usar un "marco de agente autónomo" grandioso. El truco es mantener tus propias reglas: prompts cortos, bucles ajustados, diffs visibles. Sider se aparta del camino, lo cual es más raro de lo que debería ser. Errores comunes (y cómo evitar parecer tonto)
- Contexto sobrecargado: Si tu prompt se lee como una nota de rescate, lo estás haciendo mal. Obtén archivos bajo demanda.
- Refactorización prematura: ¿El agente sugiere reorganizar los módulos? Haz que pase las pruebas primero. Refactoriza más tarde.
- Archivos alucinados: Requiere list_dir y read_file antes de cualquier write_file a una nueva ruta.
- Bucles de reejecución infinitos: Limita los pasos. Exige una justificación para cada nueva hipótesis.
- Un diff gigante: Divide los cambios. Los diffs más pequeños fallan más rápido y son más fáciles de razonar.
Seguridad sin paranoia
- Ejecución local: Ejecuta en un directorio aislado. Sin red por defecto.
- Aislamiento de dependencias: Usa un venv o contenedor local. Fija las versiones.
- Secretos: El agente no los necesita. Si un comando exige un token, detente y pregunta.
- Auditoría: Persiste cada plan, diff y comando en un registro.
Cómo saber que está funcionando
- El tiempo de entrega se reduce: Las correcciones de errores que tardaban una hora ahora tardan diez minutos.
- Menos errores de dedo gordo: Los diffs se vuelven más pequeños, las pruebas se vuelven más ecológicas.
- Confías en él: Dejas de vigilar cada acción porque no te ha quemado.
- Los compañeros de equipo lo usan: La definición de éxito es que otros lo adopten sin una reunión.
Escalar, con cuidado
Si realmente debes escalar, hazlo con disciplina:
- Subtareas paralelas, no cerebros paralelos: Divide el trabajo, ejecuta múltiples bucles ligeros en directorios separados y fusiona cuando sea ecológico.
- Memoria episódica, no un volcado de cerebro: Almacena parches exitosos y asignaciones de síntomas a correcciones. Recupera quirúrgicamente.
- Pases "más grandes" periódicos: Reserva una sesión guiada por humanos para las refactorizaciones; el agente ayuda, no lidera.
Una implementación de referencia mínima (esquema)
Pseudocódigo tipo Python para ponerse en movimiento:
- def init(self, repo_root, model):
- self.history = [] # últimos dos diffs y salidas de prueba
- "repo": summarize_repo(self.root),
- "constraints": {"write_whitelist": ["src/", "tests/"], "max_diff_lines": 300, "no_network": True},
- "history": self.history[-2:],
- plan = self.model("propose_plan", self.context(task))
- diff = self.model("propose_patch", {"plan": plan})
- out = run_cmd(plan.test_cmd)
- eval = self.model("evaluate", {"output": out, "plan": plan})
- self.history.append({"diff": diff, "out": tail(out)})
Un final de tamaño humano
La industria sigue prometiendo agentes de desarrollador autónomos. Lo que realmente necesitamos es un asistente honesto que lea, planifique, edite, ejecute y se detenga. Claude 4.5 es bueno en eso, siempre y cuando no lo entierres bajo marcos que existen principalmente para justificarse a sí mismos. Ligero no es un compromiso, es el punto. Construye el bucle, añade las barandillas y deja que la herramienta haga lo único que las herramientas siempre han hecho cuando las mantienes simples: hacer que el trabajo sea más pequeño.
Conclusión: El atajo aburrido que gana
Aquí está tu lista de verificación para un agente de codificación ligero con Claude 4.5:
- Un bucle, un modelo, herramientas pequeñas.
- Contexto ajustado: tarea, algunos archivos, últimas salidas.
- Diffs mínimos, pruebas frecuentes, límites duros.
- Ejecución local, en espacio aislado; sin red.
- Aditivo de editor opcional; nunca requerido.
Si entrecierras los ojos, se parece sospechosamente a una buena ingeniería de software, solo que más rápido. Y esa es la gracia. Lo más inteligente que puedes hacer aquí no es perseguir la "autonomía", es codificar la disciplina. Cuanto menos le pidas al agente, más obtienes.
Preguntas frecuentes
P1: ¿Cómo empiezo a construir un agente de codificación ligero con Claude 4.5?
Define un conjunto de herramientas pequeño (leer, escribir, buscar, ejecutar), escribe un prompt de sistema estricto e implementa un bucle Observar → Planificar → Actuar → Reflexionar. Mantén el contexto pequeño y alimenta registros y diffs reales: Claude 4.5 funciona mejor cuando la tarea es limitada y la retroalimentación es concreta.
P2: ¿Necesito una base de datos vectorial o una capa de memoria para un agente de codificación Claude 4.5?
No. Para la mayoría de las tareas, la memoria a corto plazo más search_code es suficiente. Añade memoria a largo plazo solo si vuelves a visitar repetidamente la misma base de código y puedes demostrar que ahorra tokens sin hacer que el agente sea más tonto.
P3: ¿Qué barandillas son esenciales para un agente de codificación Claude 4.5?
Lista blanca de rutas grabables, limita los tamaños de diff, restringe los comandos y registra cada acción. Estos límites simples mantienen al agente predecible y hacen que las reversiones sean aburridas, en el buen sentido.
P4: ¿Puede un agente ligero manejar refactorizaciones de varios archivos?
Sí, si divides el trabajo en pequeños pasos y mantienes el bucle ajustado. Claude 4.5 puede administrar las refactorizaciones, pero tú guías el alcance; de lo contrario, obtendrás un diff gigante y frágil que no querrás revisar.
P5: ¿Dónde encaja Sider.AI con un agente de codificación Claude 4.5?
Sider.AI es útil como un espacio de trabajo ordenado: conversaciones, diffs y comandos en un solo lugar, sin forzar un marco de agente pesado. Úsalo para ejecutar tu bucle, no para reinventarlo. 
