Portfolio Detachability, proyectos que se pueden separar

Tiempo: unos 25 min de teoría + 40 min de práctica

Lo esencial

La mayoría de los fundadores comete al principio un error silencioso: construye una "plataforma" donde todos los proyectos están entrelazados. En el papel parece un ahorro: un repositorio, una base de datos, un config. En la práctica, al cabo de un año se vuelve una maraña de cables donde no puedes desconectar uno sin apagar toda la casa.

Luego llega el momento: hay que vender el proyecto X. O cerrarlo. O pasárselo al equipo de un socio. Y resulta que no se puede, porque el Worker del proyecto X lee un secreto del proyecto Y, la voz de marca vive en el IDENTITY.md de la plataforma y la mitad de las tablas de producción del proyecto X son un shared schema con todos los demás.

Portfolio Detachability es un principio de ingeniería que te protege de esa trampa desde el día 1. La idea es simple: la plataforma por un lado, los proyectos por otro. La plataforma vive mucho tiempo (10 a 50 años). Los proyectos llegan y se van. Quitar un proyecto no debe romper la plataforma, ni los demás proyectos, ni el propio proyecto que se va (su nuevo dueño debe recibir algo que funcione).

En esta lección vemos cómo diseñar algo así, cómo probar la separabilidad (detachability) de forma constante y cuáles son las 4 líneas rojas que nunca se cruzan.

🎨 Imagínalo así: un edificio de departamentos vs. casas independientes en la misma calle. En el edificio, tu baño comparte bajante con el vecino: alguien se muda y hay inundación para todos. En las casas, cada una tiene su baño, su drenaje, su instalación eléctrica. Por fuera la diferencia es pequeña: el tubo es un poco más largo. A diez años, es la diferencia entre "vendí la casa" y "no puedo venderla hasta remodelar toda la calle".

Conceptos clave

• Portfolio Pattern: un modelo de arquitectura: la plataforma = nivel de infraestructura (engineering charter + shared services), los proyectos = startups independientes (su marca, su público, su economía)
• Detachability: una propiedad del proyecto: se puede recortar de la plataforma en un tiempo razonable (horas, no semanas) sin romper la plataforma y sin que el proyecto deje de funcionar
• Namespace: un espacio aislado de datos y código con sus propias reglas de acceso. En el Portfolio Pattern suelen ser 4: CORE / SHARED / PROJECT-OWNED / PRIVATE
• Coupling (acoplamiento): el grado en que una parte del sistema depende de otra. En el contexto de proyectos: hard-coupling (no se puede quitar sin romper) vs. loose-coupling (se puede quitar y lo demás funciona)
• Anti-coupling rules: restricciones formales que impiden que aparezca el acoplamiento (por ejemplo: prohibido poner datos específicos de un proyecto en CORE)
• Strangler Fig pattern: un patrón para romper el acoplamiento poco a poco: el código nuevo se escribe bien y el viejo se muda al namespace correcto un componente a la vez
• Detachment artifact: el conjunto de archivos e instrucciones que se entrega al nuevo dueño al vender o archivar un proyecto (código, marca, base de clientes, runbook, entrega de secretos)
• Sale-readiness: el estado formal de un proyecto: separable + documentado + secretos aislados + compila de forma independiente

Teoría

De dónde sale el problema

El acoplamiento rara vez aparece por una sola decisión. Son decenas de pequeños "así es más rápido" que se van juntando.

Una historia típica:

• Mes 1. Lanzamos la plataforma. Hay un solo proyecto: una agencia inmobiliaria. La voz de marca la escribimos en el IDENTITY.md de la plataforma. "Luego lo sacamos, por ahora así".
• Mes 4. Aparece un segundo proyecto: una escuela en línea. Creamos shared/brand-voice.ts. Pero la mitad de sus líneas son específicas de la agencia inmobiliaria ("asesor tranquilo, no vendedor"). La escuela hereda y sobrescribe. Funciona.
• Mes 9. Tercer proyecto: un servicio por suscripción. Tiene su propio público. Pero usa el mismo shared/auth.ts, que lee el namespace de Cloudflare KV REALTY_USERS. Todos los usuarios viven en una sola tabla. "Luego los separamos".
• Mes 14. Aparece un comprador para la agencia inmobiliaria. Está dispuesto a pagar una suma seria. Pregunta: ¿qué estoy comprando, una carpeta o toda la plataforma? Te das cuenta de que no se puede separar en una semana. El comprador se va.

