Practical Claude Code

“Esto no es solo una herramienta. Es una redefinición del propio desarrollo.”

Mi encuentro con Claude Code

En la primavera de 2025, escribí un único comando en mi terminal.

claude

Una sola palabra. No tenía idea, en ese momento, de que aquello cambiaría por completo mi carrera como ingeniero.

En ese entonces, corría MCP a través de Cursor y me emocionaba lo cómodo que era. Honestamente, me atraía más la evolución de las herramientas periféricas que los propios LLMs. Incluso llegué a creer, equivocadamente, que la clave de Claude Code era hacer que funcionara con GitHub Actions de un solo intento. Entendí completamente mal el sentido de las herramientas de coding con IA.

Cuando usé Claude Code por primera vez, sentí que algo era distinto en los primeros minutos. Era radicalmente diferente de cualquier herramienta de IA que había usado antes. No solo sugería código: entendía todo el proyecto, captaba la intención del diseño y, a veces, señalaba problemas que ni siquiera yo había notado. Se sentía como tener un pair programmer brillante al otro lado del terminal.

Por qué escribí este libro

Después de usar Claude Code por un tiempo, me convencí de algo. El verdadero valor de esta herramienta no está en su capacidad de generar código. Está en su capacidad de entender contexto.

Y para liberar esa capacidad por completo, el usuario necesita una habilidad propia: “diseñar contexto”. A esto lo llamo Context Engineering (ingeniería de contexto).

Hay muchos artículos por ahí que explican cómo usar Claude Code. Pero ningún libro había tratado de forma sistemática lo central: la filosofía de diseño, por qué importa CLAUDE.md, cómo sacar el máximo de la colaboración con IA y cómo aplicarlo en desarrollo en equipo.

Así que decidí escribirlo yo mismo.

Este libro es un registro completo de todo lo que aprendí usando Claude Code intensivamente en producción. Intenté ser lo más honesto posible, incluyendo no solo las técnicas que funcionaron, sino también las lecciones que saqué de los fracasos.

Cómo leer este libro

Este libro está organizado en cuatro partes principales.

Parte 1: Fundamentos (Capítulos 1–3) Cubre la historia del origen de Claude Code, el sentido detrás de su filosofía de diseño basada en terminal y por qué se necesita ahora un desarrollo AI-native. Si eres nuevo en Claude Code, empieza por aquí.

Parte 2: CLAUDE.md en la práctica (Capítulos 4–7) El corazón de este libro. Cobertura detallada de la filosofía de diseño de CLAUDE.md, desarrollo document-first, patrones prácticos y estrategias de desarrollo en equipo. Incluso quienes ya usan Claude Code desde hace tiempo encontrarán nuevas ideas aquí.

Parte 3: Aplicaciones reales (Capítulos 8–14) Desde flujos de trabajo del día a día hasta integración con diseño, automatización de pruebas, orquestación multi-herramienta, colaboración con no-ingenieros, automatización de conocimiento y aplicaciones de negocio. Guía concreta sobre cómo usar Claude Code en desarrollo real.

Parte 4: El futuro (Capítulos 15–19) Recorre el sentido de fondo del cambio de productividad, la evolución de los agentes de IA, consideraciones de seguridad y políticas, el cambio en la profesión de ingeniero y lo que viene por delante.

No tienes que leerlo de principio a fin. Siéntete libre de mirar el índice y saltar al capítulo que más te interese. Dicho esto, recomiendo leer los Capítulos 4 y 5 temprano, porque sientan la base conceptual para el resto del libro.

Bienvenido al mundo de Context Engineering.

“Y bien, ¿qué música estás escuchando ahora?” Esa única pregunta lo empezó todo.

El momento icónico en que nació Claude Code: un prototipo accidental que cristalizó cuatro decisiones de diseño.

”¿Qué música estoy escuchando?”

Una noche de septiembre de 2024, el ingeniero de Anthropic Boris Cherny escribía una sencilla app de chat de terminal para probar el comportamiento de la API de la empresa.

La primera herramienta fue solo bash: una única herramienta. Era un prototipo sin nada de especial, montado casi por completo a partir del código de ejemplo de la documentación oficial. Para verificar que funcionaba, escribió:

What music am I listening to?

