La guía definitiva del archivo CLAUDE.md: cómo multiplicar por 10 tu productividad con Claude Code

Qué es un archivo CLAUDE.md y por qué importa

Si usas Claude Code sin un archivo CLAUDE.md, estás dejando la mayor parte de su potencia sobre la mesa.

CLAUDE.md es un archivo de configuración en Markdown que Claude Code lee automáticamente al inicio de cada sesión. Le dice a Claude sobre la arquitectura de tu proyecto, estándares de código, herramientas preferidas, patrones de testing y reglas de flujo. En lugar de repetir las mismas instrucciones cada conversación, las escribes una vez y Claude las sigue siempre.

Piénsalo como la diferencia entre contratar a un contratista que no sabe nada de tu empresa frente a uno que ha leído todo tu manual de ingeniería. El archivo CLAUDE.md es ese manual.

Por qué CLAUDE.md supera los prompts repetidos

Solo el ahorro de tokens es significativo. Si gastas 500 tokens en establecer contexto por conversación y tienes 20 conversaciones al día, son 10 000 tokens diarios, o aproximadamente $0.15-$0.75 al día según el modelo. A lo largo de un mes, un archivo CLAUDE.md te ahorra entre $4.50 y $22.50 en costes puros de API mientras produce mejores resultados.

Créditos de Anthropic | Créditos de AWS | Créditos de Google Cloud

---

Cómo lee Claude Code los archivos CLAUDE.md

Claude Code busca archivos CLAUDE.md en un orden de prioridad específico. Entender esta jerarquía es esencial para organizar tus instrucciones eficazmente.

Orden de carga de archivos

Claude Code fusiona todos los archivos aplicables. Si tu archivo global dice "usa indentación de 2 espacios" pero tu archivo de proyecto dice "usa tabs de 4 espacios", el archivo del proyecto gana para ese proyecto.

Qué va dónde

CLAUDE.md global (~/.claude/CLAUDE.md): preferencias que se aplican en todas partes:

# Global Preferences
- Always use TypeScript over JavaScript when possible
- Prefer functional components over class components in React
- Write concise commit messages under 72 characters
- Use ESM imports, never CommonJS require()

CLAUDE.md del proyecto (raíz del proyecto): todo lo específico de esta base de código:

# Project: Acme Dashboard
## Tech Stack
- Next.js 15 with App Router
- TypeScript 5.x strict mode
- Tailwind CSS 4.0
- Prisma ORM with PostgreSQL
- Jest + React Testing Library for tests

## Architecture
- /app — Next.js routes (App Router only, no Pages Router)
- /components — reusable UI components
- /lib — business logic and utilities
- /prisma — database schema and migrations

---

Creando tu primer archivo CLAUDE.md

Aquí tienes una configuración paso a paso para empezar con Claude Code y un archivo CLAUDE.md configurado correctamente.

Paso 1: instala Claude Code

npm install -g @anthropic-ai/claude-code

Paso 2: crea CLAUDE.md en la raíz de tu proyecto

touch CLAUDE.md

Paso 3: añade configuración básica

Empieza con esta plantilla mínima y expándela según necesites:

# Project: [Your Project Name]

## Tech Stack
- [Language/Framework]
- [Database]
- [Key libraries]

## Coding Standards
- [Indentation preference]
- [Naming conventions]
- [Import ordering]

## Rules
- Always write tests for new functions
- Never commit directly to main
- Use conventional commit messages

Paso 4: ejecuta Claude Code

claude

Claude Code detecta y carga automáticamente tu archivo CLAUDE.md. Verás una confirmación en la salida de la sesión.

---

Plantillas de CLAUDE.md: inicial, avanzada y de equipo

Plantilla 1: proyecto simple (20 líneas)

Mejor para desarrolladores en solitario, side projects y bases de código pequeñas.

# My App

## Stack
- Python 3.12, FastAPI, SQLAlchemy, PostgreSQL
- pytest for testing

## Rules
- Use type hints on all function signatures
- Write docstrings for public functions
- Keep functions under 30 lines
- Use async/await for all database operations
- Format with black, lint with ruff

## Patterns
- Repository pattern for data access
- Pydantic models for request/response validation
- Dependency injection via FastAPI Depends()

