CLAUDE.md y Project Context Files

Descripción de la cápsula

CLAUDE.md es posiblemente la herramienta más infrautilizada de Claude Code. Es un archivo que le da a Claude Code comprensión del proyecto sin incluir todos los archivos: architecture overview, naming conventions, file structure, key abstractions, common patterns. Es el "briefing" que hace que cada sesión sea productiva desde el primer mensaje.

Invierte 30 minutos en un buen CLAUDE.md y cada sesión futura será significativamente más productiva. Sin CLAUDE.md, cada sesión empieza desde cero. Con CLAUDE.md, Claude Code ya "conoce" tu proyecto.

Qué es CLAUDE.md

El concepto

CLAUDE.md es un archivo markdown en la raíz de tu proyecto (o en .claude/) que Claude Code lee automáticamente al inicio de cada sesión. Contiene información que Claude Code necesita para trabajar efectivamente con tu proyecto pero que no está explícita en el código.

Lo que CLAUDE.md NO es

• ❌ No es documentación para humanos (README.md es para eso)
• ❌ No es una copia del código (eso consume context innecesariamente)
• ❌ No es una lista de tareas (use TodoWrite para eso)
• ❌ No es configuración (settings.json es para eso)

Lo que CLAUDE.md SÍ es

• ✅ Contexto del proyecto que no está en el código
• ✅ Convenciones que Claude Code debe seguir
• ✅ Estructura que ayuda a Claude Code a navegar
• ✅ Patterns que Claude Code debe usar al generar código
• ✅ Información que evita preguntas repetitivas

Estructura de un Buen CLAUDE.md

Template base

# Project: [Nombre]

## Architecture
[2-3 párrafos describiendo la arquitectura general:
layers, componentes principales, data flow]

## Structure

src/ api/ → HTTP routes (FastAPI) services/ → Business logic models/ → SQLAlchemy models repositories/ → Data access utils/ → Pure utility functions tests/ → pytest tests (mirrors src/ structure)

## Conventions
- Naming: snake_case for functions, PascalCase for classes
- Error handling: raise HTTPException in routes, raise custom exceptions in services
- Imports: absolute imports only, no relative
- Testing: pytest with fixtures, mock external services

## Key Abstractions
- BaseService: all services inherit from this
- BaseRepository: all repos inherit, provides CRUD
- ResponseModel: Pydantic base for API responses

## Patterns
- Service Layer: routes call services, services call repos
- Repository Pattern: all DB access through repos
- Dependency Injection: FastAPI Depends() for services

## Common Tasks
- Adding new endpoint: create route, service, tests
- Adding new model: create model, migration, repository
- Running tests: `pytest` (all), `pytest tests/test_X.py` (specific)

## Do NOT
- Do not use global variables for state
- Do not import from tests/ in src/
- Do not use `print()` for logging (use `logger`)

Generando CLAUDE.md con Claude Code

# Prompt para generar CLAUDE.md:
> "Analiza este proyecto y genera un CLAUDE.md que incluya:
   1. Architecture overview (2-3 párrafos)
   2. Directory structure con propósito de cada carpeta
   3. Naming conventions que el proyecto usa
   4. Key patterns (service layer, repository, etc.)
   5. Common tasks (cómo agregar endpoint, model, test)
   6. Do NOT list (qué NO hacer en este proyecto)"

Iterando el CLAUDE.md

# Después de trabajar con el proyecto por un rato:
> "Basándote en nuestra conversación y los problemas
   que encontramos, actualiza CLAUDE.md con:
   - La convención de error handling que acordamos
   - El patrón de naming para tests
   - La estructura de migrations"

CLAUDE.md Avanzado

Secciones para proyectos grandes

## Module Map
| Module | Owner | Purpose | Dependencies |
|--------|-------|---------|-------------|
| auth | Team A | Authentication + authorization | users, sessions |
| orders | Team B | Order lifecycle | products, payments, users |
| payments | Team C | Payment processing | stripe, orders |

## API Conventions
- All endpoints return `{"data": ..., "meta": {...}}`
- Pagination: `?page=1&per_page=20`
- Auth: Bearer token in Authorization header
- Errors: `{"error": {"code": "...", "message": "..."}}`

## Database
- PostgreSQL 15
- Migrations: Alembic in `migrations/`
- Naming: tables plural (`users`), models singular (`User`)
- Always use `created_at` and `updated_at` timestamps

## Environment
- Python 3.11+
- Poetry for dependencies
- Docker for local development
- CI: GitHub Actions

CLAUDE.md para refactoring (específico de esta guía)

## Refactoring in Progress
Currently refactoring the order module:
- Phase 1: Extract OrderValidator from OrderService (DONE)
- Phase 2: Move pricing logic to PricingEngine (IN PROGRESS)
- Phase 3: Standardize error handling (PENDING)

