Hay una diferencia abismal entre alguien que usa Claude Code como un autocompletado con esteroides y alguien que lo ha integrado como un agente programable con memoria, comandos personalizados y sesiones paralelas. El usuario ocasional escribe prompts y acepta sugerencias. El daily driver lo trata como un ingeniero al que delegar tareas, con un sistema de configuración que se retroalimenta de sus propios errores. Esta guía es para el segundo tipo de persona.

Basada en la documentación del equipo de Anthropic, las lecciones de Boris Cherny (creador de Claude Code) y los patrones que la comunidad ha destilado durante los últimos meses, aquí tienes todo lo que necesitas para convertir Claude Code en tu herramienta diaria de desarrollo.

De chatbot a agente: el cambio de mentalidad

El salto cualitativo ocurre cuando dejas de pensar en Claude Code como un chat con esteroides y empiezas a tratarlo como un agente autónomo que necesita guardarraíles. Boris Cherny lo explica con una regla de oro: "dale a Claude una forma de verificar su propio trabajo". Sin eso, tú eres el único bucle de retroalimentación. Con eso, Claude itera hasta que las cosas funcionan, y según el propio Cherny, esto por sí solo proporciona una mejora de calidad de entre 2 y 3 veces.

Cat Wu, también del equipo de Claude Code, va más allá: "El modelo rinde mejor si lo tratas como un ingeniero al que delegas, no como un programador en pareja al que guías línea por línea". La diferencia es sutil pero transformadora. En lugar de microgestionar cada paso, escribes un brief preciso al inicio y dejas que el agente ejecute.

Cuatro patrones cambian completamente tu flujo de trabajo diario:

  • Explora, luego planifica, luego programa. El modo plan (Shift+Tab dos veces) pone a Claude en modo solo lectura. Lee archivos, traza flujos, entiende el modelo de datos. Después obtén un plan. Luego ejecuta. Usa esto para todo lo que toque más de un archivo.
  • Usa el modo plan como documento de diseño. Un Claude escribe el plan, otro en sesión fresca lo revisa como ingeniero senior, sin sesgo de contexto. Si la implementación se tuerce, vuelve al modo plan y replanifica con pasos de verificación.
  • Referencia, no describas. En lugar de "mira el módulo de autenticación", escribe @src/auth/login.py. En lugar de pegar un error, haz pipe: cat error.log | claude. El contexto exacto vence siempre a la descripción aproximada.
  • Delega, no pares-programes. Un brief nítido al principio, después déjalo correr. La microgestión mata la eficiencia del agente.

El directorio .claude: mucho más que CLAUDE.md

La mayoría de los usuarios abren .claude/ una vez, ven CLAUDE.md y no miran más. Es un error. El sistema de configuración es mucho más profundo y está organizado en dos ámbitos: el ámbito de proyecto (dentro del repo, se commitea y lo comparte el equipo) y el ámbito global (en ~/.claude/, aplica a todos los proyectos de tu máquina). El modelo mental es sencillo: los archivos del proyecto describen el proyecto, los archivos globales te describen a ti.

