Claude Code: buenas prácticas para la codificación agéntica

(anthropic.com)

20 puntos por GN⁺ 2025-04-20 | 2 comentarios | Compartir por WhatsApp

Claude Code es una herramienta de codificación agéntica basada en CLI, que puede adaptarse con flexibilidad a diversos entornos y lenguajes de desarrollo
La configuración de CLAUDE.md, la gestión de la lista de herramientas permitidas y la creación de comandos personalizados permiten maximizar la usabilidad de Claude
Aplicar estrategias según el flujo de trabajo (explorar-planificar-implementar-commit, desarrollo guiado por pruebas, iteración visual, etc.) resulta efectivo
Con modo headless y configuraciones multi-Claude también es posible automatizar y trabajar en paralelo
Claude puede integrarse con diversas herramientas de desarrollo como Git, GitHub y Jupyter para usos más avanzados

Resumen de Claude Code

Claude Code es una herramienta para codificación agéntica (codificación automatizada basada en línea de comandos)
Fue diseñada para que los desarrolladores e investigadores internos de Anthropic puedan integrar Claude en su trabajo de programación de forma más natural
Gracias a su interfaz de bajo nivel y diseño desacoplado, no queda atada a una forma específica de desarrollo,
- por lo que cada desarrollador puede configurar y usar Claude de la manera que mejor le funcione
Como resultado, se posiciona como una herramienta de programación muy potente, flexible y segura
Como desventaja, existe una curva de aprendizaje alta para usuarios nuevos,
- por lo que hace falta ir construyendo prácticas recomendadas propias
Este artículo, basado en la experiencia de equipos internos y de ingenieros externos que realmente han usado Claude Code,
- presenta patrones generales efectivos en distintos lenguajes, codebases y entornos
Lo presentado aquí no es una respuesta definitiva, sino un punto de partida; se recomienda experimentar y mejorar según lo que mejor funcione para cada quien

# 1. Personalizar la configuración

Claude Code es un asistente de codificación agéntica que recopila contexto automáticamente para construir prompts
Esta recopilación de contexto consume tiempo y tokens, pero puede optimizarse ajustando el entorno

a. Crear un archivo `CLAUDE.md`

CLAUDE.md es un archivo especial que Claude incluye automáticamente en el contexto al iniciar una conversación
Este archivo es ideal para documentar lo siguiente:

comandos de bash usados con frecuencia
archivos clave y funciones utilitarias
lineamientos de estilo de código
cómo ejecutar pruebas
forma de trabajo del repositorio (por ejemplo, naming de ramas, merge vs. rebase)
cómo configurar el entorno de desarrollo (por ejemplo, si se usa pyenv, compiladores compatibles)
comportamientos excepcionales o advertencias del proyecto
cualquier otra información que Claude deba recordar

El archivo CLAUDE.md no tiene restricciones de formato, y se recomienda escribirlo de forma breve y fácil de leer para humanos
Ejemplo:

# Bash commands  
- npm run build: Build the project  
- npm run typecheck: Run the typechecker  
  
# Code style  
- Use ES modules (import/export) syntax, not CommonJS (require)  
- Destructure imports when possible (eg. import { foo } from 'bar')  
  
# Workflow  
- Be sure to typecheck when you’re done making a series of code changes  
- Prefer running single tests, and not the whole test suite, for performance

Ubicación del archivo `CLAUDE.md`

Claude busca CLAUDE.md en las siguientes ubicaciones y lo incluye en el contexto:

la raíz del repositorio o el directorio desde donde se ejecutó Claude
- si se guarda como CLAUDE.md y se hace check-in en git, puede compartirse entre sesiones y entre miembros del equipo (recomendado)
- para configuraciones personales, puede guardarse como CLAUDE.local.md y agregarse a .gitignore
directorios superiores al directorio de ejecución
- útil en estructuras de monorepo (por ejemplo, pueden usarse tanto root/CLAUDE.md como root/foo/CLAUDE.md)
subdirectorios del directorio de ejecución
- se incluye automáticamente en el contexto al trabajar con archivos dentro de ese directorio
el directorio home (~/.claude/CLAUDE.md)
- se aplica globalmente a todas las sesiones

