Pero después de un mes de uso real me topé con varios problemas sustanciales que ese post no cubría. El más grande — una peculiaridad oculta de Claude Code con la que me crucé por accidente, cuando añadí el MCP de Gmail y "desapareció" de mi perfil cinco minutos después. Hoy rehíce todo sobre una arquitectura nueva — compatible con XDG, con un symlink y un selector interactivo de perfil mediante gum. Esto es v2 — una evolución a partir de la experiencia real, no una mejora teórica.

Lo que empezó a molestar

Cuatro cosas. Las primeras tres son sobre orden, visibilidad y escala. La cuarta es el verdadero gotcha arquitectónico que no vi de inmediato. Las repaso en orden, porque fue justamente la cuarta la que al final forzó la reescritura.

1. Dos carpetas separadas en $HOME — es un desastre

~/.claude y ~/.claude-promova — dos dotfolders uno al lado del otro en la raíz de $HOME. La XDG Base Directory Specification dice que las configs deben vivir en ~/.config/. Las carpetas dotfile dispersas directamente en home son un antipatrón que con el tiempo convierte $HOME en un cajón de sastre. Cosmético, sí, pero me molestaba cada vez que veía ls -la ~.

2. Sin confirmación visual del perfil activo

Lanzo claude y no sé qué perfil está activo — hasta que ejecuto claude config list ya dentro de la sesión. Si olvidé qué terminal arranqué dónde, tengo que verificar. Una nimiedad, pero con personal + work corriendo en paralelo en dos pestañas se acumula.

3. Los alias no escalan

Dos perfiles — claude y claude-promova — está bien. Añades un tercero (un cliente freelance) — necesitas un tercer alias. Un cuarto — un cuarto. En medio año ya no recordaría qué alias tengo creados.

4. La trampa oculta en ~/.claude.json

Y esto es la verdadera razón de la reescritura. Claude Code tiene dos lugares distintos de configuración, y la documentación no lo grita: ~/.claude/ — el directorio donde están projects/, sessions/, hooks/, skills/. Y por separado — ~/.claude.json, un archivo justo en la raíz de $HOME, donde viven oauthAccount, mcpServers, el historial de projects, skillUsage y cerca de 40 campos más de auténtico live state.

El comando claude mcp add --scope user escribe precisamente en ese ~/.claude.json del home root, y no en ~/.claude/.claude.json ni en el directorio del perfil. No lo sabía. Hasta que un día me topé con ello.

Discovery: por qué el MCP de Gmail "desapareció"

Esta mañana estaba montando el MCP de Gmail en Claude Code. Setup habitual: proyecto en Google Cloud, credenciales OAuth, claude mcp add gmail --scope user -- npx -y @gongrzhe/server-gmail-autoauth-mcp. Todo ok. Reinicié la sesión — funciona, leo el correo, contesto mensajes. Una hora después empezamos a refactorizar los alias en una función con selector de perfil por gum, y luego migramos todo a XDG. Hice mv ~/.claude → ~/.config/claude-profiles/personal, reinicié CC, elegí personal en el menú. Y en la nueva sesión abrí /mcp:

figma            (failed)
playwright-test
claude.ai Notion

No estaba gmail. No estaba vaultforge. Solo tres servidores, uno de los cuales además había failed. Y yo acababa de añadir Gmail. Mientras tanto, la sesión en otra terminal (perfil de trabajo) mostraba Gmail y Vaultforge sin ningún problema.

Empecé a escarbar y encontré que en mi máquina tenía tres archivos distintos con el nombre .claude.json:

Ahí estaba. Ese es el gotcha arquitectónico:

1. claude mcp add --scope user siempre escribe en ~/.claude.json en el home root, independientemente de CLAUDE_CONFIG_DIR
2. Cuando CLAUDE_CONFIG_DIR está definido, Claude Code lee $CLAUDE_CONFIG_DIR/.claude.json — es decir, el archivo dentro del perfil
3. Los registros de "user-scope MCPs" y de "MCPs del perfil" viven en archivos distintos con el mismo nombre — y es fácil confundirlos

En mi caso ~/.claude.json (home root, 113 KB) era el state vivo y actual — con gmail, vaultforge, sesión OAuth, todo. Y ~/.config/claude-profiles/personal/.claude.json (29 KB) resultó ser un snapshot viejo que por alguna razón ya estaba antes en el viejo ~/.claude/ — quizás una versión anterior de CC escribía ahí, quizás un plugin. jq -r 'keys[]' sobre ambos archivos mostró que la versión del home-root tenía 41 claves únicas que no estaban en el snapshot.

Y esas 41 claves no son basura. Es el state real de Claude Code:

• skillUsage — estadísticas de uso de skills
• githubRepoPaths — caché de repos para la navegación por proyectos
• cachedGrowthBookFeatures + cachedStatsigGates — feature flags (sin ellas CC va por nuevas cada arranque)
• hasShownOpus45Notice, hasShownOpus46Notice, hasShownS1MWelcomeV2 — flags de UI (sin ellas los modales vuelven a aparecer en el próximo arranque)
• lastPlanModeUse, feedbackSurveyState, installMethod — state de onboarding y UX

Si simplemente haces mv ~/.claude ~/.config/claude-profiles/personal sin merge — pierdes todo eso. Vuelves a ver los modales de welcome, se vuelve a ejecutar la búsqueda de githubRepoPaths, recibes de nuevo todas las peticiones de survey. Como casi hice yo.

La nueva arquitectura

Todo vive bajo un único directorio padre en ~/.config/, como quiere XDG. Cada perfil es autosuficiente — tiene su state completo, incluido su propio .claude.json. ~/.claude queda como symlink al perfil personal para compatibilidad hacia atrás.

~/.config/claude-profiles/
├── personal/
│   ├── .claude.json          ← full live state + MCP list (113 KB)
│   ├── projects/, sessions/, hooks/, skills/, ...
│   └── CLAUDE.md
└── promova/
    ├── .claude.json          ← work state + work MCPs (41 KB)
    └── projects/, sessions/, agents/, skills/, ...

~/.claude  →  symlink to ~/.config/claude-profiles/personal/

Ningún .claude.json en la raíz de $HOME. Cada perfil es un directorio separado y aislado donde está todo: las carpetas projects/sessions y ese mismo archivo con los servidores MCP y los tokens OAuth. Una source of truth por perfil.

Por qué el symlink apunta a personal

Todo lo que tiene el path ~/.claude/ hardcoded — scripts viejos, plugins, extensiones de IDE de Claude Code, configs de statusline como claude-powerline.json — sigue funcionando sin cambios. El symlink se resuelve al perfil personal. Si por accidente lanzas command claude (sin la función wrapper) — también caes en personal por el lookup del default-path. Personal se convierte en el "quiet default" que era antes, pero ahora vive físicamente en la ubicación XDG.

Selector interactivo al lanzar — función + gum

En lugar de alias — una función claude() en ~/.zshrc que muestra un menú con flechas mediante gum (el TUI-helper de Charm). La función intercepta la llamada a claude a nivel de shell, deja elegir el perfil y ejecuta command claude con el CLAUDE_CONFIG_DIR correspondiente. command es importante — esquiva la función wrapper e invoca el binario real.

# brew install gum

# Claude Code: profile picker on launch
claude() {
  local profile
  profile=$(gum choose \
    --header "Claude profile:" \
    --cursor "▸ " \
    --selected.foreground 212 \
    --cursor.foreground 212 \
    --header.foreground 244 \
    "personal" "promova") || return
  case "$profile" in
    personal) CLAUDE_CONFIG_DIR="$HOME/.config/claude-profiles/personal" command claude "$@" ;;
    promova)  CLAUDE_CONFIG_DIR="$HOME/.config/claude-profiles/promova"  command claude "$@" ;;
  esac
}

Esto es lo que se ve al arrancar:

Claude profile:
▸ personal
  promova

↑↓ para navegar, Enter para elegir, Esc para cancelar (Claude simplemente no arranca). El perfil siempre está a la vista — imposible olvidarlo.

Script de migración

Para quien lea esto y quiera mudarse del esquema viejo. El paso más crítico es el segundo: fusiona ~/.claude.json del home root con lo que ya hay en el perfil personal, combinando las listas de mcpServers. Sin ese paso el perfil pierde tanto los MCPs como todo el live state.

# 1. Move existing dotfolders into a new XDG-style parent.
#    APFS mv is an inode rename — safe even if claude --resume is open in
#    another terminal, file descriptors stay alive on the same inode.
mkdir -p ~/.config/claude-profiles
mv ~/.claude          ~/.config/claude-profiles/personal
mv ~/.claude-promova  ~/.config/claude-profiles/promova   # rename as needed

# 2. CRITICAL: merge ~/.claude.json (the live state — likely 100+ KB) into
#    the personal profile, unioning mcpServers so no MCP is dropped.
jq -s '.[0] * {mcpServers: (.[0].mcpServers + .[1].mcpServers)}' \
  ~/.claude.json \
  ~/.config/claude-profiles/personal/.claude.json \
  > /tmp/personal-merged.json
mv /tmp/personal-merged.json ~/.config/claude-profiles/personal/.claude.json

# 3. Fix permissions — jq+mv inherits umask (likely 644), but this file
#    holds OAuth tokens. Tighten to 600 immediately.
chmod 600 ~/.config/claude-profiles/personal/.claude.json

# 4. Back up the orphaned home-root file (delete once verified)
mv ~/.claude.json ~/.claude.json.migrated.bak

# 5. Symlink for backward compatibility (statusline configs, IDE plugins,
#    anything that hardcodes ~/.claude/ keeps working unchanged)
ln -s ~/.config/claude-profiles/personal ~/.claude

El tercer paso, sobre permisos, merece atención propia. jq | mv crea un archivo con umask 644 (legible por todos). Dentro hay tokens OAuth. chmod 600 inmediatamente después del merge es obligatorio.

Tras la migración — cierra y abre todas las sesiones activas de Claude, recarga el shell (source ~/.zshrc o terminal nueva), ejecuta claude, elige perfil, comprueba con claude mcp list que todos los MCPs están en su sitio. Si todo está bien — borra ~/.claude.json.migrated.bak. Si algo va mal — el rollback es trivial: mv ~/.claude.json.migrated.bak ~/.claude.json y quitar el symlink.

Lo que ganas

• Un único directorio padre en lugar de dos dotfolders en $HOME — compatible con XDG
• El symlink preserva la compatibilidad con todo lo que tiene ~/.claude/ hardcoded
• Cada perfil es autosuficiente — su state completo y sus MCPs viven en su propio .claude.json
• Una source of truth por perfil — ya no hay config huérfana en el home root divergiendo silenciosamente del perfil
• Los datos sensibles (oauthAccount, tokens) tienen permisos 600 garantizados
• Confirmación visual del perfil activo en cada arranque — imposible olvidar qué perfil está activo
• Añadir un tercer perfil = añadir una línea al case de la función, no clonar un alias nuevo y memorizar su nombre

Dónde flojea

Quiero ser honesto. Esto no es una mejora gratuita — vienen algunos compromisos en el paquete, y conviene conocerlos por adelantado.