Cada decisión por separado era razonable. La suma es una catástrofe.

🎨 Imagínalo así: dos árboles de especies distintas con las raíces entrelazadas. Cada raicita por separado es delgada. En conjunto, solo puedes arrancar un árbol llevándote el otro.

Portfolio Pattern: el Startup Studio y las startups independientes

El modelo más limpio es el Startup Studio (una incubadora de nueva generación).

🎨 Imagínalo así: un Startup Studio es una empresa que lanza varios negocios a la vez. El Studio pone la infraestructura común: área legal, DevOps, contabilidad, metodología. Cada startup del portafolio es un negocio independiente: su marca, su público, su propio estado de resultados (P&L). Una startup se puede vender a un inversionista estratégico, cerrar o hacer crecer con un equipo aparte, y el Studio sigue funcionando y lanza la siguiente.

Reglas del Portfolio Pattern:

1. La plataforma no cambia por una sola startup. YC respaldó a Airbnb y los estatutos de YC no se reescribieron para Airbnb. Tu plataforma lanzó un producto nuevo y el IDENTITY.md de la plataforma se quedó igual.

2. Las startups son autónomas. Cada una tiene su marca, su base de clientes, su CLAUDE.md, su base de datos (o al menos su namespace en la común). La startup toma sus propias decisiones de producto dentro del marco de arquitectura de la plataforma.

3. Las startups pueden salir del portafolio. Venta, cierre, traspaso a un equipo: la arquitectura debe aguantar cualquier salida. Si se vende una startup, la plataforma y las demás startups siguen funcionando sin un solo cambio.

4. Los Platform Services son comunes. Auth, monitoreo, seguridad: para todas las startups. Es normal: ese es el sentido de la plataforma. Pero los servicios no deben contener lógica específica de un proyecto. Son universales por diseño.

Los 4 namespaces a detalle

CORE (federal, nivel de reglas básicas)

Qué hay: CLAUDE.md, IDENTITY.md, VISION.md, MEMORY.md, reglas para separar el contexto, reglas de seguridad, catálogo de skills, strategy/engineering-charter.md.

Reglas:

• Solo cambia mediante una enmienda formal a los estatutos (con una pausa para pensarlo, por ejemplo 7 días)
• No contiene nada específico de un proyecto
• No contiene ni un solo nombre de proyecto en la lógica de negocio (en los ejemplos sí está bien)
• Principios universales, vetos, identidad de la plataforma

Prueba de limpieza de CORE: abre IDENTITY.md y busca nombres de proyectos (por ejemplo, "realty", "school"). Si aparecen fuera de la sección "ejemplos de proyectos", es una fuga. Hay que corregirla.

SHARED (servicios federales)

Qué hay: departments/, tools/, infrastructure/ (si lo usan varios proyectos), .claude/agents/ (subagentes comunes), skills comunes.

Reglas:

• Lo usan al menos 2 proyectos al mismo tiempo
• Universal por diseño (interface-first, no "aquí está el código para la agencia inmobiliaria y los demás se adaptan")
• Un cambio requiere evaluar el impacto: ¿a qué proyectos afecta?

Prueba: si un código lo usa un solo proyecto, no va en SHARED. Muévelo a projects/<X>/.

PROJECT-OWNED (estado)

Qué hay: projects/<name>/ completo.

Adentro suele haber:

• CLAUDE.md (contexto del proyecto; se refiere a CORE con @~/platform/CLAUDE.md)
• BRAND-VOICE.md (la marca solo de este proyecto)
• code/ o app/ (código fuente)
• customers/ o db/ (datos aislados)
• deployments/ (su propio wrangler.toml, sus propios secretos de Cloudflare con prefijo del proyecto)
• decisions/ (bitácora de decisiones del proyecto)
• HANDOFF.md (lo que necesita saber el nuevo dueño)

Reglas:

• Todo lo específico del proyecto vive aquí
• No depende de otros projects/<Y>/
• Puede depender de CORE y SHARED, pero a través de interfaces documentadas