Al ejecutar el comando /init, Claude crea automáticamente el archivo CLAUDE.md

b. Ajustar el archivo `CLAUDE.md`

Como CLAUDE.md se usa como parte del prompt de Claude, debe revisarse y optimizarse repetidamente, igual que un prompt
Un error común es incluir demasiado contenido sin verificar su efecto

es importante identificar mediante experimentación qué contenido mejora el desempeño de las respuestas del modelo
se puede agregar contenido manualmente, o presionar la tecla # para indicarle a Claude que lo incorpore automáticamente en CLAUDE.md
muchos ingenieros documentan en tiempo real comandos, guías de estilo y otros elementos, y comparten con el equipo los cambios en CLAUDE.md incluyéndolos en sus commits

En Anthropic, refinan CLAUDE.md mediante un prompt improver y
añaden frases de énfasis como “IMPORTANT” y “YOU MUST” para mejorar la precisión de las respuestas

c. Gestionar la lista de herramientas permitidas de Claude

Claude Code solicita aprobación del usuario por defecto para acciones que pueden modificar el sistema (escritura de archivos, ejecución de comandos bash, uso de herramientas MCP, etc.)
Este es un diseño conservador por razones de seguridad, pero las herramientas que el usuario considere seguras pueden aprobarse previamente mediante una lista de permitidas (allowlist)

Cómo configurar las herramientas permitidas

Durante la sesión, cuando aparezca el prompt, seleccionar "Always allow"
Agregar o eliminar herramientas con el comando /allowed-tools
Ejemplos:
- Edit → permitir edición de archivos
- Bash(git commit:*) → permitir commits de git
- mcp__puppeteer__puppeteer_navigate → permitir navegación del servidor MCP de Puppeteer
Editar manualmente .claude/settings.json o ~/.claude.json
- si se quiere compartir con el equipo, se recomienda usar el primero y hacer check-in en Git
Usar el flag de CLI por sesión --allowedTools

d. Instalar `gh` CLI para usar GitHub

Claude puede usar la CLI gh, por lo que automatiza tareas de GitHub como crear issues, redactar PRs y leer comentarios
Aunque no se instale gh, puede sustituirse mediante la API de GitHub o un servidor MCP

# 2. Darle más herramientas a Claude

Claude puede acceder al entorno de shell del usuario, por lo que puede usar directamente scripts y funciones creados por el propio usuario
Además, mediante MCP o APIs REST, también puede integrarse con herramientas externas más complejas

a. Uso con herramientas de Bash

Claude Code hereda el entorno de bash del usuario, por lo que puede acceder a utilidades ya instaladas

Claude ya conoce herramientas Unix comunes y la CLI gh
pero las herramientas bash personalizadas creadas por el usuario deben indicársele por separado

Para que Claude reconozca herramientas personalizadas, haz lo siguiente:

indícale explícitamente el nombre de la herramienta y ejemplos de uso
pídele que revise cómo usar la herramienta con la opción --help
documenta en CLAUDE.md las herramientas que usas con frecuencia

b. Uso con MCP

Claude Code funciona al mismo tiempo como servidor y cliente MCP
Como cliente, puede conectarse a varios servidores MCP y aprovechar distintas herramientas

Las herramientas de servidores MCP pueden conectarse a Claude de tres maneras:

definidas en la configuración del proyecto (solo disponibles en ese directorio)
mediante configuración global, para que estén disponibles en todos los proyectos
haciendo check-in del archivo .mcp.json, para que todos los desarrolladores que colaboran puedan usar las herramientas de inmediato
- por ejemplo, si en .mcp.json se registran los servidores de Puppeteer y Sentry, todo el equipo puede usarlos

Para depurar problemas de configuración al usar MCP, resulta útil ejecutar Claude con el flag --mcp-debug