• gum es una dependencia extra (brew install gum, ~13 MB). Si por principio no quieres instalarlo — fallback a select en zsh o un read simple. Funciona, pero no se ve tan bonito y no tiene navegación por flechas.
• Un Enter en cada arranque. Para quien lanza claude decenas de veces al día — puede molestar. Alternativa abajo (direnv).
• El symlink ~/.claude → personal hace personal el default. Si necesitas que el perfil de trabajo sea el default, hay que redirigir el symlink (ln -sf). No es difícil, pero no es "olvídate y nada se rompe".
• El symlink podría romperse en teoría si alguna herramienta reescribe ~/.claude.json atómicamente con un patrón temp+rename (write-file-atomic). En la práctica Claude Code en sí no lo hace, pero si instalas plugins de terceros — verifícalo.
• Si tienes cuentas de Anthropic distintas en los perfiles con planes distintos — tras cambiar puede haber un lag de menos de un segundo mientras Claude Code sincroniza el state de OAuth. En mi uso no se nota, pero no es cero.

Alternativas que consideré

direnv — define automáticamente CLAUDE_CONFIG_DIR según el .envrc en la raíz de cada proyecto. Cero interacción, cero clics. Contra: hay que colocar un .envrc en cada work-root, y si ejecutas claude en una carpeta no reconocida — obtienes el perfil por defecto (que puede no ser el que necesitas). Para quien vive en un conjunto acotado de work-roots y quiere no clicar nunca — direnv realmente es mejor.

Switching basado en symlink (un único perfil activo redirigiendo el symlink ~/.claude) también lo consideré y lo descarté de inmediato. No puedes tener dos terminales con perfiles distintos abiertas a la vez — el "actual" global es uno solo. Para mí es un deal-breaker.

Conclusión

v2 no es solo mejor UX encima de v1. Es el reconocimiento de que Claude Code tiene una peculiaridad arquitectónica oculta (~/.claude.json como archivo separado en el home root, escrito por comandos --scope user independientemente de CLAUDE_CONFIG_DIR) que hay que tener en cuenta si quieres aislamiento real entre perfiles. El primer enfoque (~/.claude + ~/.claude-promova + alias) funcionaba al 80%, pero el 20% restante se manifestaba como una deriva silenciosa de state entre perfiles. Ahora está contemplado. Si recién empiezas — arranca directamente con v2. Si ya estás en v1 — el script de migración está arriba, la mudanza lleva cinco minutos y no rompe nada (justamente el merge con jq es el paso que te salva de perder state).

Dos reglas han convertido mis flujos de trabajo llenos de alucinaciones en pipelines fiables: un agente, una especialización, y todo lo que pueda ejecutarse como comando de shell debe ejecutarse como comando de shell. Esto no es teoría. Es lo que hago cada día con Claude Code, y estos son los patrones que realmente marcan la diferencia.

Por qué los agentes generalistas mienten

Los LLM son predictores del siguiente token. Cuando un prompt pide dos roles — construye X y verifica X — el modelo termina el primer rol y luego predice cómo sería la salida del segundo, sin ejecutarlo realmente. La auto-verificación es estructuralmente débil: mismo contexto, mismo modelo, los mismos puntos ciegos. El pass en la verificación está correlacionado con el pass en la construcción — fallan juntos.

El modelo no sabe que está mintiendo. Desde su perspectiva, narrar verifiqué todo con cuidado es una continuación coherente de haber escrito el código. Es la misma razón por la que los prompts de ¿estás seguro? no atrapan alucinaciones: el modelo tiene la misma confianza en el segundo intento. La confianza no está correlacionada con la corrección — está correlacionada con lo plausible que suena la siguiente frase.

La solución no son mejores prompts. Ten cuidado, vuelve a revisar, no alucines — estas instrucciones no sirven para nada. La solución es estructural: especializa el agente para que físicamente no pueda fingir, y enruta el trabajo cuantitativo a través del shell para que la respuesta venga del estado real, no de la probabilidad de tokens.

Regla 1: un agente, una especialización

Divide el trabajo en agentes separados con contextos separados. Cada agente tiene una sola responsabilidad y un conjunto de herramientas acotado. Todo el flujo se convierte en una carrera de relevos en lugar de un único agente dando vueltas:

• Agente builder: recibe la spec y escribe el código. Ese es su único trabajo. Tiene Read, Edit, Write, Bash.
• Agente reviewer: recibe la spec más el diff y comprueba los criterios de aceptación. Contexto limpio. Sin conocimiento de cómo se escribió el código, solo de lo que salió. Tiene Bash, Read, Grep, Glob — sin herramientas de escritura.
• Agente de analytics: responde preguntas sobre datos construyendo y ejecutando queries. Solo Bash. No puede llegar a la respuesta sin ejecutar un comando real.
• Orchestrator: la sesión principal que despacha cada agente en turno y nunca le pide a uno que haga el trabajo del otro.

Ejemplo concreto: implementación de UI más una verificación visual contra un mockup de Figma. El builder escribe los componentes y hace commit del diff. Luego el orchestrator invoca al reviewer con la URL del diseño, el diff y criterios de aceptación explícitos. El reviewer ejecuta Playwright, toma screenshots, los difiere contra la referencia y devuelve PASS o FAIL con las rutas reales de los screenshots y los pixel diffs. El builder nunca se acerca al paso de verificación — y precisamente por eso la verificación es real.

El anti-patrón es el mega-agente: un único prompt que dice implementa esta UI y asegúrate de que coincide con el mockup. Te lo garantizo: reportará que todo coincide. No coincidirá. El relato de lo verifiqué es simplemente la secuencia de tokens más probable después de lo implementé.

Regla 2: shell antes que prompt, siempre

Todo lo cuantitativo, todo lo que toca estado real, todo donde la respuesta puede estar mal de una forma que parece correcta — pásalo por sh. El trabajo del agente es construir y ejecutar el comando, luego leer su salida. El agente no es la fuente de verdad. La salida del shell lo es.

• Contar: wc -l logs.txt es verdad. Hay aproximadamente 47 líneas de log de parte del modelo es una alucinación.
• Analytics: psql -c "SELECT count(*) FROM events WHERE created_at > now() - interval '30 days'". No estima el volumen.
• Tests: pnpm test --reporter=json | jq '.numFailedTests'. No resume qué falló.
• Estado de Git: git rev-list --count main..HEAD, git diff --stat. No cuenta los commits ni describe los cambios.

Una vez que interiorizas esto, empiezas a detectar cada momento en que el agente estaba a punto de inventarse un número. Parece que hay unos 200 registros... — no. Ejecuta SELECT count(*). La mayoría de los tests pasan... — no. Ejecuta el test suite, parsea el JSON. El modelo es excelente construyendo el comando. Es poco fiable siendo el comando.

Modos de fallo que he sufrido en persona

No son hipotéticos. Cada uno de estos me costó tiempo real antes de cambiar el patrón:

• Verificación fantasma. El agente dijo comprobé las 14 secciones contra el mockup. No abrió el mockup. No tomó ningún screenshot. La comprobación era un paso alucinado en el relato.
• Números incorrectos con total confianza. Pedí los monthly active users de los datos de analytics. Me dio un número equivocado por un factor de ~3×. El modelo interpoló a partir de filas de muestra en lugar de ejecutar la query real.
• Cambios de archivos inventados. El agente dijo actualicé config/feature-flags.json. No lo había hecho. Solo lo había pretendido. git diff estaba vacío.
• Ejecuciones de tests falsas. Todos los tests pasan. No se ejecutó ningún test. El agente nunca invocó el test runner — predijo cómo habría sido la salida del runner.

Los cuatro se resuelven con las mismas dos reglas: divide el agente, empuja al shell. El reviewer no tiene Write, así que no puede falsificar ediciones de archivos. El agente de analytics solo tiene Bash, así que no puede devolver un número que no venga de una query. La imposibilidad estructural gana a las buenas intenciones siempre.

Cómo estructurar esto en Claude Code