El modelo escribió espontáneamente un AppleScript, controló el reproductor de música del Mac y devolvió el nombre de la canción que sonaba.

Boris ha dicho que ese fue el momento en que “sintió AGI por primera vez”. Sin que nadie se lo indicara, el modelo quiso usar herramientas. “El modelo quiere usar herramientas. Es solo eso.” Ese descubrimiento fue el comienzo mismo de Claude Code.

¿Quién es Boris Cherny?

Para contar la historia del nacimiento de Claude Code, primero necesitamos conocer a su creador, Boris Cherny.

Es conocido como autor de Programming TypeScript, publicado por O’Reilly, y es experto en sistemas de tipos y diseño de lenguajes de programación. TypeScript encarna una filosofía de “adaptar el sistema de tipos a la forma en que escriben los programadores, en lugar de obligar a los programadores a cambiar sus hábitos”. Esa filosofía después influyó directamente en los principios de diseño de Claude Code.

Cuando Boris entró en Anthropic, no tenía planes de construir un producto como Claude Code. Lo que quería era entender más a fondo la API de la empresa. La pequeña app de terminal que construyó para eso terminó convirtiéndose en uno de los agentes de coding con IA más usados del mundo, algo que ni él mismo pudo predecir.

Esta historia me atrae porque resuena con mi propia experiencia. En la época en que trabajé en desarrollo de robótica, construí un pequeño prototipo con un ingeniero francés que creció en direcciones inesperadas. En lugar de dibujar un gran diseño desde el principio, hay una sensación de que el descubrimiento llega cuando te ensucias las manos, algo que creo que todo ingeniero ha sentido en algún momento.

Nacido de un hackathon interno, por casualidad

Claude Code no fue resultado de un esfuerzo planeado de desarrollo de producto. La app de terminal que Boris construyó para probar el comportamiento de la API era puramente una herramienta de experimentación personal.

Sin embargo, dos coincidencias afortunadas se juntaron.

Coincidencia #1: Elegir una CLI

Boris eligió una CLI por una razón extremadamente práctica: no tenía que construir UI. Tomó el terminal como el prototipo más barato posible. Sin UI web, sin app de escritorio. Solo texto entrando, texto saliendo: la forma más simple posible.

Ese “atajo” resultó ser la mejor decisión de diseño. El terminal era el entorno con el que los desarrolladores estaban más familiarizados, y también el entorno más natural para que los modelos usen herramientas.

Coincidencia #2: Hacer de bash la primera herramienta

Al usar la herramienta bash directamente del código de ejemplo de la documentación, el modelo ganó un entorno donde podía ejecutar comandos libremente. No fue una elección intencional de diseño. Simplemente sucedió así. Pero ese grado de libertad encajó perfectamente con la tendencia del modelo de “querer usar herramientas”.

Cuando Boris compartió este prototipo internamente, la reacción fue inesperada. Los ingenieros de Anthropic empezaron a usar la herramienta en su trabajo del día a día.

”Nadie lo pidió, pero todo el mundo lo necesitaba”

A finales de 2024, el mercado de herramientas de coding con IA ya tenía players fuertes como Cursor y GitHub Copilot. Los asistentes de IA integrados en IDE eran lo dominante, y prácticamente no había demanda de “escribir código conversando con IA en el terminal”.

Aun así, la rápida adopción interna de Claude Code reveló una verdad importante: la gente no sabe lo que necesita hasta que lo tiene.

Boris explica esto usando el concepto de “Demanda Latente”. Los ingenieros ya trabajaban en el terminal. Claude Code era una herramienta que se mezclaba naturalmente con su flujo de trabajo existente. Usas tu terminal de siempre, trabajas como siempre, salvo que ahora Claude está justo a tu lado.

Esta idea de “colocar el producto en la extensión de los patrones de comportamiento existentes” es uno de los factores más importantes detrás del éxito de Claude Code. Lo trataré en detalle en el Capítulo 3.

Lo que produjo la cultura de Anthropic

No se puede contar la historia del nacimiento de Claude Code sin considerar la cultura de Anthropic como empresa.

Anthropic es única en el sector por colocar la “seguridad de la IA” en el centro de su misión corporativa. Persigue los objetivos aparentemente contradictorios de maximizar la capacidad de la IA mientras, al mismo tiempo, garantiza su seguridad.

