Agentes de Codificación Paralela con tmux y Especificaciones en Markdown

Manuel Schipper ha estado ejecutando agentes de codificación en paralelo con una configuración ligera que utiliza tmux, archivos Markdown, alias de bash y seis comandos de barra diagonal. Estos son agentes estándar sin perfiles de subagentes u orquestadores, utilizando una convención de nombres de roles por ventana de tmux: Planificador (construye especificaciones en Markdown), Trabajador (implementa a partir de especificaciones terminadas) y Gerente de Proyecto (refinamiento de backlog y volcado de ideas).

Sistema de Diseño de Funcionalidades

La mayor parte de la escritura de código ocurre a partir de especificaciones terminadas llamadas Diseños de Funcionalidades (FDs). Un FD es un archivo Markdown que contiene:

• El problema que se está resolviendo
• Todas las soluciones consideradas con pros y contras para cada una
• La solución final con el plan de implementación, incluyendo los archivos a actualizar
• Pasos de verificación

Después de adoptar este sistema, Schipper puede trabajar en paralelo con 4-8 agentes. Más allá de 8 agentes, la calidad de las decisiones se ve afectada. El sistema fue construido manualmente en un proyecto con más de 300 especificaciones, luego portado a nuevos proyectos usando un comando /fd-init que inicializa la configuración en cualquier repositorio.

Seguimiento y Ciclo de Vida de los FD

Cada FD obtiene un archivo de especificación numerado (FD-001, FD-002...) rastreado en un índice a través de todos los FDs. Los archivos residen en docs/features/ y avanzan a través de 8 etapas:

• Planificado: Identificado, aún no diseñado
• Diseño: Diseñando activamente la solución
• Abierto: Diseñado, listo para implementación
• En Progreso: Actualmente siendo implementado
• Pendiente de Verificación: Código completo, esperando verificación en tiempo de ejecución
• Completo: Verificado como funcional, listo para archivar
• Diferido: Postergado indefinidamente
• Cerrado: No se hará

Comandos de Barra Diagonal

Seis comandos de barra diagonal manejan el ciclo de vida completo:

• /fd-new: Crear un nuevo FD a partir de un volcado de ideas
• /fd-status: Mostrar el índice: qué está activo, pendiente de verificación y terminado
• /fd-explore: Inicializar una sesión: cargar documentación de arquitectura, guía de desarrollo, índice de FDs
• /fd-deep: Lanzar 4 agentes Opus en paralelo para explorar un problema de diseño difícil
• /fd-verify: Revisar código, proponer un plan de verificación, hacer commit
• /fd-close: Archivar el FD, actualizar el índice, actualizar el registro de cambios

Cada commit se vincula a su FD (por ejemplo, "FD-049: Implementar reconstrucción incremental del índice"). El registro de cambios se acumula automáticamente a medida que los FDs se completan.

Ejemplo de Archivo FD

FD-051: Clasificación de documentos multi-etiqueta
Estado: Abierto
Prioridad: Media
Esfuerzo: Medio
Impacto: Mejor recuperación para filtrado descendente

Problema
Los documentos entrantes obtienen una única etiqueta de categoría, pero muchos abarcan múltiples temas. Los filtros descendentes pierden documentos relevantes porque el clasificador fuerza un único mejor ajuste.
Solución
Reemplazar la clasificación de etiqueta única por multi-etiqueta:

Usar un LLM para asignar puntajes de confianza por categoría.
Aceptar todas las etiquetas por encima de 0.90 de confianza.
Para puntajes ambiguos (0.50-0.90), ejecutar una segunda pasada de LLM con ejemplos de pocos disparos para confirmar.
Almacenar todas las etiquetas con puntajes para que las consultas descendentes puedan umbralizar de manera flexible.

Archivos a Modificar

src/classify/multi_label.py (nuevo: lógica multi-etiqueta basada en LLM)
src/classify/prompts.py (nuevo: plantillas de pocos disparos para casos ambiguos)
sql/01_schema.sql (agregar tabla document_labels con puntajes)
sql/06_classify_job.sql (nuevo: clasificación programada después de la ingesta)

Verificación

Ejecutar clasificador en la tabla de documentos de staging
Verificar que no haya errores en el registro de operación, ejecutar comprobaciones de salud
Verificación puntual: documentos con contenido conocido de múltiples temas tienen las etiquetas esperadas
Ejecutar pruebas, confirmar que los filtros descendentes respetan el umbral de confianza

Inicialización del Sistema

Al ejecutar /fd-init en cualquier repositorio:

• Infiere el contexto del proyecto desde CLAUDE.md, configuraciones de paquetes y registro de git
• Crea la estructura de directorios (docs/features/, docs/features/archive/)
• Genera un FEATURE_INDEX.md personalizado para el proyecto
• Crea una plantilla de FD
• Instala los seis comandos de barra diagonal
• Añade las convenciones del ciclo de vida de FD al CLAUDE.md del proyecto

Los archivos creados incluyen docs/features/FEATURE_INDEX.md (índice de funcionalidades), docs/features/TEMPLATE.md (plantilla de archivo FD), docs/features/archive/ (directorio de archivo), CHANGELOG.md (formato Keep a Changelog), y actualizaciones a CLAUDE.md con las convenciones del proyecto incluyendo el sistema FD.