Claude Code admite sub-agents definidos en .claude/agents/*.md. Cada archivo de agente declara un nombre, una descripción, un conjunto de herramientas permitidas y un system prompt. El orchestrator (tu sesión principal) los despacha usando la herramienta Agent. Esta es la clase de definición que uso para el reviewer — corta, acotada y físicamente incapaz de escribir código:

---
name: reviewer
description: Reviews a diff against acceptance criteria. Cannot edit code.
tools: Bash, Read, Grep, Glob
---

You are a strict code reviewer. You receive:
- A diff (already produced by the builder)
- Acceptance criteria

Your job:
1. Run the build, the tests, the linter — through Bash.
2. Read the changed files directly.
3. Compare the actual behavior to the criteria.
4. Report PASS or FAIL with concrete evidence (command output, file excerpts).

You must NOT:
- Trust the builder's summary
- Assume anything was verified just because it was claimed
- Mark something PASS without running the actual check

Fíjate en el conjunto de herramientas: Bash, Read, Grep, Glob. Sin Write, sin Edit, sin Agent. El reviewer puede ejecutar comandos, leer archivos, buscar patrones — y nada más. Si intenta hacer pasar un diff alucinado por verificado, la forma de sus llamadas a herramientas lo deja en evidencia: no hubo comprobaciones reales. Puedes auditar las llamadas y ver exactamente qué se inspeccionó.

El patrón de orquestación: la sesión principal llama al Builder → espera → ejecuta git diff ella misma para capturar el cambio real → llama al Reviewer con la spec y el diff → lee el veredicto del Reviewer. La sesión principal nunca le pide a un agente que haga ambas cosas. Las restricciones de herramientas son más fuertes que las instrucciones en el prompt: no falsifiques la verificación es un deseo. No tener Write es un hecho.

Anti-patrones a desterrar

Cosas que veo en prompts y que no hacen nada — o peor, dan una falsa sensación de seguridad:

• Ten cuidado y revisa tu trabajo. No genera ningún comportamiento adicional. El modelo ya produce lo que parece trabajo cuidadoso.
• Asegúrate de verificar de verdad. La palabra de verdad no añade semántica sobre la que el modelo pueda actuar. Va a afirmar que verificó de verdad.
• No alucines. Un meme del prompt engineering. La alucinación no es un interruptor que el modelo pueda apagar.
• Fiarse del agente con números pequeños. Los números pequeños son donde miente con más confianza. No existe un umbral de honestidad.
• Añadir más reglas al prompt para forzar la honestidad. Las correcciones estructurales (dividir + shell) ganan a los ajustes de prompt siempre. Si una regla necesita aplicarse, codifícala en el acceso a herramientas, no en español.

Si tu estrategia para atrapar alucinaciones es redactar las instrucciones con más énfasis, no tienes una estrategia. Tienes una esperanza.

El modelo mental

Un agente no es un compañero. Es una función: prompt → tokens. La función es excelente escribiendo código y pésima introspectando si hizo lo correcto. Trata sus afirmaciones sobre su propio trabajo como una hipótesis. El diff, el exit code, el screenshot, el row count — esa es la evidencia. El resumen al final del turno es la superficie más propensa a mentir de todo el sistema.

La especialización es tu seguro contra la deriva narrativa. El shell es tu único ground truth. El builder escribe. El reviewer comprueba. Bash decide.

Conclusión

Si te quedas con una sola cosa: no dejes que un único agente produzca y juzgue su propia salida, y no dejes que ningún agente responda una pregunta cuantitativa sin ejecutar un comando. Todo lo demás se deriva de estas dos reglas. Configura el acceso a herramientas de forma agresiva, audita las llamadas a herramientas en lugar de los resúmenes, y la superficie de alucinación se reduce de todas partes a unos pocos lugares concretos que ya sabes dónde buscar.

El problema

Claude Code almacena todo en ~/.claude por defecto — token OAuth, historial de conversaciones, CLAUDE.md global, memoria de proyectos, configuraciones de servidores MCP y ajustes. Con dos cuentas, necesitas dos mundos completamente separados:

• Cuenta personal: tu suscripción Max/Pro, CLAUDE.md personal con tus preferencias, tus servidores MCP (Obsidian, herramientas personales)
• Cuenta corporativa: plan de la empresa, CLAUDE.md de trabajo con instrucciones de integración Jira/Slack, servidores MCP corporativos
• Sesiones OAuth diferentes: no puedes estar logueado en dos cuentas en el mismo directorio de configuración
• Memoria de proyectos separada: no quieres que el contexto de proyectos de trabajo se filtre a sesiones personales y viceversa

Cerrar sesión e iniciar sesión cada vez que cambias de contexto no es una opción. Pierdes el estado de la sesión, y es simplemente doloroso.

La solución: CLAUDE_CONFIG_DIR

Claude Code respeta una única variable de entorno: CLAUDE_CONFIG_DIR. Establécela en cualquier ruta y Claude usará ese directorio en lugar de ~/.claude para todo — auth, historial, ajustes, memoria. Todo el setup toma 60 segundos.

Paso 1: Crear un segundo directorio de configuración

Elige un nombre que tenga sentido para tu caso:

mkdir ~/.claude-work

Eso es todo. Claude lo poblará con la estructura necesaria en el primer lanzamiento.

Paso 2: Autenticar la segunda cuenta

Ejecuta Claude una vez con el nuevo directorio de configuración para iniciar el login OAuth:

CLAUDE_CONFIG_DIR=~/.claude-work claude

Se abre el navegador. Inicia sesión con tu cuenta corporativa. El token OAuth se almacena en ~/.claude-work — completamente separado de tu sesión personal en ~/.claude.

Paso 3: Añadir un alias de shell

Añade esto a tu configuración de shell para no tener que recordar la variable:

alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

Recarga tu shell:

source ~/.zshrc

Qué obtienes

Ahora tienes dos entornos Claude completamente aislados:

• claude — lanza con tu cuenta personal, CLAUDE.md personal, memoria personal
• claude-work — lanza con tu cuenta corporativa, CLAUDE.md de trabajo, memoria separada
• Historial aislado: las conversaciones de trabajo se quedan en trabajo, las personales en personal
• Servidores MCP separados: tu MCP de Obsidian personal no aparece en sesiones de trabajo
• Ajustes independientes: diferentes herramientas permitidas, diferentes niveles de permisos, diferentes preferencias de modelo por cuenta

Cómo funciona internamente

El directorio de configuración es la única fuente de verdad para el estado de Claude Code. Esto es lo que vive dentro de cada uno:

~/.claude/              ← personal account
├── CLAUDE.md           ← personal global instructions
├── projects/           ← personal project memory
├── settings.json       ← personal permissions & MCP servers
└── ...                 ← OAuth session, history, cache

~/.claude-work/         ← corporate account
├── CLAUDE.md           ← company-specific instructions (Jira, Slack, etc.)
├── projects/           ← separate project memory
├── settings.json       ← different MCP servers, permissions
└── ...                 ← separate OAuth session

Cuando ejecutas claude-work, Claude lee todo de ~/.claude-work. No sabe que ~/.claude existe. Las dos instancias son completamente independientes — puedes incluso ejecutarlas simultáneamente en diferentes pestañas del terminal.

Escalando a N cuentas

El patrón se extiende a cualquier número de cuentas. ¿Freelancer con múltiples clientes? Añade más aliases:

# Personal (default — no alias needed)
# Just run: claude

# Corporate
alias claude-work='CLAUDE_CONFIG_DIR=~/.claude-work claude'

# Freelance client
alias claude-client='CLAUDE_CONFIG_DIR=~/.claude-client claude'

Cada alias tiene su propio directorio de configuración, su propia sesión OAuth, su propio CLAUDE.md con instrucciones específicas del cliente.

Consejos prácticos

• Nombra los directorios claramente: ~/.claude-work, ~/.claude-clientname — te lo agradecerás cuando tengas tres o cuatro
• Escribe un CLAUDE.md adaptado para cada uno: el de trabajo puede incluir instrucciones de la empresa (cómo crear tickets Jira, canales Slack, procedimientos de despliegue). El personal se mantiene ligero.
• Diferentes servidores MCP por cuenta: configura herramientas de trabajo (Jira MCP, Slack MCP, APIs internas) solo en la configuración de trabajo. Mantén la personal limpia.
• Verifica qué cuenta está activa: ejecuta claude config list dentro de una sesión si no estás seguro — muestra la ruta al directorio de configuración

Dónde se queda corto este enfoque

CLAUDE_CONFIG_DIR aísla por cuenta, no por proyecto. Dentro de un mismo perfil, Claude ve todos los servidores MCP que alguna vez registraste para esa cuenta — a través de todos tus proyectos. Para uso personal en solitario suele estar bien. En el momento en que tienes varios proyectos críticos en producción bajo una sola cuenta, especialmente en dominios solapados como facturación, herramientas de administración o infraestructura, aparece un riesgo concreto entre proyectos: un asistente IA puede invocar una herramienta del proyecto A mientras trabaja en el proyecto B, sobre todo cuando ambos exponen operaciones con nombres parecidos.

El patrón de perfil responde a la pregunta which account am I in?. No responde a la pregunta which project's tools should be active right now?. Para trabajo de mayor riesgo, apila una segunda capa de aislamiento sobre la separación por cuentas:

• Un perfil por proyecto crítico en producción, no solo por cuenta: en lugar de ~/.claude y ~/.claude-work, crea ~/.claude-work-billing y ~/.claude-work-admin. Cada perfil ve solo los servidores MCP que realmente necesita.
• MCP a nivel de proyecto vía .mcp.json: commitea un .mcp.json en la raíz del proyecto listando solo los servidores MCP de ese proyecto. Claude los detecta cuando se lanza desde ese directorio. Mantén tu configuración global mínima — solo herramientas universales (notas, búsqueda), ningún endpoint de producción.
• Nombra los servidores MCP sin ambigüedad: evita nombres genéricos como admin, billing, mcp-server. Prefija con el proyecto: acme_billing_prod, acme_admin_stage. Un nombre descriptivo te obliga a pararte cuando algo está a punto de invocarse desde el contexto equivocado.
• Revisa cada llamada a herramienta MCP antes de aprobarla: llamadas como *_create_*, *_delete_*, *_charge_* merecen una segunda mirada deliberada. La velocidad que ganas con auto-aprobación masiva se evapora la primera vez que una herramienta del proyecto equivocado se dispara contra producción.

La regla general: divide perfiles de forma agresiva, mantén el MCP de producción fuera del perfil por defecto, y trata cualquier solapamiento de nombres de herramientas entre proyectos como un smell que vale la pena refactorizar.

Conclusión

Una variable de entorno. Un alias. Aislamiento total entre cuentas. Sin baile de logout/login, sin conflictos de configuración, sin fuga de contexto. Es el tipo de solución que es casi decepcionantemente simple — pero eso es lo que la hace buena. Configúrala una vez y no vuelvas a pensar en ello.

Qué es MCP y por qué no es tan simple

MCP (Model Context Protocol) es un protocolo abierto de Anthropic que permite a Claude conectarse a herramientas externas y datos. El principio es simple: se ejecuta un servidor local que expone "herramientas" (tools), y Claude las llama durante la conversación.

Para Obsidian hay teóricamente muchos servidores MCP. En la práctica — cada uno tiene sus propios problemas.

El problema principal del ecosistema Obsidian: Obsidian es una aplicación cerrada sin MCP oficial. La comunidad llenó el vacío, pero cada implementación va por su cuenta, y ninguna tiene "bendición oficial".

Intento 1: MarkusPfundstein/mcp-obsidian

La primera herramienta que aparece al buscar. 3.400 estrellas en GitHub, en todos los tutoriales. Parece una elección segura.

Cómo funciona: servidor Python basado en el plugin Local REST API de Obsidian. El servidor se comunica con el plugin vía HTTPS, el plugin ejecuta operaciones a través de la API de Obsidian.

Qué salió mal

• Sin actualizar en 17 meses
• 85 issues abiertas
• Sin move/rename — solo read, write, append, delete
• Local REST API tiene un bug documentado de pérdida de datos: el endpoint POST puede sobrescribir silenciosamente un archivo al hacer append

No apto para refactoring — necesitamos mover archivos y preservar enlaces. Seguimos adelante.

Intento 2: aaronsb/obsidian-mcp-plugin

Encontré una opción que funciona como plugin nativo de Obsidian. Esto significa acceso directo a la API interna de Obsidian — backlinks, Dataview, grafo de enlaces. Move a través de la API nativa actualiza todos los wiki-links automáticamente, porque Obsidian lo maneja internamente.

Dificultades de instalación

• El plugin no está en el catálogo oficial de Obsidian (PR pendiente con errores de validación)
• Hay que instalarlo vía BRAT (Beta Reviewers Auto-update Tool)
• Claude Desktop no acepta Bearer token directamente por UI — obligó a habilitar HTTPS en el plugin
• Certificado self-signed para localhost crea problemas de confianza

A través de todos estos workarounds finalmente lo conecté. Test básico — vault.move reescribe efectivamente [[wikilinks]], funciona como se espera.

Qué salió mal en producción

Cuando comencé el refactoring masivo (drag-and-drop de docenas de carpetas en Obsidian + operaciones MCP simultáneas), el servidor se colgó por 4+ minutos. Por qué: el plugin corre dentro de Obsidian. Cuando Obsidian reindexiza miles de archivos tras un cambio masivo de estructura, el plugin se bloquea con él.

Conclusión: la dependencia de una instancia abierta de Obsidian y su índice es fatal para operaciones masivas.

Intento 3: @bitbonsai/mcpvault

Lógicamente — necesitamos un servidor que no dependa de Obsidian. Trabaja directamente con archivos en disco. @bitbonsai/mcpvault — recomendado en muchas reseñas. Acceso directo al sistema de archivos, configuración simple (npx @bitbonsai/mcpvault@latest /path/to/vault), 14 herramientas. Obsidian ni siquiera necesita estar abierto.

Antes de instalar, verifiqué un punto crítico — si los wiki-links se actualizan al mover. Encontré una reseña de usuario:

El conector de filesystem no sabe que está en Obsidian — ve una carpeta de archivos <code>.md</code> y eso es todo. No sabe que los nombres de archivo llevan peso semántico, que cada <code>[[wikilink]]</code> se romperá en el momento del rename o move. Auto-update links solo funciona cuando el rename ocurre desde dentro de la app. Lo descubrí después de pedirle a Claude que limpiara nombres de archivos y volví a un dashboard con la mitad de los enlaces rotos.

Confirmado en la documentación del propio mcpvault: PR #101 (wiki link resolution) está en review, no mergeado. Así que mover vía mcpvault rompería la mitad del vault. No sirve.

Intento 4: VaultForge (Final)

blacksmithers/vaultforge — construido específicamente para agentes de IA que hacen refactoring.

Arquitectónicamente correcto

• Direct filesystem — no depende de Obsidian
• Motor propio de wikilinks — implementa lógica de resolución de [[wikilink]] que actualiza todas las formas (stem, ruta completa, alias, embed)
• Dry run por defecto en todas las operaciones destructivas — primero muestra qué cambiará, luego confirmas
• 27 herramientas vs 8–14 en competidores: batch_rename, update_links, backlinks (impact analysis), prune_empty_dirs, frontmatter, smart_search (BM25), vault_themes (TF-IDF clustering)
• Licencia MIT, TypeScript, zero sub-dependencies
• Instalación en 30 segundos vía .mcpb (extensión one-click para Claude Desktop)

Test de seguridad en archivos aislados

Creé 4 archivos de prueba con enlaces cruzados — stem links, links con alias, links con ruta completa. Moviendo un archivo a una subcarpeta:

delta.md → subfolder/delta-renamed.md

VaultForge mostró un dry run: "1 archivo será renombrado, 3 enlaces serán actualizados". Ejecutó de verdad.

Verificado después — los tres tipos de enlaces se actualizaron correctamente. Esto es exactamente lo que faltaba en todas las herramientas anteriores.

Cómo instalar VaultForge — Instrucciones finales

Si tienes macOS y Claude Desktop:

Paso 1

Descarga el archivo .mcpb:

curl -fsSL https://github.com/blacksmithers/vaultforge/releases/latest/download/vaultforge.mcpb \
  -o /tmp/vaultforge.mcpb && open /tmp/vaultforge.mcpb

Paso 2

Claude Desktop abrirá el diálogo de instalación de extensión. Ingresa la ruta absoluta a tu vault — sin backslashes, con espacios normales:

/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault

Paso 3

Haz clic en Save. Claude Desktop agregará la extensión a la configuración automáticamente. No necesita reinicio — las extensiones .mcpb se detectan automáticamente.

Paso 4

Verifica: en un nuevo chat pregunta: "What is the status of my Obsidian vault?" — debería devolver algo como totalFiles: 416, totalDirs: 135, ...

Lo que aprendí sobre el ecosistema MCP de Obsidian

Primero, "más popular" no significa "funcional". MarkusPfundstein/mcp-obsidian tiene 3.400 estrellas y es la recomendación por defecto, pero está desactualizado y le faltan operaciones clave.

Segundo, un plugin nativo tiene un costo oculto. El plugin aaronsb parecía ideal — graph, Dataview, move nativo. Pero la dependencia de una instancia abierta de Obsidian y su índice lo hace inadecuado para operaciones masivas serias.

Tercero, filesystem directo sin link-engine es una trampa. Mcpvault es rápido y simple, pero "solo mover archivos" destruye la estructura del vault. Los enlaces llevan semántica impuesta que el filesystem no conoce. Sin su propia implementación de lógica wikilink, la herramienta se convierte en una mina.

Cuarto, prueba con datos aislados. Antes de confiar a cualquier herramienta un refactoring masivo — crea una carpeta de prueba con 4–5 archivos con enlaces cruzados y mira qué pasa. 5 minutos de prueba ahorran horas de recuperación desde backup.

Quinto, mantén un backup git de tu vault. Lo más importante de todo. Un solo git init dentro del vault y commits periódicos — eso es seguro contra cualquier error de un agente AI o herramienta. Si algo se rompe — git reset --hard lo devuelve todo.

Conclusión

El camino tomó varias horas y tres intentos fallidos. La arquitectura final se ve así:

• VaultForge — la herramienta principal de trabajo. Direct filesystem + motor propio de wikilinks + 27 herramientas = refactoring estable a cualquier escala.
• Git — versionado del vault. Rollback gratuito para cualquier error.

Ahora puedo hacer lo que motivó todo esto: pedirle a Claude que organice 400 notas en una arquitectura PARA adecuada, fusione duplicados, agregue frontmatter, construya mapas MOC. Cada operación es segura, los enlaces se preservan, el dry run muestra qué pasará antes de que algo cambie.

Si tú también miras tu Obsidian desordenado y quieres un asistente de IA — empieza directamente con VaultForge. No repitas mi ruta a través de proyectos muertos, plugins beta y servidores filesystem sin lógica de enlaces.

¿Y si cada agujero negro fuera un Big Bang de un nuevo universo? Este artículo explora la idea de que nuestro universo podría ser un nodo en un árbol recursivo infinito, donde los agujeros negros engendran sub-universos, la energía retorna a través de la radiación de Hawking y las leyes fundamentales de la física están deliberadamente diseñadas para hacer imposible el contacto entre universos.

Agujero negro = universo

La idea surgió durante un momento de reflexión: un agujero negro se forma cuando suficiente masa y presión se concentran en un solo punto. Esa singularidad — densidad infinita, curvatura infinita — se parece sospechosamente a las condiciones que describimos para el Big Bang.

¿Y si se trata del mismo evento visto desde lados opuestos? Desde fuera, vemos un agujero negro engullendo materia. Desde dentro, un nuevo universo que estalla hacia la existencia. La masa y la energía que colapsaron en el agujero negro se convierten en la materia prima de un cosmos completamente nuevo, con sus propias estrellas, planetas y, posiblemente, sus propios agujeros negros.

Cada agujero negro de nuestro universo podría contener un universo. Y nuestro universo podría existir dentro de un agujero negro de un universo progenitor.

Por qué los universos no pueden contactarse entre sí

Aquí está la parte elegante: una vez cruzas el horizonte de eventos, no hay vuelta atrás. La relatividad general lo garantiza — el futuro del universo progenitor queda enteramente fuera del horizonte de eventos, inalcanzable desde el interior. Desde la perspectiva del sub-universo, el universo progenitor ya terminó. Toda su línea temporal ya transcurrió.

Esto no es una limitación técnica que podamos superar con mejor tecnología. Está incorporado en la geometría misma del espacio-tiempo. Los universos están fundamentalmente aislados unos de otros — no por la distancia, sino por la estructura del tiempo.

El ciclo energético: préstamo y devolución

Pero la energía no se pierde. La radiación de Hawking — el proceso cuántico mediante el cual los agujeros negros se evaporan lentamente — crea un ciclo extraordinario:

1. Un universo progenitor crea un agujero negro, transfiriendo energía a un sub-universo
2. El sub-universo vive todo su ciclo vital a lo largo de billones de años
3. El agujero negro se evapora lentamente, devolviendo energía al universo progenitor mediante la radiación de Hawking
4. El universo progenitor recibe su energía de vuelta — con intereses

Esos «intereses» son fascinantes: los físicos ahora creen que la radiación de Hawking preserva la información. El universo progenitor no recibe solo energía vacía de vuelta — recibe una huella de todo lo que ocurrió en su interior. Cada estrella que se formó, cada planeta, cada instante de consciencia — codificado en radiación.

Recursión hasta el fondo

Si eres programador, el patrón es inconfundible. Esto es recursión. Cada universo invoca universe() con menos energía, creando sub-universos que crean sub-sub-universos, hasta que no queda energía suficiente para formar agujeros negros — el caso base.

universe(energy)
  ├── creates black holes
  │     ├── universe(energy - n)
  │     │     ├── universe(energy - n - m)
  │     │     │     └── base case: not enough energy for black holes
  │     │     └── returns energy via Hawking radiation
  │     └── returns energy via Hawking radiation
  └── receives all energy back

El físico Lee Smolin formalizó una idea similar como Selección Natural Cosmológica: los universos se «reproducen» a través de agujeros negros, y cada generación posee constantes físicas ligeramente diferentes — optimizadas a lo largo de innumerables ciclos para producir más agujeros negros, más universos.

¿Dónde estamos en este ciclo?

Nuestro universo tiene aproximadamente 13.800 millones de años. Suena antiguo, pero en el contexto de su vida útil completa, estamos presenciando el mismísimo comienzo:

Existimos en aproximadamente el 0,00000000...01% de la vida total de nuestro universo. La era de las estrellas — todo lo que podemos ver — es un destello fugaz justo al principio. La verdadera historia del universo es la lenta y paciente era de los agujeros negros creando y evaporando sub-universos.

La cuestión de las dimensiones superiores

Todo lo discutido hasta ahora opera dentro de nuestra comprensión tridimensional. Pero si nuestro universo es un «corte» de algo de dimensiones superiores, entonces todo el árbol recursivo de agujeros negros y sub-universos podría ser solo la sombra de una estructura que no podemos percibir.

En 1884, Edwin Abbott escribió Planilandia — una historia sobre seres bidimensionales incapaces de concebir una tercera dimensión. Una esfera que atraviesa Planilandia aparece como un círculo que crece y se encoge. Los «planilandeses» pueden describirlo matemáticamente pero jamás comprenderán realmente lo que están viendo. Nosotros podríamos estar en exactamente la misma posición con respecto a nuestro universo.

¿Qué es la consciencia? ¿Por qué existe la experiencia subjetiva? David Chalmers llamó a esto el «problema difícil» — y podría ser la evidencia más contundente de que algo opera más allá de nuestro alcance dimensional.

Todo está bloqueado a nivel fundamental

La constatación más impactante no es que no sabemos — es que no podemos saber. Cada dirección de investigación choca con una barrera fundamental:

• ¿Quieres ver el universo progenitor? Bloqueado por el horizonte de eventos
• ¿Quieres entender la consciencia? Bloqueado — un sistema no puede analizarse completamente a sí mismo (teoremas de incompletitud de Gödel)
• ¿Quieres saber qué había «antes»? Bloqueado — el tiempo comenzó con el Big Bang
• ¿Quieres percibir dimensiones superiores? Bloqueado por las limitaciones cognitivas de un ser tridimensional

El filósofo Colin McGinn llama a esto clausura cognitiva: algunas preguntas están cerradas para la mente humana, no por falta de datos, sino por la arquitectura de la propia mente. La diferencia entre «aún no lo sabemos» y «no podemos saberlo» es profunda.

Lo único que queda: la mejora personal

Si cada salida está bloqueada por diseño — si no puedes mirar afuera, no puedes mirar atrás, no puedes mirar arriba — entonces solo queda una dirección: hacia adentro. El universo parece deliberadamente construido para forzar la atención sobre uno mismo.

Esta conclusión no proviene de la religión ni de los manuales de filosofía. Proviene de seguir la lógica de los agujeros negros, la recursión, la teoría de la información y los límites de la cognición. Existencialistas, budistas, estoicos y físicos llegan al mismo punto por caminos diferentes: el propósito de la existencia podría ser simplemente el perfeccionamiento del ser que existe.

Llegamos a esto no a través de la fe, sino a través de la física — desde los agujeros negros, pasando por universos recursivos, hasta los bloqueos fundamentales del conocimiento, hasta la única puerta abierta: ser mejores.

Referencias

• Lee Smolin — Selección Natural Cosmológica
• Stephen Hawking — Radiación de Hawking
• David Chalmers — El Problema Difícil de la Consciencia
• Edwin Abbott — Planilandia: Una Novela de Muchas Dimensiones (1884)
• Kurt Gödel — Teoremas de Incompletitud

Para sitios web sencillos — portfolios, blogs, landing pages, páginas de pequeñas empresas — un CMS tradicional se está convirtiendo en sobrecarga innecesaria. Herramientas de IA como Claude Code, Cursor y GitHub Copilot ahora pueden editar tu código directamente, entender el contexto, traducir contenido y desplegar cambios a través de git. La capa de abstracción que proporcionaba el CMS está siendo reemplazada por una interfaz más inteligente: el lenguaje natural.

El impuesto CMS que estás pagando

Todo CMS viene con un coste oculto. No solo la cuota de suscripción — todo un ecosistema de complejidad que envuelve tu sitio web, que de otro modo sería sencillo:

• Infraestructura: Una base de datos que alojar, una API que mantener, un panel de control que asegurar. Solo WordPress representa ~43% de la web y ~90% de los ataques dirigidos a CMS.
• Rendimiento: Generación dinámica de páginas, llamadas API en cada petición, hidratación del lado del cliente con datos del CMS. Tu portfolio de 3 páginas ahora tiene la arquitectura de un producto SaaS.
• Dependencia del proveedor: Tu contenido vive en el esquema de base de datos de otro. ¿Migrar de Contentful a Sanity? Eso es un proyecto, no un cambio de configuración.
• Cambio de contexto: Editas código en tu IDE, luego cambias al panel del CMS en el navegador para modificar un titular. Dos modelos mentales diferentes para lo que es fundamentalmente la misma operación.
• Coste: Los precios de CMS headless suelen escalar con las llamadas API o las entradas de contenido. Un blog personal no necesita una infraestructura de contenido de $99/mes.

Para un sitio de marketing donde 50 personas editan contenido a diario, este coste está justificado. ¿Para el portfolio de un desarrollador o la landing page de una pequeña empresa? Estás construyendo un puente para cruzar un charco.

Qué cambió: la IA entiende tu código

La razón de existir de los CMS era sencilla: las personas no técnicas (e incluso los desarrolladores que no querían tocar código para cambios de contenido) necesitaban una interfaz visual para actualizar sitios web. El código era demasiado complejo, demasiado frágil, demasiado fácil de romper.

La IA cambió esta ecuación de forma fundamental. Las herramientas modernas de IA para código no solo autocompletan — entienden la estructura del proyecto, leen patrones existentes y realizan ediciones contextualmente correctas. El cambio en el flujo de trabajo es radical:

# Old workflow: CMS
1. Open browser → log into CMS dashboard
2. Navigate to content → find the right page
3. Edit in WYSIWYG editor → fight with formatting
4. Preview → looks different from production
5. Hit publish → pray the cache invalidates

# New workflow: AI
1. Tell AI: "Change the pricing on the landing page to $29/month"
2. AI edits the file, you review the diff
3. Push to git → deploy

Esto no es hipotético. Este mismo blog funciona con SolidStart y el contenido se almacena como archivos TypeScript. Cada artículo — incluido este — fue creado diciéndole a la IA qué escribir, revisando el resultado y haciendo push a git. Sin panel de CMS. Sin base de datos. Sin capa API entre el contenido y el código.

Ejemplos reales de este sitio

Este sitio soporta 10 idiomas, tiene un blog, genera imágenes OG dinámicamente y produce feeds RSS y sitemaps. Así es como se ve la capa de contenido — TypeScript puro:

// This blog post you're reading right now is a TypeScript file.
// No database. No API. No CMS dashboard.
// Just a typed object that AI can read and edit directly.

export const myPost: BlogPost = {
  slug: "ai-killed-cms",
  date: "2026-04-17",
  translations: {
    en: {
      title: "Why I stopped using a CMS",
      description: "AI understands my codebase better than any CMS UI.",
      content: makeContent(proseEn),
    },
    uk: { /* ... */ },
    de: { /* ... */ },
    // 10 languages — AI translates them all
  },
};

