Respuesta corta: CLAUDE.md es el archivo de contexto persistente que la herramienta de desarrollador de Anthropic, Claude Code, lee al inicio de cada sesión. En 2026 soporta cuatro alcances (managed / project / user / local) y una sintaxis de imports (
@path/to/file) para incorporar otros archivos. El auto memory introducido en v2.1.59 permite que Claude acumule conocimiento en unMEMORY.mdpor su cuenta; juntos otorgan al proyecto una memoria en dos capas. Entre noviembre de 2025 y enero de 2026, Andrej Karpathy trasladó el 80 % de su rutina de coding al agent-driven coding y lo definió como «el mayor cambio de workflow en aproximadamente 20 años de programación.» En abril de 2026 publicó el gist idea file y redefinió CLAUDE.md como la columna esquema de una arquitectura de conocimiento personal compuesta porraw/(fuentes),wiki/(base de conocimiento mantenida por el LLM) yCLAUDE.md(esquema). Esta guía recorre todas esas innovaciones y cómo luce un CLAUDE.md efectivo en 2026.
En esta era de IA fusionada con el desarrollo de software, lo que le dices a la IA y cómo se lo dices determina la productividad real que recibes a cambio. Desde marzo de 2026, la documentación oficial de Anthropic se trasladó a su nueva dirección (code.claude.com/docs/en/memory) y CLAUDE.md sigue siendo el concepto más crítico de Claude Code, con capas complementarias formadas a su alrededor — auto memory, path-scoped rules, imports, subagent memory. Las publicaciones de Karpathy en los últimos seis meses empujaron este mecanismo más allá de un mero archivo de configuración hacia la arquitectura central de conocimiento del software en la era de la IA.
Andrej Karpathy: de Software 2.0 al Idea File
Andrej Karpathy (n. 23 de octubre de 1986, Bratislava) es uno de los diez ingenieros más influyentes de la IA moderna. Terminó su doctorado en informática en Stanford bajo Fei-Fei Li en 2016. Tres etapas estructuran su carrera: investigador fundador en OpenAI (2015-2017), Director de IA en Tesla (2017-2022) liderando el equipo Autopilot Vision, breve regreso a OpenAI en 2023 y fundación de Eureka Labs en 2024. Su canal de YouTube — hogar de las maratones «Let’s build GPT from scratch» — superó los 2 millones de suscriptores.
Leer a Karpathy solo como investigador técnico se queda corto. También es el diseñador del vocabulario creativo de la IA. En Software 2.0 (2017) sostuvo que los programas serán cada vez más «escritos» no por desarrolladores sino por redes neuronales que aprenden pesos. Provocador en 2017, realidad compartida del sector en 2026. Vibe coding — construir software conversando con la IA en lugar de tecleando directamente — es el término que popularizó a principios de 2025. Agentic coding describe la automatización de tareas largas con modelos autónomos como Claude Code, Codex CLI, Aider y Cline.
El último punto de inflexión ocurrió entre noviembre de 2025 y enero de 2026. En ese tramo Karpathy trasladó el 80 % de su rutina del coding manual al agent-driven coding y lo calificó como «el mayor cambio de workflow en aproximadamente 20 años de programación.» Claude Code y su archivo de memoria CLAUDE.md estuvieron en el centro. En abril de 2026 llevó el tema un paso más allá con el concepto «idea file»: una nueva arquitectura personal de conocimiento basada en compartir ideas, no código. En sus palabras: «You just share the idea, then the other person’s agent customizes & builds it for your specific needs.»
📺 El punto de partida de este artículo es la keynote de Karpathy «Software Is Changing (Again)» en la Y Combinator AI Startup School 2024. Vibe coding y agentic coding se sintetizan ahí con la mayor claridad.
¿Qué es CLAUDE.md y cómo se integra con el auto memory?
CLAUDE.md es el archivo de instrucciones persistente que tú escribes y mantienes; Claude Code lo lee al inicio de cada sesión. La doc de Anthropic lo dice claro: «Instructions you write to give Claude persistent context.» En 2026 se sumó una segunda capa de memoria: auto memory. El reparto: tú escribes CLAUDE.md (reglas, arquitectura); Claude escribe el auto memory (aprendizajes inferidos de tus correcciones y preferencias previas). El auto memory llegó con Claude Code v2.1.59 y se persiste en ~/.claude/projects/<project>/memory/MEMORY.md. Al inicio de cada chat se inyectan en el contexto las primeras 200 líneas (o 25 KB) del MEMORY.md.
| Característica | CLAUDE.md | Auto memory |
|---|---|---|
| Autor | Tú | Claude |
| Tipo de contenido | Instrucciones y reglas | Aprendizajes inferidos y patrones |
| Alcance | Proyecto, usuario u organización | Por worktree |
| Carga | Completa cada sesión | Primeras 200 líneas / 25 KB por sesión |
| Uso principal | Estándares de código, arquitectura, workflow | Comandos de build, hallazgos de debug, preferencias |
CLAUDE.md ganó una estructura más rica en 2026. Soporta cuatro alcances: archivos managed policy desplegados por IT/DevOps a nivel de organización (macOS en /Library/Application Support/ClaudeCode/CLAUDE.md, Linux en /etc/claude-code/CLAUDE.md, Windows en C:Program FilesClaudeCodeCLAUDE.md); archivos project específicos del equipo (./CLAUDE.md o ./.claude/CLAUDE.md); archivos user que aplican a todos tus proyectos (~/.claude/CLAUDE.md); y archivos local para notas personales de proyecto que van en .gitignore (./CLAUDE.local.md). Los alcances más específicos sobrescriben a los más amplios.
La mecánica de carga también se amplió. Partiendo del directorio de trabajo, Claude recorre hasta la raíz del sistema de archivos buscando CLAUDE.md y CLAUDE.local.md en cada carpeta; todas las coincidencias entran al contexto. Los CLAUDE.md de subcarpetas no se cargan al arrancar — lo hacen on-demand cuando Claude lee un archivo de esa carpeta. Si añades directorios extra con --add-dir, define CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 para que sus CLAUDE.md también carguen. Tras una compaction (/compact), el CLAUDE.md raíz del proyecto se recarga automáticamente; los anidados vuelven con la próxima lectura relevante.
Novedades 2026: imports, .claude/rules/, interoperabilidad con AGENTS.md
Para que CLAUDE.md no engorde hasta convertirse en un único archivo gigante, Anthropic estandarizó la sintaxis @path/to/import. Trae otros archivos Markdown a CLAUDE.md; soporta rutas relativas y absolutas; permite recursión hasta 5 saltos. Uso típico:
See @README for project overview and @package.json for available npm commands.
# Additional Instructions
- git workflow @docs/git-instructions.md
- personal preferences @~/.claude/my-project-instructions.md
La segunda gran adición es la carpeta .claude/rules/ con sus path-scoped rules. En lugar de meter todas las instrucciones en un CLAUDE.md, parte las reglas en archivos Markdown por tema con frontmatter YAML que sólo las active cuando Claude toque rutas que coinciden:
---
paths:
- "src/api/**/*.ts"
- "lib/**/*.{ts,tsx}"
---
# API Development Rules
- All API endpoints must include input validation
- Use the standard error response format
- Include OpenAPI documentation comments
Los archivos de reglas sin frontmatter paths cargan siempre; los que lo tienen se activan sólo cuando Claude trabaja en archivos coincidentes. Crítico para monorepos donde varios equipos mantienen sus propios conjuntos de reglas. La configuración claudeMdExcludes permite además desactivar selectivamente CLAUDE.md de directorios ancestros.
La tercera adición es la interoperabilidad con AGENTS.md. Cursor, Codex, Aider y otros agentes leen AGENTS.md; Claude Code sólo lee CLAUDE.md. La forma estándar de resolver el choque:
@AGENTS.md
## Claude Code
Use plan mode for changes under `src/billing/`.
Mismo conjunto de instrucciones compartido por todas tus herramientas de agente; la sección breve específica de Claude añade los extras. Lado de comandos slash: /init redacta el archivo, /memory muestra los archivos cargados y permite editarlos, el hook InstructionsLoaded sirve para depurar qué cargó cuándo. Con CLAUDE_CODE_NEW_INIT=1, /init se convierte en un flujo interactivo multi-fase: un subagente inspecciona el repo, te pregunta por las lagunas y propone un archivo revisable antes de escribir.
El enfoque idea file de Karpathy (abril de 2026)
El 3 de abril de 2026, Karpathy propuso en X y luego en un gist de GitHub un nuevo formato de compartir: el «idea file». Donde el open source clásico comparte código, un idea file comparte la idea, y el agente del otro lado la reconstruye para su entorno. La razón es simple: en 2026 — con modelos de agente lo suficientemente fuertes — copiar la intención es más eficiente que copiar el código píxel a píxel.
La forma concreta es una estructura de tres capas. Capa uno: la carpeta raw/; artículos, papers, imágenes, datasets aterrizan aquí. El LLM lee pero nunca modifica esta carpeta — las fuentes son inmutables y verificables. Capa dos: la carpeta wiki/; páginas de resumen, de concepto y de entidades producidas por el LLM viven aquí, cruzadas y creciendo acumulativamente en vez de re-derivarse por consulta. Capa tres: el archivo CLAUDE.md (alternativamente AGENTS.md o OPENCODE.md); define el esquema del sistema entero y cómo se mantiene.
El sistema corre sobre tres operaciones. Ingest: cuando una nueva fuente aterriza en raw/, el LLM la lee y actualiza simultáneamente 10-15 páginas wiki, lleva un índice y un log de actividad. Query: las preguntas atraviesan la estructura; las respuestas valiosas se archivan como nuevas páginas — el conocimiento se compone. Lint: chequeos de salud periódicos sacan a la luz contradicciones, páginas huérfanas, conceptos faltantes y revisiones sugeridas. Karpathy lo conecta con el concepto Memex de Vannevar Bush (1945); la pregunta no resuelta de Bush «¿quién lo mantiene?» encuentra al fin respuesta con los LLM.
Esta arquitectura diverge del RAG (Retrieval-Augmented Generation) clásico en un punto medular. RAG vuelve a las fuentes y sintetiza en cada consulta; el enfoque idea file compila el conocimiento una vez y lo mantiene al día, en lugar de redrivarlo en cada llamada. Según Karpathy: «The knowledge is compiled once and then kept current, not re-derived on every query.» CLAUDE.md es el archivo esquema que convierte un chatbot genérico en un mantenedor wiki disciplinado.
Cómo escribir un CLAUDE.md efectivo (estándares 2026)
Cuatro principios extraídos de la doc oficial de Anthropic forman el núcleo de la escritura efectiva de CLAUDE.md. Tamaño: mantener el archivo bajo 200 líneas; los más largos consumen más contexto y bajan la tasa de adherencia. Si las instrucciones crecen, divide con path-scoped rules o imports. Estructura: instrucciones agrupadas bajo headings y bullets de Markdown son mucho más escaneables que párrafos sueltos; Claude lee como un humano. Especificidad: instrucciones verificables y concretas. «Format the code properly» → «Use 2-space indentation»; «Test your changes» → «Run npm test before committing»; «Keep files organised» → «API handlers live in src/api/handlers/». Consistencia: en instrucciones contradictorias, Claude elige una al azar; revisa periódicamente CLAUDE.md y sus anidados.
¿Cuándo añadir algo a CLAUDE.md? La recomendación de Anthropic es directa: «Treat CLAUDE.md as the place you write down what you’d otherwise re-explain.» Si Claude comete el mismo error dos veces, si una convención cazada en code review también debería conocerla Claude, si te encuentras escribiendo hoy la misma corrección que la sesión pasada, o si un nuevo compañero necesitaría ese contexto para ser productivo — todo eso va a CLAUDE.md. Procedimientos multi-paso o reglas aplicables solo a un rincón del código pertenecen a una skill o path-scoped rule, no a CLAUDE.md.
La plantilla de abajo es el punto de partida mínimo funcional para un CLAUDE.md 2026. Cópiala tal cual:
# Project Name
## What this is
One-paragraph summary of what the project does and why it exists.
## Tech stack
- Language: Python 3.12 / TypeScript 5.4
- Framework: FastAPI / Next.js 15
- DB: PostgreSQL 16
- Tests: pytest + httpx / vitest
## Commands
- Install: `uv sync` / `pnpm install`
- Run dev: `uv run uvicorn app.main:app --reload` / `pnpm dev`
- Test: `uv run pytest -x` / `pnpm test`
- Lint: `uv run ruff check .` / `pnpm lint`
- Typecheck: `uv run mypy app/` / `pnpm typecheck`
## Conventions
- Type hints everywhere
- Public functions: docstrings (Google style)
- Tests live in `tests/` matching `app/` structure
- No global state — pass dependencies explicitly
## Don't
- No emoji in code or commits
- No `print()` for debug — use `logger.debug()`
- No new dependencies without justifying in PR description
- Don't write code comments that just restate what code does
## Common pitfalls
- DB migrations: run `alembic upgrade head` after pulling
- The `vendor/` folder is git-tracked but not editable
- `pytest` requires `.env.test` (copy from `.env.test.example`)
## Architecture in 3 lines
- Request → middleware (auth) → router → service → repository → DB
- Async I/O end-to-end with `asyncpg`
- Background jobs in `app/jobs/` use `arq` (not Celery)
## Imports
@README.md
@docs/architecture.md
@AGENTS.md
Dos consejos de la práctica de Karpathy: primero, la analogía «AI is a junior dev with infinite enthusiasm» — el agente IA es como un desarrollador junior talentoso pero amnésico que espera el briefing de la mañana; CLAUDE.md es ese briefing puesto por escrito. Segundo, el principio de «living memory»: el archivo no debería ser un README de escribir y olvidar — debe crecer con cada nuevo error que cometa la IA.
CLAUDE.md vs Cursor Rules vs ChatGPT Custom Instructions
Las tres principales herramientas de coding con IA almacenan el contexto del desarrollador de formas distintas. A 2026 el sistema CLAUDE.md de Claude Code es el más rico y jerárquico — managed/project/user/local + path-scoped rules + auto memory + imports. Cursor ofrece una estructura similar con Markdown + YAML frontmatter dentro de .cursor/rules/, pero sin un alcance de usuario compartido. ChatGPT Custom Instructions está ligado a tu cuenta de OpenAI, guardado en la nube, dos campos de texto plano — sin contexto de proyecto.
| Dimensión | CLAUDE.md (Claude Code) | Cursor Rules | ChatGPT Custom Instructions |
|---|---|---|---|
| Ubicación | Repo + usuario + managed (org) | .cursor/rules/*.md |
Cuenta OpenAI (nube) |
| Jerarquía | 4 alcances + anidados + auto memory | Solo proyecto | Solo usuario |
| Formato | Markdown + YAML frontmatter (rules) | Markdown + YAML frontmatter | Texto plano (2 campos) |
| Imports | @path recursivo 5 saltos |
Limitados | Ninguno |
| Path-scoped rules | ✅ .claude/rules/ + glob paths |
Parcial | ❌ |
| Auto memory | ✅ v2.1.59+ | ❌ | ❌ |
| Interop AGENTS.md | ✅ Import @AGENTS.md |
❌ | ❌ |
| Versionado | Sí (en Git) | Sí (en Git) | No (solo nube) |
| Compartir en equipo | Sí | Sí | No |
Recomendación práctica: si usas todas las herramientas en el mismo proyecto, escribe CLAUDE.md como fuente maestra, importa AGENTS.md desde él y copia idénticamente a .cursor/rules/ para Cursor. En ChatGPT Custom Instructions pon solo preferencias personales (p. ej. «Responde en español, comentarios de código en inglés») — los detalles de proyecto no van ahí porque se aplican a cada proyecto de tu cuenta.
Consejos prácticos para desarrolladores hispanohablantes
La adopción de CLAUDE.md se expandió rápidamente en la comunidad de desarrolladores hispanohablantes desde finales de 2025. Se ve en side projects abiertos en GitHub desde Madrid, Barcelona, Buenos Aires, Ciudad de México, Bogotá. La regla común es la coherencia lingüística: comentarios de código, mensajes de error y docstrings en inglés; documentación de usuario en español; descripciones de PR bilingües. Una sola línea en CLAUDE.md basta: «Code comments, docstrings, error messages: English. Documentation in docs/: Spanish. PR descriptions: bilingual.»
Segundo tema recurrente en proyectos hispanos: encoding y locale. UTF-8 (sin BOM), collation utf8mb4_unicode_ci, y es_ES.UTF-8 (o es_MX, es_AR) explícito en tests sensibles al orden es práctica estándar. Sin esa nota, la IA produce inconsistencias con tildes y ñ. Tercer bloque crítico: regulación y reglas de negocio locales: cumplimiento del RGPD (UE) o la LFPDPPP (México), facturación electrónica en formatos CFDI (México) o Facturae (España), formateo de precios en EUR f"{amount:,.2f} €" o MXN/ARS según el país — reglas que la IA no conoce por sí sola.
Último consejo: versiona CLAUDE.md con el equipo. Archivo en main y revisión en cada PR. Una regla añadida por un desarrollador se convierte instantáneamente en el estándar del equipo porque la IA siempre lee la versión más reciente. Esa es la base del movimiento por el cual los equipos hispanohablantes codifican estándares técnicos junto con la IA.
Preguntas frecuentes sobre CLAUDE.md
¿CLAUDE.md y auto memory son lo mismo?
No. CLAUDE.md es el archivo que escribes con reglas y arquitectura. El auto memory es lo que Claude lleva por su cuenta en ~/.claude/projects/<project>/memory/MEMORY.md — preferencias inferidas de correcciones pasadas. Los dos cargan juntos; ninguno reemplaza al otro. Auto memory está disponible a partir de Claude Code v2.1.59.
¿Qué pasa si ~/.claude/CLAUDE.md y ./CLAUDE.md chocan?
Cargan ambos, los contenidos se fusionan. En conflictos directos gana el nivel de proyecto (./CLAUDE.md) por ser más específico. Usa el nivel usuario para «cosas que quiero en cada proyecto», el de proyecto para «reglas exclusivas de este proyecto».
¿Cómo funcionan los imports @path?
@README.md o @~/.claude/preferences.md hacen que Claude incorpore el archivo al contexto. Se soportan rutas relativas y absolutas. Recursión máxima de 5 saltos — un archivo importado puede importar otro, que a su vez puede importar otro, pero el 6° nivel se rechaza. En el primer import externo aparece un diálogo de confirmación; rechazarlo cierra el diálogo de forma permanente.
¿Qué diferencia hay entre .claude/rules/ y CLAUDE.md?
CLAUDE.md carga siempre; los archivos bajo .claude/rules/ con frontmatter paths cargan solo cuando Claude procesa un archivo coincidente. En proyectos grandes, la carpeta rules corta las instrucciones por tema/ruta y baja el consumo de contexto. Los archivos rules sin paths tienen la misma prioridad que CLAUDE.md.
¿Cómo se relacionan skills, plugins y subagents con CLAUDE.md?
Las skills son módulos más pesados invocados a demanda, no cargados en cada sesión. Los plugins empaquetan servidores MCP, comandos slash y bundles de skills para distribución. Los subagents pueden tener su propio auto memory (enable-persistent-memory). CLAUDE.md sirve como capa de contexto base bajo todo eso; los flujos específicos migran a skills.
¿El concepto «idea file» de Karpathy redefinió CLAUDE.md?
No directamente, pero amplió su alcance. El CLAUDE.md clásico contiene reglas y comandos. En la propuesta de abril de 2026 de Karpathy, CLAUDE.md adicionalmente cumple el rol de archivo esquema que gobierna raw/ (fuentes) y wiki/ (conocimiento compilado por el LLM). Eso lleva CLAUDE.md de una lista de comandos al centro del sistema de gestión de conocimiento.
¿Dónde se sigue a Karpathy?
Cuatro canales principales: YouTube (@AndrejKarpathy) para las conferencias maratón, X / Twitter (@karpathy) para observaciones diarias, GitHub (github.com/karpathy) para proyectos open source como nanogpt, nanochat, makemore, micrograd, llm.c, y Eureka Labs (eurekalabs.ai) para los anuncios de la plataforma educativa de IA. El gist idea file está directamente en gist.github.com/karpathy/442a6bf555914893e9891c11519de94f.
Conclusión: CLAUDE.md, la nueva memoria del software en la era de la IA
CLAUDE.md es una convención de apariencia simple que está reconfigurando la naturaleza del desarrollo de software. A 2026 ya no es un único archivo sino un sistema que abarca cuatro alcances, imports, path-scoped rules, auto memory y arquitectura idea file. Como apunta Karpathy: la nueva moneda del software no es solo el código, es el contexto que le das a la IA. Mantener ese contexto persistente, continuamente actualizado y compartido por el equipo se convirtió en la nueva configuración base de los equipos de software modernos.
El plan práctico es simple. Día uno: arranca Claude Code en cualquier proyecto abierto y ejecuta /init (idealmente con CLAUDE_CODE_NEW_INIT=1). Día dos: edita el borrador generado contra la plantilla de esta guía. Primera semana: ante cada error de la IA, añade una línea a CLAUDE.md antes de arreglarlo. Segunda semana: comparte con el equipo e integra en la revisión de PR. Al mes: si el archivo se acerca a 200 líneas, divide con .claude/rules/ y empieza a usar imports @path. Tres meses después: considera la arquitectura idea file de Karpathy con las capas raw/ y wiki/.
Recomendación clara: trata CLAUDE.md con la misma seriedad que README.md. Cada línea añadida en un mes es un error que la IA no cometió en ese mes. Esta inversión compone — el retorno crece a medida que pasan las semanas.
Fuentes
- Anthropic. Claude Code Documentation — How Claude remembers your project. code.claude.com/docs/en/memory (acceso: 2026-05-01)
- Anthropic. Claude Code: Skills, Plugins, Hooks, Subagents documentation. code.claude.com/docs/en
- Karpathy, Andrej. Idea file — gist de GitHub, abril 2026. gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
- Karpathy, Andrej. Publicaciones en X (Twitter), @karpathy — tweet del idea file del 3 de abril de 2026 y discusiones posteriores.
- Karpathy, Andrej. Software Is Changing (Again) — keynote, Y Combinator AI Startup School, 2024. YouTube: youtube.com/watch?v=LCEmiRjPEtQ
- Karpathy, Andrej. Software 2.0. Medium, noviembre 2017. karpathy.medium.com/software-2-0-a64152b37c35
- Karpathy, Andrej. github.com/karpathy — ejemplos de CLAUDE.md y AGENTS.md en
nanogpt,nanochat,makemore,micrograd,llm.c. - Antigravity Codes. Karpathy’s LLM Wiki: The Complete Guide to His Idea File. antigravity.codes/blog/karpathy-llm-wiki-idea-file
- MCP Directory. Claude Code Best Practices: A Developer’s Guide (2026). mcp.directory/blog/claude-code-best-practices
