Arquitetura para crescer: fatias, decisões e IA

1. Por que organizar

Projeto pequeno cabe na cabeça. Projeto que cresce, não. A partir de um ponto, ninguém lembra onde fica cada coisa, e cada mudança quebra algo longe dali.

Arquitetura é como o código está organizado e por quê. Boa arquitetura é a que o time entende e consegue mudar sem medo.

2. Camadas ou fatias

Muito projeto começa separado por tipo de arquivo: todas as telas juntas, todas as regras juntas, todos os dados juntos. Parece arrumado. Mas uma funcionalidade nova mexe em todas as pastas.

Por tipo de arquivo          Por assunto (fatias)
telas/                       tarefas/
  tarefas.html                 tela.html
  metas.html                   regras.js
regras/                        dados.js
  tarefas.js                 metas/
  metas.js                     tela.html
dados/                         regras.js
  tarefas.js                   dados.js
  metas.js

Na fatia vertical, cada pasta é um assunto completo, do que aparece na tela até onde o dado fica. Mudar as tarefas mexe só em tarefas/. A ideia tem nome e autor: Jimmy Bogard chamou de Vertical Slice Architecture. A regra dele: cada fatia depende pouco das outras, e o código de uma mesma fatia fica junto.

O que todas as fatias usam, como o design system, fica numa pasta compartilhada. Só entra lá o que é de fato compartilhado.

3. O Ako em fatias

O repositório do Ako é organizado assim. Cada pasta de primeiro nível é uma parte do produto:

Uma pegadinha do Ako: o site é publicado sem build (nenhuma etapa transforma o código antes de ir ao ar), e cada arquivo vira um endereço. Mover um arquivo de pasta quebra o link de quem salvou. Por isso a regra do repositório é nunca mover um arquivo publicado sem criar um redirecionamento. Essa regra está escrita no AGENTS.md, para nenhuma IA esquecer.

4. ADR: a decisão escrita

Algumas decisões custam caro para desfazer: o banco de dados, o jeito de publicar, o formato dos dados salvos. Se ninguém escreve o porquê, daqui a seis meses o time discute tudo de novo.

O ADR (Architecture Decision Record) é uma página curta, um arquivo por decisão, numa pasta decisoes/. Este é um resumo do primeiro ADR do Ako:

# 0001: O Ako não tem build

## Contexto
O Ako é feito para quem está começando. Qualquer pessoa precisa
abrir um arquivo, entender e mandar uma correção pelo GitHub.

## Decisão
HTML, CSS e JavaScript puros, sem framework e sem build.

## Opções consideradas
Sem build (escolhida), gerador estático, framework de front-end.

## Consequências
Todo caminho de arquivo é um endereço público: mover quebra link.
O cache é controlado à mão, com ?v= nos arquivos.

O ADR inteiro está em decisoes/0001-sem-build.md, no GitHub.

Escreva ADR só para o que é difícil de desfazer. Para o resto, a mensagem do commit basta. O modelo usado na Rizzygo segue o MADR, um formato aberto.

5. AGENTS.md: o mapa para a IA

Vários agentes de IA que programam, como Codex e Copilot, leem um arquivo chamado AGENTS.md na raiz do projeto. É um formato aberto. Alguns usam outro nome: o Claude Code lê o CLAUDE.md, que no Ako só aponta para o AGENTS.md. O arquivo diz para a IA o que uma pessoa nova precisaria saber no primeiro dia.

# AGENTS.md

## O que é
Site de tarefas, HTML e JS puros, sem build.

## Onde mexer
| Quero...          | Arquivo          |
| Mudar as tarefas  | tarefas/         |
| Mudar as cores    | ds/rizzygo.css   |

## Comandos
python3 -m http.server 8000   # prévia
node --check tarefas/regras.js

## Nunca
- Mover arquivo publicado sem redirecionamento.
- Colocar senha ou token no repositório.

Mantenha curto, umas cem linhas no máximo. O AGENTS.md funciona como mapa: ele aponta para os documentos, em vez de copiar tudo.

6. Trabalhar junto com a IA

O trabalho com IA segue cinco passos:

1. Você entende o B.O. e escreve a spec.
2. A IA lê o AGENTS.md e a spec, e propõe o que vai mudar.
3. Você confere o plano antes de ela escrever o código.
4. Ela mexe só na fatia do assunto e roda os comandos de conferir.
5. Você lê, testa e abre o pull request dizendo que usou IA.

7. Missão final