Atomic Tasks (Decomposição Atômica de Tarefas)

1. Visão Geral da Conceito e Problema Sistêmico

No desenvolvimento clássico, tarefas vagas ("Implementar autenticação", "Reescrever o módulo de busca") são a principal causa de atrasos no cronograma e retrabalho. Na era do desenvolvimento com agentes de IA, o custo de uma decomposição inadequada aumentou exponencialmente.

Quando um engenheiro fornece ao agente uma instrução vaga de alto nível, o agente faz suposições sobre dezenas de detalhes indefinidos. O resultado é a geração de um diff monolítico abrangendo 40 arquivos, misturando layout, esquemas de banco de dados e regras de negócio. Revisar esse diff torna-se praticamente impossível: o engenheiro sofre sobrecarga cognitiva, clica em "Accept" e, uma semana depois, depara-se com conflitos insolúveis.

Atomic Tasks (Tarefas Atômicas) são uma disciplina de engenharia para estruturar o trabalho segundo o princípio da indivisibilidade:

• Cada subtarefa foca em uma única mudança de comportamento ou estrutura.
• Possui parâmetros de entrada claramente definidos e invariantes de saída esperados.
• Pode ser totalmente implementada, testada e commitada separadamente do restante do sistema.

Monolito Caótico (Falha do Agente):
[Requisito: "Crie uma loja online"] ---> [LLM gera um emaranhado de 30 arquivos com placeholders]

Decomposição Atômica (Sucesso Controlado):
[Requisito: "Processamento de Pedido"]
   |
   +---> Tarefa 1: Criar esquema da tabela Order no Drizzle + migração (Verificação: db:push)
   |
   +---> Tarefa 2: Escrever função pura calculateTotal(items, discount) (Verificação: 5 testes unitários)
   |
   +---> Tarefa 3: Implementar POST /api/orders com validação Zod (Verificação: curl / teste de API)
   |
   +---> Tarefa 4: Criar UI do formulário de checkout (Verificação: componente no navegador)

2. Taxonomia Arquitetural e Modelo Mental

Gradação dos níveis de granularidade das tarefas (Task Granularity Spectrum):

1. Nível Macro (System Feature / Epic):
   • Objetivo de negócio (por exemplo, "Suporte a multilíngue no site"). Não deve ser enviado diretamente ao chat do agente como um único comando.
2. Módulo Atômico (Feature Slice / Component):
   • Fatia vertical de funcionalidade (por exemplo, "Roteamento de locales via middleware").
3. Ação Atômica (Atomic Micro-Task):
   • Passo específico de modificação em uma única camada: "Criar dicionário de traduções para a página 404 em formato JSON e adicionar tipagem estrita para as chaves".
   • Tempo de execução: 2–5 minutos.
   • Linhas alteradas: até 50–100 linhas.

3. Pipeline Técnico e Mecânica Interna

Template de Tarefa Atômica de Engenharia (TASK_SPEC.md)

### Tarefa: Criação de um repositório para armazenamento de tokens de sessão

**Contexto dos arquivos:**
- Arquivo alvo: `src/lib/auth/session-store.ts`
- Arquivo de teste: `src/lib/auth/__tests__/session-store.test.ts`
- Contrato de referência: `src/lib/auth/types.ts`

**Requisitos:**
1. Implementar a classe `RedisSessionStore`, que implementa a interface `SessionStore`.
2. O método `saveSession(token, data, ttlSeconds)` deve definir a chave com TTL usando o comando Redis `SETEX`.
3. O método `getSession(token)` deve retornar o objeto desserializado ou `null`, caso a chave não exista.

**Critério de conclusão (Definition of Done):**
- O comando `npx vitest run src/lib/auth/__tests__/session-store.test.ts` retorna 100% de testes bem-sucedidos.
- Não há erros de tipagem: `npx tsc --noEmit` passa com 0 erros.

Pipeline de Execução do Passo Atômico:

1. O engenheiro formula o TASK_SPEC com contexto claro e teste.
2. O agente lê APENAS os 2-3 arquivos especificados (janela de contexto limpa, zero alucinações).
3. O agente escreve a implementação.
4. Execução do teste automatizado -> sinal verde.
5. O engenheiro revisa o diff compacto (20 linhas) em 15 segundos.
6. Commit no Git: `git commit -m "feat(auth): implement redis session store"`

4. Cenários Práticos de Engenharia em Produção

01. Migração Segura de Banco de Dados com 10 Milhões de Linhas

Em vez de uma migração complexa única, a equipe divide a tarefa em 4 atomic tasks: 1) Adicionar nova coluna como nullable; 2) Escrever script de sincronização em background processando lotes de 1000 linhas; 3) Alternar a escrita para a nova coluna; 4) Adicionar restrição NOT NULL e remover o campo antigo. Cada etapa é verificada e deployada individualmente, eliminando o risco de bloqueio da tabela.

02. Saída do Impasse Criativo Durante o Debug

O engenheiro não entende por que um algoritmo complexo de cálculo de rota retorna resultados incorretos. Em vez de examinar infrutiferamente todo o arquivo de 1000 linhas, ele divide o algoritmo em 5 funções puras e escreve testes individuais para cada uma. Na terceira função, descobre-se um erro de arredondamento de frações, e o bug é corrigido em 3 minutos.

03. Orquestração Paralela de Subagentes (Parallel Subagents)

Graças à atomicidade, o arquiteto pode iniciar 3 sessões de modelo simultaneamente: um agente escreve o parser XML, outro gera relatórios PDF, e um terceiro define o esquema do banco de dados. Como seus contratos são atômicos e não se sobrepõem em arquivos compartilhados, não há qualquer conflito de merge (Merge Conflicts).

5. Armadilhas, Erros Comuns e Segurança

1. Paralisia da Fragmentação (Micro-Task Hell): A decomposição excessiva de uma tarefa em 50 passos minúsculos de 30 segundos cada cria atrito burocrático: o tempo gasto formulando prompts e aguardando respostas começa a superar o tempo de escrever código. Mantenha uma escala saudável: 1 tarefa atômica deve conter um passo significativo na resolução do problema.
2. Perda do Invariante Global (Local Optimum Trap): Cada tarefa atômica pode ser executada perfeitamente em seu nível, mas os módulos podem não se integrar corretamente se o contrato de interface comum (Contract-First Design) não tiver sido definido previamente.
3. Acúmulo de Lixo Não Commitado: Se não for feito um git commit após a conclusão de cada tarefa atômica, após 5 iterações a árvore de trabalho transforma-se em caos com centenas de mudanças incompreensíveis, e os benefícios da atomicidade são totalmente perdidos.