Cosas que hago con IA que tradicionalmente requerirían un CMS:

• Añadir un nuevo artículo: "Escribe un nuevo artículo sobre X, sigue la misma estructura que los posts existentes" — la IA crea el archivo, añade traducciones, lo registra en el índice
• Actualizar el copy de la landing: "Cambia el titular del hero a Y" — la IA encuentra el archivo correcto y lo actualiza
• Traducir contenido: "Añade la traducción al alemán de la página de precios" — la IA lee la versión en inglés y produce una traducción culturalmente adaptada, no una traducción literal
• Corregir una errata: "Hay una errata en la página about, 'recieve' debería ser 'receive'" — hecho en 3 segundos, commiteado en git con un mensaje descriptivo

Lo que el CMS realmente resolvía — y cómo la IA lo reemplaza

Seamos honestos sobre lo que el CMS aportaba y cómo cada capacidad se traduce al flujo de trabajo con IA:

La clave: git ya es un mejor sistema de control de versiones que cualquier CMS haya construido jamás. Y el lenguaje natural es una mejor interfaz que cualquier editor WYSIWYG — porque transmite intención, no solo formato.

El cambio de paradigma: el código es la capa de contenido

Estamos presenciando una inversión. Durante dos décadas, la tendencia fue separar el contenido del código — poner el contenido en una base de datos, exponerlo vía API, renderizarlo en el frontend. Esto tenía sentido cuando el código era difícil de editar y el contenido necesitaba ser accesible para personas no técnicas.

