Qué son estos archivos en la práctica
Si has usado Claude Code, es probable que hayas encontrado dos archivos de contexto: CLAUDE.md y AGENTS.md. A primera vista se parecen, y los nombres no dejan clara la diferencia. Ambos son archivos de markdown simple que Claude lee para orientarse. Pero sirven para cosas distintas, y entender cuál usar ahorra tiempo.
La versión corta: CLAUDE.md es el archivo de contexto general. Ahí va todo lo que Claude necesita saber para trabajar bien en un proyecto o negocio, con orientación clara y comportamiento consistente. AGENTS.md es un archivo más específico, introducido después, para definir reglas sobre el comportamiento de los agentes, especialmente cuando Claude Code ejecuta tareas automatizadas o semi-automatizadas. Los dos pueden coexistir en el mismo proyecto sin conflicto.
CLAUDE.md: la capa de orientación
CLAUDE.md fue el primer archivo de contexto para Claude Code. Cuando inicias una sesión, Claude lee cualquier CLAUDE.md que encuentre en el directorio actual (y en los directorios superiores). Lo trata como contexto de fondo, no como instrucciones paso a paso. Piénsalo como el documento de bienvenida que le das a alguien nuevo antes de que empiece a trabajar.
Lo que suele ir en un CLAUDE.md:
- Qué hace el proyecto o negocio
- Convenciones y preferencias clave (nombres, formatos, tono)
- Qué herramientas y sistemas se usan
- Qué evitar o verificar antes de actuar
- Referencias a documentos más detallados
Un CLAUDE.md para un proyecto de software puede describir la arquitectura. Uno para un negocio puede describir el servicio, el cliente típico y las reglas de voz. El archivo es flexible, y esa flexibilidad es parte de su valor. Es una forma estructurada de darle a Claude suficiente contexto para que no haya que reintroducirlo en cada sesión.
Porque CLAUDE.md no es un concepto exclusivo de Claude Code, se ha convertido también en una convención más amplia para darle contexto estructurado a cualquier conversación de Claude. Un dueño de negocio que nunca ha abierto una terminal puede pegar un CLAUDE.md bien escrito en un chat de Claude y obtener respuestas sustancialmente mejores y más consistentes. El archivo no requiere Claude Code para ser útil.
AGENTS.md: reglas específicas para agentes
AGENTS.md es una adición más reciente. Anthropic lo introdujo para darle a los desarrolladores un lugar dedicado para las reglas que aplican específicamente cuando Claude opera como agente, es decir, cuando está tomando acciones en múltiples pasos, llamando herramientas, editando archivos o ejecutando comandos con mínima interrupción.
La distinción importa en un contexto de desarrollo. Cuando Claude Code opera de forma autónoma, puede que necesites reglas más precisas que la orientación general. Cosas como: qué directorios no debe tocar, cómo manejar errores, cuándo pausar y preguntar en lugar de seguir, qué nivel de confirmación se necesita antes de una acción destructiva. Este tipo de restricciones de comportamiento pertenecen a AGENTS.md, en lugar de saturar un CLAUDE.md que también leen personas.
Para la mayoría de los desarrolladores que usan Claude Code, AGENTS.md vive junto a CLAUDE.md en la raíz del repositorio. Claude lee ambos. CLAUDE.md provee la orientación del proyecto; AGENTS.md provee las reglas operativas del agente.
La diferencia práctica para quienes no son desarrolladores
Si eres dueño de un negocio y no eres desarrollador, probablemente no necesitas AGENTS.md. Ese archivo aborda un problema específico de flujos de trabajo automatizados con herramientas. La mayoría de los dueños de negocio usan Claude de forma conversacional, lo que significa que CLAUDE.md es el archivo relevante.
Lo que un buen CLAUDE.md hace por un dueño de negocio es considerable. Sin uno, cada conversación con Claude empieza desde cero. Tienes que volver a explicar qué hace tu negocio, quiénes son tus clientes, cuáles son tus reglas de voz, qué herramientas usas. Con un CLAUDE.md bien estructurado, Claude retoma donde lo dejaste. Pegas el archivo en la conversación una vez, y la IA tiene contexto de trabajo real.
La diferencia en calidad de respuesta no es sutil. Claude sin contexto da respuestas genéricas. Claude con un CLAUDE.md adecuado puede redactar tu copy en tu voz, escribir correos dirigidos a clientes con el tono correcto, ayudarte a pensar decisiones con conocimiento real de tus restricciones. El archivo no es magia; es contexto estructurado que reemplaza el trabajo mental de reintroducir todo en cada sesión.
Qué hace útil de verdad a un CLAUDE.md
No todos los CLAUDE.md son igual de útiles. Un archivo que dice "tengo una agencia de marketing" es técnicamente un CLAUDE.md, pero le da a Claude casi nada con qué trabajar. Uno que cubre la oferta de servicios, el cliente típico, los formatos de entrega que realmente usas y algunas reglas de voz le da a Claude una base real.
Los CLAUDE.md más útiles tienden a compartir ciertas características. Son específicos: nombran cosas en lugar de describirlas en categorías. Cubren restricciones además de capacidades, porque saber qué no hacer es tan valioso como saber qué hacer. Incluyen una orientación breve al inicio para que Claude, y cualquier persona que lea el archivo, pueda entender la situación en el primer párrafo.
La capa de profundidad son los documentos de la base de conocimiento que acompañan al CLAUDE.md. Esos archivos pueden entrar en detalle sobre procesos, historial de clientes, especificaciones de productos, lo que el negocio necesite. El CLAUDE.md en sí mismo se mantiene orientado a darle a Claude una lectura rápida y precisa de la situación.
Cómo encaja AI Brain Docs
Escribir un buen CLAUDE.md desde cero tarda más de lo que la mayoría espera. Tienes que saber qué incluir, cómo estructurarlo y cómo redactarlo para que Claude lo use correctamente. La mayoría de los dueños de negocio o lo omiten o escriben algo demasiado vago para ser útil.
AI Brain Docs genera un CLAUDE.md para tu negocio a partir de un cuestionario corto. Respondes seis preguntas y la herramienta produce un brain estructurado que tu IA puede usar de verdad: un CLAUDE.md con la orientación de tu negocio, una base de conocimiento con documentos de profundidad en siete áreas clave y un Plan de Acción con IA que mapea lo que Claude puede hacer por ti ahora mismo.
Pegas los archivos generados en Claude, ChatGPT o Gemini, y la IA conoce tu negocio. Sin configuración, sin tener que reintroducir contexto en cada sesión. Si has trabajado con herramientas de IA que se sienten genéricas, vale la pena ver de primera mano la diferencia que hace un CLAUDE.md bien construido.