c. Comandos slash personalizados

Para flujos de trabajo repetitivos (depuración, análisis de logs, etc.),
es posible guardar plantillas de prompts como archivos Markdown en la carpeta .claude/commands

Al escribir / en Claude, el comando aparece en el menú de autocompletado
Se puede hacer commit en git para compartirlo con el equipo

Pasar parámetros: `$ARGUMENTS`

Si incluyes $ARGUMENTS en un comando slash, puedes insertar automáticamente los parámetros enviados al ejecutar el comando

Ejemplo: análisis y corrección automática de un issue de GitHub

Please analyze and fix the GitHub issue: $ARGUMENTS.  
  
Follow these steps:  
  
1. Use `gh issue view` to get the issue details  
2. Understand the problem described in the issue  
3. Search the codebase for relevant files  
4. Implement the necessary changes to fix the issue  
5. Write and run tests to verify the fix  
6. Ensure code passes linting and type checking  
7. Create a descriptive commit message  
8. Push and create a PR  
  
Remember to use the GitHub CLI (`gh`) for all GitHub-related tasks.

Si guardas lo anterior en .claude/commands/fix-github-issue.md, puedes usarlo con el comando /project:fix-github-issue
Ejemplo: /project:fix-github-issue 1234 → Claude intentará corregir automáticamente el issue #1234

Si guardas comandos de configuración personal en la carpeta ~/.claude/commands, podrás usarlos en todas las sesiones

# 3. Aprovechar flujos de trabajo comunes

Claude Code no impone un flujo de trabajo específico y ofrece flexibilidad total al usuario
A partir de esa flexibilidad, en la comunidad de usuarios han surgido diversos patrones de uso que han funcionado bien

a. Explorar → planificar → implementar → hacer commit

Pídele a Claude que lea archivos, imágenes y URL relevantes
- Ej.: “lee el archivo que procesa los logs”, “lee logging.py”
- Eso sí, indícale claramente que no escriba código
- En esta etapa, usar subagentes (subagents) es muy efectivo, sobre todo cuanto más complejo sea el problema
Pídele a Claude que elabore un plan para resolver el problema
- Si usas palabras clave como “think”, “think hard” o “ultrathink”, se le asigna más presupuesto de cómputo
- Si el plan es válido, organiza ese contenido en un documento o créalo como un issue de GitHub para tener un punto de referencia al que volver
Después, pídele a Claude que implemente el código según el plan
- Incluso durante la implementación, puedes pedirle explícitamente que verifique por sí mismo la validez del resultado
Por último, indícale que haga commit del resultado y cree un PR
- Si hace falta, también puedes pedirle que actualice el README o el CHANGELOG

📌 En este flujo, si te saltas los pasos 1 y 2, Claude se pondrá a programar de inmediato, así que la etapa de planificación es especialmente importante cuanto más complejo sea el problema

b. Escribir pruebas → hacer commit → escribir código → iterar → hacer commit (desarrollo guiado por pruebas)

Es una forma de trabajo que se usa con frecuencia dentro de Anthropic, adecuada para tareas con pruebas unitarias, de integración o e2e

Pídele a Claude que escriba pruebas con base en criterios de entrada/salida
- Déjale claro que es desarrollo guiado por pruebas → así se enfocará en escribir solo las pruebas, sin implementar la funcionalidad
Pídele que confirme si las pruebas fallan
- Indícale que no implemente nada y que solo ejecute las pruebas
Si las pruebas te convencen, haz commit
Pídele a Claude que escriba código que haga pasar las pruebas
- Especifica que no debe modificar las pruebas
- Por lo general, termina haciéndolas pasar tras varias iteraciones
- También es útil usar subagentes para verificar si hay sobreajuste
Cuando todas las pruebas pasen, indícale que haga commit del código

✅ Claude funciona mejor cuando tiene un objetivo claro (por ejemplo, casos de prueba, imágenes, etc.)

c. Escribir código → proporcionar capturas del resultado → mejorar de forma iterativa