Cómo influyó esta cultura en Claude Code se ve claramente en varias decisiones de diseño.

Gestión de Permisos para la ejecución de herramientas

Claude Code tiene un mecanismo integrado que pide aprobación al usuario cuando el modelo modifica archivos o ejecuta comandos. En lugar de “dejar que la IA haga lo que quiera”, la filosofía de diseño es dejar el control en manos del humano.

Claude wants to run: rm -rf node_modules && npm install

Allow? (y/n)

Este prompt puede parecer pesado a primera vista. Pero es la implementación técnica del énfasis de Anthropic en la “supervisión humana”.

Diseñado para no enviar código al exterior

Claude Code no almacena tu codebase en un vector DB ni construye índices en servidores externos. La arquitectura en la que el modelo busca directamente en archivos locales vía grep/glob es también una elección excelente desde el punto de vista de seguridad.

Esta decisión se tomó inicialmente por razones técnicas (Agentic Search era más preciso que RAG), pero se alineó hermosamente con la cultura safety-first de Anthropic.

Conciencia del ASL (AI Safety Level)

Boris habla abiertamente en entrevistas sobre riesgos como ASL4 (el nivel de riesgo para modelos que se auto-mejoran recursivamente), uso indebido para armas biológicas y exploits zero-day. El simple hecho de que un desarrollador de una herramienta de coding con IA discuta estos riesgos públicamente refleja la cultura de Anthropic.

Cuando empecé a usar Claude Code, lo primero que noté fue ese “cuidado por la seguridad”. Comparado con otras herramientas de coding con IA, Claude Code restringe intencionalmente lo que puede hacer en ciertas áreas. Pero esto no es una limitación: es diseño. En lugar de soltar la rienda, está pensado para colaborar con humanos. Esa filosofía es lo que crea confianza en el uso real.

Veinte pull requests al día

La evidencia más convincente de la efectividad de Claude Code viene de los propios resultados internos de Anthropic.

El estilo de trabajo de Boris cambió drásticamente antes y después de adoptar Claude Code:

• Desde Opus 4.5, escribe el 100% de su código con Claude Code
• Desinstaló su IDE
• Manda 20 pull requests por día

El equipo en su conjunto reportó resultados como:

• Aumento del 150% en productividad por ingeniero
• La predicción del CEO Dario de que “el 90% del código será escrito por Claude” se hizo realidad
• Dependiendo del equipo, el 70–90% del código es generado por IA

El ex-ingeniero de Google Steve Yegge ha dicho que “los ingenieros de Anthropic son 1000x más productivos que los ingenieros de Google en la época dorada de Google”. Puede ser una exageración, pero la sensación de que la productividad cambió a una dimensión completamente diferente es algo que viví en carne propia usando Claude Code intensivamente.

En mi caso, llevo cinco proyectos en paralelo en una pequeña empresa mientras, al mismo tiempo, tomo cursos de extensión universitaria y preparo nuevos negocios. Este estilo de trabajo de “ponerse muchos sombreros” se hizo posible en gran medida gracias a Claude Code. La reducción dramática del tiempo dedicado a escribir código me permitió enfocarme en la toma de decisiones y la revisión.

No queda ni una línea de código de hace seis meses

El propio equipo de desarrollo de Claude Code practica una metodología de desarrollo interesante.

Según Boris, no queda ni una línea de código de hace seis meses en el codebase de Claude Code. Agregan y quitan herramientas cada pocas semanas; el código tiene una expectativa de vida de unos pocos meses. Reescriben código constantemente para acompañar la evolución del modelo.

Esto refleja su filosofía de que “scaffolding (andamiaje) = deuda técnica”.

Puedes obtener ganancias de 10–20% en performance con código alrededor del modelo (scaffolding). Pero el siguiente modelo borra esas ganancias. Siempre es un tradeoff entre construir y esperar.

Boris, según se cuenta, tiene el ensayo de Rich Sutton “The Bitter Lesson” enmarcado en la pared de su oficina. La tesis central de ese ensayo es que “a largo plazo, escalar computación supera al ingenio humano”. En otras palabras, en lugar de construir sistemas complejos alrededor del modelo, es mejor apostar por la evolución del propio modelo.