Plantilla 2: proyecto full-stack avanzado (más de 80 líneas)

Para aplicaciones de producción con varios desarrolladores y arquitectura compleja.

# Acme SaaS Platform

## Tech Stack
- Frontend: Next.js 15, TypeScript 5.x, Tailwind CSS 4.0
- Backend: Node.js 22, tRPC, Prisma ORM
- Database: PostgreSQL 16, Redis 7
- Infrastructure: Vercel (frontend), Railway (backend)
- Testing: Vitest, Playwright, MSW

## Architecture
All code follows Clean Architecture principles:
- /packages/web — Next.js frontend (App Router only)
- /packages/api — tRPC backend
- /packages/shared — shared types and utilities
- /packages/db — Prisma schema and client

## Coding Standards
- Strict TypeScript: no any, no ts-ignore
- All components must be functional with hooks
- Server Components by default, "use client" only when needed
- All API routes must have Zod input validation
- Database queries go through repository layer, never raw SQL

## Testing Requirements
- Minimum 80% coverage for new code
- Unit tests for all business logic
- Integration tests for API endpoints
- E2E tests for critical user flows
- Use MSW for API mocking, never mock fetch directly

## Git Workflow
- Conventional commits: feat:, fix:, chore:, docs:
- All PRs require passing CI before merge
- Squash merge to main
- Branch naming: feature/TICKET-123-description

## Security Rules
- NEVER hardcode secrets or API keys
- Always use environment variables for config
- Sanitize all user input
- Use parameterized queries (Prisma handles this)
- NEVER expose internal error details to clients

Plantilla 3: configuración de equipo (compartida vía Git)

Para equipos que quieren comportamiento consistente de Claude Code entre todos los miembros.

# Team Engineering Standards — Acme Corp

## Overview
This file ensures Claude Code follows our team's engineering
standards. Committed to Git so all engineers get identical behavior.

## Code Review Checklist (Claude must follow before suggesting code)
1. Does this change have tests?
2. Are error cases handled?
3. Is the function documented?
4. Does it follow our naming conventions?
5. Are there any security implications?

## Naming Conventions
- Components: PascalCase (UserProfile.tsx)
- Hooks: camelCase with use prefix (useAuth.ts)
- Utils: camelCase (formatDate.ts)
- Constants: SCREAMING_SNAKE (MAX_RETRIES)
- Database tables: snake_case (user_profiles)
- API routes: kebab-case (/api/user-settings)

## Forbidden Patterns
- DO NOT use console.log in production code (use our logger)
- DO NOT use any TypeScript escape hatches (any, @ts-ignore)
- DO NOT install new dependencies without justification
- DO NOT modify database schema without migration file
- DO NOT use default exports (use named exports only)

## Preferred Libraries (do not suggest alternatives)
- State management: Zustand (not Redux)
- Forms: React Hook Form + Zod (not Formik)
- HTTP client: native fetch (not Axios)
- Date handling: date-fns (not Moment.js)
- Animation: Framer Motion (not React Spring)

---

Comparativa: CLAUDE.md vs .cursorrules vs .github/copilot-instructions.md

Si estás evaluando herramientas de programación con IA, entender cómo cada una maneja la configuración es crítico.

El diferenciador clave de Claude Code es el ecosistema en torno a CLAUDE.md: hooks, comandos personalizados, servidores MCP y soporte multi-agente lo convierten de un archivo de configuración en un framework completo de automatización.

---

Hooks: automatizando tu flujo de Claude Code

Los hooks se configuran en .claude/settings.json, no en CLAUDE.md en sí. Ejecutan comandos de shell automáticamente antes o después de eventos de Claude Code.

Estructura de configuración de hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "echo 'File about to be modified'"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH"
      }
    ],
    "PreCommit": [
      {
        "command": "npm run lint && npm run test:changed"
      }
    ]
  }
}

Patrones de hooks más útiles

Ejemplos prácticos de hooks

Auto-formato después de cada edición de archivo:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "command": "npx prettier --write $CLAUDE_FILE_PATH"
      }
    ]
  }
}

Ejecutar tests para archivos modificados:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "npx vitest run --reporter=verbose --changed"
      }
    ]
  }
}

---

Slash commands personalizados

