Documentación Viva: Magic Docs vs Synapse vs Codex
Tu documentación está desactualizada desde que la escribiste. Tres sistemas intentan resolverlo. Ninguno lo logra solo. Juntos serían imbatibles.
La documentación muere el día después de escribirla. Todo developer lo sabe. El README dice "18 módulos" pero el código tiene 21. El API doc lista 80 endpoints pero hay 95. El changelog no se actualiza desde hace tres sprints.
Este artículo cierra nuestra serie comparativa analizando cómo tres sistemas de CadencesLab atacan el mismo problema desde ángulos distintos:
Magic Docs
Claude Code — IA mantiene archivos automáticamente
Synapse Docs
Architecture-as-Code — docs estructurados con audit manual
Codex Index
Embeddings + Vectorize — búsqueda semántica
Y al final proponemos Magic Codex — un sistema que combina los tres para crear documentación que se escribe, actualiza, audita e indexa sola.
Magic Docs: IA que Mantiene tus Docs
Claude Code tiene un concepto brillante: si un archivo empieza con # MAGIC DOC: [Title], la IA lo mantiene automáticamente. Cuando el código relacionado cambia, un agente background actualiza el documento.
🪄 Cómo Funciona
# MAGIC DOC: Authentication System ## Overview JWT-based auth with refresh tokens. Entry point: `src/auth/index.ts` ## Architecture - Login → verify → issue JWT (15min) + refresh (7d) - Middleware: `authGuard()` in every protected route - Token storage: httpOnly cookie ## Key Files - `src/auth/jwt.ts` — token generation - `src/auth/middleware.ts` — route guard - `src/auth/refresh.ts` — token renewal ─────────────────────────────────── Auto-maintained by Claude Code. Last updated when auth/ changed. Philosophy: "BE TERSE. High signal only. OVERVIEWS, ARCHITECTURE, ENTRY POINTS"
✓ Fortalezas
- 100% automático (IA actualiza)
- Inline con el código (misma carpeta)
- Terse: solo lo esencial, signal > noise
- Se actualiza cuando el código cambia
✗ Debilidades
- Solo funciona con Claude Code
- Sin versioning (último estado)
- Sin búsqueda semántica
- Bajo descubrimiento (hay que saber que existe)
Architecture-as-Code: Docs Estructurados
Synapse Studio trata la documentación como un artefacto de ingeniería: archivos Markdown versionados en Git, con estructura predecible y métricas auditables.
📋 Documentos de Synapse
SYNAPSE_ARCHITECTURE.md
Métricas del sistema, módulos, líneas de código
SYNAPSE_CHANGELOG.md
Entradas por versión, cambios documentados
SYNAPSE_API.md
Endpoints documentados, parámetros, respuestas
SYNAPSE_AGENTS_GUIDE.md
Guía de agentes, capabilities, routing
🔍 El problema del drift: En el último audit de Synapse descubrimos que los docs decían "18 módulos" pero el código tenía 21. Decían "80+ endpoints" pero había 95. Decían "~6,900 líneas backend" pero había 8,562. La documentación driftea — siempre.
✓ Fortalezas
- Estructurado (formato predecible)
- Versionado en Git (historial completo)
- Comprehensivo (architecture + API + agents)
- Auditable (se puede verificar vs código)
✗ Debilidades
- Manual (requiere humanos para actualizar)
- Se desactualiza entre audits
- Sin search semántico (solo Ctrl+F)
- Sin automatización de updates
Indexación Semántica: Buscar sin Saber
Codex no genera docs — los indexa. Toma contenido existente, genera embeddings con bge-m3 via Workers AI, y los almacena en Vectorize para búsqueda semántica.
🔍 Pipeline de Indexación
// Codex Indexing Pipeline index-codex-content.cjs ├── Scan: 38 artículos Astro ├── Extract: sections, headings, paragraphs ├── Chunk: smart splitting (~500 tokens/chunk) ├── Embed: Workers AI (bge-m3) ├── Store: Vectorize index └── Result: 695 chunks searchables // Search flow User query → embed → nearest neighbors → ranked results "¿cómo funciona auth?" → [auth.astro §3, security.astro §2, ...]
✓ Fortalezas
- Búsqueda semántica (no necesitas saber la palabra exacta)
- Escala bien (695 → 10,000 chunks sin cambios)
- Agnóstico de formato (HTML, MD, Astro...)
- Re-indexación automática
✗ Debilidades
- No genera docs (solo busca lo que existe)
- No actualiza contenido (index ≠ update)
- Calidad depende de la fuente
- Sin versioning propio
Tabla Comparativa
| Aspecto | Magic Docs | Synapse | Codex |
|---|---|---|---|
| Auto-generación | ✅ IA | ❌ manual | ❌ solo indexa |
| Auto-update | ✅ al cambiar código | ❌ necesita audit | ✅ re-index |
| Búsqueda semántica | ❌ | ❌ | ✅ |
| Versioning | ❌ | ✅ Git | ❌ |
| Formato | Free text (terse) | Markdown estructurado | Chunks + embeddings |
| Precisión | Alta (IA lee código) | Driftea | Depende de fuente |
| Descubrimiento | Bajo | Medio | Alto |
| Tooling | Claude Code | Git + manual | Workers AI + Vectorize |
Magic Docs genera. Synapse estructura. Codex busca. Ninguno hace las tres cosas. Pero juntos...
Lo que Cada Uno Puede Aprender
Synapse ← Magic Docs
Añadir headers Magic Doc a docs existentes
Convertir SYNAPSE_ARCHITECTURE.md en # MAGIC DOC: Synapse Architecture. Cuando Claude Code edite Synapse, actualizará los docs automáticamente.
Auto-audit CI pipeline
En vez de auditar manualmente, un script CI cuenta módulos, endpoints, líneas → compara con lo que dicen los docs → si hay >10% discrepancia → PR automático con correcciones.
Claude Code ← Codex
Semantic index sobre Magic Docs
Indexar todos los Magic Docs con embeddings. De repente son buscables: "¿cómo funciona la autenticación?" → encuentra el Magic Doc de auth sin saber que existe.
Cross-reference graph
Los embeddings permiten descubrir docs relacionados automáticamente. Magic Doc de auth + Magic Doc de permisos → link automático detectado por cercanía vectorial.
Magic Codex: El Sistema Ideal
Si combinamos los tres approaches, emerge un sistema de 4 capas que resuelve el problema de documentación viva de manera definitiva:
✨ Magic Codex — 4 Capas
Magic Doc Headers — IA genera y mantiene documentación inline. Archivos con header # MAGIC DOC: que se actualizan automáticamente cuando el código cambia.
Structured Templates — Changelogs y architecture docs con formato predecible. Versionados en Git. El esqueleto no cambia — el contenido se auto-rellena.
Semantic Indexing — Todo chunk-eado y embebido en Vectorize. Búsqueda inteligente, cross-references automáticos, descubrimiento por similaridad.
CI/CD Integration — Pipeline de audit detecta drift. Auto-PR con correcciones. Re-indexing automático. Docs que se auditan solos.
💡 El sueño: documentación que se escribe sola (Magic Docs), se estructura sola (templates), se busca sola (embeddings), se audita sola (CI), y se corrige sola (auto-PR). Ninguno de los tres sistemas lo hace todo — pero juntos, es posible.
Plan de Implementación para CadencesLab
Añadir Magic Doc headers a docs de Synapse
Impacto inmediato. 30 minutos de trabajo. Los docs se actualizan solos cada vez que Claude Code toque el código.
CI script de audit de métricas
1 semana. Script que cuenta módulos, endpoints, líneas y compara con ARCHITECTURE.md. Alerta si drift > 10%.
Extender Codex indexer para Magic Docs
2 semanas. El indexer ya procesa Astro — añadir soporte para .md con header Magic Doc. Búsqueda semántica sobre docs técnicos.
Cross-reference graph con embeddings
1 mes. Para cada doc, calcular los N docs más cercanos vectorialmente. Generar links "Relacionados" automáticos.
Auto-PR on drift detectado
1 mes. Cuando el audit CI detecta discrepancia, generar PR automático con las correcciones. Review humano antes de merge.
10 Artículos, 1 Conclusión
Esta serie de 10 artículos — 6 deep-dives + 4 comparaciones — ha desarmado Claude Code pieza por pieza y lo ha comparado con nuestros propios sistemas. ¿La conclusión?
No se trata de quién es mejor.
Claude Code es un producto de consumo brillante construido para developers individuales. CadencesLab es una plataforma multi-tenant construida para empresas. Son dominios diferentes con restricciones diferentes.
Pero los patrones son transferibles. El tri-state ACL, la compresión progresiva, los Magic Docs, el sacred data pattern, el coordinator con workers aislados — cada uno de estos conceptos puede mejorar lo que construimos. Y eso es lo que haremos.
El mejor código no se escribe — se descubre comparando soluciones de otros que resuelven el mismo problema de otra manera.
¿Te gustó la serie?
En Cadences construimos sistemas que aprenden de los mejores — incluyendo Claude Code. Si quieres llevar estos patrones a tu producto, hablemos.
Gonzalo Monzón
Fundador de CadencesLab. Construye Synapse, Codex y NutriNen. Analizó Claude Code para extraer patrones que hagan mejores nuestros propios sistemas.