Agentes de Codificação Paralela com tmux e Especificações em Markdown

Manuel Schipper tem executado agentes de codificação paralelos com uma configuração leve usando tmux, arquivos Markdown, aliases bash e seis comandos de barra. Estes são agentes padrão sem perfis de subagentes ou orquestradores, usando uma convenção de nomenclatura de função por janela tmux: Planejador (constrói especificações Markdown), Trabalhador (implementa a partir de especificações finalizadas) e Gerente de Projeto (refinamento de backlog e despejo de ideias).

Sistema de Design de Funcionalidade

A maior parte da escrita de código acontece a partir de especificações finalizadas chamadas Designs de Funcionalidade (FDs). Um FD é um arquivo Markdown contendo:

• O problema sendo resolvido
• Todas as soluções consideradas com prós e contras para cada uma
• A solução final com plano de implementação incluindo arquivos a atualizar
• Etapas de verificação

Após adotar este sistema, Schipper pode trabalhar em paralelo com 4-8 agentes. Além de 8 agentes, a qualidade das decisões sofre. O sistema foi construído manualmente em um projeto com 300+ especificações, depois portado para novos projetos usando um comando /fd-init que inicializa a configuração em qualquer repositório.

Rastreamento e Ciclo de Vida do FD

Cada FD recebe um arquivo de especificação numerado (FD-001, FD-002...) rastreado em um índice através de todos os FDs. Os arquivos ficam em docs/features/ e passam por 8 estágios:

• Planejado: Identificado, ainda não projetado
• Design: Ativamente projetando a solução
• Aberto: Projetado, pronto para implementação
• Em Andamento: Atualmente sendo implementado
• Verificação Pendente: Código completo, aguardando verificação em tempo de execução
• Completo: Verificado funcionando, pronto para arquivamento
• Adiado: Adiado indefinidamente
• Fechado: Não será feito

Comandos de Barra

Seis comandos de barra lidam com o ciclo de vida completo:

• /fd-new: Criar um novo FD a partir de um despejo de ideias
• /fd-status: Mostrar o índice: o que está ativo, verificação pendente e concluído
• /fd-explore: Inicializar uma sessão: carregar documentação de arquitetura, guia de desenvolvimento, índice FD
• /fd-deep: Lançar 4 agentes Opus paralelos para explorar um problema de design difícil
• /fd-verify: Revisar código, propor um plano de verificação, fazer commit
• /fd-close: Arquivar o FD, atualizar o índice, atualizar o registro de alterações

Cada commit está vinculado ao seu FD (ex: "FD-049: Implementar reconstrução incremental do índice"). O registro de alterações acumula automaticamente conforme os FDs são concluídos.

Exemplo de Arquivo FD

FD-051: Classificação de documentos com múltiplos rótulos
Status: Aberto
Prioridade: Média
Esforço: Médio
Impacto: Melhor recall para filtragem downstream

Problema
Documentos recebidos recebem um único rótulo de categoria, mas muitos abrangem múltiplos tópicos. Filtros downstream perdem documentos relevantes porque o classificador força um único melhor ajuste.
Solução
Substituir classificação de rótulo único por múltiplos rótulos:

Usar um LLM para atribuir pontuações de confiança por categoria.
Aceitar todos os rótulos acima de 0.90 de confiança.
Para pontuações ambíguas (0.50-0.90), executar uma segunda passagem LLM com exemplos few-shot para confirmar.
Armazenar todos os rótulos com pontuações para que consultas downstream possam definir limite flexivelmente.

Arquivos a Modificar

src/classify/multi_label.py (novo: lógica multi-rótulo baseada em LLM)
src/classify/prompts.py (novo: modelos few-shot para casos ambíguos)
sql/01_schema.sql (adicionar tabela document_labels com pontuações)
sql/06_classify_job.sql (novo: classificação agendada após ingestão)

Verificação

Executar classificador na tabela de documentos de staging
Verificar sem erros no log de operação, executar verificações de saúde
Verificação pontual: documentos com conteúdo multi-tópico conhecido têm rótulos esperados
Executar testes, confirmar que filtros downstream respeitam limite de confiança

Inicialização do Sistema

Executando /fd-init em qualquer repositório:

• Infere contexto do projeto a partir de CLAUDE.md, configurações de pacote e log git
• Cria estrutura de diretórios (docs/features/, docs/features/archive/)
• Gera um FEATURE_INDEX.md personalizado para o projeto
• Cria um modelo de FD
• Instala os seis comandos de barra
• Anexa convenções de ciclo de vida FD ao CLAUDE.md do projeto

Arquivos criados incluem docs/features/FEATURE_INDEX.md (índice de funcionalidades), docs/features/TEMPLATE.md (modelo de arquivo FD), docs/features/archive/ (diretório de arquivo), CHANGELOG.md (formato Keep a Changelog), e atualizações para CLAUDE.md com convenções do projeto incluindo sistema FD.