🏗️ Proyectos a largo plazo

La estructura de carpetas es el mapa físico de tu proyecto. Determina cómo se encuentran los módulos, cómo fluyen las dependencias y cómo los nuevos colaboradores (o Claude) entienden el sistema sin leer una línea de código.

Los proyectos sin estructura se convierten en monolitos caóticos en cuestión de semanas. Una carpeta bien pensada desde el inicio ahorra horas de refactorización después. Claude Code navega mejor por proyectos organizados: menos contexto, respuestas más precisas.

Principio de Responsabilidad Única aplicado a archivos y módulos: cada pieza del código tiene una razón para existir y una razón para cambiar.

Los módulos coherentes ayudan a Claude a entender, modificar y probar partes aisladas sin introducir regresiones. Menos acoplamiento = iteración más rápida.

Elegir el lenguaje, el runtime, los frameworks y las herramientas de build según criterios explícitos: ecosistema, rendimiento, facilidad de deploy y compatibilidad con Claude.

Cambiar de stack a mitad de un proyecto es costoso. Elegir bien al principio reduce la deuda técnica y maximiza la ayuda que Claude puede ofrecerte: conoce mejor los stacks populares.

Los Architecture Decision Records (ADRs) son documentos breves que registran el contexto de una decisión, las opciones consideradas y la elección tomada. El CLAUDE.md es el ADR principal.

Sin documentación de las decisiones, Claude (y tú en el futuro) se preguntarán por qué se tomaron ciertas decisiones y podrían deshacerlas inadvertidamente.

Estrategia de construir primero el núcleo funcional y agregar capas progresivamente — sin planificar una arquitectura enorme antes de validar las hipótesis.

Los proyectos con Claude evolucionan rápido. Empezar con algo pequeño permite validar el diseño antes de invertir energía en abstracciones que quizá no sean necesarias.

Principios que mantienen un proyecto saludable durante meses o años: revisión de código asíncrona, documentación viva, automatización de tareas repetitivas y métricas de salud.

La mayoría de los proyectos muere por falta de mantenimiento planificado, no por falta de funcionalidades. Con Claude, el riesgo es agregar código demasiado rápido sin mantener sólida la base.

El CLAUDE.md es el archivo de instrucciones persistentes del proyecto. Claude lo lee al inicio de cada sesión para obtener contexto sobre el proyecto, las convenciones y las reglas de comportamiento.

Sin CLAUDE.md, repites el mismo contexto en cada sesión. Con él, Claude sabe dónde está, qué puede y qué no puede hacer, y cómo está estructurado el proyecto.

Claude no tiene memoria nativa entre sesiones. La memoria persistente se construye explícitamente: archivos de estado, logs de decisiones, contexto guardado en JSON o Markdown.

Los proyectos largos acumulan decisiones y estado. Sin memoria explícita, cada sesión empieza desde cero y Claude puede contradecir decisiones anteriores.

Mantén el CLAUDE.md conciso y relevante: incluye solo lo que Claude necesita saber ahora, no toda la historia del proyecto.

Un CLAUDE.md muy largo diluye la atención. Claude prioriza la información al inicio del contexto; la información crítica debe aparecer primero.

Sección de CLAUDE.md que define los estándares de código, la nomenclatura, el flujo de git, las reglas para los PR y el tono de comunicación que Claude debe respetar.

Sin convenciones explícitas, Claude adopta sus propios estándares, que pueden diferir de los del equipo y crear inconsistencias difíciles de mantener.

Directrices sobre qué información debe estar en el CLAUDE.md (arquitectura, convenciones, contexto) y qué nunca debe aparecer (secrets, tokens, datos personales).

CLAUDE.md se lee y potencialmente se envía al modelo. La información sensible que contiene crea riesgos de filtración, especialmente en proyectos con varios colaboradores.

Cómo mantener CLAUDE.md actualizado a medida que crece el proyecto: cuándo revisarlo, quién puede editarlo y cómo versionar los cambios en el archivo de instrucciones.

Un CLAUDE.md desactualizado es peor que no tener ninguno: Claude sigue instrucciones obsoletas y puede tomar decisiones equivocadas basadas en un contexto incorrecto.

