Claude Code: Buenas Prácticas de Uso Real en Producción

[Lectura de operador] Uso Claude Code todos los días laborables en dos negocios — una marca de consultoría y Pickleland, una instalación de pickleball en Pflugerville, Texas — para todo, desde el pipeline de publicación de este blog hasta el code review en Workers de producción. Esto no es una introducción a qué es Claude Code. Son los hábitos que he mantenido tras meses de usarlo de verdad, y los que abandoné porque me costaban más de lo que me ahorraban.

Tabla de contenidos

Abrir Tabla de contenidos

• Escribe el CLAUDE.md como reglas, no como documentación
• Qué delego a un subagente y qué mantengo en mi propio hilo
• La gestión de contexto es la disciplina diaria, no una configuración de una sola vez
• Lo que he aprendido a no dejarle hacer solo
• Verifica antes de publicar — el “listo” de Claude es una afirmación, no un hecho
• La conclusión del operador
• Preguntas frecuentes
  • ¿Qué debería ir realmente en un archivo CLAUDE.md?
  • ¿Cómo decides cuándo confiar en el output de Claude Code sin volver a revisarlo?
  • ¿Dejas que Claude Code haga commit y push por su cuenta?
  • ¿Cuál es el hábito que más tiempo te ha ahorrado?

Escribe el CLAUDE.md como reglas, no como documentación

La primera versión de cada CLAUDE.md que he escrito era demasiado larga, y todas se han ido acortando con el tiempo, nunca alargando. El error es tratarlo como una página de wiki — contexto, filosofía, “por qué hacemos las cosas así”. Claude lee el archivo completo en cada sesión, necesite o no el detalle para la tarea actual, así que cada párrafo que no es una instrucción compite por atención con los párrafos que sí lo son.

Lo que sobrevive a la edición es más estrecho: reglas duras, idealmente las que exige una prueba automática para que no puedan regresionar en silencio, más enlaces a documentos más largos para los casos que de verdad necesitan el detalle. “Los títulos van bajo 60 caracteres” merece una línea. La historia de por qué existe ese límite merece un enlace a un documento, no un párrafo en el archivo que Claude relee en cada sesión.

Lo segundo que he añadido, y lo que no esperaba que importara tanto: una lista corta de hechos ya resueltos, escritos una vez, con la instrucción explícita de no volver a investigarlos. Al principio, Claude Code volvía a diagnosticar la misma falsa alarma cada pocas sesiones — un chequeo inestable, una rareza conocida en un paso del build — y quemaba contexto rederivando una conclusión a la que yo ya había llegado. Una línea que declara el hecho verificado y le dice al agente que siga adelante en vez de reabrir la investigación redujo ese tiempo muerto casi a cero. La regla que uso: si has explicado dos veces el mismo “en realidad, eso es esperado”, pertenece al CLAUDE.md como hecho, no como algo que vuelves a teclear en el chat una tercera vez.

Qué delego a un subagente y qué mantengo en mi propio hilo

Ya escribí el marco de decisión completo sobre skills, slash commands y subagentes por separado, así que no lo voy a repetir aquí. Lo que vale la pena añadir es el filtro a nivel operativo que aplico de verdad antes de generar uno: ¿puedo describir en una frase qué aspecto tiene “terminado”, y de verdad leería los pasos intermedios si se quedaran en mi hilo principal?

Si la respuesta a ambas es no — la tarea está acotada y solo quiero el resultado — es un subagente. Traducir este post a 12 idiomas es el ejemplo más claro: cada traducción se puede verificar de forma independiente, ese reparto de trabajo es exactamente por lo que el pipeline de contenido corre un subagente por idioma, y jamás querría que 12 idiomas de ida y vuelta intermedia saturaran el hilo donde todavía estoy decidiendo si el post en inglés está bien.

Si la tarea necesita que yo vea el razonamiento mientras ocurre — un cambio de esquema donde la tercera decisión depende de lo que reveló la segunda — se queda en mi hilo principal. El modo de fallo que de verdad he sufrido es generar un subagente para ese tipo de tarea de todos modos, recibir un resumen limpio, y luego preguntar “espera, ¿qué encontraste exactamente?” tres veces porque el resumen descartó el único detalle que importaba. Cuando eso pasa dos veces con el mismo tipo de tarea, dejo de delegarla.

La gestión de contexto es la disciplina diaria, no una configuración de una sola vez

El CLAUDE.md es la parte que la gente escribe una vez y olvida. La ventana de contexto es la parte que gestiono en cada sesión, y es la que de verdad determina si el resultado es bueno.

• Lee antes de dejarlo editar. Claude Code propondrá con gusto un cambio contra un archivo cuyo estado actual completo no ha visto. Hago que lea el archivo primero, siempre, incluso cuando estoy seguro de saber qué hay dentro — me he equivocado con ese “seguro” bastantes veces como para que ya no sea opcional.
• No dejes que una sesión haga dos trabajos sin relación. Un hilo que pasó una hora depurando un problema de deploy y luego gira hacia escribir copy de marketing arrastra esa hora de output de herramientas irrelevante a cada respuesta siguiente. Empiezo una sesión nueva en vez de pedirle a Claude que “olvide lo del deploy” — esa instrucción no elimina los tokens, solo le pide al modelo que los ignore, y lo hace de forma imperfecta.
• Planifica antes de dejarlo ejecutar. Para cualquier cosa con más de dos o tres pasos, pido el plan primero y lo leo antes de aprobar la ejecución. Leer un plan de cinco líneas toma quince segundos. Descubrir que el paso tres estaba mal después de que el paso cinco ya corrió cuesta el resto de la tarde.
• Pegar bloques enormes es un costo, no una comodidad. Soltar un archivo de log completo o una respuesta de API entera en la conversación cuando solo tres líneas importan quema contexto en el otro 97%. Hago grep primero y pego la coincidencia.

