Esboçando a Estrutura de Pastas do SDK no Papel

Uma base de código construída por agentes ou vira papa em três meses ou se mantém coerente por anos - e a diferença é decidida antes de a primeira linha ser escrita. A RakuAI desenhou as caixas primeiro para que os agentes sempre caíssem no lugar certo.

Existe um tipo de trabalho de design que é invisível de fora e estrutural por dentro. A estrutura de pastas de uma base de código é uma dessas coisas. Parece gerenciamento de arquivos. Na verdade é o organograma do código. Acerte cedo e todo PR pelos próximos dois anos cai no lugar certo. Erre cedo e todo PR pelos próximos dois anos vai ter que discutir onde pertence.

Este sábado foi dedicado a acertar cedo.

O que a estrutura precisa suportar

Antes de desenhar as caixas, fiz uma lista de restrições que a estrutura precisa satisfazer.

Cada demo tem seu próprio lugar. As oito demos que especifiquei no mês passado precisam cada uma de uma pasta onde seu código, seus assets e sua documentação vivam juntos. Um desenvolvedor lendo qualquer uma das demos não deveria precisar pular entre quatro partes diferentes do SDK para entendê-la.

Módulos compartilhados são separáveis das demos. Qualquer coisa reutilizada entre demos (renderização de HUD, entrada por gesto, rastreamento de olhar, sincronização multiplayer, controle por voz, efeitos visuais) vive no seu próprio lugar e é consumida pelas demos através de uma superfície pública.

Assets são organizados por tipo, não por demo. Um PNG de barra de vida é um widget de HUD, não um asset da Arena Demo. Assets visuais reutilizáveis vivem em uma pasta de assets compartilhada e as demos que precisam deles apontam para lá.

A documentação fica junto com o que descreve. O doc de instalação do SDK fica ao lado do SDK. O guia de demos fica ao lado das demos. O doc de API do HUD fica ao lado do módulo de HUD. A descobribilidade da documentação é, na maior parte, uma questão de localização.

Configuração é uma preocupação própria. Os arquivos de configuração do HUD, os layouts padrão, as configurações de papéis de multiplayer. Isso não é código, não é asset, não é documentação. Tem seu próprio lugar.

A estrutura

Depois de uma manhã de quadro branco, o layout ficou assim.

A pasta raiz é o próprio SDK. Sob a raiz:

/apps/ é onde vivem as demos. Cada demo tem sua subpasta. arena_demo/ para a arena solo. coach_demo/ para o coaching em RA. hud_designer/ para o designer de overlay de HUD. streamer_demo/ para o modo streamer. pos_demo/ para o overlay de ponto de serviço. companion_demo/ para o HUD companheiro de RA. aimlab_demo/ para o treinador de mira em RA. hudsync_demo/ para a sincronização de HUD multiplayer. Cada pasta de demo contém seu próprio código-fonte, sua própria configuração, seus próprios assets específicos da demo, e seu próprio README.

/modules/ é onde vive o código compartilhado. Seis módulos no início. O renderizador de HUD, que toda demo consome. Detecção de entrada por gesto, que a maioria das demos consome. Rastreamento de olhar, usado pelas demos que precisam dele. Sincronização multiplayer, usada pelas demos de multiplayer via LAN. O animador de overlay para efeitos visuais. A interface de controle por voz para as demos que recebem entrada de voz. Cada módulo expõe uma superfície pública pequena e estável à qual as demos se conectam.

/assets/ é a biblioteca de assets compartilhada. Widgets de HUD (barras de vida, contadores de munição, overlays de bússola) em PNG e SVG. Efeitos sonoros de acertos, alertas, locuções. Ícones de gesto que mostram ao usuário quando um gesto foi detectado. As demos apontam para os assets aqui em vez de duplicá-los.

/docs/ é o lar da documentação. Um README que apresenta o SDK e conduz pela instalação. Um guia de demos que explica como rodar cada uma das oito demos. Uma referência de API para o módulo de HUD. Uma referência de API para o módulo de controle por voz. A documentação está deliberadamente colocalizada para que um desenvolvedor que queira saber como o HUD funciona possa ler o código-fonte e a documentação na mesma pasta.

/config/ é configuração. O layout de HUD padrão usado como ponto de partida para novos projetos. Layouts de exemplo exportados do designer de HUD. Definições de papéis de multiplayer. Manter a configuração separada do código mantém as demos limpas e permite que um desenvolvedor mude o comportamento sem recompilar.

Os stubs

