Imagen generada con Gemini

Tu documentación miente y tu prototipo lo sabe

Si trabajas en producto, esto te va a sonar: partes un proyecto con un PRD impecable, flujos mapeados, métricas claras y casos de uso bien documentados. Tres doritos después, el prototipo ya evolucionó cinco veces, tomaste un montón de decisiones sobre la marcha, y esa documentación que tanto te costó armar describe un producto que ya no existe.

Y ojo, no es que documentes mal. La cosa es que la documentación y el prototipo viven a velocidades distintas. La spec la escribes una vez y actualizarla cuesta; el prototipo, en cambio, cambia cada vez que iteras. Si no hay algo que los mantenga conversando, el drift es cuestión de tiempo.

Acá te explico la forma en la que estoy trabajando con Claude Code y Claude Cowork sincronizados, pensada sobre todo para PM, PO y UX, donde la documentación deja de ser un documento muerto y pasa a ser un contrato vivo entre las dos herramientas.

Dos cerebros, dos pegas

Antes de meternos en carpetas y archivos, hay que separar bien qué hace cada herramienta. Ahí está la clave de todo.

Claude Cowork es el cerebro de producto. Es donde orquestas la investigación, sintetizas hallazgos, defines el problema, ordenas las métricas, exploras soluciones, mapeas flujos y casos, y armas el PRD completo. Cowork no toca el código del prototipo: piensa, sintetiza y mantiene la narrativa del por qué estás construyendo lo que construyes.

Claude Code es el ejecutor. Es donde el prototipo cobra vida y se itera. Acá ajustas, pruebas, botas, rehaces. Es rápido y concreto, pero por su propia naturaleza está enfocado en el cómo, y mientras más avanza, más se aleja del por qué.

El drift nace justo en la frontera entre estos dos mundos: cuando el ejecutor toma decisiones que el cerebro de producto nunca se entera.

La carpeta /docs como contrato, no como bodega

La intuición correcta es meter la documentación dentro del proyecto de Claude Code y versionarla junto al prototipo. Es el patrón docs-as-code, y tiene ventajas reales: una sola ubicación física, historial en git, y ambas herramientas mirando exactamente los mismos archivos.

Pero acá hay una distinción que lo cambia todo. Compartir esa carpeta con Cowork resuelve el acceso; no resuelve la sincronización. Que ambas herramientas puedan ver lo mismo no significa que la documentación se vaya a actualizar sola cuando el prototipo cambie. El drift es un problema de proceso, no de dónde guardas los archivos.

La diferencia está en cómo piensas la carpeta /docs:

• Como bodega, es donde tiras archivos para que Cowork los lea. Pasivo. El drift sigue igual.
• Como contrato, es la interfaz compartida entre dos agentes con roles definidos. Cowork escribe la intención, Claude Code escribe la implementación y deja registradas sus desviaciones, y ambos saben exactamente qué pueden tocar y qué no.

Todo lo que viene después es, básicamente, convertir esa carpeta en un contrato.

Una estructura que separa intención de implementación

La regla de oro: cada artefacto tiene una fuente de verdad clara. El PRD y la research son la verdad de producto. El código es la verdad de implementación. El drift aparece en la brecha entre ambos, así que necesitas un lugar explícito donde esa brecha quede anotada.

Una estructura que funciona bien:

mi-proyecto/
├── CLAUDE.md                    # El contrato: reglas de juego para Claude Code
├── src/                         # El prototipo (verdad de implementación)
└── docs/
    ├── product/
    │   ├── prd.md               # PRD completo y detallado
    │   ├── research.md          # Síntesis de investigación
    │   ├── metrics.md           # Métricas y objetivos
    │   └── problem.md           # Definición del problema
    ├── ux/
    │   ├── flows.md             # Flujos de usuario
    │   ├── cases.md             # Casos de uso y edge cases
    │   └── states.md            # Estados de UI (vacío, error, carga, etc.)
    ├── decisions/
    │   └── log.md               # Decision log: dónde se captura el drift
    └── _sync/
        └── reconciliation.md    # Reporte de divergencias spec vs. código

Las carpetas product/ y ux/ son territorio de Cowork. La carpeta decisions/ la escribe Claude Code mientras itera. Y _sync/ es donde Cowork, al cerrar cada ciclo, deja constancia de lo que se alineó y lo que quedó pendiente.

El decision log: cachar el drift en el momento exacto

Este es el componente que casi todos los flujos se saltan, y es el más importante. Un decision log es un archivo donde cada decisión que desvía el prototipo de la spec queda registrada en el momento que pasa, no tres semanas después cuando ya nadie se acuerda por qué.

No tiene que ser nada elaborado. Una entrada por decisión y listo:

## 2026-06-03 — Onboarding pasó de 3 pasos a 2