Los slash commands te permiten crear plantillas de prompt reutilizables que se activan con un solo comando /.

Cómo crear slash commands

1. Crea un directorio .claude/commands/ en tu proyecto
2. Añade archivos Markdown: cada archivo se convierte en un comando
3. Usa $ARGUMENTS como placeholder para entrada dinámica

Ejemplo: .claude/commands/review.md

Review the following code for:
1. Security vulnerabilities
2. Performance issues
3. Missing error handling
4. Test coverage gaps

Code to review: $ARGUMENTS

Provide a severity rating (low/medium/high/critical) for each finding.

Uso en Claude Code:

/project:review src/auth/login.ts

Ideas útiles de slash commands

---

Servidores MCP: extendiendo las capacidades de Claude Code

Los servidores MCP (Model Context Protocol) conectan Claude Code con herramientas y servicios externos. Configurados correctamente, Claude Code puede consultar bases de datos, navegar por la web, gestionar archivos, interactuar con GitHub y mucho más, todo desde dentro de tu sesión de programación.

Cómo configurar servidores MCP

Los servidores MCP se configuran en .claude/settings.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://localhost:5432/mydb"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

Servidores MCP más populares para desarrolladores

Referenciando MCP en CLAUDE.md

Tu CLAUDE.md puede instruir a Claude Code sobre cuándo y cómo usar servidores MCP conectados:

## Available Tools
- Use the postgres MCP to check schema before writing migrations
- Use the github MCP to create PRs after completing feature branches
- Use the memory MCP to track progress on multi-step tasks

---

La configuración viral de 27 agentes: cómo un ingeniero de Google automatizó el 80 % de su trabajo

A principios de 2026, el hilo de Twitter de un ingeniero de Google se hizo viral describiendo cómo configuró 27 agentes especializados de Claude Code para manejar distintas partes de su flujo. Cada agente tenía su propio CLAUDE.md con instrucciones estrechas y enfocadas.

La idea central

En lugar de una sola sesión de Claude Code generalista intentando hacer todo, descompuso su trabajo en roles especializados. Cada agente tenía:

• Un CLAUDE.md dedicado con conocimiento específico del dominio
• Acceso restringido a herramientas (solo lo que ese agente necesita)
• Límites claros sobre qué debería y no debería tocar
• Formatos de salida específicos y estándares de calidad

Ejemplo de desglose de agentes

Cómo replicar esta configuración

No necesitas 27 agentes para beneficiarte de este patrón. Empieza con 3-5 configuraciones especializadas:

1. Crea archivos CLAUDE.md separados por rol:

.claude/agents/frontend.md
.claude/agents/backend.md
.claude/agents/testing.md

2. Lanza Claude Code con una configuración específica:

# Use different profiles by combining global + agent-specific context
claude --profile frontend

3. Define puntos de transferencia claros:

Tu CLAUDE.md principal puede referenciar cuándo cambiar de agente:

## Agent Workflow
- Frontend changes: use the frontend agent profile
- API changes: use the backend agent profile
- After any code change: run the test agent
- Before merging: run the review agent

Por qué funciona

El enfoque de 27 agentes funciona por un principio fundamental en productividad de IA: el contexto estrecho produce mejor salida que el contexto amplio. Una sesión de Claude Code cargada con 400 líneas de instrucciones sobre frontend, backend, DevOps, testing y documentación rendirá peor en cualquier tarea individual que una cargada con 50 líneas altamente relevantes.

---

Errores comunes en CLAUDE.md (y cómo arreglarlos)

Error 1: ser demasiado vago

Malo:

Write good code that follows best practices.

Bueno:

- Use TypeScript strict mode, no implicit any
- All functions must have JSDoc comments
- Error handling: wrap async operations in try/catch
- Max function length: 30 lines

Error 2: sobrecargar con instrucciones

Poner más de 500 líneas de instrucciones hace que Claude Code desprioritice reglas importantes. Mantén tu CLAUDE.md enfocado.

Error 3: no versionar CLAUDE.md

Tu CLAUDE.md debería hacerse commit a Git. Esto garantiza:

• Consistencia del equipo
• Historial de cambios y responsabilidad
• Rollback fácil si las instrucciones causan problemas
• Revisiones de PR para cambios de instrucciones