Semantic Versioning (semver): MAJOR.MINOR.PATCH — cada número tiene un significado preciso sobre el tipo de cambio y la compatibilidad.

Las versiones semánticas comunican el impacto. Cuando le pides a Claude que "actualice una versión", necesita saber qué dígito incrementar y por qué.

Archivo CHANGELOG.md estructurado por versión, con secciones Added / Changed / Fixed / Removed. Lo leen las personas, no las máquinas.

El CHANGELOG es el diario del proyecto. Permite auditar cuándo algo dejó de funcionar, justificar cambios ante stakeholders y guiar a Claude en sesiones de mantenimiento.

Estrategias para revertir el estado del proyecto de forma segura: git revert, git reset, feature flags, deploy de una versión anterior.

Con Claude generando código rápidamente, la capacidad de hacer rollback es la red de seguridad. Necesitas saber cómo deshacer cambios sin perder trabajo válido.

Proceso para mejorar la estructura interna del código sin alterar su comportamiento externo, con pruebas como red de seguridad.

Refactorizar con Claude es rápido y arriesgado. Sin pruebas, una refactorización que parece segura puede romper flujos que no estaban visibles en la sesión.

Las pruebas bien escritas documentan el comportamiento esperado del sistema. Son la especificación más confiable porque deben pasar, a diferencia de la documentación, que queda obsoleta.

Claude usa las pruebas existentes para entender qué debe hacer un módulo antes de modificarlo. Los proyectos con buenas pruebas reciben una ayuda mejor y más segura.

La deuda técnica es el costo futuro de los atajos que tomas hoy. No siempre es mala, pero hay que registrarla, priorizarla y pagarla antes de que sea impagable.

Los proyectos con Claude pueden acumular deuda técnica rápidamente: el código generado con rapidez no siempre es sostenible. Monitorear y saldar la deuda periódicamente es un hábito de proyecto saludable.

ClaudeOS (Hermes) es un dashboard personal de solo lectura para quienes ejecutan un stack de IA local. Consolida datos de Claude Code, Codex, OpenRouter, Pinecone y Obsidian en una sola interfaz.

Es un proyecto concreto que aplica todos los principios de esta ruta: arquitectura por capas, CLAUDE.md riguroso, control de versiones con CHANGELOG y separación de responsabilidades.

El archivo scripts/aggregate.ts es el corazón del sistema: lee ~/.claude/, vaults de Obsidian, Pinecone y OpenRouter, y luego genera src/data/live-data.json, que consume el dashboard de React.

Este patrón «script generador → archivo estático → UI» es una arquitectura elegante que separa la recopilación de datos de la presentación. Se puede replicar en cualquier proyecto de dashboard.

La skill /dream audita las últimas 24h del stack de IA en 8 categorías de señales y escribe en JSON las 4 recomendaciones de mayor impacto. El dashboard muestra esas recomendaciones como tarjetas de acción.

Es un ejemplo de skill con output estructurado (JSON) consumido por una UI: un patrón reutilizable para cualquier integración de Claude Code + dashboard.

El CLAUDE.md de ClaudeOS define: saludo de onboarding, reglas críticas (nunca leer/escribir ~/.claude directamente, datos locales, anonimización activada, sin telemetría, dashboard de solo lectura).

Este CLAUDE.md es un ejemplo de nivel de producción. Muestra cómo usar restricciones explícitas para proteger los datos del usuario y mantener al agente en su función.

El CHANGELOG de ClaudeOS narra la evolución del proyecto: V2.3 (Documents Gallery, 31 mai 2026) muestra cómo se agregó cada feature, qué cambió y qué se corrigió.

El CHANGELOG es evidencia de un proyecto maduro. Cada versión cuenta la historia del mantenimiento — y sirve como contexto para Claude al planificar próximas features.

Extracción de patrones replicables de ClaudeOS: la separación scripts/src, el CLAUDE.md con restricciones, el JSON como artefacto de estado y el CHANGELOG como narrativa.

Estudiar proyectos reales bien estructurados acelera mucho más que los tutoriales abstractos. ClaudeOS es una plantilla mental para cualquier proyecto de larga duración con Claude Code.