Planejar antes de escrever uma linha

Antes de escrever qualquer código, pedi um plano.

Não lembro das perguntas que o Claude me fez antes de montá-lo. Lembro bem do que veio depois. Era um texto que explicava, de um jeito simples, como cada peça se ligava à outra e por que aquilo ia funcionar.

O caminho de uma notificação

O plano partia de uma pergunta: como o Owl fica sabendo que uma sessão do Claude Code precisa de mim?

A resposta foram os hooks. O Claude Code chama um programa sempre que algo acontece numa sessão, como quando ela termina, quer aprovação ou tem uma pergunta. Em vez de ficar lendo o histórico das sessões de tempos em tempos, o Owl é avisado na hora.

Quem recebe esse aviso é o owl-hook, um programa pequeno escrito em Swift e compilado. Ele repassa a mensagem por um socket Unix, um canal de comunicação local entre processos, até o app que mora no notch.

Por que Swift

O app era só para macOS, sem intenção de virar algo mais geral. Fazer tudo em Swift era também o jeito de entender como um app de Mac funciona por dentro.

Também pesava no hook. Compilado, ele responde em uns 5 a 15 milissegundos, contra 50 a 150 de um script em Node. Como ele roda a cada evento de cada sessão, essa diferença conta.

Questionei várias decisões do plano, mais para entender o motivo de cada escolha do que para mudar. Nenhuma delas ficou grande o bastante na memória.

Fail-open

Uma regra do plano dizia que o Owl nunca pode ser uma dependência rígida. Se ele cair, travar ou nem estiver aberto, o Claude Code segue funcionando como se ele não existisse. Isso é fail-open, ou seja, na falha o caminho fica aberto.

Eu já conhecia o conceito, mas ver ele aplicado num caso tão concreto, no meu próprio app, foi o que fez ele ficar de vez.

O que eu acrescentei

Com o plano validado, a ideia era criar o repositório e começar a subir as novas ideias. Daí veio o versionamento, com cada pequeno ajuste virando uma versão. Eu queria que ficasse claro o motivo de cada mudança e em qual versão ela estava, para saber o que validar e quando aquilo chegou ao meu app.

Confiança

Ao terminar de ler, fiquei confiante. Senti que, com aquele plano na mão, eu conseguiria construir o Owl sozinho. Não no mesmo tempo que o Claude, mas conseguiria sair criando as regras e as conexões de cada ponto importante.

Onde o plano falhou

Na implementação não tenho nada a apontar. A falha veio antes, na concepção.

Eu não conhecia apps de Mac e não tinha um projeto anterior para servir de referência. Mandei um pedido abstrato, e para aquele pedido o resultado foi incrível. Mas faltou coisa que nem eu nem o Claude pensamos.

O exemplo mais claro é que eu queria uma versão para cada ajuste, mas ninguém pensou em como eu atualizaria o app para a versão nova. Mais tarde, comparando o Owl com outros apps, cheguei a descartar a ideia de atualização. Depois voltei atrás. Parece bobo, mas é uma falha de concepção, simples, que passou porque eu só queria saber se era viável.

Para uma ferramenta pessoal, tudo bem, mas para um sistema maior, ou para um card dentro de um produto que já existe, vale gastar mais tempo nas premissas e nos requisitos antes de pedir o plano. As issues do Owl guardam outras falhas que só apareceram com o uso e que poderiam ter estado no plano desde o começo.

É óbvio, mas escrevo para lembrar que o plano é tão bom quanto as premissas que eu explico.

No próximo post, conto sobre o notch do Mac, que eu achava que era como a Dynamic Island do iPhone.