Es el mismo principio detrás de context engineering para agentes de IA en general — Claude Code solo hace el costo visible antes, porque eres tú quien ve la ventana de contexto llenarse en tiempo real en vez de depurarlo después en un log de un Worker.

Lo que he aprendido a no dejarle hacer solo

Toda acción irreversible — commit, push, publicar, enviar, gastar — queda detrás de un paso de aprobación explícito que ejecuto yo mismo, nunca uno que Claude Code decide tomar porque juzgó que la tarea estaba terminada. Es el mismo patrón de humano supervisando que uso en todos los demás agentes que corro, y Claude Code no es una excepción solo porque corre en mi propia máquina en vez de en la nube.

Lo otro que dejé de hacer: dar permiso amplio y permanente para comandos destructivos. rm -rf, force-push, saltarse hooks de pruebas — ninguno de estos recibe un sí general. Cada uno se pide, cada vez, en contexto, porque la única vez que preaprobé algo amplio “para ahorrar tiempo” fue la única vez que la tarea se salió hacia un alcance que no había revisado de verdad. Los cinco segundos que cuesta un prompt de permiso son un seguro barato contra la alternativa.

Verifica antes de publicar — el “listo” de Claude es una afirmación, no un hecho

Este es el hábito que más se ha pagado a sí mismo, y es el menos vistoso: no confío en un reporte de finalización. Corro la comprobación real.

Claude Code te dirá que un build pasó, que una suite de pruebas está en verde, que un enlace resuelve. A veces ese reporte se genera a partir de output real. A veces es un resumen confiado de un comando que corrió a medias, o un chequeo que retornó temprano sin nada útil dentro. Los dos se ven idénticos en la transcripción del chat. La única forma de distinguirlos es mirar tú mismo el output real — la misma disciplina detrás de el eval harness que uso para lanzar agentes: una tarea no se marca como terminada porque el agente lo diga, se marca cuando la comprobación definida de verdad pasa.

En la práctica eso significa: corre el comando de build y lee su output, no la paráfrasis de Claude. Abre el archivo que dice haber editado. Haz clic en el enlace que dice que resuelve. Para contenido específicamente, releo el borrador de forma adversarial contra las reglas que sé que se exigen — límites de longitud, patrones prohibidos, enlaces internos rotos — en vez de confiar en que Claude las aplicó correctamente la primera vez, porque casi siempre lo hizo y ocasionalmente no, y el costo de que el fallo ocasional llegue a un sitio en vivo es más alto que los noventa segundos que toma la relectura.

La conclusión del operador

Nada de esto es sobre confiar menos en Claude Code con el tiempo — es sobre ser específico en dónde tiene que ganarse esa confianza. CLAUDE.md cortos y exigibles en vez de documentación larga. Subagentes para trabajo acotado y verificable, tu propio hilo para todo donde el razonamiento importa tanto como el resultado. Contexto nuevo en vez de una sesión arrastrada. Compuertas de aprobación en todo lo que no puedas deshacer. Y una comprobación real, leída por ti mismo, antes de que cualquier cosa que hayas delegado salga a producción. Esa es toda la lista, y es la que de verdad sigo.

Preguntas frecuentes

¿Qué debería ir realmente en un archivo CLAUDE.md?

Reglas que el agente debe seguir en cada sesión, expresadas como instrucciones — no el contexto de por qué el código llegó a verse así. Si una regla la exige una prueba automática, dilo y deja que la prueba sea la fuente de verdad. El contexto más largo pertenece a un documento al que el CLAUDE.md enlaza, que se lee solo cuando la tarea de verdad toca esa área, no recargado en cada sesión por defecto.

¿Cómo decides cuándo confiar en el output de Claude Code sin volver a revisarlo?

No decido saltarme la comprobación — decido qué tan cara es. Correr un comando de build es casi gratis, así que siempre lo corro. Una relectura adversarial completa de un documento largo toma más tiempo, así que la reservo para lo que va a salir frente a una audiencia real. Lo único que nunca me salto es cualquier cosa irreversible: publicar, hacer commit, gastar dinero.

¿Dejas que Claude Code haga commit y push por su cuenta?

No. Cada commit y cada push son algo que ejecuto yo mismo, después de haber mirado el diff. Claude Code propone el cambio; yo soy la compuerta de aprobación para todo lo que sale del estado de borrador, la misma regla que aplico a cualquier otro agente que corro.

¿Cuál es el hábito que más tiempo te ha ahorrado?

Tratar un reporte de finalización como una afirmación, no como un hecho, y correr yo mismo la comprobación real. Suena como que ralentizaría las cosas. En la práctica es al revés — detectar un “listo” falso en treinta segundos es más rápido que detectarlo en producción tres días después.

---

Relacionado: Claude skills vs. slash commands vs. subagentes · El stack que uso para 30+ agentes en producción · Agentes de IA supervisados: cuándo pedir aprobación · Cómo usar Claude scheduled tasks

¿Quieres correr Claude Code así en tu propio negocio? Mi curso AI Agents for Beginners cubre los fundamentos de construcción que este manual asume. El programa cowork es donde enseño estos hábitos operativos en grupo estructurado. Si prefieres que te haga la configuración a ti, reserva una sesión de 30 minutos.