Buenas prácticas con Claude Code, para ir rápido sin perder prolijidad

Claude Code puede escribir una función entera en diez segundos. Eso no es el problema. El problema es que “rápido” y “bien” son ejes distintos: podés terminar una tarea rapidísimo y dejar código que nadie entiende dentro de un mes, incluido vos. Ir rápido con un agente y seguir siendo un buen programador no son cosas contradictorias, pero tampoco pasan solas. Dependen de un puñado de hábitos concretos.

Esto no es una lista de trucos de prompt. Es lo que cambia cuando dejás de tratar a Claude Code como un chat que contesta preguntas y empezás a tratarlo como un programa que tenés que dirigir: qué configurar una sola vez, qué pedirle en cada tarea, y qué revisar antes de dar algo por terminado.

Dale un CLAUDE.md, no le repitas las reglas cada vez

CLAUDE.md es un archivo que Claude lee solo, al principio de cada conversación. Ahí va lo que no puede adivinar leyendo el código: comandos de tu proyecto, convenciones que se salen de lo estándar, cómo correr los tests.

# Estilo de código
- Módulos ES (import/export), no CommonJS (require)
- Desestructurar imports cuando se pueda (ej: import { foo } from 'bar')

# Flujo de trabajo
- Corré el chequeo de tipos después de una serie de cambios
- Preferí correr un test puntual, no la suite entera, por velocidad

La tentación es escribir uno larguísimo con todo lo que se te ocurre. Es exactamente lo que no hay que hacer: un CLAUDE.md inflado hace que Claude ignore la mitad, porque las reglas importantes se pierden entre las que no lo son. Por cada línea, preguntate: ¿sacar esto haría que Claude se equivoque? Si no, se borra.

Va acá	No va acá
Comandos de shell que Claude no puede adivinar	Cualquier cosa que ya se entiende leyendo el código
Reglas de estilo distintas a lo estándar del lenguaje	Convenciones estándar que Claude ya conoce
Cómo correr los tests, y con qué runner	Documentación detallada de una API (mejor un link)
Decisiones de arquitectura propias del proyecto	Descripción archivo por archivo del proyecto

Corré /init para que Claude te arme un primer borrador a partir de tu proyecto, y /context para confirmar que se cargó. Se sube al control de versiones: el archivo se vuelve más útil con el tiempo, a medida que el equipo le agrega lo que va aprendiendo.

No lo dejes saltar directo a programar

Dejar que Claude vaya directo del pedido al código produce, muchas veces, código que resuelve el problema equivocado. Separar “entender” de “escribir” es la diferencia entre una tarea que hay que corregir tres veces y una que sale bien la primera.

Explorar: Shift+Tab hasta que la barra de estado diga “plan mode on”, o arrancá la sesión con claude --permission-mode plan. Claude lee archivos y contesta preguntas, sin tocar nada:

leé /src/auth y entendé cómo manejamos las sesiones y el login.
mirá también cómo manejamos las variables de entorno para secretos.

Planificar: le pedís el plan, y podés editarlo directo con Ctrl+G antes de que Claude siga.

quiero agregar login con Google. ¿qué archivos hay que tocar?
¿cómo es el flujo de sesión? armá un plan.

Implementar: salís del modo plan (aprobando o con Shift+Tab de nuevo) y dejás que programe, verificando contra su propio plan.

Commitear: mensaje descriptivo y PR, no un commit de “cambios varios”.

Planificar no es gratis: para un typo, un log, o renombrar una variable, pedíselo directo. Conviene planificar cuando no estás seguro del enfoque, el cambio toca varios archivos, o no conocés bien esa parte del código. Si podrías describir el diff en una sola oración, salteá el plan.

Sé específico, y dale algo para verificar

Dos hábitos que van juntos: pedile las cosas con precisión, y dale una forma de comprobar que las hizo bien sin que tengas que mirar vos cada línea.

Antes	Después
“agregale tests a foo.py”	“escribí un test para foo.py que cubra el caso donde el usuario está deslogueado. sin mocks.”
“arreglá el bug del login”	“los usuarios reportan que el login falla después de que expira la sesión. revisá el flujo en src/auth/, sobre todo el refresh del token. escribí un test que reproduzca el problema, después arreglalo”
“hacé que el dashboard se vea mejor”	“[pegás una captura] implementá este diseño. sacá una captura del resultado y compará contra la original. listá las diferencias y arreglalas”

La regla general: nombrá el archivo, el escenario, y qué contás como “terminado”. Claude infiere intención, pero no lee la mente.

Lo segundo es darle una forma de verificar que no dependa de vos: un test que corre, un build que compila, un linter, una captura para comparar contra un diseño. Sin eso, “parece terminado” es la única señal que tiene, y vos te convertís en el único control de calidad — cada error espera a que vos lo notes. Con un chequeo que da pasa/no-pasa, Claude corre el chequeo, lee el resultado, y sigue solo hasta que pasa.

Pedile que muestre la evidencia —la salida del test, el comando que corrió y qué devolvió— en vez de que te asegure que “ya está”. Revisar la evidencia es más rápido que volver a correr la verificación vos, y funciona incluso en sesiones que no estuviste mirando.

Las herramientas que conviene tener activas

Cada una resuelve un problema distinto. No hace falta usarlas todas desde el primer día, pero conviene saber cuál existe para cuál caso:

• CLI de las herramientas externas que usás (gh, aws, gcloud) — Claude ya sabe usarlas para crear issues, abrir PRs, leer logs. Sin el CLI de GitHub, por ejemplo, sigue funcionando con la API pero pega contra límites de uso más rápido.
• Servidores MCP para conectar herramientas externas —una base de datos, Figma, Notion— que Claude puede consultar directamente. Ya escribimos sobre el protocolo detrás de esto.
• Hooks para lo que tiene que pasar siempre, sin excepción. A diferencia de una instrucción en CLAUDE.md, que es una sugerencia, un hook es determinístico: corre un script tuyo en un punto exacto del flujo. “Escribí un hook que corra eslint después de cada edición” es un pedido que Claude puede resolver solo.
• Skills para conocimiento de dominio o flujos repetibles —las convenciones de tu API, cómo se arma un componente en tu equipo. Se cargan solo cuando hacen falta, sin ocupar contexto el resto del tiempo. Ya escribimos cómo armar una paso a paso.
• Subagentes para investigación aislada o una revisión con ojos frescos. Corren en su propio contexto, así que no ensucian tu conversación principal con archivos que solo hacía falta leer una vez.

---
name: security-reviewer
description: Revisa el código en busca de vulnerabilidades de seguridad
tools: Read, Grep, Glob, Bash
model: opus
---
Sos un ingeniero de seguridad senior. Revisá el código buscando:
- Vulnerabilidades de inyección (SQL, XSS, comandos)
- Fallas de autenticación y autorización
- Secretos o credenciales en el código
- Manejo inseguro de datos

Dá referencias de línea concretas y arreglos sugeridos.

Mantené la sesión limpia

El contexto es el recurso que más rápido se gasta, y el rendimiento baja a medida que se llena. Un par de hábitos bastan:

• /clear entre tareas sin relación. Si empezás una tarea, después le pedís algo distinto, y volvés a la primera, el contexto queda lleno de información que no sirve para ninguna de las dos.
• Corregí apenas notes que se desvía, no después de tres intentos. Esc lo frena a mitad de acción sin perder el contexto. Si ya lo corregiste dos veces por lo mismo, /clear y arrancá de nuevo con un pedido más preciso que incluya lo que aprendiste: un contexto limpio con mejor pedido gana casi siempre a una sesión larga llena de correcciones acumuladas.
• /rewind (o Esc dos veces) para volver a un punto anterior de la conversación o del código, si algo salió mal y preferís rehacerlo distinto en vez de seguir corrigiendo.

Ya escribimos sobre los comandos para esto en detalle.

Antes de dar algo por terminado: una revisión con ojos frescos

Cuanto más tiempo trabajó Claude sin que lo miraras, más importa un chequeo independiente antes de contarlo como hecho. Un subagente que arranca en un contexto nuevo ve solo el diff y el criterio que le diste, no el razonamiento que llevó hasta ahí — así que juzga el resultado por sí mismo, no porque “suena convincente”.

usá un subagente para revisar el diff del rate limiter contra PLAN.md.
Comprobá que cada requisito esté implementado, que los casos límite
tengan test, y que no haya cambiado nada fuera del alcance de la tarea.
Reportá huecos, no preferencias de estilo.

El comando /code-review hace justo esto para una revisión general: corre en un subagente aparte y te devuelve los hallazgos en la misma sesión, sin que tengas que copiar nada entre ventanas. Ya escribimos sobre cómo revisar a fondo el código que escribió una IA.

Un aviso: a un revisor al que le pediste que busque huecos, casi siempre le va a encontrar alguno, aun cuando el trabajo esté bien — es lo que le pediste que hiciera. Perseguir cada hallazgo termina en sobre-ingeniería: capas de abstracción de más, código defensivo para casos que no pueden pasar. Pedile al revisor que marque solo lo que afecta la corrección o los requisitos, y tratá el resto como opcional.

Errores comunes, y cómo se arreglan

• La sesión de todo un poco. Empezás con una tarea, le pedís algo sin relación, volvés a la primera. Arreglo: /clear entre tareas.
• Corregir en bucle. Claude se equivoca, lo corregís, sigue mal, lo corregís de nuevo. Arreglo: después de dos correcciones fallidas, /clear y un pedido inicial mejor.
• El CLAUDE.md sobrecargado. Si es muy largo, Claude ignora la mitad porque las reglas importantes se pierden en el ruido. Arreglo: podá sin piedad. Si Claude ya hace algo bien sin la instrucción, borrala o convertila en un hook.
• Confiar sin verificar. El código se ve razonable pero no cubre los casos límite. Arreglo: siempre con verificación —tests, script, captura—. Si no lo podés comprobar, no lo publiques.
• La exploración infinita. Le pedís que “investigue” algo sin acotarlo, y termina leyendo cientos de archivos. Arreglo: acotá la investigación, o delegala a un subagente para que no se coma tu contexto principal.

Para trabajar en equipo y escalar

Lo anterior alcanza para trabajar solo. Para que esto funcione en una empresa, con más de una persona y más de una tarea al mismo tiempo, hay tres recursos más:

• Sesiones en paralelo, cada una en su propio worktree de git: cambios que no chocan entre sí porque cada sesión trabaja en su propia copia aislada del repositorio.

• Modo no interactivo, para integrarlo en CI o en un hook de pre-commit:

  claude -p "explicá qué falló en este build" --output-format json

  El formato json devuelve un único objeto con el resultado, listo para que lo procese un script en vez de leerlo una persona.

• Reparto entre varias sesiones para migraciones grandes: se genera la lista de archivos a cambiar, y un script recorre esa lista invocando claude -p una vez por archivo, con las herramientas permitidas acotadas explícitamente —importa cuando corre sin supervisión.

  for archivo in $(cat archivos.txt); do
    claude -p "Migrá $archivo de Python 2 a Python 3. Devolvé OK o FAIL." \
      --allowedTools "Edit,Bash(git commit *)"
  done

Nada de esto reemplaza la revisión de código de siempre. La diferencia es que ahora una parte de esa revisión también la puede hacer un subagente, antes de que el cambio llegue a una persona.