Protocolo de Proyecto
Cómo Revisar tu CLAUDE.md
Guía práctica para crear y mantener reglas de proyecto que escalen con Claude. Basado en 2 años de experimentación con documentación viva.
Cubre: reglas de código · protocolos de sesión · divisiones de responsabilidad · arquitectura
Template + checklist + ejemplos reales de 3 proyectos
¿Por qué CLAUDE.md?
CLAUDE.md es un archivo que vive en tu repo y contiene las reglas de proyecto. Claude lo lee automáticamente en cada sesión. Es el puente entre tu intención como desarrollador y las decisiones que toma la IA.
Sin CLAUDE.md
Cada sesión, el modelo adivina patrones desde cero.
Con CLAUDE.md
Cada sesión, el modelo aplica las reglas que definiste.
Las 6 Secciones Clave
Protocolo de Sesión
Qué debe leer Claude al inicio. Orden de prioridad: wiki → logs → cambios recientes.
- •Al iniciar: leer wiki/index.md + log más reciente
- •Si hay archivos nuevos en raw/: revisar antes de procesar
- •Nunca editar wiki/ durante trabajo normal
- •Al cerrar: documentar decisiones en wiki/logs/
Reglas de Código
Cambios quirúrgicos, fallar ruidoso, respetar patrones existentes.
- •Leer antes de escribir: exports, callers, utilidades compartidas
- •Cambios quirúrgicos: solo lo que la tarea pide
- •Falla ruidoso: si algo se saltó en silencio, súbelo al output
- •Conflictos: elige un patrón, explica por qué, marca el otro para limpieza
Seguridad Supply-Chain
Chequeos automáticos contra RATs, paquetes npm comprometidos, inyectores.
- •Run cada sesión: python3 scripts/sec-check.py . (silencioso si limpio)
- •Si imprime [!]: NO buildees, investiga primero
- •Antes de npm nuevo: revisa con pin-guard o IOC
- •Extender indicadores: edita sec-check.py (única fuente)
Decisiones Arquitectónicas
Dónde vive cada decisión y cómo documentarla para futuras sesiones.
- •Decisiones técnicas → wiki/decisions.md
- •Por qué las cosas son como son → explicación breve + link a PR/issue
- •Patrones contradictorios → marca para limpieza, no mezcles
- •Historial de planes → docs/planes/YYYY-MM-DD-tema.md
División: Wiki vs Auto-Memory
Qué va donde. Wiki = conocimiento del proyecto. Auto-memory = preferencias.
- •wiki/ = dominio específico del proyecto, reutilizable en futuras sesiones
- •Auto-memory = preferencias personales, convenciones del usuario
- •No duplicar: si está en wiki/, no repitas en auto-memory
- •Revisión periódica: wiki/logs/ es el índice de cambios
Archivos Clave del Proyecto
Qué documenta cada archivo crítico. Única fuente de verdad por tema.
- •CLAUDE.md → reglas globales (leído automáticamente por IA)
- •wiki/index.md → mapa del proyecto (leer PRIMERO)
- •wiki/architecture.md → decisiones técnicas
- •segundo-cerebro/ → brand voice, ofertas, contexto personal
- •docs/planes/ → historial de decisiones + iteraciones
Estructura Mínima de CLAUDE.md
# [Nombre del Proyecto] ## Protocolo de Sesión 1. **Al iniciar:** leer wiki/index.md 2. **Cambios estructurales:** documentar en wiki/logs/ 3. Nunca editar wiki/ en trabajo normal ## Reglas de Código 1. Leer antes de escribir (exports, callers) 2. Cambios quirúrgicos (solo lo que la tarea pide) 3. Falla ruidoso (si algo se saltó, súbelo) ## Archivos Clave - CLAUDE.md — reglas globales - wiki/index.md — mapa del proyecto - wiki/architecture.md — decisiones técnicas
Mínimo viable: 3 secciones. Expande según necesidad.
Checklist: Revisar tu CLAUDE.md
¿Listo para crear tu CLAUDE.md?
Template + checklist + ejemplos reales de 3 proyectos