Prepara un entorno que pueda proporcionar automáticamente capturas del navegador (por ejemplo, Puppeteer MCP, simulador de iOS, etc.)
Proporciona un mock visual (pegando una imagen, indicando una ruta, etc.)
Pídele a Claude que implemente el diseño → revisa la captura resultante → indícale que vuelva a comparar y mejorar
Si te satisface, haz commit

💡 Igual que una persona, Claude mejora mucho más tras 2 o 3 iteraciones → el bucle de retroalimentación visual es importante

d. Modo Safe YOLO

Con la opción --dangerously-skip-permissions, se omiten todas las solicitudes de aprobación
Claude realiza el trabajo de forma totalmente automática sin aprobación del usuario

⚠️ Existe riesgo de pérdida de datos, daños al sistema e inyección de prompts → se recomienda ejecutarlo solo en contenedores sin acceso a internet
→ Como implementación de ejemplo, se recomienda usar Docker Dev Container

e. Q&A sobre la base de código

Al adaptarte a un proyecto nuevo, puedes hacerle preguntas a Claude como si se las hicieras a un ingeniero del equipo
Claude explora la base de código y encuentra por sí mismo las respuestas

Preguntas de ejemplo:

¿Cómo funciona el logging?
¿Cómo creo un nuevo endpoint de API?
¿Qué función cumple el async move en la línea 134 de foo.rs?
¿Qué edge cases maneja CustomerOnboardingFlowImpl?
¿Por qué se llama a bar() en lugar de foo()?
¿Qué código Java es similar a la línea 334 de baz.py?

📌 Se puede explorar solo con preguntas en lenguaje natural, sin prompts especiales
→ En Anthropic, este enfoque se usa como herramienta principal de onboarding

f. Integración con Git

Claude automatiza muy bien tareas de Git como las siguientes:

Buscar en el historial de Git:
- Ej.: “¿Qué cambios se incluyeron en v1.2.3?”, “¿Quién hizo esta funcionalidad?”, “¿Por qué esta API tiene esta estructura?”
Redactar mensajes de commit:
- Los arma automáticamente en función de los cambios y del contexto circundante
Tareas avanzadas de Git:
- revertir archivos, resolver conflictos de rebase, comparar y fusionar parches, etc.

g. Integración con GitHub

Claude Code puede automatizar ampliamente las tareas relacionadas con GitHub:

Crear Pull Requests:
- Reconoce la palabra clave pr y genera automáticamente mensajes de commit según los cambios
Corregir comentarios de code review:
- Con solo decir “corrige los comentarios del PR”, puede hacer los cambios y luego hacer push
Corregir fallas de build y errores de lint
Clasificar y organizar issues:
- Pídele a Claude: “revisa los issues abiertos y organízalos”

💡 Puedes automatizar tareas de GitHub sin necesidad de memorizar los comandos de gh

h. Trabajo con Jupyter Notebook

Claude puede leer y escribir archivos .ipynb, e incluso interpretar salidas que incluyen imágenes
Se recomienda usarlo en VS Code abriendo Claude Code y el archivo del notebook en paralelo

Funciones adicionales:

Antes de compartirlo con otras personas, puedes pedirle que ordene el notebook y mejore su presentación visual
- Solicitudes como “ordénalo para que se vea mejor” o “haz más bonitas las visualizaciones” suelen funcionar bien para optimizar una vista centrada en humanos

# 4. Optimización del flujo de trabajo

Las sugerencias de abajo son métodos de optimización que pueden aplicarse en común a todos los flujos de trabajo

a. Escribe instrucciones específicas

En Claude Code, cuanto más específicas sean las instrucciones, mayor será la tasa de éxito, especialmente en el primer intento
Si haces una solicitud clara desde el principio, se reduce la necesidad de correcciones a mitad del proceso

Comparación de ejemplos

