El Sistema CLAUDE.md

Esto suena aburrido pero es la parte mas importante de usar Claude Code. Es la diferencia entre realmente shipear tu app vs frustrarte y abandonar.

El Problema

Tenes tu app creada. Perfecta, no? NO.

Aca viene el problema que nadie te cuenta: La proxima vez que arranques Claude, va a olvidar todo. Tu arquitectura, tus decisiones, tus convenciones. Vas a empezar de cero.

La Solucion: CLAUDE.md

El sistema CLAUDE.md permite que Claude mantenga memoria entre sesiones:

Decisiones arquitecturales
Convenciones de codigo
Patrones que debe respetar

Sin esto, Claude "olvida" todo cada vez que empezas un chat nuevo.

Inicializar CLAUDE.md

Cuando Claude termine de crear tu app (o cuando abras un proyecto existente), escribi:

/init

Este comando hace que Claude:

Revise todo el proyecto
Analice la estructura
Cree un archivo CLAUDE.md

Estructura de un CLAUDE.md

Un archivo bien configurado se ve asi:

# CLAUDE.md
 
This file provides guidance to Claude Code when working with this repository.
 
## Architecture
 
This is a full-stack personal finance tracker with a React frontend and Node.js/Express backend:
 
- **Frontend**: React 18 with Vite, single-page application
- **Backend**: Express.js REST API with SQLite database
- **Database**: SQLite3 with three main tables
- **Communication**: Frontend calls backend API at `http://localhost:3001/api/`
 
## Key Patterns
 
- Always use error boundaries around components that make API calls
- Use Zod for input validation on all endpoints
- Follow the existing naming conventions for files
 
## Database Schema
 
- `categories`: id, name, color, icon
- `transactions`: id, type, amount, description, category_id, date
- `savings_goals`: id, title, target_amount, current_amount

Actualizar CLAUDE.md en Tiempo Real

Mientras chateas con Claude, podes agregar reglas usando el comando #:

# Always use error boundaries around components that make API calls

Esto agrega la regla directamente al archivo CLAUDE.md.

Te recomiendo tener el habito de hacer esto mientras trabajas y notas patrones que queres que Claude haga o deje de hacer.

Jerarquia de Archivos CLAUDE.md

Claude Code soporta multiples archivos CLAUDE.md en diferentes niveles:

~/.claude/CLAUDE.md                    # Global user preferences
~/dev/                                 # Parent directory
├── CLAUDE.md                          # Organization/team standards
└── finance-tracker-pro/
    ├── CLAUDE.md                      # Project-specific knowledge
    ├── backend/
    │   └── CLAUDE.md                  # Backend-specific patterns
    ├── frontend/
    │   └── CLAUDE.md                  # Frontend-specific patterns
    └── docs/
        └── CLAUDE.md                  # Documentation guidelines

Como Claude Procesa la Jerarquia

Claude lee todos los archivos CLAUDE.md que apliquen
Archivos mas especificos sobreescriben a los generales
Todo el contexto relevante se combina automaticamente
Claude prioriza la guia mas especifica para cada situacion

Documentacion Adicional

Ademas de los archivos CLAUDE.md, agrega una carpeta docs con:

PRD inicial
Arquitectura
Principios de diseno
Esquemas de base de datos

En tu CLAUDE.md, referencia esta documentacion:

# Finance Tracker Pro - Main Documentation
 
@docs/architecture.md
@docs/design-standards.md
@docs/database-schema.md
@docs/testing-strategy.md
 
## Project Overview
 
[Your main project description]

Esto separa lo que va en el prompt (los CLAUDE.md) de lo que se mantiene afuera hasta que sea referenciado.

Colaborar y Control de Versiones

Los archivos CLAUDE.md deben ser tratados como infraestructura critica:

Agregalos a tu repositorio
Incluilos en tu proceso de code review
Usa mensajes de commit convencionales
Taggealos como cambios mayores

Evolucion del CLAUDE.md en el Tiempo

Tu CLAUDE.md no deberia ser estatico. Asi es como deberia crecer:

Semana 1: Lo Basico

# Mi Proyecto
 
## Tech Stack
- React 18 + TypeScript
- Node.js + Express
- PostgreSQL
 
## Comandos
- `pnpm dev` - desarrollo
- `pnpm test` - tests

Mes 1: Patrones Emergentes

# Mi Proyecto
 
## Tech Stack
[...]
 
## Patrones de Codigo
- Usar Zod para validacion de inputs
- Error boundaries en componentes con API calls
- Nombres: camelCase para variables, PascalCase para componentes
 
## Decisiones Arquitecturales
- 2024-01-15: Elegimos tRPC sobre REST por type-safety
- 2024-01-20: Migramos de SQLite a PostgreSQL por concurrencia

Mes 3: Documento Maduro

# Mi Proyecto
 
## Tech Stack
[...]
 
## Patrones de Codigo
[Patrones refinados con ejemplos]
 
## Decisiones Arquitecturales
[Log de decisiones importantes]
 