PRIVATE (personal)

Qué hay: carpeta personal del dueño, archivo cifrado con claves, configuración de la llave de hardware, carta para un sucesor.

Reglas:

• Nunca se entrega al vender un proyecto
• No se cruza con PROJECT-OWNED
• Acceso: solo el dueño de la plataforma, con llave de hardware

Detachability test (la herramienta principal)

Una sola pregunta define la salud de la arquitectura:

Si mañana borro toda la carpeta projects/X/, ¿qué se rompe?

Respuestas posibles y lo que significan:

Principio: la prueba no se corre una vez, sino en cada release. De preferencia, automatizada (un paso de CI: simular el borrado del proyecto en una rama efímera y compilar los demás).

🎨 Imagínalo así: el juego de Jenga. Cada vez que agregas un bloque, revisas la estabilidad de toda la torre. En la arquitectura de una plataforma es un ritual gratuito y obligatorio. Si no, al cabo de un año la torre "está de pie, pero no se puede sacar nada".

4 Red Lines (reglas contra el acoplamiento)

Son prohibiciones formales. No son "best practices": son líneas rojas, como en seguridad. Romperlas = deuda técnica que crece de forma exponencial.

Red Line 1: no meter datos específicos de un proyecto en CORE

❌ No se vale:

• La biografía de la cara de la marca de la agencia inmobiliaria en el IDENTITY.md de la plataforma
• La lista de competidores de la escuela en línea en un COMPETITORS-PLAYBOOK.md común en CORE
• La voz de marca de la agencia inmobiliaria en el CLAUDE.md de la plataforma
• Las personas de cliente del proyecto en el MEMORY.md de la plataforma

✅ Lo correcto:

• Datos específicos del proyecto → projects/<X>/
• En CORE, solo principios universales y la identidad de la propia plataforma

Red Line 2: no cambiar CORE mientras trabajas en un proyecto

Si la sesión se declaró como "trabajamos en la agencia inmobiliaria", el plan general de la plataforma, IDENTITY.md, VISION.md y la carpeta personal del dueño no se tocan. Aunque "de paso viste un error de dedo". Sobre todo si "de paso viste un error de dedo": es el canal de fuga más común.

Si el error es importante: una sesión aparte de "trabajamos en la plataforma", un commit aparte, una entrada aparte en la bitácora.

Red Line 3: no duplicar datos entre namespaces

Una sola fuente de verdad por tipo de dato.

❌ No se vale:

• Las reglas de marca tanto en las reglas personales del dueño de la plataforma como en projects/realty/BRAND-VOICE.md
• Las decisiones del proyecto tanto en el journals/decisions.md de la plataforma como en projects/<X>/decisions/
• La lista de clientes en SHARED y en PROJECT-OWNED

✅ Lo correcto:

• Un archivo = una fuente de verdad
• En la carpeta del proyecto, una referencia @~/platform/IDENTITY.md si hace falta contexto de CORE

Red Line 4: no confundir al dueño de la plataforma con las personas de los proyectos

❌ No se vale:

• Aplicar el estilo de marca de un proyecto al propio dueño de la plataforma
• Aplicar la biografía de una persona de proyecto (por ejemplo, la cara de la marca de la agencia inmobiliaria) al contenido de otro proyecto (por ejemplo, la escuela en línea)
• Usar la voz de uno de los proyectos en la comunicación de la plataforma

✅ Lo correcto:

• El dueño de la plataforma = guardián del sistema, no un producto
• Cada persona de proyecto = su propia identidad dentro de projects/<X>/
• La escuela en línea (si se lanza) = otra persona aparte

Recorrido de un escenario de venta

Supongamos que llega un comprador para el proyecto realty. Está dispuesto a pagar una suma seria. ¿Qué entregas?

Se entrega (PROJECT-OWNED):

• La carpeta projects/realty/ completa
• El código del proyecto
• La marca: BRAND-VOICE.md, assets, logo
• La base de clientes (con una transferencia que cumpla la ley de protección de datos aplicable, como el GDPR o la ley de tu país, o con seudonimización si el contrato lo pide)
• El dominio (realty-example.com, si se registró para el proyecto)
• La cuenta de Cloudflare del proyecto (si está aislada) O un plan de migración a la nueva cuenta del comprador
• Tokens de bots y claves de API específicos del proyecto (por un canal seguro, no por email)
• HANDOFF.md: el runbook para el nuevo dueño
• La bitácora de decisiones decisions/