❌ add tests for foo.py → demasiado amplio
✅ Para foo.py, escribe un nuevo caso de prueba que cubra el caso de usuarios desconectados. No uses mocks
❌ why does ExecutionFactory have such a weird api? → ambiguo
✅ Rastrea el historial de git de ExecutionFactory y resume por qué la API terminó con su estructura actual
❌ add a calendar widget → dirección de implementación poco clara
✅ Analiza cómo están implementados los widgets existentes en la página principal (por ejemplo, HotDogWidget.php), identifica el patrón de separación entre código e interfaz y luego implementa un nuevo widget de calendario siguiendo ese mismo enfoque, donde el usuario pueda seleccionar el mes y cambiar entre páginas de años. Solo se permiten bibliotecas externas que ya se usen en el proyecto actual

Claude puede inferir la intención, pero no puede leer la mente → la claridad es clave

b. Proporcionar imágenes

Claude es muy bueno procesando imágenes y diagramas
Puedes proporcionarle imágenes de las siguientes maneras:

En macOS, cmd+ctrl+shift+4 → captura de pantalla al portapapeles → pegar con ctrl+v (no disponible en entornos remotos)
Arrastrar y soltar un archivo de imagen
Pasar la ruta del archivo de imagen

Es muy útil para implementar mockups de diseño, analizar gráficos visuales, etc.
Incluso si no hay elementos visuales, también ayuda indicar claramente si la calidad visual del resultado es importante

c. Especificar los archivos con los que trabajar

Si le indicas a Claude con claridad qué archivos debe consultar o modificar, mejora la precisión del trabajo

Puedes introducir rápidamente rutas de archivos/carpetas con el autocompletado de la tecla Tab

d. Proporcionar URLs a Claude

Si le das una URL a Claude, puede leer directamente la documentación o la página web

Por ejemplo: enlaces a documentación de API, páginas del sistema de diseño, etc.
Si vas a acceder repetidamente al mismo dominio, puedes agregar el dominio a la whitelist con el comando /allowed-tools para omitir aprobaciones

e. Corregir el rumbo rápido y con frecuencia (course redirect)

Puedes presionar Shift + Tab para automatizar el trabajo con el modo de autoaprobación (auto-accept mode),
pero por lo general, ajustar el rumbo colaborando activamente con Claude produce mejores resultados

4 herramientas útiles de ajuste:

Pedir primero un plan: hacer que prepare un plan antes de implementar y continuar solo después de revisarlo
Interrumpir al instante con la tecla Escape: puedes detenerlo en cualquier momento, incluso mientras piensa o edita archivos
Presionar Escape dos veces para editar el prompt anterior: puedes modificar la instrucción anterior y cambiar a una nueva dirección
Pedir revertir cambios: puedes solicitar a Claude que haga rollback de lo modificado para probar otro enfoque

A veces Claude resuelve todo perfectamente de una sola vez, pero usar estas herramientas permite obtener resultados más rápidos y precisos

f. Reiniciar el contexto con el comando /clear

Si una sesión se prolonga, la ventana de contexto (context window) de Claude puede llenarse de información innecesaria y degradar el rendimiento
→ se recomienda adquirir el hábito de reiniciar el contexto con /clear en cada unidad de trabajo

g. Usar checklists y scratchpads

En tareas complejas (por ejemplo, migraciones de código, corrección masiva de errores de lint, etc.),
usar un archivo Markdown o un issue de GitHub como checklist mejora la eficiencia

Ejemplo: resolver errores de lint

Pedirle a Claude que ejecute el comando de lint → organizar los errores en una checklist con formato Markdown
Ir resolviendo cada elemento uno por uno, verificarlo y marcarlo → luego continuar con el siguiente

Con este enfoque, puedes hacer seguimiento del progreso y controlar la calidad al mismo tiempo

h. Pasarle datos a Claude

Hay varias maneras de pasarle datos a Claude:

Copiar/pegar (la forma más común)
Entrada por pipe (por ejemplo, cat foo.txt | claude)
- Adecuada para logs, CSV y grandes volúmenes de texto
Indicarle que los obtenga directamente mediante comandos bash, herramientas MCP o comandos slash
Pedirle que lea un archivo o una URL (incluidas imágenes)