Este pensamiento lleva al principio central del desarrollo de Claude Code:

Construye no para el modelo de hoy, sino para el modelo de dentro de seis meses.

Aunque encuentres PMF (Product Market Fit) optimizando para el modelo de hoy, el siguiente modelo dejará que los competidores te superen. Entonces percibes los límites de la capacidad del modelo y apuestas por la frontera que se resolverá en seis meses.

Este principio tiene implicaciones importantes para nosotros como usuarios de Claude Code. Ya sea cómo escribimos CLAUDE.md o cómo diseñamos flujos de trabajo, la clave no es “hackear alrededor de las debilidades del modelo actual”, sino mantener las cosas simples, asumiendo que el modelo va a evolucionar.

De la coincidencia a la inevitabilidad

El nacimiento de Claude Code fue coincidente. Una app de terminal para probar la API, la herramienta bash del código de ejemplo, elegir una CLI porque “construir UI daba demasiado trabajo”. Nada de eso fue intencional.

Pero el resultado que apareció más allá de esas coincidencias fue inevitable:

• Los ingenieros ya trabajaban en el terminal → CLI
• Los modelos querían usar herramientas → bash
• Se necesitaba seguridad y simplicidad → Agentic Search
• Hacía falta control humano → gestión de permisos basada en aprobación

Todo era una respuesta a demanda que ya estaba ahí.

Lo que quiero transmitir en este libro no es solo cómo usar Claude Code. Al entender la filosofía detrás de su creación (“no pelees con el modelo”, “descubre demanda latente”, “construye para dentro de seis meses”), descubrirás principios para desarrollar junto con la IA que van más allá del mero uso de la herramienta.

En el próximo capítulo, vamos a ver con más detalle la pregunta “¿por qué el terminal?” y a llegar al corazón de la filosofía de diseño de Claude Code.

✅ Puntos clave

• Claude Code no fue un producto planeado: nació accidentalmente de una herramienta de prueba de API
• El descubrimiento de que “los modelos quieren usar herramientas” fue el comienzo de todo
• Las elecciones de terminal, bash y Agentic Search fueron todas respuestas a “demanda existente”
• La cultura de seguridad de Anthropic llevó a una filosofía de diseño que mantiene a los humanos en control
• “Construye no para el modelo de hoy, sino para el modelo de dentro de seis meses” es el principio central de desarrollo de Claude Code

Referencias

• Boris Cherny, “Inside Claude Code With Its Creator” — Y Combinator The Light Cone (2026-02-17)

CLAUDE.md no es una “hoja de comandos para el modelo”. Es una “base de conocimiento del proyecto”.

Las dos líneas de Boris Cherny

Voy a retomar un hecho del Capítulo 1. Boris Cherny, creador de Claude Code, tiene un CLAUDE.md que ocupa solo dos líneas.

# CLAUDE.md
- Habilitar automerge al abrir un PR
- Postear en el canal interno de Slack al abrir un PR

Eso es todo. Sin convenciones de código, sin descripción de arquitectura, sin lineamientos de testing.

Mientras tanto, los practicantes de Claude Code escriben archivos CLAUDE.md que pasan de las 100 líneas. Empacan todo: el stack del proyecto, convenciones de código, estructura de archivos, estrategia de testing, procedimientos de deploy. El resultado es un CLAUDE.md gigante repleto de toda información imaginable.

¿Qué significa esa diferencia?

Por qué Boris se las arregla con dos líneas

La respuesta es simple. El CLAUDE.md de Boris tiene dos líneas porque el resto de la información está consolidado en el CLAUDE.md compartido por el equipo.

En el proyecto de Claude Code existe un CLAUDE.md compartido en la raíz del repositorio, separado de los archivos CLAUDE.md individuales, y se actualiza varias veces por semana. El archivo personal de Boris tiene solo dos líneas porque el CLAUDE.md compartido cubre el contexto del equipo.

En otras palabras, es arriesgado concluir a la ligera que “CLAUDE.md debe ser corto”. Más precisamente, tu CLAUDE.md personal puede ser corto, pero el contexto del proyecto necesita existir en alguna parte.

Los pros y contras de CLAUDE.md

