Cómo uso Claude Code todos los días y cómo reviso lo que hace

La conclusión primero, para quien lee en diagonal: Claude Code escribe la mayor parte del código de lo que construyo hoy, y mi parte se movió a los dos extremos de cada tarea. Antes de que empiece, digo exactamente qué quiero y cómo se ve algo terminado. Cuando termina, reviso la evidencia. Lo del medio es problema suyo.

Es mi herramienta de todos los días, y tanto este sitio como mi homelab se mantienen con ella. (Todavía abro Cursor cuando quiero meter mano en el código yo mismo.) Así trabajo con ella, incluidas las partes que me guardo para mí.

Plantea la tarea como un ticket para alguien nuevo en el equipo

El agente es rápido y literal, y no sabe nada de por qué quieres algo. Por eso escribo las tareas como escribiría un ticket para una persona capaz que acaba de entrar al equipo: el resultado, dónde vive, las restricciones, qué no tocar y cómo vamos a saber los dos que está terminado.

Agrega la charla de <URL> a src/content/speaking.ts.
Usa la fecha del evento, no la de publicación del video.
No toques ningún otro archivo.
Está terminado cuando `npm run check` pasa y la charla aparece en /speaking.

La última línea es la que hace casi todo el trabajo. Con una meta que puede comprobar, el agente ejecuta el chequeo por su cuenta y sigue hasta que pasa, en lugar de parar cuando el código solo parece estar bien.

Para cualquier cosa más grande que un arreglo pequeño, primero pido un plan (Claude Code tiene un modo de planificación justo para esto) y lo leo antes de que cambie un solo archivo. Corregir un plan cuesta un mensaje. Corregir una ejecución terminada cuesta bastante más.

Escribe las reglas una sola vez: CLAUDE.md y AGENTS.md

Claude Code lee un archivo CLAUDE.md del repo al comienzo de cada sesión. El CLAUDE.md de este sitio tiene una sola línea, @AGENTS.md, que importa un AGENTS.md compartido, así que todos los agentes y todas las personas leen la misma guía.

Esa guía empieza con un TL;DR que incluye la definición de terminado, y sigue con una tabla de comandos, un mapa del código, recetas para los cambios más comunes (“agregar una charla” es un objeto en un archivo), convenciones y una lista de trampas conocidas. Las trampas son lo más valioso, porque cada una trae su motivo. Las fuentes, por ejemplo, están alojadas en el propio sitio porque los builds en sandboxes sin acceso a la red fallan, y una actualización anterior perdió la fuente sin avisar justamente por eso. Un agente que conoce el motivo no lo deshace creyendo que lo arregla.

También hay una regla que ningún linter podría verificar: este es un sitio público sobre una persona real, así que nunca se agregan datos privados, aunque estén en un CV que te pasaron.

Si empiezas de cero, con esto ya alcanza para que sea útil:

## Antes de decir que terminaste

- Ejecuta `npm run check` (format, lint, typecheck, build). Tiene que pasar.
- Cambios de UI: levanta la app y revisa tema claro y oscuro, a 390px y 1280px.
- No agregues una dependencia sin explicar por qué.
- Nunca subas secretos, tokens ni datos personales.

Cuando el agente se equivoque en algo que una sola oración habría evitado, agrega esa oración.

Verificar es la mayor parte del trabajo

Que un agente diga que terminó es una afirmación, y la trato como tal. En este sitio, npm run check corre el formateo, el lint, el chequeo de tipos y un build de producción, igual que en CI. Después, npm run smoke recorre el sitio levantado: cada página tiene que devolver 200, y también se revisan los feeds, la imagen para redes sociales, el sitemap y la página 404. CI corre las dos cosas en cada pull request, así que la rama de un agente recibe el mismo trato que la mía.

Los píxeles necesitan ojos. El checklist de AGENTS.md para cambios de UI enumera las páginas que hay que abrir en los dos temas, en ancho de teléfono y de escritorio, más el menú móvil y la paleta de comandos. Cuando este sitio pasó a Tailwind CSS v4, el criterio era cero cambios visuales, y la actualización se comprobó contra 62 capturas (cada ruta, tema claro y oscuro, móvil y escritorio) que salieron idénticas píxel por píxel al build anterior.