**Contexto:** El PRD especificaba un onboarding de 3 pasos (perfil → preferencias → tutorial).
**Decisión:** Fusionamos preferencias y tutorial en una sola pantalla.
**Razón:** En el prototipo el paso 3 se sentía redundante; el tutorial cobra
más sentido contextualizado dentro de preferencias.
**Impacto en la spec:** Contradice `product/prd.md` §4.2 y `ux/flows.md`.
**Estado:** Pendiente de reconciliar con Cowork.

Cada entrada es una señal de drift declarada en voz alta. En vez de que la divergencia se esconda en el código, queda visible y trazable. Cuando Cowork hace su pasada de reconciliación, este archivo es directamente su lista de tareas.

CLAUDE.md: convertir la disciplina en automatismo

CLAUDE.md es el archivo que Claude Code lee como instrucciones permanentes del proyecto. Es el lugar perfecto para dejar el contrato escrito, así la disciplina de documentar no depende de que te acuerdes en cada sesión (porque no te vas a acordar, seamos honestos).

# Reglas del proyecto

## Documentación
- La carpeta `docs/` es la fuente de verdad de producto. NO la contradigas en silencio.
- Antes de cambiar un comportamiento que afecte un flujo o un caso de uso,
  revisa `docs/product/prd.md` y `docs/ux/flows.md`.
- Si una iteración del prototipo se desvía de la spec, registra la decisión
  en `docs/decisions/log.md` ANTES de continuar, usando el formato establecido.
- No edites archivos en `docs/product/` ni `docs/ux/`: esos los mantiene Cowork.
  Tu canal para reportar cambios es `docs/decisions/log.md`.

Con esto, Claude Code va dejando migas de pan cada vez que se aleja de la spec, sin que tengas que andar pidiéndoselo.

Front-matter para que Cowork sepa qué sigue vigente

Para que Cowork pueda auditar la documentación con criterio, cada .md de producto y UX debería partir con un poco de metadata estructurada:

---
status: vigente        # vigente | en-revisión | obsoleto
owner: producto
last_updated: 2026-06-03
related: [ux/flows.md, decisions/log.md]
---

Esto le da a Cowork las pistas para detectar inconsistencias: un documento marcado como vigente que tiene un related apuntando a un decision log con entradas sin reconciliar es, casi seguro, un documento desactualizado.

El ritual de reconciliación

Todo lo anterior se activa con un ritual simple, que corres al cerrar cada iteración del prototipo. En tu proyecto de Cowork, le pides una auditoría de sincronización:

1. Leer docs/decisions/log.md y filtrar las entradas en estado pendiente.
2. Contrastar cada desviación contra el PRD, los flujos y los casos afectados.
3. Para cada una, decidir: ¿actualizamos la spec para reflejar la nueva realidad, o devolvemos el prototipo porque la decisión de producto sigue en pie?
4. Actualizar los documentos de product/ y ux/ que correspondan.
5. Escribir un resumen en docs/_sync/reconciliation.md y marcar las entradas del log como reconciliadas.

Y acá está el cambio de fondo: el drift deja de acumularse en silencio. Cada ciclo termina con la documentación y el prototipo declarados como alineados — o con una lista explícita de lo que falta alinear — . La pregunta “¿esta doc todavía describe el producto?” por fin tiene una respuesta verificable.

Por qué este reparto de roles importa

Podrías intentar que Claude Code mantenga toda la documentación, o que Cowork meta mano directo en el código. Cualquiera de los dos caminos te diluye las fortalezas de cada herramienta.

Claude Code es la raja iterando, pero pedirle que además sea el guardián de la narrativa de producto lo distrae de lo que hace bien. Cowork es brillante sintetizando y razonando sobre producto, pero no es el lugar para iterar un prototipo línea por línea. El sistema funciona justamente porque cada uno hace lo suyo, y la carpeta /docs —con su decision log y su ritual de reconciliación— es el puente entre los dos.

Para cerrar

• Comparte la documentación dentro del repo, pero piénsala como un contrato entre dos agentes, no como una bodega de archivos.
• Separa intención de implementación: el PRD es la verdad de producto, el código la de implementación, y necesitas un lugar explícito para la brecha.
• El decision log es el corazón del sistema: cacha el drift en el momento exacto en que ocurre.
• **CLAUDE.md convierte la disciplina en automatismo** y le deja claro a Claude Code qué tocar y qué no.
• El ritual de reconciliación transforma el drift de un problema invisible y acumulativo en una lista de tareas que revisas cada ciclo.

Así la documentación deja de ser una foto que se desactualiza y pasa a ser un sistema vivo. El prototipo va a seguir ganándole en velocidad a la spec — eso no va a cambiar — , pero ahora, cada vez que se adelanta, deja una huella que el cerebro de producto puede seguir.