La IA no hizo obsoleto al CMS siendo un CMS mejor. Lo hizo obsoleto haciendo que el código fuera tan accesible como un panel de control.

La progresión de la gestión de contenido web sigue una trayectoria clara:

1. 2000s: CMS monolíticos (WordPress, Drupal) — contenido y presentación acoplados en un solo sistema
2. 2010s: CMS headless (Contentful, Strapi) — contenido separado vía API, renderizado por frameworks frontend
3. 2020s: Generadores de sitios estáticos + Markdown (Hugo, Astro) — contenido como archivos, compilado en el despliegue
4. 2025+: Código-como-contenido + IA — el contenido vive en código tipado, la IA es la interfaz de edición

Cuándo todavía necesitas un CMS

Esto no es un discurso de "el CMS ha muerto". El CMS resuelve problemas reales a escala. Todavía lo necesitas cuando:

• Grandes equipos editoriales: Más de 10 editores de contenido que necesitan acceso basado en roles, flujos de aprobación y edición simultánea. Los conflictos de merge en git no son un problema que deba resolver un editor de contenido.
• Contenido de alta frecuencia: Sitios de noticias que publican más de 50 artículos al día necesitan pipelines editoriales optimizados, no commits de git.
• Relaciones de contenido complejas: Catálogos de e-commerce con miles de SKUs, variantes de producto y precios dinámicos necesitan bases de datos estructuradas.
• Cumplimiento regulatorio: Industrias que requieren registros de auditoría, cadenas de aprobación de contenido y procesos de revisión legalmente obligatorios necesitan sistemas especializados.

El límite es claro: si tus cambios de contenido requieren coordinación entre múltiples stakeholders no técnicos a alta frecuencia, un CMS merece su complejidad. Si eres un desarrollador en solitario, un equipo pequeño, o gestionas un sitio que cambia semanalmente en lugar de cada hora — IA + código es más simple, más rápido, más barato y más fiable.

El futuro: la IA como interfaz universal

La tendencia va más allá del CMS. Cada capa de abstracción que existía porque "el sistema subyacente es demasiado complejo para la interacción directa" está siendo comprimida por la IA. Paneles de administración, interfaces de configuración, editores visuales de bases de datos — todos son interfaces que traducen la intención humana en cambios del sistema. La IA hace esta traducción de forma nativa.

Para sitios web sencillos, el futuro ya está aquí. Tu contenido es código. Tu editor es IA. Tu control de versiones es git. Tu despliegue es un push. Toda la capa CMS — el panel, la base de datos, la API, el hosting — era middleware entre tu intención y tu sitio web. La IA eliminó la necesidad de ese middleware.

El mejor CMS es no tener CMS. No porque la gestión de contenido no importe — sino porque la IA convirtió al código en la interfaz de gestión de contenido más intuitiva que jamás hemos tenido.

Perplexity Desktop soporta conectores MCP (Model Context Protocol). Al agregar el servidor oficial @modelcontextprotocol/server-filesystem apuntando a tu Obsidian vault, puedes decirle a Perplexity en lenguaje natural que lea, cree y edite notas — directamente desde el chat. Sin plugins, sin extensiones, sin copiar y pegar.

El Problema

Perplexity es excelente para investigar — busca en la web, resume fuentes y da respuestas con citas. Pero cuando quieres guardar esos hallazgos en tu Obsidian vault, el flujo de trabajo se rompe: copias texto, cambias a Obsidian, encuentras la nota correcta, pegas, formateas. Cada. Vez.

Las extensiones de navegador como "Perplexity to Obsidian" ayudan con la exportación, pero son unidireccionales — la IA no puede ver tu vault, no puede leer tus notas existentes y no puede decidir dónde poner las cosas basándose en tu estructura de carpetas.

¿Qué es MCP?

Model Context Protocol (MCP) es un estándar abierto que permite a los modelos de IA interactuar con herramientas y fuentes de datos locales. Piensa en ello como un puerto USB para IA — conectas un "servidor" (un pequeño programa) y la IA obtiene nuevas capacidades. En nuestro caso, el servidor filesystem le da a Perplexity 14 herramientas para trabajar con archivos:

Perplexity Desktop (Mac App)
  │
  ├── MCP Connector: "Obsidian Vault"
  │     │
  │     └── @modelcontextprotocol/server-filesystem
  │           │
  │           ├── read_file()      → read any .md file
  │           ├── write_file()     → create or overwrite files
  │           ├── edit_file()      → patch existing files
  │           ├── list_directory() → browse vault structure
  │           ├── search_files()   → find files by pattern
  │           └── ... 14 tools total
  │
  └── Perplexity AI Model
        │
        └── "Save this to my daily note" → calls write_file()

El punto clave: el modelo de IA no accede directamente a tus archivos. Llama a herramientas proporcionadas por el servidor MCP, que se ejecuta localmente en tu máquina. Tus datos nunca salen de tu computadora a menos que le pidas explícitamente a la IA que haga algo con ellos.

Requisitos

• Suscripción Perplexity Pro (los conectores MCP están disponibles para usuarios de pago)
• Perplexity Mac App del App Store (no la versión del navegador)
• Node.js instalado en tu Mac (para que funcione npx)

Configuración paso a paso

Toda la configuración toma unos 2 minutos:

El Comando

El comando a pegar en el campo Command:

npx -y @modelcontextprotocol/server-filesystem "/Users/yourname/Library/Mobile Documents/iCloud~md~obsidian/Documents/Obsidian Vault"

Reemplaza la ruta con la ubicación real de tu Obsidian vault. Si tu vault se sincroniza via iCloud, la ruta estará bajo ~/Library/Mobile Documents/iCloud~md~obsidian/Documents/. Asegúrate de mantener las comillas — la ruta probablemente contiene espacios.

Cómo usarlo

Una vez que el conector muestre Running con 14 herramientas disponibles, ve a cualquier chat de Perplexity y empieza a hablar con tu vault:

> Show me the structure of my Obsidian vault
> Add a new reflection to daily notes/2026-04-12.md: "Started using MCP today"
> Find all notes that mention "meditation"
> Create a new note in concepts/ about quantum computing
> List all files in my ideas/ folder