Después leo el diff. Todos los nombres de archivo, siempre; cada línea de cualquier cosa que toque configuración, dependencias, autenticación o la red. Lo que busco:

• Archivos que no deberían estar en el diff.
• Tests borrados u omitidos, tipos relajados, un any suelto.
• Dependencias nuevas.
• Números escritos a mano que deberían calcularse.
• Cualquier cosa que “arregle” en silencio una trampa que AGENTS.md explica.

MCP: conecta el contexto en vez de pegarlo

Los servidores MCP le dan a Claude Code herramientas más allá de la terminal: un gestor de issues, el panel del hosting, una base de datos, un navegador. En lugar de pegar un log de errores en el chat, el agente lo lee donde está. Es también lo que muchos equipos pasaron el día construyendo en el Tokyo AI Hackathon, que coorganicé con Anthropic, Raycast y Supabase.

Dos reglas. Empieza en solo lectura, porque un servidor MCP actúa con las credenciales que le hayas dado. Y agrega los servidores uno por uno, porque cada herramienta que conectas es una cosa más que el agente puede decidir usar.

Ejecuciones largas, y cómo las reviso

Las ejecuciones autónomas largas son donde el agente se paga solo: una actualización, una migración, el mismo cambio en decenas de archivos. Solo funcionan con una meta que el agente pueda comprobar por su cuenta, así que la fijo antes de empezar: los comandos que tienen que pasar, las capturas que quiero y lo que no debe tocar.

Cuando vuelvo, el código es lo último que leo. Primero viene la evidencia: su resumen de qué ejecutó y qué se saltó, la lista de commits, el resultado de CI, las capturas. Si el resumen dice que se saltó un chequeo, eso es lo primero que vuelvo a correr yo. Recién ahí abro el diff, empezando por el archivo más riesgoso.

El homelab, y un asistente de Discord en una Mac mini

El mismo método mantiene mi homelab: notebooks viejas convertidas en terminales livianas, un NAS con Immich, Jellyfin, Paperless y Home Assistant, y dos dashboards en Next.js con estética de Evangelion que muestran el estado de cada máquina de la casa. Los dashboards son apps de Next.js comunes, así que se revisan como tales. El resto no tiene CI, así que el smoke test es Uptime Kuma: si un cambio deja un servicio sin responder, me entero.

El caso aparte es un asistente de Discord que funciona con Claude, alojado en una Mac mini sin monitor y siempre encendida. Ahí Claude es directamente el programa que está corriendo. Si armas uno, el checklist cambia: dale solo las herramientas que necesita, guarda un registro de lo que hizo y mantén sus claves fuera del repo.

Lo que no delego

• Qué construir y por qué. El agente es bueno en el cómo.
• Qué se publica sobre mí. AGENTS.md lo dice claramente: los datos sobre mí tienen que poder rastrearse hasta una fuente pública, y lo privado queda afuera, encuentre lo que encuentre el agente.
• Los secretos, y cualquier cosa que cambie lo que queda expuesto a internet. Mis máquinas se conectan entre sí por Tailscale sin abrir un solo puerto, y eso no lo cambia un agente.
• El merge. Un agente puede abrir el pull request. Decidir que sale a producción es trabajo mío.

Confianza basada en evidencia

La confianza funciona igual que con alguien nuevo en el equipo: se gana por tipo de tarea, con un historial. Las ediciones de contenido de este sitio tienen un largo historial pasando check y smoke, así que las leo por encima. Las actualizaciones de dependencias tienen uno más corto, así que las leo con atención. Todo lo que toca autenticación o la red empieza de cero cada vez.

Y cuando una ejecución sale mal, el arreglo va en dos lugares: el código y una línea en AGENTS.md, para que la próxima sesión empiece sabiéndolo.

Antes de tu próxima ejecución larga, escribe cómo se ve algo terminado, y haz que el agente te muestre que llegó ahí.