Cómo obtener buenos resultados con Claude Code

 (dzombak.com)
45 puntos por GN⁺ 2025-08-09 | 5 comentarios | Compartir por WhatsApp
  • 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

Lecturas relacionadas

5 comentarios

 
wedding 2025-08-11

Que haya dado buenos resultados, ¿significa que hizo buena referencia al código que alguien ya había creado?
 
aeolian21 2025-08-11

Todo lo que hizo el autor ya lo vienen haciendo todos desde hace mucho, así que en vez de presumir cosas inútiles,
sería mucho más valioso que explicara por qué pensó que Claude fue el mejor al compararlo con otros LLM.
Comparaciones del código generado en la práctica, frecuencia de errores de compilación, estabilidad al entender el contexto, etc.
En realidad, el que mejor capacidad tiene para entender el contexto es Gemini (1 millón de tokens).
 
zxcv123 2025-08-10

Solo hizo cosas inútiles y se extendió de forma demasiado verbosa en el texto.
 
knunu 2025-08-11

A alguien podría servirle, jaja
 
GN⁺ 2025-08-09
Opiniones de Hacker News

  • Hoy tuve mi primera experiencia realmente exitosa programando con Claude y un agente de código. Antes había probado Cursor, pero ahora también estoy intentando con Claude y otras herramientas. Como menciona el artículo, la clave es escribir una especificación clara. Durante 2 horas redacté yo mismo un documento de 12 pasos para organizar la forma de implementación e incluir información de contexto. Claude siguió ese procedimiento y fue generando el código paso a paso. Creo que probablemente me ahorró entre 6 y 10 horas. Ahora planeo revisarlo, probarlo, ajustarlo gradualmente y agregar funciones. La base de este éxito fue que yo mismo escribí con claridad todos los pasos que Claude debía seguir; es decir, yo diseñé el flujo completo y Claude solo siguió instrucciones. Este proceso me dio la certeza de que los desarrolladores de nivel intermedio o superior no serán reemplazados por la IA en el corto plazo. Aun así, ver a Claude leer toda la especificación y producir código bien documentado es una experiencia realmente fascinante. Es impresionante no tener que programarlo yo mismo

    • Yo obtengo buenos resultados con Claude sin prepararme tanto. Casi como cuando escribo código yo mismo, le voy pidiendo a Claude un paso a la vez. Cada vez aplico de inmediato los cambios, hago commit y reviso el diff. Si Claude produce algo raro, le pido correcciones enseguida. Y también le indico directamente el código existente o las referencias de funciones que quiero que use. Con este método se pueden lograr resultados excelentes con mucho menos tecleo y tiempo

    • Recomiendo leer “Programming as Theory Building” de Naur. Fue una experiencia de aprendizaje sobre cómo entender teóricamente un problema y modelarlo uno mismo. Si no lo haces, el LLM puede inventar su propia teoría, aunque sea incorrecta
      Leer “Programming as Theory Building” - Naur

    • Como dice el artículo, una especificación clara es realmente importante. Yo estoy creando un lenguaje de programación con Claude, y lo siento directamente. Programar implica una larga cadena de decisiones pequeñas. Si no lo guías con claridad, el LLM resuelve la mayoría por conjetura y a menudo elige mal. Esos pequeños errores pueden acumularse y llevar a un resultado incorrecto

    • Si pudieras compartir un ejemplo real de un documento de especificación así, sería genial. Para alguien como yo, que aprende desarrollo por su cuenta y está experimentando con Claude Code, sería de mucha ayuda para entender qué tipo de información y qué nivel de profundidad sirven de verdad

    • La verdad es que bastantes desarrolladores intermedios y senior tampoco saben redactar una especificación adecuada. Aun así, entiendo la idea que quieres transmitir

  • Crear ~/.claude/CLAUDE.md e incluir reglas ahí probablemente no tenga mucho efecto en la práctica. Claude no es una persona y no razona con cuidado sobre cada línea de código. Las instrucciones subjetivas y ambiguas no hacen que el código cambie de verdad. Y además está el problema del "context rot"
    (explicación de context rot: es cuando un LLM pierde o distorsiona el contexto durante una conversación o tarea larga; enlace de referencia: https://news.ycombinator.com/item?id=44564248)
    En términos realistas, es imposible meter toda clase de reglas en un solo archivo y esperar que la IA las cumpla por sí sola. Para lograrlo habría que crear un sub-agent para cada regla y separarlo en un pipeline convencional, no basado en IA. Pero entonces el costo crece de forma exponencial

    • Si el problema es el costo, una vez que el flujo de trabajo se estabiliza se puede usar un LLM barato, aunque el costo operativo siga siendo alto. Con fine-tuning, optimización de prompts y técnicas especializadas de distillation, entre otras, se puede reducir el costo. Ya hay bastante investigación en esta área

    • Me da curiosidad qué conviene incluir dentro de CLAUDE.md

  • Al ver los proyectos de ejemplo al final de la página, la mayoría son software optimizado para un solo propósito específico. Creo que en adelante los proyectos open source también podrían evolucionar así, hacia formas muy especializadas que satisfacen la necesidad de una sola persona. Tengo la impresión de que este tipo de software, estas utilidades, se convertirá en código desechable generado de una sola vez por un LLM

  • Mi forma de abordar Claude Code sigue cambiando. Todavía no he logrado usar Claude Code para aportar de inmediato una función realmente significativa a la gran web app de mi empresa. Las especificaciones ayudan un poco, pero al final la cosa se desvía hacia direcciones extrañas y cae en un bucle de decisiones equivocadas. Puede ser una limitación de Claude, o puede que mi especificación aún no sea lo bastante precisa. Hice muchos experimentos, pero en cosas “desafiantes o que requieren mucho conocimiento de dominio” tuve tantos fracasos que ya no lo intento más. En cambio, por recomendación de un amigo, empecé a usar Claude para tareas del backlog con casi nula carga mental. Por ejemplo, le pedí a Claude que creara pruebas de Playwright en un nuevo workspace para algo a lo que no le tengo mucho apego, y fue un gran éxito. Le expliqué la experiencia de usuario como se la explicaría a una persona y le indiqué la ruta del servidor dev. Le pedí que usara Playwright MCP para averiguar cómo usar cada feature, documentar el proceso de ejecución, escribir las pruebas y depurar errores. También incluí la tarea de revisar el código UI del proyecto para agregar selectores data-testid. Dejé todo el proceso resumido en un master task.md, y además le indiqué que creara tareas markdown individuales por feature. Este enfoque funcionó muy bien. Incluso lo usé en una feature compleja donde 2 usuarios del navegador interactúan de forma poco intuitiva; no fue 100% exacto, pero cuanto más compleja era la tarea, solo hacía falta un poco más de corrección de contexto y ajustes de código. En general, resolvió de golpe trabajos tediosos que me habrían tomado varios días

  • Lo mejor fue mantener CLAUDE.md como un archivo minimalista de menos de 100 líneas,

    • un resumen del contexto esencial y el propósito del proyecto
    • una explicación mínima de la estructura del proyecto para ubicar tipos, interfaces y helpers
    • solo los comandos clave, para no tener que volver a parsear package.json Durante el flujo de implementación/pruebas, por experiencia, Claude a veces intentaba escribir todas las pruebas de una vez por adelantado o implementar todo solo cuando fallaban los imports, lo cual no era un verdadero enfoque TDD. Por eso hice un hook llamado TDD-Guard para forzar que pasara una sola prueba a la vez, que la prueba fallara por la razón correcta y que implementara el código mínimo necesario para hacerla pasar. Con la calidad del código, obtuve resultados muy buenos automatizando husky, lint-staged, commitlint, etc. Así se puede reservar más contexto para información realmente importante. Coincido en que, cuando Claude Code se atasca, al final lo mejor es que el desarrollador intervenga directamente. Aun así, me deja con ganas de más cuando todo se queda en guías demasiado generales,
    • Si te interesa un enfoque de automatización:

  • Llevo más de un mes trabajando todos los días con Claude Code. Probé Cursor, Q y otros, pero Claude Code es mucho mejor. Varios de los consejos mencionados en el artículo coinciden bastante con lo que yo mismo descubrí.
    Para compartir algunas ideas adicionales:

    • Empiezo desde una sesión de ideas con Claude en la consola web. Le explico el objetivo del proyecto y bosquejo a grandes rasgos el modelado del dominio y los hitos. Si es un proyecto pequeño, eso se ordena en unas horas de ida y vuelta. De ahí sale la primera versión de CLAUDE.md

    • Al empezar el proyecto real, Claude lee tanto mi CLAUDE.md global como el CLAUDE.md del proyecto. Así funciona en cada sesión

    • Incluso durante el progreso, le indico a Claude Code que siga actualizando el CLAUDE.md del proyecto: que marque el avance siguiendo el plan y que al final de la sesión escriba un resumen del proyecto, cómo funciona y cómo navegar el código. Funciona como una especie de memoria a largo plazo, y me dio buenos resultados

    • Por buenas que sean las guías, Claude tiende a adelantarse por su cuenta. Por eso, en el trabajo donde participo directamente, me aseguro de que se enfoque paso a paso en incrementos pequeños. Solo cuando es algo puntual o un prototipo lo dejo implementar libremente

      • Me gustaría saber si la suscripción de $20 tiene buena relación costo-beneficio frente a Cursor, y si hace falta usarlo a diario para que realmente valga la pena

  • Es mejor mantener el CLAUDE.md a nivel de proyecto corto y conciso, y mover el contenido más detallado a subcarpetas. La parte superior se usa como una especie de mapa. Cada vez que se planifica una feature, Claude revisa las carpetas adecuadas, consulta el contexto necesario y arma un plan de implementación por etapas. Al final de cada etapa le indico que actualice el plan de implementación con el nuevo contexto. Así el contexto se transmite de forma natural a la siguiente fase, y también se puede reiniciar la ventana para entrar a la siguiente etapa con la mente fresca

  • Estoy creando con Claude Code un juego ASCII tipo factorio. Al principio lo dejé escribir código casi sin supervisión e implementó de una sola vez la mayoría de las funciones principales: guardar/cargar, opciones, debug, generación de mapas, construcción, cintas, crafteo, QoL, etc. Pero cuando intenté corregir detalles, empezaron a romperse otras cosas; por ejemplo, si cambiaba el movimiento, se rompían las cintas. Entonces le pedí que añadiera automatización con Playwright, pero las pruebas eran de mala calidad y estaban llenas de llamadas a sleep. Al revisar el código en detalle, vi que la estructura estaba hecha con frontend en React y useEffect, y no seguía una arquitectura de motor de juego propiamente dicha. Tampoco respetaba bien las reglas de hooks y su comprensión del timing era débil. Así que esta vez introduje un motor de juego basado en ticks y empecé de nuevo desde cero, además de agregar revisión de código. El avance es más lento, pero el desarrollo es mucho más sólido. Si termino una buena demo, planeo publicarla en Show HN

    • Hasta que no queda armado el esqueleto básico del principio, la contribución directa de una persona vale muchísimo. Después de una buena pasada de refactorización, ya se puede estar un poco más tranquilo

  • Si alguien, como yo, usa suscripciones de Claude tanto para trabajo como para uso personal, puede simplificar el cambio de cuenta con algo como alias claude-personal="CLAUDE_CONFIG_DIR=~/.claude-personal claude"
    Blog sobre cómo usar varias cuentas de Claude de forma eficiente

  • Todo el mundo dice que “la clave es escribir una especificación clara de antemano y dar contexto”, pero en mi experiencia eso no siempre funciona. De hecho, hice sesiones de CC con un experto real usando Opus 4 y Sonnet 4; la otra persona preparó una spec realmente clara, pero no obtuvo mejores resultados que mi enfoque, que consiste en pedir las cosas de inmediato en contextos separados, sin CLAUDE.md, conforme se me ocurren las features. En los workflows basados en especificación, Claude seguía olvidando cosas importantes o inventando por su cuenta cosas que no estaban en el documento de contexto, incluso algunas prohibidas. En cambio, a mí me funcionaba mejor darle instrucciones inmediatas como: “agrégame una página CRUD para invoice, pero primero analiza el codebase”. Esto es solo mi experiencia anecdótica, pero después de hacer más de 100 proyectos con Claude, no puedo asegurar que haya una forma claramente mejor, salvo usar hooks aparte para evitar que Claude se pase de la raya. Aunque mucha gente diga que “basado en spec es mejor”, cuando les pides que lo demuestren, a menudo terminan gastando demasiado tiempo corrigiendo una y otra vez partes obviamente equivocadas. Incluso cuando escribían en CLAUDE.md cosas como “nunca hagas esto”, Claude tendía a seguir haciéndolo de todos modos