Se queda (CORE + SHARED + PRIVATE):

• La plataforma completa
• Todos los demás proyectos
• Las reglas y datos personales del dueño de la plataforma
• Engineering Charter, IDENTITY, VISION
• El archivo cifrado con claves, la llave de hardware

Qué hay que dejar por escrito en el contrato:

• Plazo para migrar los secretos (normalmente 7-14 días)
• Plazo para transferir el dominio (propagación de DNS, 48-72 h)
• Qué NO recibe el comprador: la marca de la plataforma, la metodología, el código de SHARED (que el proyecto solo usaba)
• No competencia durante la transición (si aplica)
• Soporte al comprador el primer mes (horas, formato)

Qué debe pasar técnicamente en un día:

1. Una rama efímera sale/realty-detach
2. Borrar projects/realty/ de la rama main (el historial de git se queda: muestra que el proyecto existió)
3. Compilar todos los demás proyectos: deben pasar
4. Correr las pruebas de la plataforma: deben pasar
5. Si algo falla, hay hidden coupling. La venta se pone en pausa hasta corregirlo.

🎨 Imagínalo así: rentar un departamento. Si no puedes mudarte en una semana llevándote tus cosas y dejando el lugar listo para el siguiente inquilino, viviste mal. Guardaste cachivaches en las bodegas comunes, pusiste tu lavadora en el pasillo. El Portfolio Pattern desde el día 1 es el hábito de vivir de forma que mudarte sea posible.

Strangler Fig pattern: romper el acoplamiento poco a poco

¿Qué hacer si ya todo está entrelazado y el detachability test muestra una catástrofe?

No hacer un refactoring de golpe (big bang). Strangler Fig es un patrón para romperlo poco a poco.

La idea: el acoplamiento viejo no se toca, pero el código nuevo se escribe bien. Poco a poco, los componentes se mudan a los namespaces correctos y los viejos desaparecen.

Paso a paso:

1. Congelamos el acoplamiento. En CI agregamos un hook: "los archivos nuevos en shared/ no pueden contener nombres de proyectos". No dejamos que la basura siga creciendo.
2. Catalogamos lo que existe. Un solo documento: coupling-inventory.md. Qué está entrelazado y dónde, severidad, responsable.
3. Atacamos por prioridad. Lo más peligroso es el acoplamiento que bloquea una venta. Menos peligroso: el que estorba el desarrollo.
4. Un acoplamiento = un PR. No "limpié medio sistema en una semana". Limpiamos de forma puntual, con pruebas de regresión en cada paso.
5. Detachability test después de cada PR. ¿Se mueve la métrica? ¿El proyecto está más cerca de ser separable? Si no, algo anda mal con el enfoque.

Ritmo realista: una ruptura de acoplamiento importante por semana. En medio año, el sistema llega a un estado limpio.

Antipatrones (a detalle)

Monorepo coupling

Síntoma: todos los proyectos en un solo workspace de npm/cargo/Python, un package.json compartido con dependencias específicas de proyectos.

Por qué es malo: al vender un proyecto, el comprador recibe todo el monorepo (del que no necesita el 90%) o hay que pasar un mes desenredando dependencias.

Remedio: workspaces por proyecto (projects/<X>/package.json) + un núcleo compartido mínimo con una interfaz explícita.

Base de datos compartida sin fronteras

Síntoma: una sola base de Cloudflare D1, todos los proyectos escriben en las mismas tablas, separados por una columna project_id.

Por qué es malo: al vender un proyecto hay que exportar las filas con project_id = X, limpiar llaves foráneas, comprobar que no se rompió nada a los demás. Y todo eso con la carga de producción encima.

Remedio: un namespace por proyecto. En Cloudflare, un D1 / KV namespace aparte por proyecto. En Postgres, un schema o una base de datos aparte. El costo extra es mínimo; la ganancia en separabilidad es enorme.

