Cómo obtener buenos resultados con Claude Code

• Tras experimentar durante los últimos meses con varios agentes de programación con LLM, Claude Code fue la herramienta que dejó la mejor impresión
• Gracias a Claude Code, pudo desarrollar alrededor de 12 programas y proyectos en poco tiempo, e incluso abordar trabajos que normalmente no habría comenzado por falta de tiempo
• Para usarlo con éxito, la clave está en redactar especificaciones claras, proporcionar documentación con la estructura del proyecto y cómo ejecutar build y lint, pedirle al AI que revise su propio código y operar con una guía global del agente personalizada
• Como el código escrito por la AI a menudo puede ser impreciso o ineficiente, es indispensable revisar personalmente todo el código y los casos de prueba, y agregar pruebas faltantes o pedírselas a la AI para luego volver a revisarlas
• La guía global del agente publicada como apéndice incluye lineamientos detallados de desarrollo como un plan de implementación por etapas, desarrollo guiado por pruebas, una filosofía centrada en simplicidad, claridad y pragmatismo, criterios de calidad y procesos de resolución de problemas

---

Experiencia y resultados al usar Claude Code

• Durante los últimos meses probó varios agentes de programación con LLM, y en particular la experiencia con Claude Code fue la mejor
• No es que esté libre de problemas, pero le permitió completar más de 12 programas y proyectos en poco tiempo
• Sin Claude Code, habría sido casi imposible realizar todo ese trabajo en el mismo período
• Muchos de esos trabajos eran proyectos que ni siquiera habría intentado por el tiempo que requerían

Estrategia para usar Claude Code

• Redactar especificaciones claras
  • Antes de iniciar el proyecto, documentar claramente los requisitos y el contexto para entregárselos al agente
  • Esto ayuda a dejar clara la dirección y el alcance del código a escribir
• Documentar la estructura del proyecto
  • Preparar documentación que incluya cómo ejecutar build, lint y pruebas
  • Así el agente puede explorar y trabajar sobre la base de código de forma más efectiva
• Pedir revisión de código al agente
  • Hacer que Claude Code revise directamente el código que generó para descubrir mejoras inesperadas o bugs
• Usar una guía global personal
  • Mantener un proceso de desarrollo consistente mediante ~/.claude/CLAUDE.md, que contiene reglas personales sobre el enfoque para resolver problemas, uso de TDD, mantener simplicidad y claridad, y limitar los intentos a 3

Verificación del código escrito por LLM

• El código generado por AI suele tener problemas como errores lógicos, degradación de rendimiento y pruebas incompletas
• El autor revisa manualmente todo el código y confirma su funcionamiento
  • Agrega directamente los casos de prueba faltantes
  • O se los pide a la AI y luego vuelve a revisar el código y las pruebas
• En un entorno profesional, si el PR lleva tu nombre, enfatiza que la responsabilidad final por la calidad recae en uno mismo

Contenido principal de la guía personal “global” del agente

Esta guía se administra en el archivo ~/.claude/CLAUDE.md

• Filosofía y principios clave

  • Avance gradual: hacer cambios pequeños y que siempre compilen y pasen las pruebas
  • Aprender del código existente: analizar los patrones del código y planificar antes de implementar
  • Pragmatismo primero: enfoque flexible según la situación del proyecto
  • Claridad primero: código fácil de leer y con intención evidente, evitando trucos innecesarios

• Definición de simplicidad

  • Las funciones y clases deben tener una sola responsabilidad
  • Evitar la abstracción prematura
  • Reducir la complejidad y apuntar a código que no necesite explicación

• Proceso de trabajo

  • 1. Planificación y definición de etapas:
    • Las tareas complejas se dividen en 3 a 5 etapas y se registran en IMPLEMENTATION_PLAN.md
    • Se especifican por etapa los objetivos, criterios de éxito, casos de prueba y estado de avance
  • 2. Flujo de implementación:
    • comprender → escribir pruebas (rojo) → implementación mínima (verde) → refactorización → commit
  • 3. Reevaluar tras el límite de 3 intentos:
    • Si falla, registrar los intentos realizados, los errores y sus causas
    • Explorar alternativas (2 o 3 enfoques)
    • Revisar de nuevo el diseño de fondo y la descomposición del problema
    • Probar otros patrones o funcionalidades

• Estándares técnicos

  • Priorizar la composición y usar inyección de dependencias
  • Usar interfaces para facilitar las pruebas
  • Flujo de datos explícito
  • Se recomienda TDD y no se permite desactivar pruebas

• Reglas de calidad de código

  • Todo commit debe compilar, pasar las pruebas, incluir pruebas para la funcionalidad nueva y respetar el estilo de código
  • Antes de hacer commit, ejecutar formatter y linter, revisar uno mismo los cambios y escribir mensajes de commit que expliquen el “por qué”

• Manejo de errores

  • Fallar rápido y con mensajes específicos
  • Proporcionar el contexto necesario para depurar
  • Manejar excepciones en el nivel adecuado y no ocultarlas

• Criterios de toma de decisiones

  • 1. Facilidad para probar
  • 2. Legibilidad que siga siendo comprensible dentro de 6 meses
  • 3. Consistencia con los patrones del proyecto
  • 4. Simplicidad
  • 5. Facilidad para cambiar

• Integración con el proyecto

  • Analizar 3 o más funciones similares
  • Reutilizar patrones y librerías existentes
  • Usar las mismas utilidades de prueba
  • Incorporar herramientas nuevas solo con una razón sólida

• Quality gates

  • Todas las pruebas pasan
  • Se respetan las reglas del proyecto
  • No hay advertencias del linter
  • El mensaje de commit es claro
  • La implementación coincide con el plan
  • Los TODO incluyen número de issue

• Guía de pruebas

  • Pruebas centradas en el comportamiento, no en la implementación
  • Si es posible, una sola aserción por prueba
  • Nombres claros que describan el escenario
  • Reutilizar utilidades de prueba existentes
  • Las pruebas deben ser deterministas

• Absolutamente prohibido

  • Saltarse hooks con --no-verify
  • Desactivar pruebas
  • Hacer commit de código que no compila
  • Hacer suposiciones sin verificar

• Obligatorio

  • Commits incrementales
  • Actualizar la documentación de forma continua
  • Aprender de las implementaciones existentes
  • Reevaluar el enfoque después de 3 fallos

Proyectos open source creados con Claude Code

• Reverse proxy con reconocimiento de HTML/XML (cdzombak/xrp)
• Tema Solarized para VS Code (claro/oscuro) (cdzombak/dzsolarized-vscode)
• Generador de RSS para photostream de Flickr (cdzombak/flickr-rss)
• Herramienta de metadatos para la biblioteca de fotos Lychee (cdzombak/lychee-meta-tool)
• Reporte por MQTT del estado de bloqueo de pantalla en macOS (cdzombak/macos-screenlock-mqtt)
• Configuración automática de títulos de fotos de Bird Buddy en Lychee (cdzombak/lychee-birb-title)
• Clasificación automática de fotos basada en LLM local (cdzombak/lychee-ai-organizer)
• Automatización de instalación masiva de software para macOS (cdzombak/mac-install)
• Proyecto de servicio RSS (cdzombak/rss.church)
• Exportación total/selectiva de fotos de Flickr y preservación de metadatos (cdzombak/flickr-exporter)
• Generador de galerías HTML estáticas (cdzombak/gallerygen)