La IA entiende la estructura de tu vault, respeta tus convenciones de formato y puede trabajar con contenido existente. Puedes pedirle que investigue un tema en la web y guarde el resumen directamente en una nota específica.

Por qué MCP supera otros enfoques

Antes de MCP, había formas limitadas de conectar Perplexity y Obsidian:

Limitaciones actuales

• Solo Mac — los conectores MCP de Perplexity actualmente solo funcionan en la versión de Mac App Store
• Sin integración con Obsidian API — el servidor filesystem trabaja con archivos directamente, no a través de la API de Obsidian. Esto significa que no activará plugins de Obsidian (Linter, Templater) al crear archivos
• Requiere aprobación — las operaciones sensibles de archivos pueden requerir tu confirmación en la app de Perplexity — es una función de seguridad, no un bug

Conclusiones

Esta configuración convierte Perplexity de una herramienta de investigación en una herramienta de investigación-y-captura:

1. Investiga en la web y guarda en Obsidian en una conversación
2. La IA ve la estructura de tu vault y se adapta a tu sistema de organización
3. Cero cambios entre apps — todo sucede en el chat de Perplexity

Fuentes

• Model Context Protocol — official MCP specification
• MCP Filesystem Server — the server used in this setup
• Perplexity Help Center — Local and Remote MCPs for Perplexity
• Perplexity Blog — Everything is Computer

Un script bash de 6 líneas que ejecuta Claude Code CLI en modo headless cada mañana a las 9:00. Busca noticias en 11 temas configurables, filtra el ruido y escribe un digest markdown formateado directamente en un Obsidian vault sincronizado vía iCloud. Cero dependencias. ~100 líneas de configuración total.

El Problema

Como desarrollador, mantenerse al día con múltiples tecnologías es un impuesto diario. Los feeds RSS son ruidosos, Twitter consume tiempo, los newsletters llegan cuando estás en estado de flujo. Necesitaba algo que hiciera la investigación por mí.

La solución típica es construir un pipeline de scraping: un programador, un crawler, un pipeline NLP, una base de datos, un servicio de notificaciones. Eso son semanas de trabajo. Yo quería algo que pudiera hacer en una tarde.

Arquitectura

Todo el sistema son 4 archivos y cero dependencias:

macOS launchd (9:00 AM daily)
  │
  └── digest.sh
        │
        └── claude -p "$(cat prompt.md)" --max-turns 20 --allowedTools Read,WebSearch,WebFetch,Write
              │
              ├── Reads topics.yaml (11 configurable topics)
              ├── WebSearch → finds news for each topic (last 24-48h)
              ├── WebFetch → reads full articles
              ├── Filters noise: old tutorials, promos, AI spam
              └── Write → saves digest to Obsidian Vault
                    │
                    └── ~/Obsidian Vault/digests/2026-04-12.md
                          │
                          └── iCloud sync → available on all devices

El Código (todo)

El proyecto es intencionalmente mínimo.

Punto de entrada: digest.sh

Toda la aplicación es un script bash de 6 líneas:

#!/bin/bash
DIGEST_DIR="$HOME/Developer/news-digest"

claude -p "$(cat "$DIGEST_DIR/prompt.md")" \
  --max-turns 20 \
  --allowedTools Read,WebSearch,WebFetch,Write

Los flags clave: -p ejecuta Claude en modo headless, --max-turns 20 da suficientes turnos al agente, --allowedTools restringe al agente a lectura, búsqueda y escritura.

El Cerebro: prompt.md

Aquí vive la inteligencia. El prompt convierte a Claude en un agente de investigación de noticias:

# News Digest Agent

You are a news research agent. Your job is to find today's most important
and interesting news for a senior frontend developer.

## Instructions

1. Read the topics file at ~/Developer/news-digest/topics.yaml
2. For EACH topic, search the web for news from the last 24-48 hours
3. Filter: only include genuinely new and noteworthy items
4. Write the digest as a markdown file to Obsidian Vault digests/YYYY-MM-DD.md
5. IMPORTANT: Use the Write tool to save the file. Do NOT output to stdout.

## Rules

- Language: Ukrainian for summaries, English for titles and technical terms
- If there's no real news for a topic — SKIP IT ENTIRELY
- Prioritize: releases > breaking changes > security > new patterns > discussions
- Max 5 items per topic, sorted by importance
- Include direct links to sources
- Skip promotional content, generic tutorials, and AI-generated spam

Configuración: topics.yaml

Los temas son totalmente configurables — agrega uno nuevo y estará en el digest de mañana:

topics:
  - name: better-auth
    context: "auth library for TypeScript. New releases, breaking changes"

  - name: Next.js
    context: "GitHub issues, releases, App Router, Turbopack, performance"

  - name: SolidJS
    context: "SolidStart, releases, ecosystem, comparison with React"

  - name: Tailwind CSS
    context: "v4 updates, new utilities, plugins"

  - name: Claude AI
    context: "Anthropic announcements, Claude Code, new models, MCP, API"

  - name: GPT AI
    context: "OpenAI announcements, new models, ChatGPT features"

  - name: React
    context: "React 19+, Server Components, new patterns, ecosystem"

  - name: Apple
    context: "Hardware, software, WWDC, developer tools, Apple Intelligence"

  - name: Notable People
    context: >
      Latest tweets from: Elon Musk, Dario Amodei, Sam Altman,
      Jensen Huang, Andrej Karpathy, Simon Willison, Swyx...

  - name: AI Global
    context: "Major AI news, new models, regulations, open-source AI"

Programación con launchd

En macOS, launchd es la forma nativa de programar tareas recurrentes:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.news-digest</string>

    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>/Users/you/Developer/news-digest/digest.sh</string>
    </array>

    <key>StartCalendarInterval</key>
    <dict>
        <key>Hour</key>
        <integer>9</integer>
        <key>Minute</key>
        <integer>0</integer>
    </dict>

    <key>StandardOutPath</key>
    <string>/Users/you/Developer/news-digest/logs/stdout.log</string>
    <key>StandardErrorPath</key>
    <string>/Users/you/Developer/news-digest/logs/stderr.log</string>

    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
        <key>HOME</key>
        <string>/Users/you</string>
    </dict>
</dict>
</plist>

Instalar con launchctl load ~/Library/LaunchAgents/com.news-digest.plist. El script se ejecuta diariamente a las 9:00.

Cómo se ve el resultado

Cada mañana aparece un nuevo archivo markdown en el Obsidian vault:

---
date: 2026-04-12
---

# News Digest — 2026-04-12

## Next.js

