Llevo semanas construyendo Memorias, un entrevistador de voz con IA que se sienta a hablar con una persona mayor, sesión tras sesión, y convierte esas conversaciones en el material de un libro de memorias. No es un prototipo de fin de semana: tiene voz en tiempo real con Gemini, una base de datos con búsqueda semántica, un compositor que redacta capítulos y 54 tests en verde. Y lo he hecho solo.
La pregunta que me hago en cada proyecto es la misma: ¿cómo mantengo la calidad de un equipo siendo una sola persona? En mi workflow anterior respondí con un sistema propio de nueve agentes sobre un proyecto Django. Esta vez cambié de estrategia: en lugar de fabricarme el andamiaje a mano, apoyé todo el desarrollo en Superpowers, un conjunto de skills para Claude Code que imponen un proceso —diseñar antes de programar, escribir el test antes que el código, revisar antes de mergear— y lo combiné con desarrollo dirigido por agentes. Este artículo es la crónica técnica de cómo encaja todo eso, con el proyecto real por delante como prueba.
El proyecto: un entrevistador que escribe libros
Memorias nace de una idea sencilla y un poco melancólica: la voz y las historias de nuestros mayores se pierden. Un biógrafo profesional cuesta entre 800 y 5.000 euros y no escala. La propuesta es un entrevistador de IA que hace el trabajo de campo —conversar con calma, sin interrogar— y deja el testimonio listo para convertirse en un libro, un podcast o un audiolibro.
Por dentro son tres subsistemas sobre una misma base de datos PostgreSQL con pgvector:
- Voz en vivo. Un servidor FastAPI abre un WebSocket con el navegador. El usuario habla con un orbe en pantalla; el audio viaja en PCM a la Live API de Gemini a través del Agent Development Kit (ADK) de Google, y la respuesta vuelve como voz. Todo el turno queda transcrito y guardado según llega, para que un corte de conexión no pierda material.
- Compositor de capítulos. Un pipeline offline recupera los fragmentos de un entrevistado por similitud semántica, los agrupa en capítulos que emergen del propio material (sin catálogo fijo) y los redacta en primera persona: planifica una escaleta de beats, escribe beat por beat y pasa un juez editorial que detecta invenciones contra el texto crudo.
- Datos. El pegamento. Un modelo de dominio que encadena
Subject → Session → Utterance → Chunk → ChapterDraft, con embeddings de 768 dimensiones e índice HNSW para la búsqueda por coseno.
El stack, resumido:
| Capa | Tecnología |
|---|---|
| Voz y agente | Google ADK + Gemini Live (gemini-3.1-flash-live-preview, voz Sulafat) |
| Servidor | FastAPI + WebSocket, Runner.run_live() de ADK |
| Frontend | HTML/CSS/JS vanilla, orbe + AudioWorklets (16 kHz entrada / 24 kHz salida) |
| Datos | PostgreSQL 16 + pgvector, SQLAlchemy async (asyncpg), migraciones con Alembic |
| Composición y post-proceso | Gemini 2.5 Flash (JSON mode) + embeddings gemini-embedding-001 |
| Calidad | pytest (54 tests), ruff, CI en GitHub Actions |
Son unas 3.600 líneas de Python repartidas en tres subsistemas, 4 migraciones de esquema y 60 commits. Nada de esto es grande por sí mismo; lo interesante es cómo se construyó sin que se convirtiera en un castillo de naipes.
El problema de método: un proyecto de verdad, un solo desarrollador
El vibe coding —pedirle cosas al modelo a golpe de prompt e ir viendo— funciona para prototipar. Para un proyecto que crece, con audio en tiempo real, migraciones de base de datos y un pipeline de LLM que puede alucinar, no funciona. Sin proceso, cada sesión con el agente empieza de cero, las decisiones de diseño se toman a mitad de una implementación y el scope creep se cuela sin que nadie lo haya aprobado.
Lo que necesitaba no era un modelo más listo, sino un método: mover las decisiones de diseño al momento correcto (antes de escribir código), dejar constancia verificable de esas decisiones y tener una red de seguridad para las operaciones peligrosas. Eso es exactamente lo que aporta Superpowers.
La columna vertebral: las skills de Superpowers
Una skill es, en la práctica, un procedimiento que el agente está obligado a seguir cuando la situación encaja. No es un prompt que sugiere; es un checklist que bloquea el atajo. Estas son las que sostienen el desarrollo de Memorias:
| Skill | Qué impone |
|---|---|
| brainstorming | Explorar intención y requisitos antes de tocar código; termina en un spec aprobado. |
| writing-plans | Convertir el spec en un plan de implementación por pasos, con criterios de aceptación. |
| test-driven-development | Escribir el test que falla antes que la implementación. |
| requesting-code-review | Revisar el trabajo contra los requisitos antes de mergear. |
| verification-before-completion | No declarar nada «terminado» sin haber corrido la verificación y visto la salida. |
| finishing-a-development-branch | Cerrar la rama con criterio: merge, PR o limpieza. |
Brainstorming antes de una sola línea
Ninguna feature de Memorias empezó en el editor. Empezó en una conversación de diseño: preguntas de una en una, dos o tres alternativas con su recomendación, y una decisión explícita en cada bifurcación. ¿Sesión única o multi-sesión con memoria? ¿Capítulos guiados en vivo o temas abiertos que emergen después? ¿Base de datos en la nube desde el día uno o Postgres local en Docker? Cada respuesta quedó escrita.
El resultado de esa fase no es código: es un spec técnico, un documento persistente que vive en el repositorio. A día de hoy hay cuatro, uno por bloque de trabajo:
docs/superpowers/specs/
├── 2026-07-13-memorias-voice-interviewer-design.md
├── 2026-07-27-memorias-bloque-3-composicion-design.md
├── 2026-08-04-memorias-perfiles-configurables-design.md
└── 2026-08-06-memorias-correo-loop-design.mdLa gracia del spec no es la burocracia. Es que las decisiones difíciles —»el audio original se conserva fuera de la base de datos y en la tabla solo guardamos el puntero», «no se toca jamás la base de datos de producción»— se toman una vez, en frío, y quedan como contrato. Cuando el agente implementa semanas después, no reinventa esas decisiones: las lee.
Del spec al plan, y del plan al test
El spec dice qué y por qué. El plan de implementación dice cómo y en qué orden, descompuesto en tareas con criterios de aceptación. Y sobre ese plan entra la regla que más ha cambiado la calidad del proyecto: TDD.
Cada pieza testeable se escribió empezando por el test que falla. El compositor de capítulos es el mejor ejemplo: todas las funciones que llaman a la LLM o al embedder reciben esas dependencias como parámetros, precisamente para poder sustituirlas por dobles en los tests y ejercitar la lógica sin tocar la red.
# El núcleo del compositor recibe sus dependencias inyectadas:
draft_chapter(chunks, llm=..., llm_text=..., embedder=...)
# 1. plan_outline → escaleta de beats
# 2. write_beats → escribe beat a beat, sin repetir
# 3. judge_and_revise → juez editorial; revisa una sola vez si hace faltaCincuenta y cuatro tests después, el efecto es el que prometía Superpowers: predecibilidad. Puedo cambiar el modelo de voz o reescribir el post-proceso y saber en segundos si rompí algo, porque la suite recrea la base de datos de test desde las migraciones en cada corrida y valida de paso que el esquema se construye entero.
Desarrollo dirigido por agentes: subagentes con un solo trabajo
La segunda mitad del método es agent-driven development: en lugar de un único hilo que lo hace todo, delego trozos de trabajo en subagentes especializados que devuelven una conclusión, no un volcado de archivos. Para explorar el código heredado de otro proyecto lancé agentes de búsqueda en paralelo; para diseñar la arquitectura, un agente de planificación; para investigar, agentes que leen fuentes y verifican.
Pero el salto de calidad vino al crear agentes propios del proyecto. Memorias había heredado once agentes de un proyecto Django de evaluación de manuscritos —con conocimiento de Vertex, Opik, plantillas de Django— que aquí solo generaban consejo desalineado. Los borré todos y los sustituí por dos, afilados al stack real:
| Agente | Dominio |
|---|---|
| adk-live-bridge | El puente de voz: WebSocket, run_live(), el detalle de que las transcripciones llegan en campos dedicados del evento y no en las parts de texto, la grabación de audio crudo y el orbe. |
| memorias-data-migrations | La capa de datos: SQLAlchemy async, Alembic, pgvector y la guardia dura de no apuntar jamás los tests a producción. |
Un agente propio no es más que un archivo Markdown con instrucciones y unas reglas invariantes en la cabecera. Lo valioso es que codifica el contexto que de otro modo tendría que repetir en cada prompt: cuál es el puerto de la base de datos local, por qué el proyecto no usa Vertex en el PoC, qué error clásico evitar. Cada uno lleva escrita, además, una línea explícita: «si ves consejo de Django o de Opik, es contaminación de otro repo».
---
name: adk-live-bridge
description: "Puente de voz de Memorias: FastAPI + WebSocket + ADK run_live()..."
model: sonnet
---
Reglas duras:
1. Nunca toques la BD de producción. El PoC usa Postgres local en Docker (puerto 5433).
2. No introduzcas Django, Vertex ni Opik: este proyecto es FastAPI + ADK + frontend vanilla.
...La lección, contraintuitiva: menos agentes y más específicos rinden más que un catálogo genérico. Dos que conocen tu proyecto valen más que once que conocen otro.
Investigar también es desarrollar
Antes de decidir si Memorias debía vivir en un dispositivo físico —unos auriculares, un objeto de sobremesa— no quise opinar de memoria. Lancé un workflow de investigación: agentes que abren búsquedas en abanico, leen las fuentes, extraen afirmaciones concretas y las someten a una verificación adversarial —varios agentes intentando refutar cada dato— antes de sintetizar un informe citado.
Salieron dos informes que hoy viven en el repositorio y que cambiaron decisiones de producto reales:
- Hardware. Un asistente de voz 100 % local en una Raspberry Pi tarda entre 3 y 15 segundos por respuesta: inviable para una conversación empática. Conclusión verificada: graba en local, piensa en la nube; y no fabricar hardware propio (el caso Humane, de 850 millones de valoración a ser adquirida por 116, lo deja claro).
- Mercado. El cliente que paga no es el mayor, es el hijo o el nieto de 40-55 años, y el producto se vende como regalo emocional, no como tecnología. En español no hay nadie ofreciendo captura por IA de voz: solo biógrafos artesanales de 800 a 5.000 euros. Ahí está el hueco.
El detalle honesto: la verificación chocó un par de veces con límites de sesión y la síntesis automática se quedó a medias. Cuando eso pasó, no inventé el informe: recogí el material ya recopilado y lo redacté marcando tres niveles de confianza —verificado, refutado y de fuente única sin verificar—. Un dato sin verificar no es un dato falso, pero tampoco se disfraza de verdad.
La red de seguridad: hooks, memoria y datos intocables
Delegar trabajo en agentes con permiso para ejecutar comandos da vértigo si no hay barandillas. Las mías son tres capas.
Hooks. Siete reglas declarativas —vía hookify— interceptan operaciones peligrosas antes de que se ejecuten: bloquear un rm destructivo, un git que reescribe historia, un DROP DATABASE, el borrado de una migración, un push directo a main. No confío en que el agente «se acuerde» de no hacerlo: el harness se lo impide.
Memoria persistente. El proyecto mantiene una memoria de archivos con los hechos que no se deducen del código: que la identidad de git es estrictamente local a este repositorio, que la base de datos de producción no se toca jamás. Son decisiones que sobreviven entre sesiones y que cualquier agente lee al empezar.
Reglas de datos. La más importante está escrita en el propio conftest.py: los tests fuerzan la variable de conexión a una base memorias_test y la recrean desde cero en cada corrida. Los fixtures truncan tablas; por eso solo pueden ver la base de test, nunca la real. Una barandilla en el código pesa más que una buena intención en un prompt.
Lo que he aprendido
Después de un mes largo con este método, estas son las lecciones que me llevo:
- El proceso vale más que el modelo. La diferencia entre un proyecto que aguanta y uno que se desmorona no fue la potencia de la IA, sino la disciplina de diseñar, testear y verificar en el orden correcto.
- El spec es el activo, no el código. El código es desechable; las decisiones documentadas son lo que da continuidad. Cuando vuelvo a un subsistema semanas después, releo el spec, no el diff.
- Especializa tus agentes o no los uses. Un agente genérico heredado es peor que ninguno: te da consejo con la confianza de un experto en el proyecto equivocado.
- La verificación no es opcional. Tanto en el código (TDD, CI) como en la investigación (verificación adversarial, niveles de confianza), lo que no se comprueba no se afirma.
Y no todo es perfecto. El flujo tiene fricción: escribir specs y planes antes de programar cuesta, y hay días en que uno solo quiere teclear. Los límites de sesión interrumpen tareas largas. Y montar los agentes, hooks y memoria del proyecto es una inversión inicial que solo se paga cuando el proyecto crece lo suficiente. Para un script de una tarde, esto es pasarse de frenada. Para algo que quieres que dure, es justo lo contrario.
Para cerrar
Memorias funciona: dos sesiones reales de conversación, con la entrevistadora retomando en la segunda lo que se había contado en la primera, y los fragmentos ya clasificados y listos para componer capítulos. Pero lo que quería enseñarte en este artículo no es tanto el producto como el andamiaje: cómo las skills de Superpowers, el desarrollo dirigido por agentes y una red de seguridad de hooks y specs convierten a un desarrollador solo en algo parecido a un equipo pequeño y ordenado.
El patrón se generaliza más allá de este proyecto: decide antes de implementar, verifica antes de afirmar, y automatiza las barandillas en lugar de confiar en la memoria. Da igual que construyas un entrevistador de voz o una plataforma de otra cosa.
Si trabajas con Claude Code en proyectos reales y quieres montar un flujo así —skills, agentes propios, hooks y desarrollo dirigido por specs— en tu equipo o en el tuyo propio, puedo ayudarte. Escríbeme y lo vemos.
