Blog de Diego García Morate

∞ Explorando la interesección entre IA, emprendimiento y la tecnología

Algunos consejos para programar con agentes

Los agentes de IA para programación están transformando fundamentalmente nuestra forma de desarrollar y entender el software. Sistemas como Claude Code de Anthropic, Aider, OpenAI Codex CLI, o GitHub Copilot han pasado a ser la herramienta fundamental de trabajo para muchos desarrolladores en muy poco tiempo.

En este artículo comparto algunas estrategias prácticas y consejos basados en mi experiencia utilizando Claude Code. Si bien Anthropic ya ofrece una guía oficial de mejores prácticas, aquí me centraré en otras técnicas complementarias que utilizo y que no están cubiertas en dicha documentación.

Índice

CLAUDE.md

Quizás la mayor dificultad que tiene cualquier agente para desarrollar es la comprensión del contexto de una aplicación. Cualquier sistema tiene decenas de miles de líneas de código, multitud de dependencias y uno o varios lenguajes de programación. Para poder ofrecer una ayuda útil es necesario comprender todo esto.

Algo especialmente interesante que muchos asistentes incorporan son ficheros de contexto en los que podemos indicar al agente información del proyecto para que la tome en cuenta para todas las acciones. En el caso de Claude Code, CLAUDE.md es un archivo especial que sirve como guía para el asistente de IA, proporcionándole contexto crucial sobre tu proyecto. Funciona como un manual de instrucciones personalizado que le indica al agente cómo debe comportarse cuando trabaja con tu código. En él puedes documentar comandos frecuentes, patrones de diseño, convenciones de código, decisiones arquitectónicas y cualquier conocimiento específico de tu proyecto que sea valioso recordar entre sesiones.

CLAUDE.md es mucho más que una simple configuración; es un mecanismo para capturar y transferir conocimiento de forma incremental. No te olvides de guardar en el repositorio este fichero, forma parte del proyecto.

Un ejemplo de fichero podría ser:

# CLAUDE.md

## Objetivos del proyecto

- Crear un blog personal con enfoque en tecnología y desarrollo
- Optimizar la velocidad de carga y experiencia de usuario
- Mantener un diseño minimalista y accesible
- Facilitar la categorización y búsqueda de contenido

## Tecnologías utilizadas

- Hugo como generador de sitios estáticos
- HTML5, CSS3 y JavaScript para frontend
- Bear theme como base de diseño
- Nginx para servir el contenido estático
- Traefik como proxy inverso y gestor de SSL
- Docker y Docker Compose para orquestación de servicios

## Buenas prácticas

- Utilizar imágenes optimizadas (WebP, dimensiones apropiadas)
- Mantener una estructura de carpetas coherente para posts (/año/tema)
- Seguir convenciones de Markdown para contenido consistente
- Priorizar la carga de contenido crítico
- Minimizar dependencias externas para mejorar privacidad
- Aplicar HTTPS en todas las conexiones
- Implementar caché adecuado para recursos estáticos

## Patrones aprendidos
- Las llamadas a la API externa deben usar el cliente con reintentos
- Los componentes de UI mantienen estado local solo para UX, no para lógica de negocio
- Logs de error incluyen ID de transacción para trazabilidad

## Decisiones arquitectónicas
- Usamos arquitectura hexagonal (09/03/2025)
- Migrando de Redux a Context+Reducers (15/04/2025)
- Feature flags gestionadas en config/features.ts (02/05/2025)