Configuración específica de un proyecto en archivos de toda la plataforma

Síntoma: en el wrangler.toml de la plataforma están las routes de todos los proyectos. En el .env de la plataforma, los secretos de todos los proyectos con prefijos.

Por qué es malo: el nuevo dueño del proyecto no puede simplemente copiar la configuración: ahí hay secretos y routes ajenos.

Remedio: un wrangler.toml por proyecto. Un .env.<project> por proyecto. A nivel de plataforma, solo la infraestructura que atiende a todos (monitoreo, respaldos).

El nombre "temporal" de un proyecto en CORE

Síntoma: "por ahora la plataforma = la agencia inmobiliaria, luego separamos". Un año después, el IDENTITY.md de la plataforma habla de vender departamentos.

Por qué es malo: cuando aparezca el segundo proyecto, esa línea se vuelve falsa. Vas a tener que corregirla cuando ya tengas tres proyectos y diez enredos. Sale más barato no escribir nunca líneas específicas de un proyecto en CORE desde el principio.

Remedio: si dudas, escribe en projects/<X>/. Súbelo a CORE cuando veas el patrón en 2 proyectos o más. Es la regla de "rule of three" aplicada a promover algo de namespace.

🧪 Práctica

Paso 1: auditoría de los namespaces del proyecto actual (15 minutos)

Abre tu proyecto (el que estás trabajando ahora) y haz un inventario. Crea un archivo coupling-inventory.md en la raíz del proyecto:

# Coupling Inventory — <project-name>

**Fecha:** YYYY-MM-DD
**Objetivo:** identificar qué hay en cada namespace y dónde hay acoplamiento

## Nivel CORE (plataforma)
Archivos donde aparece el NOMBRE DEL PROYECTO ACTUAL (es una fuga):
- [ ] CLAUDE.md — ¿aparece?
- [ ] IDENTITY.md — ¿aparece?
- [ ] VISION.md — ¿aparece?
- [ ] MEMORY.md — ¿aparece?

## Nivel SHARED
Archivos en shared/ o tools/ que usa SOLO este proyecto:
- [ ] lista

## PROJECT-OWNED
Lo que el proyecto tiene como propio:
- [ ] BRAND-VOICE.md
- [ ] CLAUDE.md del proyecto
- [ ] wrangler.toml aislado
- [ ] Namespace D1/KV aislado
- [ ] Secretos aislados con prefijo del proyecto

## Cross-project dependencies
Imports de otros projects/<Y>/ en el proyecto actual:
- [ ] lista

## Hidden coupling
- [ ] Cron / queue / webhook que tocan varios proyectos
- [ ] Variables de entorno compartidas
- [ ] Webhooks comunes

Llénalo con honestidad. No "pues creo que no": busca con grep por nombre:

# En la raíz de la plataforma
PROJECT_NAME="realty"  # pon el tuyo

# Dónde aparece el nombre del proyecto fuera de su propia carpeta
grep -r "${PROJECT_NAME}" . \
  --include="*.md" --include="*.ts" --include="*.js" --include="*.toml" \
  --exclude-dir="projects/${PROJECT_NAME}" \
  --exclude-dir="node_modules" \
  --exclude-dir=".git" \
  --exclude-dir="_archive"

Cada coincidencia es una posible fuga. Revísalas una por una.

Paso 2: detachability test (10 minutos)

Simulamos el borrado del proyecto sin borrarlo de verdad.

# Creamos una rama efímera
git checkout -b detachability-test/$(date +%Y%m%d)

# "Borramos" el proyecto
PROJECT_NAME="realty"
git rm -r projects/${PROJECT_NAME}/