## Lo Que NO Hacer
- NUNCA usar `any` en TypeScript
- NUNCA hacer queries SQL raw (usar ORM)
- NUNCA commitear secrets
 
## Onboarding
1. Clonar repo
2. Copiar .env.example a .env
3. Correr `pnpm install && pnpm dev`
4. Leer docs/architecture.md
 
## Performance Guidelines
- Lazy load componentes >50kb
- Usar React.memo para listas grandes
- Cachear queries que no cambian

Señales de CLAUDE.md Saludable

Señal	Que Significa
Tiene fechas	Las decisiones tienen contexto temporal
Tiene "NO hacer"	Aprendiste de errores
Se actualiza mensualmente	Esta vivo, no abandonado
Juniors lo entienden	Es util para onboarding

Para Equipos: CLAUDE.md Organizacional

Si trabajas en equipo, necesitas una jerarquia clara:

Estructura Recomendada

~/.claude/CLAUDE.md              # Preferencias personales (no compartidas)
~/company/CLAUDE.md              # Standards de la empresa (compartido)
~/company/proyecto/CLAUDE.md     # Reglas del proyecto (compartido)

Template Organizacional

# [Empresa] - Standards de Desarrollo
 
## Principios
- Ship > Perfect
- Tests para codigo critico
- Documentar decisiones, no codigo
 
## Stack Aprobado
- Frontend: React 18, Next.js 14+
- Backend: Node.js 20+, tRPC
- DB: PostgreSQL (produccion), SQLite (dev)
- Hosting: Vercel (frontend), Railway (backend)
 
## Convenciones
- Commits: Conventional Commits (feat, fix, docs, etc)
- Branches: feature/*, fix/*, hotfix/*
- PRs: Requieren 1 approval minimo
 
## Seguridad
- Secrets en variables de entorno, NUNCA en codigo
- Usar tokens con minimo privilegio
- Rotar API keys cada 90 dias
 
## Lo Que Claude NO Debe Hacer
- Modificar archivos en /config/production/
- Ejecutar comandos de deploy
- Acceder a secrets de produccion

Governance: Quien Actualiza Que

Archivo	Quien Aprueba	Frecuencia
Org CLAUDE.md	Tech Lead/CTO	Trimestral
Proyecto CLAUDE.md	Team Lead	Mensual
Personal CLAUDE.md	Individual	Libre

Resolviendo Conflictos

Si el CLAUDE.md del proyecto contradice el organizacional:

El mas especifico gana (proyecto > org)
Documenta la excepcion en el PR
Revisa periodicamente si la excepcion sigue siendo necesaria

Estrategias Avanzadas

1. Decile a Claude que lo Haga por Vos

Simplemente decile a Claude que actualice la documentacion cuando hayas terminado una funcionalidad grande. Tiene todo el contexto del trabajo que acaba de terminar.

2. Estandares de Calidad

Agrega estandares de calidad directamente en tus archivos:

## Code Quality Standards
 
- All functions must have JSDoc comments
- No any types in TypeScript
- Minimum 80% test coverage for new features

3. Onboarding de Nuevos Miembros

Nuevos desarrolladores pueden empezar super rapido:

Explica la arquitectura de este proyecto y como empiezo a contribuir

Claude lee el CLAUDE.md y da un overview completo.

Errores Comunes

Error 1: CLAUDE.md Desactualizado

El error: Agregue features pero no actualice CLAUDE.md con las nuevas decisiones.

El costo: Claude "olvido" decisiones arquitecturales y recreo codigo viejo. Tuve que refactorear dos veces.

La leccion: Actualizar CLAUDE.md es parte del workflow de desarrollo, no es opcional.

Error 2: CLAUDE.md Demasiado Largo

El error: Mi CLAUDE.md tenia 500 lineas. Claude lo procesaba pero ignoraba partes importantes.

El costo: Inconsistencias porque Claude no podia absorber todo.

La leccion: Mantene el CLAUDE.md principal en menos de 150 lineas. Usa @docs/ para detalles.

Error 3: Sin "NO Hacer"

El error: Solo documente lo que queria, no lo que NO queria.

El costo: Claude genero codigo que rompia mis patrones porque no sabia que evitar.

La leccion: La seccion "Lo Que NO Hacer" es tan importante como "Lo Que Hacer".

Desafio: Crea Tu CLAUDE.md

Antes de continuar, crea un CLAUDE.md para tu proyecto actual:

Corre /init en tu proyecto
Revisa lo que Claude genero - es un punto de partida
Agrega una seccion "Lo Que NO Hacer" con 3 reglas minimo
Agrega una fecha a al menos una decision arquitectural
Commitea el archivo - es codigo, no documentacion opcional

Tiempo estimado: 15 minutos

Checklist de CLAUDE.md Saludable

Tiene tech stack documentado
Tiene comandos principales (dev, test, build)
Tiene al menos 3 "NO hacer"
Tiene al menos 1 decision con fecha
Es menor a 150 lineas (core file)
Esta commiteado en git

Siguiente Paso

Ahora que tenes memoria persistente, vamos a aprender a manejar el contexto durante sesiones largas.

Developers