CLAUDE.md es una de las funcionalidades más innovadoras de Claude Code, pero también es la más fácilmente malinterpretada. Shingo Yoshida, autor del libro Claude Code in Practice, analiza los pros y contras de CLAUDE.md en el contexto del Spec-Driven Development (SDD).

Pro: persistir el conocimiento del proyecto

La mayor ventaja de CLAUDE.md es ser el único contexto que sobrevive al /clear.

Las sesiones de Claude Code son temporales. Cuando la ventana de contexto se llena o se reinicia con /clear, toda la conversación previa se pierde. Pero la información escrita en CLAUDE.md persiste de forma permanente en el proyecto y se carga automáticamente en la siguiente sesión.

Sesión 1: instruir "escribe tests con Vitest" → Hecho
  ↓ /clear
Sesión 2: "Agrega tests" → no recuerda Vitest ❌

Con CLAUDE.md:
Sesión 2: "Agrega tests" → sabe usar Vitest por el CLAUDE.md ✅

Esto significa que CLAUDE.md funciona como memoria de largo plazo.

Contra: el problema del inflado

Sin embargo, que CLAUDE.md funcione como memoria de largo plazo es, al mismo tiempo, una causa de inflado.

Cada vez que Claude se equivoca durante una sesión, agregas una regla: “de ahora en adelante, hazlo así”. Cada vez que el proyecto crece, agregas nuevo contexto. Cuando te das cuenta, CLAUDE.md se infló a 300, 500, 1000 líneas.

Un CLAUDE.md inflado tiene los siguientes problemas:

Problema 1: el modelo empieza a ignorar instrucciones

Los LLM tienden a “darle más peso al inicio y al final de la entrada”. Las instrucciones enterradas en medio de un CLAUDE.md gigante tienen más probabilidad de ser ignoradas por el modelo.

Problema 2: se acumulan instrucciones contradictorias

Cuando vas agregando durante mucho tiempo, las instrucciones viejas y las nuevas pueden contradecirse. Una instrucción vieja que dice “escribe tests con Jest” coexiste con una nueva que dice “los tests fueron migrados a Vitest”.

Problema 3: desperdicio de la ventana de contexto

CLAUDE.md se carga por entero al inicio de la sesión. Un CLAUDE.md de 1000 líneas se come una porción significativa de la ventana de contexto disponible para las tareas reales.

El propio Boris dio un consejo claro sobre este problema:

Si CLAUDE.md se vuelve demasiado largo, bórralo y empieza de nuevo. Si el modelo se desvía, empújalo de regreso de a poco. A medida que los modelos mejoran, necesitas agregar menos.

Siete principios para CLAUDE.md

Con los pros y contras en mente, van aquí principios prácticos de operación. Estos siete principios sintetizan el conocimiento acumulado por la comunidad.

Principio 1: mantenlo pequeño y enfocado

# ✅ Bien: lo esencial mínimo
Este proyecto es Next.js 14 App Router + TypeScript + Prisma.
Los tests usan Vitest. Corre todos los tests con `npm test`.
Se prefieren comentarios en japonés.

# ❌ Mal: sobrecarga de información
Este proyecto es un sitio de e-commerce construido con Next.js 14
App Router + TypeScript + Prisma. El desarrollo empezó en
marzo de 2024, el equipo tiene 3 miembros... (sigue indefinidamente)

La meta es menos de 300 líneas, con como máximo 150–200 instrucciones. La generación automática vía /init tiende a ser verbosa, así que siempre haz curaduría manual después de generar.

Principio 2: deja el estilo de código a los linters/formatters

# ❌ Cosas que no deberían estar en CLAUDE.md
Usa indentación de 2 espacios.
Omite punto y coma.
Usa comillas simples para strings.

# ✅ Qué hacer en su lugar
Configura .prettierrc y .eslintrc
→ Una sola línea en CLAUDE.md: "Sigue las reglas de Lint/Formatter para el estilo de código"

Esta es la práctica de “No pelees con el modelo” explicada en el Capítulo 2. Delega el control de formato a las herramientas y escribe en CLAUDE.md solo aquello en lo que quieres que el modelo ejerza juicio.

Principio 3: los tres elementos esenciales

Hay tres cosas que CLAUDE.md debe contener como mínimo:

# CLAUDE.md