## Tech Debt
- user_service.py has circular import with auth_service.py
- 3 functions in utils/helpers.py are never called (dead code)
- payment_processor.py uses deprecated stripe.Charge API

## Test Coverage
- Overall: 72%
- services/: 85%
- api/routes/: 60% (needs improvement)
- models/: 90%

Múltiples Archivos de Context

Estructura jerárquica

.claude/
  CLAUDE.md              → Context global del proyecto
project-root/
  CLAUDE.md              → Override/additions para el proyecto
  src/
    payments/
      CLAUDE.md          → Context específico del módulo de pagos

Claude Code lee los CLAUDE.md en cascada: global → proyecto → módulo. El más específico tiene prioridad.

Manteniendo CLAUDE.md Actualizado

Cuándo actualizar

• Después de un refactoring significativo
• Cuando agregas un nuevo patrón o convención
• Cuando un nuevo miembro se une al equipo y pregunta algo que debería estar documentado
• Cuando detectas que Claude Code repite un error que CLAUDE.md debería prevenir

Prompt para actualización

> "Basándote en los cambios que hicimos hoy (extraer
   PricingEngine, cambiar error handling pattern),
   actualiza CLAUDE.md para reflejar el nuevo estado
   del proyecto."

Conexión con Proyecto

En el Proyecto del Módulo (cápsula 05), crear un CLAUDE.md es uno de los entregables principales. Es el artefacto que permite trabajar con el proyecto 100K+ de forma efectiva.

Troubleshooting

Problema 1: CLAUDE.md es demasiado largo

Solución: Máximo 200 líneas. Si necesitas más, usa CLAUDE.md jerárquicos por módulo.

Problema 2: CLAUDE.md está desactualizado

Solución: Agrégalo a tu workflow: después de cada refactoring significativo, actualiza CLAUDE.md.

Problema 3: Claude Code no parece leer CLAUDE.md

Solución: Verifica que está en la ubicación correcta (raíz del proyecto o .claude/). Verifica que Claude Code se ejecuta desde ese directorio.

Ejercicios

Ejercicio 1: Escribir CLAUDE.md básico (Fácil)

Escribe un CLAUDE.md de 50 líneas para un proyecto FastAPI con 3 módulos: users, products, orders.

# Project: E-Commerce API

## Architecture
FastAPI REST API with service layer pattern. Routes handle HTTP,
services handle business logic, repositories handle database.

## Structure
src/
  api/routes/    → FastAPI endpoints
  services/      → Business logic
  models/        → SQLAlchemy models
  repositories/  → Database queries
tests/           → pytest (mirrors src/)

## Conventions
- snake_case functions, PascalCase classes
- Services raise custom exceptions, routes catch and return HTTP errors
- All models have created_at, updated_at fields
- Tests use factory_boy for test data

## Key Patterns
- Service Layer: routes → services → repositories
- Dependency Injection: FastAPI Depends()
- Response Models: Pydantic for all API responses

## Common Commands
- Run: uvicorn src.main:app --reload
- Test: pytest
- Migrate: alembic upgrade head

## Do NOT
- Do not put business logic in routes
- Do not import models directly in routes (use services)
- Do not use print() (use structlog)

Ejercicio 2: Generar CLAUDE.md con Claude Code (Medio)

Escribe el prompt completo para que Claude Code analice un proyecto y genere CLAUDE.md.

> "Analiza la estructura completa de este proyecto y
   genera un archivo CLAUDE.md que incluya:
   
   1. Architecture (2-3 párrafos: qué es, qué patterns usa,
      cómo fluyen los datos)
   2. Directory structure (tree con propósito de cada carpeta)
   3. Naming conventions (que observas en el código actual)
   4. Key abstractions (clases base, interfaces compartidas)
   5. Common patterns (cómo se crean endpoints, models, tests)
   6. Database info (qué DB, ORM, naming de tablas)
   7. Testing (framework, patterns, cómo correr)
   8. Do NOT list (anti-patterns que el proyecto evita)
   
   Basa TODO en lo que observas en el código real,
   no en suposiciones. Si no estás seguro de algo,
   no lo incluyas."

Resumen

• CLAUDE.md es contexto del proyecto que Claude Code lee automáticamente
• Invierte 30 minutos y cada sesión futura es significativamente más productiva
• Incluye: architecture, conventions, patterns, common tasks, do-not list
• No incluye: código, documentación para humanos, configuración
• Máximo 200 líneas — conciso es mejor que exhaustivo
• Actualiza después de cada refactoring significativo
• Jerárquico: global → proyecto → módulo para proyectos grandes

Próxima cápsula: Proyecto — Strategy de Context para Proyecto 100K+.

Recursos Adicionales

1. Claude Code - CLAUDE.md - Documentación oficial
2. ADR - Architecture Decision Records - Complemento de CLAUDE.md para decisiones
3. README Best Practices - Para comparar README vs CLAUDE.md
4. Project Documentation - Write the Docs community