# ADR: dispatch via CLI primeiro (exemplo ilustrativo)

## Status
Aceito

## Contexto
O agente principal exige chave de API mesmo com CLIs autenticados na máquina.

## Decisão
Executar um CLI autenticado antes de qualquer API HTTP, salvo pedido explícito.

Quatro seções, uma decisão. O agente que lê isso sabe o que foi decidido, por quê e o que não pode quebrar.

## Por que ADR funciona melhor que memória de ferramenta

Cada CLI tem seu mecanismo de memória. Eles não se enxergam. Uma decisão registrada na memória do Claude Code não existe para o Codex.

A ADR fica no repositório. Ela tem três propriedades que a memória das ferramentas não tem:

| Propriedade | Por que importa com vários agentes |
|---|---|
| Versionada no Git | dá para ver quando e em que commit a decisão mudou |
| Legível por qualquer CLI | é só um arquivo markdown |
| Revisável em PR | decisão errada é pega antes de virar código |

O lemon-code chegou a 67 arquivos de ADR, cobrindo de 0001 (visão geral da arquitetura) a 0060 (runtime do Cursor CLI). Os primeiros doze são o histórico de fundação. A partir do 0013, muitas são propostas de evolução com fonte declarada, como o changelog do Claude Code.

## Fonte única de instruções

O segundo pilar é um arquivo só de instruções. No lemon-code, o `AGENTS.md` abre dizendo que é a fonte única de verdade para comportamento de agentes, e que `CLAUDE.md` e `GEMINI.md` só apontam para ele.

Isso evita um problema que tive cedo: três arquivos de instrução divergindo. O Claude seguia uma regra, o Gemini outra. O script `ai:sync-check` verifica os caminhos de symlinks de skills e comandos definidos pelo projeto e a paridade de algumas cópias internas de skills. Ele não detecta texto de instrução duplicado em geral.

## O erro do 0049

Voltando aos seis `0049-`. A explicação mais provável (é interpretação minha, não está registrada em lugar nenhum): sessões paralelas listaram a pasta, viram que o último número era 0048 e criaram o 0049. O mesmo aconteceu, em escala menor, com 0050, 0051, 0052 e 0055, que têm dois arquivos cada.

O README das ADRs já registrava outro tropeço de numeração: `005-agent-swarm-handoff.md` deveria ter quatro dígitos e não foi renomeado para preservar links.

O que eu tiraria disso:

- **Número sequencial é recurso compartilhado.** Com vários escritores, ele precisa de dono. Ou um script reserva o número, ou o nome usa data e slug.
- **Colisão não quebra nada na hora.** Por isso passa. Ela só aparece quando alguém tenta citar "a ADR 0049".
- **Renomear tem custo.** Links e referências em commits apontam para o nome antigo. Melhor prevenir.

## Checklist: suas ADRs servem para agentes?

- [ ] Cada ADR tem Status, Contexto, Decisão e Consequências.
- [ ] Existe um único arquivo de instruções; os outros só apontam para ele.
- [ ] A validação automática confere os symlinks e as cópias internas declaradas pelo projeto.
- [ ] A numeração tem dono (script ou convenção por data).
- [ ] O índice de ADRs diz quais estão aceitas e quais são propostas.
- [ ] Decisões que um agente não pode quebrar estão nas Consequências, não num chat.

## Conclusão

Com vários agentes no mesmo repositório, a memória do projeto precisa morar no repositório. ADRs curtas, com formato fixo e uma fonte única de instruções, são o diário de bordo que todos os turnos leem. Os seis `0049-` lembram que até o diário precisa de regra para quem escreve.

Na segunda, a série muda de camada: como coloquei um app nativo SwiftUI por cima do CLI sem reimplementar nada.

Se o seu time usa vários agentes de código e as decisões estão se perdendo entre sessões, organizar essa memória é um trabalho que faço na [LEMON.DEV](https://lemon.dev.br).

## Referências

- [Michael Nygard, Documenting Architecture Decisions](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
- [adr.github.io, coleção de templates e ferramentas](https://adr.github.io/)
- [AGENTS.md, convenção aberta](https://agents.md/)

## Leituras relacionadas

- [Versionamento de decisões de IA](https://lemon.dev.br/pt/blog/versionamento-reprodutibilidade-decisoes-ia)
- [Guardrails e aprovações em um agente de código](https://lemon.dev.br/pt/blog/guardrails-aprovacoes-agente-codigo)