## Visión General del Proyecto
Sitio de e-commerce en Next.js 14, con gestión de productos, pedidos y pagos.

## Comandos comunes
- `npm run dev` — iniciar el dev server
- `npm test` — correr tests
- `npm run build` — build
- `npx prisma migrate dev` — migración del DB

## Trampas específicas del proyecto
- Si: el schema Prisma cambió → Entonces: corre siempre `npx prisma generate`
- Si: se agregó variable de entorno → Entonces: actualiza también `.env.example`
- Si: se agregó ruta de API → Entonces: actualiza las definiciones de tipo en `src/lib/api-client.ts`

El tercer elemento, “trampas específicas del proyecto”, es particularmente importante. Escribe las trampas no solo como prohibiciones, sino en el formato “Si X, entonces Y” (gatillo + acción). Así le resulta más fácil al modelo entender con precisión.

Principio 4: divulgación progresiva

No necesitas poner todo en CLAUDE.md. Separa los detalles en archivos dedicados dentro de subdirectorios e incluye solo las referencias en CLAUDE.md.

# CLAUDE.md (raíz)
Ve docs/api-spec.md para la especificación detallada de la API.
Ve docs/testing-strategy.md para la estrategia de tests.
Ve docs/deploy.md para los procedimientos de deploy.

CLAUDE.md se posiciona de forma jerárquica: Claude Code lee automáticamente solo los archivos relevantes al directorio en el que está trabajando.

Claude Code carga automáticamente el CLAUDE.md del directorio en el que está trabajando. Al trabajar en auth, carga src/auth/CLAUDE.md; al trabajar en pagos, carga src/payment/CLAUDE.md. Un diseño que ofrece la información correcta, en el momento correcto.

Principio 5: pon las reglas críticas arriba

Los LLM tienden a darle más peso al inicio y al final de la entrada. Pon tus reglas más importantes en el tope del CLAUDE.md.

# CLAUDE.md

<!-- Reglas más críticas: ponlas aquí -->
⚠️ Nunca te conectes directamente al DB de producción. Usa siempre staging.
⚠️ Nunca commitees archivos .env.

## Visión General del Proyecto
...

Principio 6: hazlo crecer como documento vivo

CLAUDE.md no es algo que escribes una vez y olvidas. Cuando Claude repite el mismo error, agrega una línea de lección. Cuando la situación del proyecto cambia, actualízalo. Es un documento que exige mantenimiento continuo.

Pero, si solo agregas, se infla. Revísalo periódicamente y elimina las reglas que ya no son relevantes. Como dice Boris, a veces hay que tener el coraje de “borrarlo y empezar de nuevo”.

Principio 7: ten conciencia del alcance

La ubicación de CLAUDE.md determina su alcance.

~/.claude/CLAUDE.md          # Global (compartido entre todos los proyectos)
~/project/CLAUDE.md           # Raíz del proyecto
~/project/src/auth/CLAUDE.md  # Específico del módulo
~/project/claude.local.md     # Configuraciones personales (recomendado .gitignore)

Pon las reglas compartidas por el equipo en el CLAUDE.md de la raíz del proyecto, y las preferencias personales en claude.local.md, para separar con claridad el conocimiento compartido de las configuraciones personales.

La pregunta de fondo: “¿qué es contexto?”

Cuando piensas a fondo en el diseño de CLAUDE.md, llegas a la pregunta de base: “¿qué es contexto?”

Contexto es la información que el modelo necesita para tomar decisiones correctas. Pero “información necesaria” cambia según la situación:

• Para captar la visión general del proyecto → descripción de la arquitectura
• Para arreglar un bug específico → trampas específicas de ese módulo
• Para escribir tests → estrategia de tests y configuración de las herramientas de test
• Para hacer deploy → procedimientos de deploy y configuraciones de entorno

Proveer toda la información de una sola vez sobrecarga la ventana de contexto y entierra la información importante. Proveer solo la información necesaria en el momento necesario: este es el centro del Context Engineering (ingeniería de contexto).

CLAUDE.md es solamente un mecanismo para practicar esa ingeniería de contexto.

La conexión con Spec-Driven Development (SDD)

Spec-Driven Development (SDD), promovido por Shingo Yoshida, es un enfoque que lleva la filosofía de CLAUDE.md aún más lejos.