La estructura completa incluye:

  • CLAUDE.md — Instrucciones que se cargan en cada sesión. Se commitea, se comparte en equipo.
  • CLAUDE.local.md — Notas privadas del proyecto. No se commitea (gitignorado).
  • settings.json — Permisos, hooks, variables de entorno, modelo por defecto.
  • .mcp.json — Servidores MCP compartidos por el equipo.
  • skills/<nombre>/SKILL.md — Prompts reutilizables que se invocan con /nombre. Soportan archivos auxiliares, restricciones de herramientas y overrides de agente.
  • agents/*.md — Definiciones de subagentes.
  • rules/*.md — Instrucciones por temática, opcionalmente restringidas por ruta (path-gated).
  • commands/*.md — Comandos de una sola línea con slash.

Un detalle que se escapa fácilmente: los archivos CLAUDE.md en monorepos cascadan. Tanto root/CLAUDE.md como root/services/billing/CLAUDE.md se cargan cuando trabajas en el servicio de billing. Esto es increíblemente potente para codebases con convenciones diferentes por carpeta.

Skills sobre commands. Aunque ambos crean comandos slash, los skills soportan archivos auxiliares, desactivación del modelo, herramientas permitidas y overrides de agente. El trabajo nuevo debería ir siempre en skills.

Cómo escribe CLAUDE.md el equipo de Anthropic

Boris Cherny ha compartido el CLAUDE.md real que el equipo de Claude Code utiliza en su propio repositorio. El archivo completo es sorprendentemente corto:

# Development Workflow

**Always use `bun`, not `npm`.**

# 1. Make changes

# 2. Typecheck (fast)
bun run typecheck

# 3. Run tests
bun run test -- -t "test name" # Single suite
bun run test:file -- "glob"    # Specific files

# 4. Lint before committing
bun run lint:file -- "file1.ts"
bun run lint

# 5. Before creating PR
bun run lint:claude && bun run test

Eso es todo. Comandos de build que Claude no puede adivinar, el orden exacto de ejecución, invocaciones de tests individuales, el ritual pre-PR. Sin preferencias de estilo. Sin visitas guiadas al código. Sin platitudes. La filosofía de Cherny es brutalmente directa: "Por cada línea, pregúntate: si la elimino, ¿Claude cometería un error? Si no, quítala".

El segundo principio, y quizá el más importante, es dejar que Claude escriba sus propias reglas. Cada vez que Claude comete un error, termina el prompt con "Update CLAUDE.md so you do not repeat this." Cherny dice que Claude es "sorprendentemente bueno destilando sus propios fallos en reglas precisas". Después de unas semanas haciendo esto, el archivo se convierte en una lista curada de cada gotcha de tu proyecto.

Boris también usa @claude en comentarios de PR para que Claude commitee una regla directamente. Lo llama "Compounding Engineering": cada revisión de PR se convierte en una mejora de CLAUDE.md.

Subagentes y skills: tu ejército personal de IA

Una de las características más infrautilizadas de Claude Code son los subagentes. Puedes definir agentes especializados en archivos .claude/agents/*.md y luego invocarlos cuando los necesites. Por ejemplo, un agente pr-review.md que solo revisa pull requests con un conjunto específico de instrucciones, o un test-writer.md que se centra exclusivamente en generar tests.

Los skills, por su parte, permiten crear prompts reutilizables que se activan con una barra. Un skill de "api-conventions" puede cargar todas las convenciones de API de tu proyecto con solo escribir /api-conventions. La diferencia con los comandos simples es que los skills pueden incluir archivos de soporte, restringir qué herramientas puede usar el modelo, e incluso cambiar el modelo base para esa tarea concreta.

Combinados, subagentes y skills te permiten construir un sistema de herramientas de IA específicas para tu proyecto que cualquier miembro del equipo puede usar sin tener que recordar decenas de instrucciones diferentes.

MCPs: el protocolo que conecta Claude con tu stack

El Model Context Protocol (MCP) es probablemente la característica más subestimada de Claude Code. Permite conectar Claude con APIs externas, bases de datos y servicios directamente desde el agente. La configuración va en .mcp.json y se comparte con el equipo a través del repositorio.

¿Qué puedes hacer con MCPs?

  • Consultar tu base de datos directamente desde Claude sin pegar esquemas manualmente
  • Interactuar con Jira, GitHub o cualquier API que tengas
  • Ejecutar consultas a tu documentación interna
  • Conectar Claude con servicios de CI/CD para diagnosticar fallos en tiempo real

Cada MCP se define con su comando de inicio, argumentos y variables de entorno necesarias. La comunidad ya ha publicado docenas de servidores MCP listos para usar, desde conexiones a PostgreSQL hasta integraciones con Slack. Si tu equipo usa Claude Code, los MCPs son la forma más rápida de multiplicar su utilidad sin tener que cambiar la herramienta.

El truco que pocos conocen: sesiones paralelas y verificación cruzada

Uno de los patrones más avanzados que recomienda el equipo de Anthropic es usar dos sesiones de Claude Code en paralelo. Una escribe el plan, la otra lo revisa como un staff engineer sin sesgo de contexto. Esto funciona porque una sesión fresca no tiene el "sesgo de arrastre" de la sesión que escribió el plan — ve los agujeros que la primera pasó por alto.

Otro truco: cuando Claude Code se equivoca, pulsa Ctrl+G para abrir el plan de Claude en tu editor y retocarlo antes de que genere código. El plan es solo texto, así que puedes darle forma antes de que se convierta en código. Esto evita que el agente malinterprete la dirección y ahorra iteraciones enteras.

Y si quieres saber exactamente qué estado local tiene Claude para un proyecto, ejecuta claude project purge ~/path/to/repo --dry-run. Muestra todo lo que Claude guarda, útil antes de entregar un portátil o diagnosticar problemas de configuración.

Lo que no debes poner en CLAUDE.md

Tan importante como saber qué incluir es saber qué no incluir. El equipo de Anthropic es muy claro: fuera del archivo van las convenciones estándar del lenguaje (ES modules sí, CommonJS no — eso va en la guía de estilo, no en CLAUDE.md), las descripciones archivo por archivo del codebase, los tutoriales largos, la documentación de APIs y cualquier cosa que cambie con frecuencia.

Usa palabras como IMPORTANTE o DEBES con moderación para que tengan impacto real cuando aparezcan. Y si necesitas documentación extensa, usa la sintaxis @path para importar archivos externos manteniendo el CLAUDE.md limpio y escaneable.

Veredicto

Claude Code no es solo una herramienta de autocompletado potenciada por IA. Es un sistema de agente programable cuya eficacia depende casi por completo de cómo lo configures. La diferencia entre un usuario ocasional y un daily driver no está en el modelo subyacente — es la misma Claude — sino en el ecosistema de reglas, skills, subagentes y MCPs que has construido a su alrededor.

Invertir tiempo en configurar bien CLAUDE.md y el directorio .claude es la decisión con mejor retorno de inversión que puedes tomar como desarrollador en 2026. Cada hora que dediques a afinar las reglas se multiplica en cada sesión futura, y el efecto compuesto del "Compounding Engineering" del que habla Boris Cherny es real: después de semanas dejando que Claude aprenda de sus errores, tienes un agente que conoce tu proyecto mejor que cualquier desarrollador nuevo que pudiera incorporarse.

Para más información, consulta la guía original de Arpan Patel sobre dominio de Claude Code y el análisis de VentureBeat sobre los benchmarks de codificación con IA.