## Comandos importantes
- `pnpm dev` - Servidor local (http://localhost:3000)
- `pnpm test` - Suite de pruebas completa
- `pnpm lint` - Verifica estilo y errores potenciales

## Pasos a completar en cada nueva feature

1. Crear rama feature/nombre-descriptivo desde main
2. Implementar cambios siguiendo las buenas prácticas documentadas
3. Verificar la visualización en dispositivos móviles y escritorio
4. Comprobar rendimiento (Lighthouse score > 90)
5. Solicitar revisión antes de integrar a main
6. Desplegar primero en entorno de staging
7. Validar funcionalidad en staging antes de promover a producción

Sintetizar lo aprendido

CLAUDE.md no sólo debería ser una descripción del proyecto, sino una síntesis de cómo se trabaja. Debería ser una guía condensada de todo aquello que debería saber cualquier integrante del equipo. Piensa en los agentes como un miembro más del equipo.

Algo que funciona bastante bien es que al final de cada sesión productiva con Claude, pídele que sintetice lo aprendido o las decisiones tomadas en formato Markdown para añadir a tu CLAUDE.md. Este proceso es increíblemente valioso:

Claude, basado en nuestra conversación hoy, ¿podrías sintetizar los patrones y decisiones clave que deberíamos documentar en CLAUDE.md para futuras sesiones?

Resolver creando un patrón para el futuro

También algo que hago es resolver lo que no me gusta que haga el agente modificando el fichero CLAUDE.md evitando hacerlo por instrucciones. Esto me ayuda a desarrollar una base escalable sobre la que trabajar.

Múltiples archivos CLAUDE.md

Algo también muy útil es mantener múltiples archivos CLAUDE.md en diferentes directorios, cada uno específico para su contexto:

Claude dará prioridad al archivo más cercano al código con el que estás trabajando, permitiendo instrucciones contextuales específicas que el modelo irá utilizando en función de la parte del proyecto en la que vaya trabajando. Al pedirle que actualice estos archivos cuando descubrimos nuevos patrones, creo una documentación viva que evoluciona con el proyecto.

Gestión del contexto

Algo también bastante útil es que tras cada interacción significativa, uso el comando /clear para mantener el contexto enfocado y reducir el tamaño total. Esto no solo optimiza el uso de tokens, sino que también ayuda a que Claude se concentre en la tarea actual sin distracciones de conversaciones anteriores. Cuando necesito referirme a decisiones pasadas, simplemente comparto el CLAUDE.md actualizado.

Interacción con otros agentes

Algo tedioso es que muchos agentes utilizan ficheros diferentes para almacenar estos metadatos. Espero que en breve Claude Code adopte el estándar AGENT.md que están promoviendo desde otros agentes como el de OpenAI con Codex CLI, su agente de código ligero que funciona en terminal. La convergencia hacia un estándar común tipo AGENT.md facilitaría enormemente la interoperabilidad entre diferentes asistentes de IA y permitiría que nuestras guías de proyecto funcionen con cualquier agente. Mientras tanto, seguiré evolucionando mis CLAUDE.md para que eventualmente puedan convertirse en archivos AGENT.md universales.

El enfoque “Pair Programming Asimétrico”

La forma en que abordo los problemas ha cambiado desde que uso agentes. Ahora aplico “pair programming asimétrico” con Claude Code. Funciona así:

  1. Yo defino la estrategia y los requisitos
  2. Claude implementa la primera versión
  3. Yo reviso críticamente y solicito cambios específicos
  4. Claude refina la implementación
  5. Juntos verificamos el resultado

Este ciclo me permite mantener el control creativo y estratégico mientras delego la implementación táctica. La clave está en las revisiones críticas: no te limites a aceptar la primera solución, cuestiona y refina. Esta es la razón por la cual para que el desarrollo asistido por agentes no se vuelva un batiburrillo de código inmantenible es imprescindible entender lo que quieres hacer y ser muy exigente y crítico en cómo se implemente.

Algunos patrones habituales de este enfoque son:

Planificación y alternativas

Antes de implementar soluciones, pido a Claude que genere un plan y considere alternativas:

Claude, antes de implementar la funcionalidad de carrito de compras,
¿puedes generar un plan de implementación y proponer 2-3 enfoques
alternativos con sus pros y contras?

Este enfoque evita la ceguera de solución única y a menudo revela consideraciones que habría pasado por alto.

Desarrollo guiado por pruebas (TDD)

He descubierto que los agentes de IA funcionan excepcionalmente bien con TDD:

Claude, antes de implementar la funcionalidad, vamos a escribir las pruebas
que deberá pasar. Por favor, escribe pruebas unitarias para un servicio
que debe actualizar el inventario cuando se completa una compra.

Claude escribe pruebas que capturan tanto los casos típicos como los edge cases, creando un conjunto de pruebas más completo de lo que habitualmente escribiría yo mismo. Además, muchas veces hablar sobre las pruebas que el sistema debe cumplir es más útil que el código porque habla de lo que debería pasar y de lo que no.

Aprendizaje del estilo de código existente

Antes de solicitar nuevo código, pido a Claude que analice cómo se implementan funcionalidades similares en otras partes del proyecto:

Claude, antes de implementar el nuevo endpoint de API, revisa cómo
están estructurados los endpoints existentes en ./src/api/ para
seguir el mismo patrón y estilo.

Esta técnica de “vibe coding” funciona especialmente bien en aplicaciones consolidadas con patrones establecidos y produce código que se integra naturalmente con la base existente.

FIXME y TODO en el código

Muchas veces la manera más efectiva de referirnos a los cambios que queremos realizar es anotarlos directamente en el código y pedirle al agente que los resuelva.

Aquí hay ejemplos en Python de cómo usar comentarios para guiar al agente:

# TODO: Optimizar esta consulta para grandes volúmenes de datos
users = db_session.query(User).filter(User.active == True).all()

# FIXME: Esta función falla con valores decimales
def calculate_discount(price, percentage):
    return int(price * (percentage / 100))

# TODO: Implementar caché para evitar consultas repetidas
def get_user_profile(user_id):
    return db_session.query(UserProfile).filter(UserProfile.user_id == user_id).first()

Este enfoque es mucho más eficaz que tratar de explicar todo el problema en el chat.

Comandos personalizados

Identificar los patrones en tu trabajo y tareas es algo fundamental para optimizarlas. Crear una biblioteca personal de prompts optimiza enormemente mi flujo de trabajo. Para ello Claude soporta crear comandos personalizados. Para ello puedes crear una carpeta .claude/commands donde puedes almacenar los comandos personalizados.

Estos son algunos ejemplos de prompts desarrollados que he optimizado con el tiempo:

/crea-ticket.md

Genera un ticket completo con la siguiente estructura:
- Título: Breve y descriptivo (max 80 caracteres)
- Descripción: Detallada pero concisa
- Criterios de aceptación: Lista de 3-5 condiciones verificables
- Estimación: Story points (1, 2, 3, 5, 8)
- Prioridad: Alta/Media/Baja con justificación
- Etiquetas: Palabras clave relevantes

A partir de la siguiente descripción:

/fix-unit-tests.md

#!/bin/bash
# Ejecuta pruebas unitarias, verifica linting y corrige errores automáticamente
claude-code "Realiza estas acciones secuencialmente:

1. Ejecuta las pruebas unitarias usando el comando adecuado para el proyecto (pytest, unittest, etc.)
2. Captura todos los errores y fallos de las pruebas
3. Ejecuta el linter del proyecto (flake8, eslint, etc.) y captura todas las violaciones
4. Para cada error de prueba:
   - Identifica la causa raíz
   - Proporciona una corrección específica
   - Implementa la corrección
5. Para cada error de linting:
   - Corrige automáticamente los problemas de formato
   - Para problemas más complejos, proporciona correcciones específicas
6. Ejecuta nuevamente las pruebas y el linting para verificar que todos los problemas se han resuelto
7. Resume las correcciones realizadas y cualquier patrón identificado para evitar futuros errores"

/doc-api.md

Analiza detalladamente la API en y genera documentación en formato OpenAPI/Swagger que incluya:
1. Resumen general de la API y su propósito
2. Para cada endpoint:
   - Método HTTP y ruta
   - Parámetros de ruta, consulta y cuerpo con tipos y restricciones
   - Respuestas posibles con códigos HTTP y ejemplos de payload
   - Manejo de errores y excepciones
   - Limitaciones y consideraciones de rate-limiting
3. Modelos de datos y esquemas
4. Flujos típicos de uso con ejemplos de secuencias de llamadas
5. Consideraciones de seguridad y autenticación
6. Ejemplos de código en JavaScript y Python para casos comunes

Preserva y documenta todas las convenciones existentes detectadas en el código.

Una vez creados, puedes ejecutarlos directamente desde la terminal de claude-code con la sintaxis: /project:command

Esta biblioteca de prompts estandariza mis interacciones más comunes y me permite ejecutar flujos de trabajo complejos con comandos simples, ahorrando tiempo y asegurando consistencia.

Otras Técnicas

Acceso a documentación externa

Claude puede acceder y utilizar documentación externa, lo que amplía enormemente su conocimiento contextual:

Claude, revisa esta documentación de la API de pagos y ayúdame a implementar 
la validación de tarjetas: https://docs.stripe.com/api/payment_methods

Esta capacidad es invaluable para trabajar con APIs o tecnologías que están fuera del conocimiento base del modelo.

Modo pensamiento extendido

Para problemas complejos, activo el modo de pensamiento extendido utilizando palabras clave específicas:

think
think hard
think harder
ultrathink

Estas frases están mapeadas directamente a niveles crecientes de presupuesto de pensamiento en el sistema: think < think hard < think harder < ultrathink. Cada nivel asigna progresivamente más presupuesto de pensamiento para que Claude evalúe alternativas más exhaustivamente, elabore razonamientos más detallados y considere múltiples enfoques antes de proponer una solución.

Ejecución de múltiples instancias

Para optimizar el tiempo, ejecuto múltiples instancias de Claude en paralelo:

# Terminal 1: Trabajando en la API
claude-code ./src/api/

# Terminal 2: Trabajando en los tests
claude-code ./tests/

# Terminal 3: Trabajando en la documentación
claude-code ./docs/

Esta paralelización me permite avanzar en múltiples frentes simultáneamente.

Más allá del código: Documentos, notebooks y otros formatos

Algo importante en mi experiencia con agentes de IA es que su utilidad trasciende significativamente el código. Estos asistentes son igual de potentes para trabajar con:

La misma metodología de conversación estructurada que uso para el código funciona perfectamente para estos otros formatos. Por ejemplo, al trabajar con notebooks de análisis de datos, puedo pedirle a Claude que:

Esta versatilidad convierte a los agentes de IA en una puerta de entrada a prácticamente cualquier tipo de trabajo técnico, expandiendo enormemente su valor más allá del desarrollo de software tradicional.

Más allá de la programación: tareas de administración y operaciones

Los agentes de IA no se limitan a escribir código; son igualmente efectivos para tareas operativas:

Análisis y generación de datos de prueba

Claude puede examinar la estructura de tu base de datos y generar datos de prueba realistas:

Genera datos de prueba realistas para 50 clientes con nombres, direcciones
de correo, historial de compras y preferencias basadas en este esquema de base de datos.

Operaciones de mantenimiento

Claude puede ayudar con tareas de mantenimiento, como limpiar datos obsoletos:

Claude, necesito un script para identificar y archivar clientes inactivos
(sin compras en los últimos 12 meses) en nuestra base de datos PostgreSQL.

Obviamente has de revisar todos los resultados y no ejecutarlos nunca en producción (ya estás advertido).

Scripting

Los agentes de IA son excelentes para generar scripts de automatización que resuelvan tareas repetitivas. Desde scripts de procesamiento de datos hasta automatización de flujos de trabajo, pueden ayudarte a crear soluciones robustas con documentación clara:

Desarrolla un script de Python que:
1. Monitoree una carpeta en busca de nuevos archivos CSV
2. Cuando detecte un nuevo archivo, lo procese utilizando pandas
3. Limpie los datos (elimine duplicados, maneje valores nulos)
4. Genere un reporte en formato Excel con estadísticas básicas
5. Envíe una notificación por email cuando el procesamiento esté completo

Incluye manejo de errores, logging, y documentación clara.

Disfruta y atrévete

Estamos viviendo un momento apasionante en la evolución del desarrollo de software. Los agentes de IA nos permiten centrarnos en mejorar aspectos que antes parecían imposibles o prohibitivamente costosos:

Mi consejo final es simple: disfruta del proceso y atrévete a experimentar. Las posibilidades son prácticamente ilimitadas y apenas estamos comenzando a descubrir todo el potencial de esta nueva forma de trabajar.

Surfear la ola de cambio

Estamos viviendo un momento fascinante en la evolución del desarrollo de software. Claude Code no representa solo una herramienta, sino un cambio fundamental en cómo conceptualizamos el desarrollo.

La velocidad de su evolución es a la vez un desafío y una oportunidad. Aquellos que pueden adaptarse rápidamente, que documentan y sintetizan su conocimiento de forma progresiva, y que ven a Claude como un colaborador en constante mejora, son los que extraerán el mayor valor.

El código seguirá siendo escrito, los bugs seguirán apareciendo, y los desarrolladores seguiremos siendo necesarios. Pero la naturaleza de nuestro trabajo está evolucionando hacia un rol más estratégico y creativo. Claude no es un reemplazo; es un amplificador que evoluciona tan rápidamente que nos mantiene constantemente reaprendiendo y redescubriendo lo que es posible.

Y ahí radica quizás la lección más importante: en un entorno que cambia tan rápidamente, la capacidad de aprender, desaprender y reaprender continuamente se convierte en la ventaja más valiosa.

Claude IA desarrollo programación Agentes Mejores Prácticas