La diferencia respecto al Vibe Coding (“haz algo lindo”) es clara:

Vibe Coding:
  "Haz una funcionalidad de login" → la IA implementa libremente → no es lo que esperabas

Spec-Driven Development:
  1. Escribe el spec (deja claro qué construir)
  2. Define políticas de orientación en CLAUDE.md (deja claro cómo construir)
  3. Haz que la IA implemente → la implementación sigue el spec
  4. Verifica los resultados → actualiza el spec

El núcleo del SDD es concentrar el esfuerzo humano no en las “instrucciones a la IA”, sino en la “definición de la especificación”. Con un buen spec, la IA llega a la implementación correcta.

Este es también el enfoque que practico en el día a día. Antes de escribir código, escribo el spec primero. Defino el contexto del proyecto en CLAUDE.md. Luego delego la implementación a Claude Code. Lo que debes escribir no es código, sino especificaciones.

Esta idea se conecta de forma profunda con el “Document-First Development” tratado en el siguiente capítulo.

Una plantilla práctica de CLAUDE.md

Para cerrar, va aquí la plantilla de CLAUDE.md que de hecho uso.

# CLAUDE.md

## ⚠️ Reglas críticas
- No acceder al entorno de producción directamente
- No commitear archivos .env
- Pedir confirmación siempre antes de migraciones destructivas

## Visión General del Proyecto
[Nombre del proyecto]: [Descripción en una línea]

## Stack técnica
- Framework: Next.js 14 (App Router)
- Lenguaje: TypeScript (strict mode)
- DB: PostgreSQL + Prisma
- Tests: Vitest + Testing Library
- CI: GitHub Actions

## Comandos
- `npm run dev` — dev server
- `npm test` — correr tests
- `npm run test:watch` — tests en watch
- `npm run build` — build

## Trampas (Si → Entonces)
- Si: se agregó nueva ruta de API → Entonces: actualiza los tipos en `src/types/api.ts`
- Si: el schema Prisma cambió → Entonces: corre `npx prisma generate`
- Si: se agregó variable de entorno → Entonces: actualiza `.env.example` + documenta en el README

## Referencias
- Spec de la API: docs/api-spec.md
- Estrategia de tests: docs/testing.md

Cabe en 50 líneas. La información detallada queda separada en documentos referenciados, y CLAUDE.md sirve como un índice.

El CLAUDE.md de dos líneas de Boris puede ser extremo, pero la dirección es la correcta. No escribas lo que no necesita ser escrito. Pon la información necesaria en el lugar correcto, en la granularidad correcta. Ese es el corazón de la gestión de CLAUDE.md.

✅ Puntos clave

• El CLAUDE.md de dos líneas de Boris Cherny funciona porque el CLAUDE.md compartido por el equipo da la cobertura
• El inflado de CLAUDE.md causa tres problemas: instrucciones ignoradas, contradicciones acumuladas y contexto desperdiciado
• El núcleo de los siete principios: “mantenlo pequeño y enfocado”, “déjalo a los linters” y “trampas en formato Si→Entonces”
• La divulgación progresiva provee la información correcta solo cuando es necesaria
• Diseña CLAUDE.md no como “órdenes al modelo”, sino como “la base de conocimiento del proyecto”

🎯 Practícalo tú mismo

1. Escribe un CLAUDE.md para tu proyecto: siguiendo los siete principios de este capítulo, escribe un CLAUDE.md de 50 líneas o menos para un proyecto en el que estés trabajando ahora. Incluye los tres elementos esenciales: visión general del proyecto, comandos y trampas (en formato Si→Entonces).
2. Pon a dieta un CLAUDE.md inflado: si ya tienes un CLAUDE.md, revísalo a la luz de los principios de este capítulo y elimina lo que no necesita estar ahí. Identifica los ítems que deberían quedar con los linters/formatters, las instrucciones duplicadas y las reglas desactualizadas. Compara el conteo de líneas antes y después.

Referencias

• Boris Cherny, “Inside Claude Code With Its Creator”, Y Combinator The Light Cone (17/02/2026)
• Shingo Yoshida, “Introduction to Spec-Driven Development with Claude Code”, SpeakerDeck