### Next.js 16.1 Released with Improved Turbopack Caching
Нова версія Next.js 16.1 включає покращене кешування для Turbopack,
що зменшує час холодного старту на ~40%.
[Посилання](https://nextjs.org/blog/next-16-1)

### Critical Memory Leak Fix in App Router
Виправлено витік пам'яті в App Router при частому перемиканні
між динамічними маршрутами.
[GitHub Issue](https://github.com/vercel/next.js/issues/...)

## Claude AI

### Claude Code 1.5 — MCP Server Auto-Discovery
Anthropic випустив оновлення Claude Code з автоматичним
виявленням MCP серверів у проєкті.
[Блог](https://www.anthropic.com/news/...)

En números

Decisiones clave de diseño

• Claude Code CLI en vez de API — sin gestionar API keys, clientes HTTP o parseo de respuestas
• Obsidian en vez de email — los digests son buscables, enlazables y permanentes
• launchd en vez de cron — programador nativo de macOS con manejo de ejecuciones perdidas
• YAML para temas — un nuevo tema es un cambio de 2 líneas
• Saltar temas vacíos — sin noticias = sin sección

Cómo construir el tuyo

Listo en 10 minutos:

1. Instalar Claude Code CLI y autenticarse
2. Clonar el repo: git clone https://github.com/oleksiimazurenko/news-digest
3. Editar topics.yaml y prompt.md
4. Editar el plist y launchctl load
5. Esperar a las 9:00 — o probar manualmente con bash digest.sh

Conclusiones

Lo más interesante de este proyecto es lo que no tiene. Sin base de datos, sin servidor API, sin Docker, sin npm, sin Python, sin parser HTML, sin pipeline NLP.

Así es construir con agentes AI: defines el qué y el dónde, el agente maneja el cómo. Tiempo total: unas 2 horas.

Fuentes

• news-digest on GitHub — full source code
• Claude Code Documentation — headless mode and CLI flags
• Apple Developer — creating launchd jobs
• Obsidian — markdown knowledge base

next-themes renderiza una etiqueta <script> dentro de un componente cliente de React para evitar el parpadeo de tema (FOUC). React 19 ahora advierte sobre esto — y no hay forma de suprimirlo. La librería no ha sido actualizada desde marzo de 2025. La solución: reemplazar next-themes con un store de Zustand + useServerInsertedHTML para inyectar el script fuera del árbol de React. Sin dependencias adicionales. Sin FOUC. Sin advertencias.

El Problema

Si usas next-themes con Next.js 15+ y React 19, obtienes este error en la consola en cada carga de página:

Encountered a script tag while rendering React component.
Scripts inside React components are never executed when rendering on the client.
Consider using template tag instead.

src/providers/theme-provider.tsx (7:10) @ ThemeProvider

Esto no es un desajuste de hidratación. Es React 19 advirtiendo explícitamente que las etiquetas <script> renderizadas por componentes React en el cliente nunca se ejecutarán. El script funciona durante el SSR (está en el HTML), pero React lo marca como incorrecto.

Por Qué Ocurre

next-themes necesita establecer la clase de tema correcta en <html> antes de que React hidrate — de lo contrario se produce un destello del tema incorrecto. Para lograr esto, inyecta un <script> en línea mediante React.createElement:

// next-themes renders a <script> inside a Client Component
return React.createElement(Provider, { value },
  React.createElement("script", {
    suppressHydrationWarning: true,
    dangerouslySetInnerHTML: { __html: `(...theme init code...)` }
  }),
  children
)

React 19 cambió su comportamiento: las etiquetas script dentro de componentes ahora se marcan explícitamente. Antes de React 19, esto se ignoraba silenciosamente. La prop suppressHydrationWarning en el script no ayuda — suprime las advertencias de hidratación, no la advertencia de "script en componente".

Qué Intentamos (Y Por Qué Falló)

Probamos sistemáticamente cada enfoque antes de encontrar la solución:

La Solución: Zustand + useServerInsertedHTML

La clave: useServerInsertedHTML es un hook de Next.js que inyecta HTML en el stream SSR fuera del árbol de componentes de React. El script termina en el HTML pero React nunca lo "ve" durante el renderizado en el cliente — por lo tanto, sin advertencias. Combinado con un store de Zustand para el estado reactivo del tema, obtenemos un reemplazo completo sin dependencias adicionales.

Cómo Funciona

SSR (server):
  useServerInsertedHTML → injects <script> into HTML stream
  ↓
  Browser receives HTML with theme script already in it
  ↓
  Script runs BEFORE React hydrates → correct class on <html>
  ↓
  No flash. No mismatch. No warning.

Client (after hydration):
  useEffect → _init() → Zustand store syncs with localStorage
  ↓
  useTheme() → reactive theme state for components

Paso 1: Store de Zustand

El store gestiona el estado del tema, aplica clases al DOM, maneja la detección del tema del sistema y sincroniza entre pestañas. El método _init() devuelve una función de limpieza para usar en useEffect:

import { create } from "zustand";

const STORAGE_KEY = "theme";
const MEDIA_QUERY = "(prefers-color-scheme: dark)";

function getSystemTheme(): "light" | "dark" {
  return window.matchMedia(MEDIA_QUERY).matches ? "dark" : "light";
}

function applyTheme(resolved: string, disableTransition: boolean) {
  const d = document.documentElement;

  if (disableTransition) {
    const style = document.createElement("style");
    style.appendChild(
      document.createTextNode(
        "*,*::before,*::after{transition:none!important}"
      )
    );
    document.head.appendChild(style);
    window.getComputedStyle(document.body);
    setTimeout(() => document.head.removeChild(style), 1);
  }

  d.classList.remove("light", "dark");
  d.classList.add(resolved);
  d.style.colorScheme = resolved;
}

interface ThemeState {
  theme: string;
  systemTheme: "light" | "dark";
  resolvedTheme: string;
  setTheme: (theme: string) => void;
  _init: (disableTransition: boolean) => () => void;
}

export const useThemeStore = create<ThemeState>((set, get) => ({
  theme: "system",
  systemTheme: "light",
  resolvedTheme: "light",

  setTheme: (newTheme) => {
    const { systemTheme, disableTransitionOnChange } = get();
    const resolved = newTheme === "system" ? systemTheme : newTheme;
    localStorage.setItem(STORAGE_KEY, newTheme);
    applyTheme(resolved, disableTransitionOnChange);
    set({ theme: newTheme, resolvedTheme: resolved });
  },

  _init: (disableTransition) => {
    const stored = localStorage.getItem(STORAGE_KEY) || "system";
    const system = getSystemTheme();
    const resolved = stored === "system" ? system : stored;

    set({ theme: stored, systemTheme: system, resolvedTheme: resolved });
    applyTheme(resolved, disableTransition);

    // System theme changes
    const mq = window.matchMedia(MEDIA_QUERY);
    const onChange = (e: MediaQueryListEvent) => {
      const newSystem = e.matches ? "dark" : "light";
      const { theme } = get();
      set({ systemTheme: newSystem,
            resolvedTheme: theme === "system" ? newSystem : theme });
      if (theme === "system") applyTheme(newSystem, disableTransition);
    };
    mq.addEventListener("change", onChange);

    // Cross-tab sync
    const onStorage = (e: StorageEvent) => {
      if (e.key !== STORAGE_KEY || !e.newValue) return;
      const system = getSystemTheme();
      const resolved = e.newValue === "system" ? system : e.newValue;
      set({ theme: e.newValue, resolvedTheme: resolved });
      applyTheme(resolved, disableTransition);
    };
    window.addEventListener("storage", onStorage);

    return () => {
      mq.removeEventListener("change", onChange);
      window.removeEventListener("storage", onStorage);
    };
  },
}));

export function useTheme() {
  return useThemeStore((s) => ({
    theme: s.theme,
    setTheme: s.setTheme,
    resolvedTheme: s.resolvedTheme,
    systemTheme: s.systemTheme,
  }));
}

Paso 2: ThemeProvider

El provider hace dos cosas: inyecta el script de prevención de FOUC mediante useServerInsertedHTML, e inicializa el store de Zustand al montarse:

"use client"

import { useEffect } from "react"
import { useServerInsertedHTML } from "next/navigation"
import { useThemeStore } from "@/store/use-theme-store"

const THEME_INIT_SCRIPT = `(function(){
  try {
    var t = localStorage.getItem("theme") || "system";
    var r = t;
    if (t === "system") {
      r = window.matchMedia("(prefers-color-scheme: dark)").matches
        ? "dark" : "light";
    }
    document.documentElement.classList.remove("light", "dark");
    document.documentElement.classList.add(r);
    document.documentElement.style.colorScheme = r;
  } catch(e) {}
})()`

export function ThemeProvider({
  children,
  disableTransitionOnChange = false,
}) {
  // Injects script into SSR HTML outside the React tree
  // — prevents FOUC without triggering React 19 warning
  useServerInsertedHTML(() => (
    <script dangerouslySetInnerHTML={{ __html: THEME_INIT_SCRIPT }} />
  ))

  useEffect(() => {
    return useThemeStore.getState()._init(disableTransitionOnChange)
  }, [disableTransitionOnChange])

  return <>{children}</>
}

Paso 3: Layout

import { ThemeProvider } from "@/providers/theme-provider"

export default function RootLayout({ children }) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body>
        <ThemeProvider disableTransitionOnChange>
          {children}
        </ThemeProvider>
      </body>
    </html>
  )
}

Paso 4: Úsalo

import { useTheme } from "@/store/use-theme-store"

export function ThemeSwitch() {
  const { theme, setTheme } = useTheme();

  return (
    <button onClick={() => setTheme(
      theme === "dark" ? "light" : "dark"
    )}>
      {theme === "dark" ? "☀️" : "🌙"}
    </button>
  );
}

Migración desde next-themes

La API es intencionalmente idéntica. La migración es un único cambio de import por archivo:

- import { useTheme } from "next-themes"
+ import { useTheme } from "@/store/use-theme-store"

  // API is identical — no other changes needed
  const { theme, setTheme, resolvedTheme, systemTheme } = useTheme()

Comparación

¿Por Qué No Otras Alternativas?

@wrksz/themes

Un reemplazo directo que también usa useServerInsertedHTML. Funciona, pero es otra dependencia de un único mantenedor. Si next-themes nos enseñó algo — las dependencias se abandonan. Con ~100 líneas de código, puedes ser dueño de la solución por completo.

next-themes@1.0.0-beta.0

Existe en npm, pero sin fecha de lanzamiento, sin changelog y sin indicación clara de que la advertencia de React 19 esté corregida. Apostar el código de producción a una beta indefinida no es un riesgo que valga la pena asumir.

Solo CSS (prefers-color-scheme)

Funciona para la detección del tema del sistema, pero no puede manejar la persistencia de preferencias del usuario (localStorage), el cambio manual de tema ni la opción "system". Para eso se necesita JavaScript.

Conclusiones

1. next-themes está efectivamente abandonado — última versión marzo de 2025, advertencia de React 19 sin corregir
2. useServerInsertedHTML es el primitivo correcto de Next.js para inyectar scripts sin advertencias de React
3. Zustand proporciona estado reactivo del tema con menos código que un proveedor de Context
4. La solución completa tiene ~100 líneas, cero nuevas dependencias, y eres dueño de cada línea

Fuentes

• shadcn/ui #10104 — Dark mode guide should address React 19 script warning
• next-themes #296 — React 19 support request (open since 2024)
• React #34008 — Script tags not executing in components (by design)
• @wrksz/themes — Drop-in replacement using useServerInsertedHTML
• Next.js Docs — useServerInsertedHTML API

Nuestra aplicación (Promova) usa Next.js 16 con un Landing Builder — un sistema impulsado por CMS que ensambla páginas de marketing a partir de ~90 componentes de sección diferentes (heroes, FAQs, precios, reseñas, etc.). La arquitectura usa un sectionRegistry.tsx que mapea nombres de sección a llamadas next/dynamic():

// sectionRegistry.tsx — imports all 90 sections
export const sectionRegistry = {
  HeroSection: dynamic(() => import('./HeroSection/HeroSection')),
  FAQSection: dynamic(() => import('./FAQSection/FAQSection')),
  ReviewsSection: dynamic(() => import('./ReviewsSection/ReviewsSection')),
  // ... 87 more
}

Una sola landing page solo renderiza 5-8 secciones. Pero Lighthouse mostraba:

Eliminate render-blocking resources
  94 CSS resources (~330 KB)
  Potential savings: 5,440 ms

¿Por qué? Turbopack ve las 90 rutas import() como alcanzables y genera <link rel="stylesheet"> para cada módulo SCSS. Incluso secciones que nunca se renderizan obtienen su CSS inyectado en <head>. Este es un comportamiento confirmado y esperado del Next.js App Router. No se planea una corrección.

Todo lo que intenté (y por qué falló)

Pasé días repasando cada enfoque que pude encontrar. Aquí está la lista completa:

La trampa de inlineCss

Next.js tiene un flag experimental.inlineCss que reemplaza todos los <link rel="stylesheet"> con etiquetas <style> inline. ¿Suena perfecto, verdad?

El problema: es todo o nada. No se puede activar por ruta. Si tienes páginas SSR (force-dynamic), cada solicitud reconstruye todo el CSS inline. Lo probamos — nuestro headless CMS no soportó la carga y se cayó.

El descubrimiento: Turbopack Import Attributes

Investigando las notas de la versión Next.js 16.2, encontré una característica poco documentada: Turbopack Import Attributes. Permite anular el pipeline del bundler para un import específico usando la sintaxis TC39 with {}:

import { cssText, styles } from './hero.module.scss' with {
  turbopackLoader: '@promova/scss-to-inline-loader',
  turbopackAs: '*.js'
}

Esto le dice a Turbopack: "No proceses este import como hoja de estilos. Pásalo por mi loader personalizado y trata la salida como JavaScript."

Este es el insight clave. En lugar de que Turbopack genere un <link rel="stylesheet"> que bloquea el renderizado, nuestro loader compila el SCSS y lo exporta como string JS. Resultado: solo el CSS de las secciones que realmente se renderizan llega al HTML de la página.

La solución

1. Loader personalizado de Turbopack

Un script Node.js de ~70 líneas como paquete yarn workspace (@promova/scss-to-inline-loader):

const { createHash } = require('node:crypto')
const sass = require('sass')
const postcss = require('postcss')
const postcssModules = require('postcss-modules')
const path = require('path')

const SHARED_STYLES = path.resolve(__dirname, '../shared/styles')

// Same prependData as sassOptions.prependData in next.config.ts
const PREPEND_DATA = `
@use "sass:math" as math;
@use "sass:list" as list;
@use "${SHARED_STYLES}/_variables.scss" as *;
@use "${SHARED_STYLES}/_breakpoints.scss" as *;
@use "${SHARED_STYLES}/_mixins.scss" as *;
`

module.exports = function scssToInlineLoader(source) {
  const callback = this.async()
  processScss(source, this.resourcePath)
    .then((js) => callback(null, js))
    .catch((err) => callback(err))
}

async function processScss(source, resourcePath) {
  // 1. Compile SCSS → CSS (with global variables, mixins, breakpoints)
  const sassResult = sass.compileString(PREPEND_DATA + '\n' + source, {
    loadPaths: [path.dirname(resourcePath), SHARED_STYLES],
    style: 'compressed',
    sourceMap: false,
    url: new URL('file://' + resourcePath),
  })

  // 2. Scope class names with postcss-modules (CSS Modules compatible)
  let classNames = {}
  const result = await postcss([
    postcssModules({
      generateScopedName(name, filename) {
        const file = path.basename(filename, path.extname(filename))
          .replace('.module', '')
        const hash = createHash('md5')
          .update(filename + name)
          .digest('base64url')
          .slice(0, 6)
        return `${file}__${name}__${hash}`
      },
      getJSON(_, json) { classNames = json },
    }),
  ]).process(sassResult.css, { from: resourcePath })

  // 3. Export as JS module — same interface as CSS Modules
  return [
    `export const cssText = ${JSON.stringify(result.css)};`,
    `export const styles = ${JSON.stringify(classNames)};`,
    `export default styles;`,
  ].join('\n')
}

Qué hace: styles — el mismo mapa de nombres de clase con scope que CSS Modules estándar. cssText — el CSS compilado como string.

2. Componente InlineStyle

Usa la API integrada de React 19 <style href precedence> para deduplicación automática:

export function InlineStyle({ css, id }: { css: string; id: string }) {
  return (
    <style href={id} precedence="default">
      {css}
    </style>
  )
}

React 19 garantiza: mismo href → solo un <style> en el DOM.

3. Migración por componente (~6 líneas por sección)

// BEFORE: Turbopack → <link rel="stylesheet"> (render-blocking)
import styles from './hero_section.module.scss'

// AFTER: Custom loader → JS module → inline <style> (non-blocking)
import { cssText, styles } from './hero_section.module.scss' with {
  turbopackLoader: '@promova/scss-to-inline-loader',
  turbopackAs: '*.js'
}
import { InlineStyle } from '@promova/scss-to-inline-loader/InlineStyle'

export function HeroSection() {
  return (
    <section className={styles.hero}>
      <InlineStyle css={cssText} id="hero-section" />
      {/* ... component JSX, className usage is identical */}
    </section>
  )
}

Los archivos .module.scss permanecen exactamente iguales. Sin reescritura de CSS.

Por qué esto es mejor que inlineCss: true

Esta es la diferencia crítica:

Con inlineCss: true, una página sigue obteniendo TODOS los 94 estilos inline. Con nuestro enfoque, solo el CSS que realmente se renderiza llega al HTML.

La trampa de Turbopack: sin reglas globales para .module.scss

Una trampa en la que caí: podrías pensar que puedes agregar una regla de Turbopack en next.config.ts para aplicar el loader globalmente:

// ❌ THIS CAUSES A FATAL PANIC
turbopack: {
  rules: {
    '**/components/**/*.module.scss': {
      loaders: ['@promova/scss-to-inline-loader'],
      as: '*.js'
    }
  }
}

No lo hagas. El pipeline integrado de módulos CSS de Turbopack intercepta archivos .module.scss antes de que se apliquen reglas personalizadas, causando:

FATAL PANIC: inner asset should be CSS processable

Los atributos with {} funcionan porque instruyen a Turbopack en el sitio de importación a omitir completamente el pipeline de módulos CSS.

Resultados

Migrados 127 componentes de sección en el Landing Builder. Build de producción verificado.

Limitaciones

• with {} por import es verboso — cada import necesita 3 líneas extra.
• Solo Turbopack — los atributos with {} no son soportados por Webpack.
• Hashing de nombres de clase — nuestro loader usa un algoritmo de hashing diferente al de Turbopack.
• El tamaño del HTML aumenta — CSS inline en HTML en lugar de archivos cacheados separados.

Cuándo usar esto

Esta técnica es más efectiva cuando:

1. Tienes un patrón registry/barrel — un archivo importa muchos componentes, pero solo unos pocos se renderizan por página
2. Estás en Turbopack — Import Attributes son específicos de Turbopack
3. Quieres control por componente — no un flag de todo o nada
4. Tu SCSS es complejo — variables, mixins, breakpoints, anidación — todo soportado
5. No puedes usar experimental.inlineCss — porque tienes páginas SSR o quieres control granular

Issues de GitHub relacionados

Si te afecta el CSS que bloquea el renderizado en Next.js App Router — no estás solo:

El problema central

• #62485 — Render blocking CSS (maintainers: "expected behavior")
• #61066 — Dynamic imports from Server Components are not code-split
• #54935 — Server-side dynamic imports don't split client modules
• #61574 — JS/CSS code splitting doesn't work as documented
• #57634 — Add support for critical CSS inlining with App Router
• #50300 — next/dynamic on server component does not build CSS modules

Feature inlineCss y problemas

• PR #72195 — experimental: css inlining (the implementation)
• PR #73182 — Don't inline CSS in RSC payload for client navigation
• #75648 — WhatsApp preview broken with inlineCss + Tailwind
• #83612 — Turbopack wrong font URL with inline CSS

La comunidad busca soluciones

• Discussion #82894 — How to prevent render-blocking with CSS Modules? (2025)
• Discussion #70526 — Ideas for reducing render-blocking CSS
• Discussion #59814 — Render blocking styles with Tailwind
• Discussion #49691 — How to deal with render-blocking modular CSS
• Discussion #59989 — Critical CSS inlining with App Router
• Discussion #80486 — Is optimizeCss still in use?
• Discussion #85465 — Turbopack plugin API (doesn't exist)

Bugs de CSS en Turbopack

• #68412 — Incorrect CSS modules load order with external components
• #76464 — Turbopack sometimes strips SCSS imports
• #82497 — SCSS module not loading when not-found.tsx is present
• #88544 — Exporting Sass variables from CSS modules doesn't work with Turbopack

Construido en Promova — una plataforma de aprendizaje de idiomas que sirve a millones de usuarios.

Next.js parchea el fetch global y añade una capa de caché que mantiene referencias a los datos de respuesta después de que deberían haber sido liberados. Cada llamada a fetch añade memoria que nunca es devuelta al GC. En Docker/Kubernetes esto provoca crashes OOM cada pocas horas. El bug existe desde Next.js 14 (abril 2024) y sigue sin resolverse en 16.2.x (marzo 2026). En Vercel el problema no se manifiesta gracias a las funciones serverless efímeras.

Cómo funciona fetch normalmente

Request → fetch → got data → response to user → GC cleans up → memory free

Cómo funciona fetch en Next.js

Next.js intercepta el fetch global y lo envuelve con su propia capa de caché/tracking:

Request → Next.js fetch wrapper → creates:
  - Performance entry (speed tracking)    ← not cleaned
  - Request metadata object               ← not cleaned
  - Internal promise wrapper              ← not cleaned
  - Cache lookup entry                    ← not cleaned
  - Response body (for unique URL)        ← not cleaned
→ Response to user
→ GC sees objects are still referenced → doesn't touch them
→ Memory grows indefinitely

Qué ocurre en producción

Self-hosted (Docker/K8s):
  Request 1:      fetch → +100KB → RAM: 100KB
  Request 2:      fetch → +100KB → RAM: 200KB
  Request 1000:   fetch → +100KB → RAM: 100MB
  Request 50,000: fetch → +100KB → RAM: 5GB → OOM Kill 💀
  → Kubernetes restarts the pod → cycle repeats

Vercel (Serverless):
  Request 1: [start] → fetch → +100KB → [process dies] → 0 KB ✅
  Request 2: [start] → fetch → +100KB → [process dies] → 0 KB ✅
  → Memory never accumulates

Versiones afectadas

Next.js — Todas las versiones con App Router

Node.js

Probado en Node.js 20, 22, 24, 25 — fuga en todos.

Qué no funciona

Qué funciona (workarounds)

Limitación del workaround con axios

Tus propias llamadas API pueden reemplazarse con axios. Pero Next.js usa internamente el fetch parcheado para:

• ISR (Incremental Static Regeneration)
• revalidatePath / revalidateTag
• Data fetching de Server Components con deduplicación
• use cache (Next.js 16)

Incluso sin un solo fetch en tu código — Next.js lo sigue usando internamente.

Por qué Vercel no lo arregla

Lógica de negocio

Vercel es una empresa que gana dinero alojando Next.js. En su plataforma el problema no se manifiesta (serverless = efímero). El bug solo afecta a self-hosted (Docker, K8s, VPS) — los que no pagan a Vercel.

Posición oficial

Tim Neutkens (mantenedor de Vercel) analizó el problema y declaró que es un problema de undici (biblioteca fetch de Node.js), no de Next.js. El issue #90433 fue cerrado. A pesar de que:

• axios y node-fetch en el mismo Node.js funcionan sin fugas
• La fuga solo aparece cuando fetch pasa por el wrapper de Next.js
• El bug lleva 2 años abierto sin solución

Prioridades

En estos 2 años el equipo de Next.js lanzó:

• Turbopack (builds 2-5x más rápidos) — ventaja de marketing
• Cache Components / use cache — reduce carga en servidores Vercel
• proxy.ts en lugar de middleware — simplifica el despliegue edge en Vercel
• DevTools MCP — hype de IA

¿Memory leak en self-hosted? No es prioridad.

Solución: AWS Lambda (SST + OpenNext)

Qué es

OpenNext es un adaptador open-source que convierte un build de Next.js en formato para AWS Lambda. SST es un framework que automatiza la infraestructura.

Arquitectura

Next.js build
  → OpenNext
    → AWS Lambda (SSR, API routes)
    → S3 (static, assets)
    → CloudFront (CDN)
    → SQS + DynamoDB (ISR revalidation)

Por qué esto resuelve el memory leak

Las funciones Lambda procesan peticiones y se reciclan tras 5-15 minutos de inactividad. La memoria no tiene tiempo de acumularse.

Despliegue

npx sst@latest init
npx sst deploy --stage production

Comparación

Matices de Lambda

• Cold starts — la primera petición es más lenta (~200-500ms)
• Seguridad — activar OAC (Origin Access Control), sino la URL de Lambda es pública
• OpenNext — proyecto comunitario, no oficial de Vercel. Nuevas funciones de Next.js pueden romperse
• Ataque al monedero — durante DDoS, el auto-scaling de Lambda puede generar una factura grande

Por qué una solución real es poco realista

1. Problema arquitectónico

La fuga no es un bug accidental sino consecuencia de una decisión de diseño: Next.js intercepta el fetch global y añade caché/tracking encima. Para arreglarlo hay que rediseñar cómo App Router interactúa con fetch. Esto afecta ISR, revalidation, data cache, request deduplication — el núcleo del framework.

2. Conflicto de intereses

Vercel no está motivado a arreglar lo que no afecta su plataforma. Self-hosted compite con su negocio. Cuantos más problemas en self-hosted — más personas migran a Vercel.

3. Echar la culpa

La posición oficial es "es undici, no nosotros". Hasta que eso cambie — no trabajarán en una solución.

4. Sin solución comunitaria

La licencia AGPL-3.0 de Next.js permite forks, pero la base de código es enorme y está estrechamente acoplada con la infraestructura de Vercel. Un PR comunitario para arreglar el wrapper de fetch requeriría un profundo conocimiento de la arquitectura interna y la aprobación de los mantenedores — que ya cerraron el issue.

Conclusiones

1. Si estás en Vercel — no hay problema, nada que hacer
2. Si self-hosted y necesitas serverless — SST + OpenNext en AWS Lambda
3. Si self-hosted Docker — reemplazar fetch con axios donde sea posible, monitorear RAM, configurar reinicios automáticos de pods
4. Si empiezas un proyecto nuevo — considerar SvelteKit o Nuxt como alternativas sin este problema

Fuentes

• Issue #64212 — Memory Leak with global fetch (April 2024)
• Issue #68578 — Possible memory leak in Fetch API (August 2024)
• Issue #85914 — Memory Leak with fetch + standalone (November 2025)
• Issue #90433 — OOM in 16.0.10 (February 2026)
• Discussion #88603 — OOM in Docker/K8s (January 2026)
• Discussion #88078 — cacheMaxMemorySize behavior
• OpenNext
• SST — Next.js on AWS
• Secret knowledge to self-host Next.js
• Next.js Memory Usage Guide