Uma estrutura de pastas por si só é só um sistema de arquivos vazio. A outra coisa que rascunhei hoje é um conjunto de stubs de código que mostram aos agentes (quando eventualmente começarem a escrever código sobre essa estrutura) como uma implementação real deveria se parecer em cada ponto de entrada.

Os stubs estão em pseudocódigo Python por enquanto. Serão traduzidos para a linguagem de produção (C++ para o runtime, com bindings para Python e outros ecossistemas) assim que o repositório do motor abrir. A forma em Python é o que me permite raciocinar sobre as interfaces sem me perder em detalhes de implementação.

Um stub de exemplo, para o módulo de entrada por gesto. Aproximadamente:

def detect_gesture(frame):
    """Detect gestures like swipe, point, raise, duck in a single sensor frame."""
    if is_swipe(frame):
        return "swipe"
    elif is_raise(frame):
        return "raise_arm"
    else:
        return None

Isso não é o código de produção. É o contrato. O código de produção vai substituir is_swipe e is_raise por pipelines reais de visão computacional. A interface permanece a mesma. A assinatura é a coisa contra a qual as demos vão codificar. Travar a assinatura cedo significa que posso lançar as demos antes que o pipeline de CV esteja à prova de falhas, porque as demos não dependem da implementação, dependem da interface.

Rascunhei stubs desse formato para cada módulo na pasta /modules/. Seis pequenos arquivos Python. Nenhum deles implementa nada. Todos definem o contrato que as implementações eventuais vão ter que honrar.

Por que os agentes precisam disso

Esta é a ligação de volta com a escalação de agentes de alguns sábados atrás.

Quando chegar a hora de escrever o código de verdade, os agentes não vão estar inventando a arquitetura. A arquitetura está no papel. A estrutura de pastas diz a eles onde o código novo vai. Os stubs de módulo dizem a eles qual interface implementar. A organização de assets diz a eles onde procurar as coisas de que precisam. A estrutura de documentação diz a eles onde colocar a documentação que escrevem.

Essa é a diferença entre uma base de código construída por agentes que vira papa depois de três meses e uma que se mantém coerente por anos. A estrutura é a disciplina. Os agentes herdam a disciplina através da estrutura.

Sem esse trabalho de preparação, um agente instruído a “implementar entrada por gesto” inventaria uma pasta, inventaria uma API, escreveria o código, e produziria algo que funcionasse isoladamente. Multiplicado por seis módulos, essa abordagem produz seis mini-motores incompatíveis. A estrutura evita esse modo de falha desenhando as caixas nas quais os agentes precisam escrever.

O que é difícil nisso

Algumas coisas honestas.

Estruturas de pastas querem crescer. Daqui a seis meses vou querer adicionar um sétimo módulo. A estrutura precisa permitir isso sem virar uma gaveta de bagunça. A regra que estou me impondo: qualquer pasta nova de nível superior precisa justificar por que não é uma subpasta de uma existente. A maioria das coisas novas acaba sendo subpasta.

Os stubs precisam de manutenção. À medida que as implementações reais chegam, os stubs ficam desatualizados. Os agentes que lerem os stubs como “o contrato” vão herdar qualquer desvio entre o stub e a implementação real. A solução é fazer dos stubs a fonte de verdade, e exigir que as implementações reais os atualizem quando o contrato mudar.

Algumas dessas pastas são especulativas. A pasta /config/ é uma aposta de que arquivos de configuração de runtime vão ser uma categoria real de artefato neste SDK. Se acabar não sendo o caso, a pasta encolhe ou se funde a outra coisa. Estou tranquilo com isso. É mais barato remover uma pasta depois do que inventar uma daqui a um ano quando a convenção já tiver se desviado.

O que vem a seguir

O próximo sábado é o design da superfície de API. Cada um dos seis módulos acima precisa ter sua superfície pública especificada. Isso significa decidir quais tipos de dados cruzam a fronteira, quais códigos de erro são retornados, quais eventos são emitidos. Com a estrutura de pastas pronta, o design de API tem onde pousar.

Depois vem a especificação demo a demo de quais módulos cada demo consome e em que ordem. Depois a arquitetura do runtime. Depois, finalmente, o repositório do motor abre.

O portfólio de patentes está esperando há uma década. Mais algumas semanas de trabalho de design para acertar isso não vai ser o que nos custa a janela de oportunidade.

Estrutura de pastas pronta. A base de código já tem uma forma agora, mesmo sem ter nenhum código dentro dela ainda.