# Compilamos los demás proyectos
for project in projects/*/; do
  name=$(basename "$project")
  echo "Building: $name"
  cd "$project"
  # Pon tu comando de build
  npm run build 2>&1 | tail -5
  cd - > /dev/null
done

# Corremos las pruebas de la plataforma
npm test 2>&1 | tail -10

# Corremos lint / type check de la plataforma
npm run lint 2>&1 | tail -5

Lo que debe pasar:

• Todos los builds de los demás proyectos pasan
• Las pruebas de la plataforma pasan
• Lint limpio
• Ni un solo import roto

Si algo falló, ese es tu acoplamiento. Anótalo en coupling-inventory.md bajo "Hidden coupling".

Lo más importante: después de la prueba, git checkout main && git branch -D detachability-test/.... Fue una simulación, no se borró nada de verdad.

Paso 3: limpiamos un acoplamiento (15 minutos)

Toma un acoplamiento que encontraste, el que cueste menos esfuerzo. Le aplicamos Strangler Fig.

Ejemplo: en shared/brand-voice.ts hay líneas específicas de la agencia inmobiliaria.

// ANTES — shared/brand-voice.ts
export const brandVoice = {
  tone: "asesor tranquilo, no vendedor",  // ¡específico de la agencia inmobiliaria!
  avoidPhrases: [
    "soy experto",  // regla de este proyecto
    "los mejores precios de la ciudad",  // regla de este proyecto
    "compra antes de que se acabe"  // regla de este proyecto
  ]
}

Paso 1. Movemos lo específico al proyecto:

// DESPUÉS — projects/realty/brand-voice.ts
import { BaseBrandVoice } from "@platform/shared/brand-voice"

export const realtyVoice: BaseBrandVoice = {
  tone: "asesor tranquilo, no vendedor",
  avoidPhrases: [
    "soy experto",
    "los mejores precios de la ciudad",
    "compra antes de que se acabe"
  ]
}

Paso 2. SHARED se vuelve una interfaz universal:

// DESPUÉS — shared/brand-voice.ts
export interface BaseBrandVoice {
  tone: string
  avoidPhrases: string[]
  // ... otros campos universales
}

export function validateContent(content: string, voice: BaseBrandVoice): ValidationResult {
  // lógica de validación universal
}

Paso 3. Prueba de regresión:

# Debe pasar como antes
npm test
# El detachability test debe mostrar avance
git checkout -b detachability-test/iter2
git rm -r projects/realty/
npm test  # ahora shared/brand-voice.ts pasa sin las líneas del proyecto inmobiliario
git checkout main && git branch -D detachability-test/iter2

Un acoplamiento roto. Lo anotamos en decisions:

## YYYY-MM-DD: Se rompió el acoplamiento shared/brand-voice → realty

**Context:** shared/brand-voice.ts tenía líneas específicas del proyecto
**Decision:** sacamos la interfaz a shared y la implementación a projects/realty/
**Impact:** sube la separabilidad del proyecto realty
**Tag:** detachability-iter1

Paso 4: documentamos HANDOFF.md (opcional, 15 minutos)

Cada PROJECT-OWNED debe tener un HANDOFF.md en su raíz. Es el documento para un hipotético nuevo dueño. Se escribe como si mañana le entregaras el proyecto a un desconocido.

Plantilla mínima:

# HANDOFF — <Project Name>

## Qué es
1-2 párrafos. Qué proyecto es, qué problema resuelve, quién es el público.

## Stack
- Frontend: ...
- Backend: ...
- Hosting: ...
- BD: ...
- Pagos: ...

## Cómo correrlo en local
```bash
cd projects/<name>
npm install
cp .env.example .env  # llenar los secretos, ver abajo
npm run dev
```

## Secretos (de dónde sacarlos)
- `STRIPE_SECRET_KEY` — dashboard de Stripe
- `CLOUDFLARE_API_TOKEN` — Cloudflare → My Profile → API Tokens
- ... (¡sin valores! solo instrucciones de dónde sacarlos)

## Deploy
1 párrafo. Qué hacer para subirlo a producción.

## Base de clientes
Dónde está, cómo exportarla, si la estructura cumple con la ley de protección de datos.

## Dominio y DNS
Dónde está registrado, de quién es la cuenta, cómo transferirlo.

## Riesgos conocidos
3-5 puntos de qué cuidar (APIs obsoletas, un certificado por vencer, deuda técnica en el módulo X).

## Contacto del dueño anterior
Email / horas de soporte el primer mes.

Este documento es el artefacto principal de la separabilidad. Si puedes escribir un HANDOFF.md honesto en una hora, el proyecto está listo para venderse. Si no, hay conocimiento oculto que hay que sacar de tu cabeza a un archivo.

⚠️ Antipatrones

❌ "Luego lo separamos": nunca se hace. El acoplamiento que no se rompió al inicio solo se rompe bajo presión (una venta, el agotamiento, un conflicto con un socio). En ese momento cuesta 10 veces más.

❌ Una sola cuenta de Cloudflare para todos los proyectos sin aislamiento: al vender un proyecto hay que migrarlo a otra cuenta. Si todos los Workers / KV / D1 están en una cuenta sin prefijos de proyecto, la migración tarda semanas.

❌ Routes específicas de proyectos en el wrangler.toml de la plataforma: cada proyecto debe tener su propio wrangler.toml. Un archivo que describe las routes de todos los proyectos se vuelve una maraña inseparable.

❌ La base de clientes en una tabla común con columna project_id: exportar las filas con project_id = X en teoría se puede. En la práctica hay llaves foráneas a tablas compartidas, columnas JSON con referencias a entidades de la plataforma, y la migración se come un sprint.

❌ La marca de la plataforma y la del proyecto mezcladas: si el nuevo dueño de la agencia inmobiliaria recibe un BRAND-VOICE.md donde la mitad de las reglas son de la plataforma, no podrá trabajar sin reescribirlo.

❌ Mover el acoplamiento a _archive/ en vez de romperlo: un error común. "El código viejo se fue al archivo, ya está limpio". Pero los imports del código principal al archivo siguen ahí. Eso no es romper el acoplamiento, es cambiarlo de lugar.

❌ Las bitácoras de la plataforma contienen decisiones de proyectos: el journals/decisions.md de la plataforma solo debe tener decisiones de CORE. Las decisiones del proyecto van en projects/<X>/decisions/. Si no, al vender el proyecto el nuevo dueño no recibe el contexto de las decisiones tomadas.

❌ La llave de hardware o la frase maestra en la carpeta de un proyecto: PRIVATE siempre se queda en PRIVATE. Si algo secreto se coló en projects/<X>/, es una violación y una posible fuga al vender.

🔗 Relacionado

• CLAUDE.md: el prompt de sistema de tu proyecto: cómo separar el contexto de la plataforma y el del proyecto
• La filosofía de las carpetas: el sistema PARA: una estructura de carpetas que sostiene el Portfolio Pattern
• Seguridad en Claude Code: .env y secretos: aislar los secretos por proyecto como base de la separabilidad
• Despliegue: Cloudflare Workers: un wrangler.toml por proyecto, aislamiento de namespaces
• Plantillas de 3 niveles: solo, mediana, corporativa: el contexto general de los patrones de producción

✅ Checkpoint

Antes de seguir, recorre la lista. Cada punto debe ser un "sí" honesto.

• Entiendo la diferencia entre los 4 namespaces: CORE / SHARED / PROJECT-OWNED / PRIVATE
• Puedo decir en un minuto en qué namespace debe ir cualquier archivo nuevo
• Tengo un coupling-inventory.md para mi proyecto actual
• Hice el detachability test (la simulación de borrar el proyecto en una rama efímera)
• Conozco al menos 3 acoplamientos ocultos en mi proyecto (si no hay, o el proyecto es perfecto o no busqué)
• Tengo un plan para romper un acoplamiento la próxima semana
• Puedo escribir en una hora un HANDOFF.md honesto para mi proyecto (o sé qué me falta)
• Conozco las 4 Red Lines y las recuerdo sin ayuda
• Entiendo cuándo el Portfolio Pattern sobra (un solo proyecto, no una plataforma: ahí es exagerado)

Si hay huecos, vuelve a la teoría. No es una lección para leer "por encimita". El acoplamiento que no frenes ahora, en un año va a bloquear tu libertad de acción.

Fuentes

• Martin Fowler — Strangler Fig Pattern (martinfowler.com)
• Sam Newman — "Monolith to Microservices": los capítulos sobre descomposición de bases de datos
• AWS Well-Architected Framework — Reliability Pillar, principios de aislamiento de fallas
• Y Combinator — el modelo Startup Studio, la independencia de las empresas del portafolio
• Cloudflare — buenas prácticas de aislamiento de namespaces (Workers KV, D1, R2)

Más sobre el tema → Production Observability: qué medir y dónde mirar cuando algo sale mal.