En el trabajo real, es común combinar varios métodos
Por ejemplo: pasar logs por pipe y pedirle a Claude que use herramientas MCP para traer contexto adicional

# 5. Automatizar infraestructura con el modo headless

Claude Code admite un modo headless para entornos no interactivos (CI, hooks de pre-commit, scripts de build, automatización, etc.)

Ejecuta el modo headless con un prompt mediante la bandera -p
Con la opción --output-format stream-json puedes usar salida JSON en streaming

⚠️ El modo headless no persiste entre sesiones, por lo que debe ejecutarse manualmente cada vez

a. Clasificar issues automáticamente con Claude

El modo headless es ideal para disparadores de automatización basados en eventos de GitHub
Por ejemplo: analizar automáticamente un issue nuevo y clasificarlo con etiquetas

De hecho, en el repositorio público de Claude Code también se usa esta función para etiquetar automáticamente nuevos issues

b. Usar Claude como linter

Claude puede automatizar una revisión de código subjetiva que las herramientas de lint tradicionales suelen tener dificultad para detectar
Por ejemplo:

errores tipográficos
comentarios desactualizados
nombres de funciones/variables que pueden inducir a error
flujo de código poco intuitivo, etc.

Esto permite mejorar la calidad del código más allá de lo que ofrecen las herramientas de análisis estático

# 6. Subir de nivel con flujos de trabajo multi-Claude

Más allá de usar un solo Claude, ejecutar varias instancias de Claude en paralelo es una forma de uso muy poderosa
Al igual que cuando varios ingenieros colaboran, una estrategia de división de tareas con Claude puede mejorar tanto la eficiencia como la calidad

a. Un Claude escribe código, otro Claude lo revisa

El patrón más simple y efectivo:

Claude 1: escribe el código
Ejecutar Claude 2 con /clear o en otra terminal → revisar el código escrito
Ejecutar Claude 3 o usar nuevamente /clear → leer tanto el código como la revisión y aplicar correcciones

O bien,

Claude 1: escribe las pruebas
Claude 2: escribe el código que haga pasar las pruebas

❗ Entre instancias de Claude también es posible compartir scratchpads separados
o configurar una separación de roles del tipo “este Claude solo escribe en el archivo A, ese Claude solo lee el B”

📌 Separar el trabajo suele dar mejores resultados que usar un solo Claude

b. Hacer varios checkouts del repositorio

En lugar de esperar a que Claude termine una tarea, puedes crear varios directorios de checkout de Git y trabajar en paralelo

Crear 3 o 4 checkouts de git en carpetas separadas
Abrir cada carpeta en una pestaña distinta de la terminal
Asignar tareas diferentes a cada instancia de Claude
Ir cambiando entre pestañas para revisar el avance y aprobar o rechazar

c. Usar Git worktree

git worktree es una función de Git que permite hacer checkout de varias ramas en distintos directorios dentro de un mismo repositorio
→ ideal para procesar en paralelo múltiples tareas independientes

Ejemplo:

Un Claude refactoriza el sistema de autenticación
Otro Claude crea por separado un componente de visualización de datos
No interfieren entre sí → máxima paralelización

Cómo usarlo

Crear un worktree:
git worktree add ../project-feature-a feature-a
Ejecutar Claude:
cd ../project-feature-a && claude
Repetir según sea necesario

Consejos

Mantén consistencia en los nombres de los worktrees
Usa un worktree por pestaña de terminal
Si usas iTerm2 (Mac), se recomienda configurar notificaciones
Separa también el IDE según cada worktree
Al terminar, limpia:
git worktree remove ../project-feature-a

d. Modo headless + estructura de automatización personalizada

El modo headless (claude -p) permite integrar Claude Code de forma programática en los flujos de trabajo
Combinándolo con las propias herramientas de Claude y prompts del sistema, se pueden usar los siguientes dos patrones

1. Fanning out: distribuir tareas de migración/análisis a gran escala