Error 4: ignorar la sección de seguridad

Incluye siempre reglas de seguridad en tu CLAUDE.md:

## Security (CRITICAL — never ignore)
- NEVER hardcode API keys, tokens, or passwords
- NEVER commit .env files
- ALWAYS use parameterized database queries
- ALWAYS validate and sanitize user input
- NEVER expose stack traces or internal errors to users

Error 5: olvidar mencionar el tech stack

Claude Code puede inferir tu stack del código, pero las declaraciones explícitas previenen suposiciones equivocadas:

## Stack (authoritative — do not infer differently)
- Runtime: Node.js 22 (NOT Deno, NOT Bun)
- Framework: Next.js 15 App Router (NOT Pages Router)
- ORM: Prisma (NOT Drizzle, NOT TypeORM)
- Package manager: pnpm (NOT npm, NOT yarn)

---

Mejores prácticas de Claude Code: consejos de power users

Consejo 1: usa instrucciones condicionales

## Environment-Specific Rules
- In development: use verbose logging, skip minification
- In production: no console.log, enable all optimizations
- In CI: run full test suite, fail on any warning

Consejo 2: define formatos de salida

## When I ask for a code review, respond with:
1. **Summary** (1-2 sentences)
2. **Issues found** (bulleted, severity-tagged)
3. **Suggested fixes** (with code snippets)
4. **Overall grade** (A/B/C/D/F)

Consejo 3: establece límites en dependencias

## Dependency Rules
- NEVER install packages with fewer than 1,000 weekly downloads
- NEVER install packages with known CVEs
- Prefer built-in Node.js APIs over third-party packages
- Always check bundle size impact before adding frontend deps

Consejo 4: usa archivos de memoria para proyectos largos

## Memory
- Track all completed features in .claude/memory/features.md
- Log all architecture decisions in .claude/memory/decisions.md
- Update progress after each session

Consejo 5: integra con tu CI/CD

Tu CLAUDE.md puede instruir a Claude Code para respetar tu pipeline de CI:

## Before pushing any code:
1. Run `pnpm lint` — fix all errors
2. Run `pnpm test` — all tests must pass
3. Run `pnpm build` — build must succeed
4. Check bundle size — must not exceed 250KB

---

¿Cuánto cuesta Claude Code? (Y cómo conseguir créditos)

Claude Code usa créditos de API, lo que significa que tus costes dependen del modelo que uses y cuánto contexto le des.

Desglose de costes de Claude Code

Un día típico intensivo de Claude Code usa 500K-2M tokens, costando $2-$30 según la elección del modelo. Un CLAUDE.md bien configurado reduce el uso de tokens al eliminar contexto repetido.

Consiguiendo créditos gratuitos para Claude Code

La mejor forma de financiar tu uso de Claude Code es a través de programas de créditos:

Créditos acumulables totales: hasta más de $230 000 entre todos los programas.

Créditos de Anthropic | Créditos de AWS | Créditos de Google Cloud | Créditos de Azure

Un solo archivo CLAUDE.md combinado con entre $5000 y $25 000 en créditos de startup te da entre 3 y 6 meses de desarrollo intensivo con Claude Code a coste cero. Explora todos los programas de créditos disponibles en ClaimAICredits para encontrar para cuáles calificas.

---

Referencia rápida: chuleta de CLAUDE.md

---

Empieza hoy

El archivo CLAUDE.md es la configuración de mayor apalancamiento que puedes establecer para desarrollo asistido por IA. Empieza con la plantilla simple de esta guía, haz commit a tu repo e itera basándote en lo que funciona para tu flujo.

Los ingenieros que obtienen más valor de Claude Code no escriben mejores prompts: escriben mejores archivos CLAUDE.md. La configuración viral de 27 agentes demuestra que la configuración bien pensada vence al prompting por fuerza bruta cada vez.

Si los costes de la API de Claude Code te están frenando para experimentar con configuraciones avanzadas como flujos multi-agente, explora los programas de créditos gratuitos disponibles a través de ClaimAICredits. Acumular créditos de Anthropic, AWS y Google Cloud puede darte meses de tiempo de desarrollo gratuito para perfeccionar tu configuración de CLAUDE.md.