CLAUDE.md Best Practices

Guía compilada de fuentes oficiales de Anthropic (Enero 2026) para optimizar archivos CLAUDE.md.

Sources

Core Principle

“Think of CLAUDE.md as the ‘unwritten knowledge’ in your codebase - things a new developer would need to know but might not find in code.”

CLAUDE.md es el único contenido automáticamente incluido en cada conversación, haciéndolo esencial para onboardear agentes a tu codebase.

Golden Rule

Para cada línea en CLAUDE.md, preguntá:

“¿Eliminar esto causaría que Claude cometa errores?”

Si la respuesta es no, eliminalo. CLAUDE.md inflados causan que Claude ignore instrucciones.

Quick Tools

/init Command

Genera un CLAUDE.md inicial basado en la estructura del proyecto:

claude /init

# Key

Durante una sesión de Claude Code, presioná # para agregar instrucciones dinámicamente que se guardan en CLAUDE.md.

@import Syntax

CLAUDE.md puede importar contenido de otros archivos usando @:

See @README.md for project overview and @package.json for available commands.

For git workflow details: @docs/git-workflow.md

Esto permite mantener CLAUDE.md conciso mientras se referencia documentación detallada.

The Three Dimensions

Todo CLAUDE.md debe cubrir:

Dimension Description Example
WHAT Tech stack, estructura, organización “Built with React, components in src/components/”
WHY Propósito, qué problema resuelve “Enables users to manage their accounts”
HOW Build tools, testing, verificación “npm run build after changes”

Length Guidelines

Source Recomendación
HumanLayer < 300 líneas (ideal ~60 líneas)
Anthropic “Conciso y legible” (sin límite específico)
Practical < 200 líneas para la mayoría de proyectos

Por qué importa

  • Claude Code’s system prompt contiene ~50 instrucciones
  • Research muestra que LLMs siguen confiablemente ~150-200 instrucciones
  • Cada instrucción en CLAUDE.md “compite” por atención
  • Bloat reduce compliance uniformemente en TODAS las instrucciones

Qué Incluir vs Excluir

✅ Incluir ❌ Excluir
Comandos bash que Claude no puede adivinar Lo que Claude puede deducir leyendo código
Reglas de estilo que difieren de defaults Convenciones estándar del lenguaje
Testing instructions y test runners preferidos API docs detallados (linkear)
Etiqueta del repo (branch naming, PR) Info que cambia frecuentemente
Decisiones arquitectónicas del proyecto Explicaciones largas o tutoriales
Developer environment quirks (env vars) Descripciones file-by-file
Common gotchas o comportamientos no obvios Prácticas self-evident

CLAUDE.md vs Skills

CLAUDE.md Skills
Reglas que aplican a TODAS las tareas Domain knowledge solo relevante a veces
Code style y workflow del repo Workflows especializados reutilizables
Convenciones universales Info que cambia por contexto
Se carga automáticamente Se cargan on-demand

Regla práctica: Si la información solo aplica a ciertos tipos de tareas, probablemente debería ser un skill.

Emphasis Techniques

Usar keywords de énfasis para reglas críticas:

Keyword Uso
**CRITICAL** Nunca debe violarse
**IMPORTANT** Siempre debe seguirse
**YOU MUST** Acción mandatoria
**Note** Callout informativo

Ejemplo 

## Key Development Rules

- **CRITICAL**: NUNCA commitear secrets o API keys
- **IMPORTANT**: Siempre correr tests antes de push
- **YOU MUST**: Seguir el PR template al crear PRs

Progressive Disclosure

En lugar de poner todo en CLAUDE.md, usar referencias:

✅ Hacer esto 

### Component Structure

Reference implementation: `src/components/Button/Button.tsx`

Key patterns:
- Props defined as types
- Styles co-located with component

❌ Evitar esto 

### Component Structure

interface ButtonProps {
  label: string;
  onClick: () => void;
  variant?: 'primary' | 'secondary';
}

export const Button: React.FC<ButtonProps> = ...

Por qué

  • Code snippets se vuelven obsoletos; file references se mantienen actuales
  • Reduce consumo de tokens
  • Claude puede leer el archivo real cuando lo necesita

File Placement Strategy

Ubicación Caso de uso
Root directory Más común, compartido vía git
CLAUDE.local.md Solo local (agregar a .gitignore)
Parent directories Monorepos - auto-loaded
Child directories On-demand cuando se trabaja en esa área
~/.claude/CLAUDE.md Global, aplica a todas las sesiones

Common Anti-Patterns

Anti-Pattern Problema Solución
Kitchen sink Muchas instrucciones diluyen efectividad Mantener < 200 líneas
Code snippets Se vuelven obsoletos, gastan tokens Usar file:line references
Styling rules LLM es lento para tareas determinísticas Usar linters
No emphasis Reglas críticas mismo peso que menores Usar CRITICAL/IMPORTANT
No WHY section Agent no entiende contexto del proyecto Agregar explicación de propósito
Domain knowledge Infla cada sesión Mover a skills

Quick Checklist

Antes de commitear cambios a CLAUDE.md:

  • ¿Menos de 200 líneas?
  • ¿Pasa la Golden Rule? (cada línea previene errores)
  • ¿Tiene secciones WHAT, WHY, HOW?
  • ¿Reglas críticas tienen énfasis?
  • ¿Code snippets reemplazados por file references?
  • ¿Comandos bash tienen descripciones?
  • ¿Referencia external docs para temas detallados?
  • ¿Sin styling rules que deberían estar en linters?
  • ¿Domain-specific content movido a skills?

Template Structure 

# CLAUDE.md

Brief intro about Claude Code guidance.

## Repository Overview

One paragraph: what this project is and tech stack.

## Why This Exists

What problem it solves, who uses it.

## Quick Start & Commands

```bash
npm ci        # Install dependencies
npm start     # Dev server
npm run build # Production build
npm test      # Run tests

Note: Any important setup notes.

Architecture Overview

Key patterns, folder structure, main concepts.

Key Development Rules

  • CRITICAL: [Most important rule]
  • IMPORTANT: [Second most important]
  • Other rules…

References

  • /docs/architecture/ - Detailed architecture
  • /docs/development/ - Development guides ```

Last updated: 2026-01