Em julho comecei o Carmoku, um jogo de Sudoku para telemóvel, com a ajuda do Claude Code. Dois meses e meio e mais de 400 commits depois, a app estava em testes nas duas lojas e submetida à revisão da App Store. Ao longo do caminho percebi uma coisa: a IA escreve código muito depressa, mas não se lembra de nada.
Cada sessão nova começa do zero. Não sabe o que ficou decidido ontem, porque é que uma solução foi posta de lado, nem que erro já te fez perder uma tarde. Se essa memória não estiver escrita em algum lado, vais repetir as mesmas conversas, as mesmas decisões e os mesmos erros.
Por isso, a parte mais importante de trabalhar com IA não é o código. É a gestão do projeto. Neste artigo partilho o que funcionou para mim, e no fim deixo um script para começares um projeto novo já com esta estrutura.
1. Um bom plano: PLANO.md
Antes de escrever uma linha de código, escreve o plano: o que estás a construir, para quem, com que tecnologias, e em que fases. No Carmoku, o PLANO.md dividiu o projeto em fases, desde o motor de Sudoku até à publicação nas lojas, e a ordem das fases era a ordem de trabalho.
O plano não é um documento para escrever uma vez e esquecer. Quando uma decisão muda, atualiza-se o plano nesse momento. Um plano desatualizado é pior do que nenhum, porque a IA vai segui-lo com toda a confiança.
2. As tarefas: TASKS.md
O plano diz para onde vais; o TASKS.md diz onde estás. Cada fase é partida em steps pequenos, pequenos o suficiente para rever o resultado de uma só vez. Uma regra que me poupou muitos problemas: um step só fica marcado como feito quando está testado, revisto e commitado, não apenas quando o código está escrito.
Quando abro uma sessão nova, a primeira coisa que a IA faz é ler o TASKS.md. Em segundos sabe onde ficámos e o que vem a seguir.
3. O código no GitHub, com checkpoints regulares
Tudo vai para o GitHub, com um commit por step e uma mensagem que explique o porquê. Isto dá-te duas coisas: um histórico que a IA também consegue ler, e a possibilidade de voltar atrás quando algo corre mal. E com IA, algo corre mal mais vezes do que parece.
Além dos commits, faço checkpoints: de tantos em tantos steps, paro e peço uma revisão ao código acumulado, à procura de bugs, duplicações e coisas que ficaram a meio. Coisas que num step isolado parecem bem, às vezes só se veem quando se olha para o conjunto. Trabalho mais arriscado, como dados guardados ou compras, vai sempre para um ramo à parte, nunca diretamente para o main.
4. Testar, sempre
A IA diz “está feito” com a mesma confiança quando está feito e quando não está. A única forma de saber é testar. No Carmoku, cada step tinha de passar numa suite de testes automáticos antes de ser dado como concluído.
Os testes não servem só para apanhar erros. São também a forma de a IA verificar o próprio trabalho sem precisares de estar a olhar para o ecrã.
5. Delegar a subagentes (com critério)
O Claude Code consegue lançar subagentes: outras instâncias que trabalham numa tarefa em paralelo. É ótimo para ganhar tempo, mas aprendi a separar o trabalho por risco:
- Delegar: trabalho mecânico e repetitivo, como criar ecrãs, formulários, traduções ou testes a partir de um padrão que já existe.
- Não delegar: lógica crítica, como algoritmos, migrações de dados ou tudo o que possa falhar em silêncio.
- Rever sempre: o trabalho de um subagente é revisto e testado antes de entrar no projeto.
6. Documentar tudo: RULES.md e CLAUDE.md
O RULES.md diz como se trabalha no projeto: como se fazem commits, quando se usam subagentes, como se testa. E tem uma secção que acabou por ser das mais valiosas: as lições aprendidas. Cada regra nasce de um erro. Um exemplo real: o projeto estava numa pasta do iCloud, e apagar e copiar uma pasta inteira criou mais de cem ficheiros duplicados em silêncio. Isso custou uma tarde. Hoje é uma regra escrita, e não voltou a acontecer.
O CLAUDE.md é o ponto de entrada: o Claude Code lê-o sozinho no início de cada sessão. O meu é curto, explica onde está cada coisa e lista as regras que não se negoceiam.
7. Um sítio para as ideias: IDEIAS.md
A meio de uma tarefa surgem sempre ideias novas, como um modo de jogo diferente ou uma funcionalidade que “era giro ter”. Se paras para as planear, perdes o foco. Se não as escreves, perdes a ideia.
O IDEIAS.md resolve isto: a ideia fica escrita e continuas. Só passa para o plano quando for decidida a sério. Algumas ficam lá meses; outras nunca saem. E está tudo bem.
8. Decisões que servem para o próximo projeto
Há decisões que não são deste projeto. São tuas, e vais voltar a tomá-las. No Carmoku criei um LOJAS.md com tudo o que as lojas pedem: identificador da app, emails de suporte e privacidade, respostas aos formulários de dados, público-alvo, e o porquê de cada escolha.
Deu trabalho da primeira vez. Da próxima, é copiar e adaptar. O mesmo vale para alojamento, textos legais ou configuração de servidores: escreve uma vez, reutiliza sempre.
Uma dica extra: regista também quanto tempo demora cada step. No Carmoku isso mostrou-me onde é que o tempo ia realmente, e nem sempre era onde eu pensava.
Conclusão
A IA é um acelerador incrível, mas quem conduz és tu. Um plano claro, tarefas pequenas, código guardado, testes e decisões escritas são o que transforma sessões soltas num projeto que chega ao fim.
O Carmoku é a prova disso: um projeto a tempo parcial que foi do zero às lojas porque cada sessão sabia exatamente onde a anterior tinha ficado.
Também usas IA nos teus projetos? Conta-me como te organizas! >> [email protected]