TL;DR: Meu agente de IA tinha um arquivo de instruções com 246 linhas para gerenciar issues no Linear. Dentre elas, 150 eram gambiarras: UUIDs hardcoded, alternativas com curl, notas explicando “a CLI não suporta X”. Em vez de reescrevê-las, criei uma ferramenta que tornou essas linhas desnecessárias. Agora, essas 150 linhas se reduziram a zero.
Você já escreveu um documento de instruções tão longo que a própria extensão dele é prova de que algo está errado?
Não estou falando de documentação legítima. Refiro-me àqueles arquivos que começam dizendo “use a ferramenta X” e dedicam 80% do texto para explicar quando a ferramenta X não funciona e o que fazer no lugar. Instruções que, na prática, são uma lista de desculpas pela ferramenta que deveria ter sido projetada.
Eu tinha algo assim. E era vergonhoso.
Anatomia de 150 linhas de lixo
Contexto: trabalho com um agente de IA (Claude Code) que gerencia meus issues no Linear. Para que o agente soubesse como fazer isso, ele tinha uma skill — um arquivo de instruções que o agente lia quando precisava criar, listar ou atualizar issues.
Esse arquivo tinha 246 linhas. Delas, cerca de 100 eram documentação legítima: quais comandos existem, quais equipes há, quais labels usar. Razoável.
As outras 150 eram lixo defensivo, dividido em três categorias:
~30 linhas de UUIDs hardcoded. A CLI que eu usava não suportava --project. Então o skill incluía 17 UUIDs (5 equipes + 12 projetos) em uma tabela XML. O agente precisava buscar o UUID correto e construir manualmente uma mutação GraphQL para atribuir um projeto. Uma operação que deveria ser --project Tokamak envolvia memorizar um UUID de 36 caracteres.
~25 linhas de alternativas com curl. A CLI não tinha busca. Não tinha filtragem por projeto. Não tinha atribuição de projeto em create. Três operações básicas, três blocos com curl contendo queries GraphQL embutidas, escaping de aspas e cabeçalhos de autenticação. Cada um era uma bomba-relógio, esperando o agente estragar tudo por conta de uma aspas errada.
~15 linhas de “NÃO suporta X”. Cinco avisos de “a CLI NÃO suporta” e dois de “OBRIGATÓRIO” (–sort e –no-pager em cada list). Preste atenção: eu estava documentando as deficiências da ferramenta dentro das próprias instruções de uso da ferramenta. É como se o manual de um carro dedicasse três páginas para explicar que o limpador de para-brisa só funciona se você der um soco no painel antes.
~80 linhas de contexto defensivo. Uma seção inteira intitulada “quando usar a API em vez da CLI”. Tabelas de mapeamento diretório→UUID. Heurísticas para escolher labels. Regras sobre o que fazer quando a CLI travar. Material que só existia porque a ferramenta era incapaz.
O aviso de “cuidado, degrau”
Quando uma ferramenta tem uma interface problemática, a reação natural é documentar as gambiarras. Você escreve instruções. Coloca avisos. Cria uma seção de “erros comuns”. E quanto mais detalhada é a documentação, mais você se convence de que resolveu o problema.
Mas você não resolveu. Você só colocou um aviso de “cuidado, degrau” em vez de consertar o degrau.
E quando o usuário dessas instruções é um LLM, o problema se multiplica. Um humano lê “NÃO use –project” e mais ou menos lembra disso. Um LLM lê, processa — e três interações depois usa --project mesmo assim. Não é porque ele é burro — é porque sua função é concluir a tarefa, e --project é o caminho lógico para atribuir um projeto. A proibição vira ruído em um mar de informações.
Já escrevi sobre isso em outro post: instruções verbosas para um LLM são literalmente como colocar avisos. O LLM não as ignora por rebeldia. Ele as ignora porque otimiza para seguir o caminho mais direto, e “não use –project, ao invés disso procure o UUID nessa tabela e depois execute um curl com essa query GraphQL” não é um caminho direto — é uma gambiarra.
A solução não era melhorar o skill
Eu poderia ter reescrito o skill com melhores instruções. Mais claras. Com exemplos. Com diagramas. Poderia ter aumentado de 246 para 400 linhas e incluído todos os casos extremos.
Seria como fazer o aviso “cuidado, degrau” mais chamativo.
O que eu fiz foi construir lql — uma CLI em Rust projetada especificamente para que um agente de IA (ou um humano, mas principalmente um agente) pudesse interagir com o Linear sem precisar de um manual de sobrevivência.
A filosofia de design era uma ideia única: o caminho errado não deve ser proibido, deve ser impossível.
Simplificando: você não proíbe --status na documentação — você faz com que ele funcione. Você não documenta que --project não existe em create — você faz com que ele exista. Você não mantém uma tabela de UUIDs — você resolve os nomes automaticamente. Você não oferece alternativas com curl — a ferramenta deve ser capaz de fazer tudo. Você não fala “OBRIGATÓRIO: –sort” — você define um default sensato.
O que desapareceu
Aqui está o inventário do que foi eliminado:
| Lixo defensivo | Linhas eliminadas | Motivo da eliminação |
|---|---|---|
| UUIDs hardcoded (17 IDs) | ~30 | lql resolve nomes automaticamente |
Alternativas com curl + GraphQL | ~25 | lql tem busca, projeto e relacionamentos nativos |
| Notas “NÃO suporta X” (5) | ~15 | Tudo que o agente espera, existe |
| Flags “OBRIGATÓRIOS” (2) | ~5 | Defaults sensatos, nada obrigatório |
| Seção “quando usar API vs CLI” | ~15 | Não há “vs” — lql faz tudo |
| Tabela de mapeamento contexto→UUID | ~20 | Auto-detecção via configuração TOML |
| Heurísticas e regras defensivas | ~40 | A ferramenta é tolerante, e sobram |
| Total | ~150 |
O que restou é documentação legítima: quais comandos existem, quais equipes há, quais labels usar. Zero gambiarras. Zero desculpas.
Por que funciona (a parte interessante)
A redução do número de linhas é chamativa, mas não é o principal. O mais importante é o porquê da eliminação dessas linhas.
Cada linha de gambiarra no skill anterior existia porque a ferramenta subjacente era frágil e intolerante. Frágil porque falhava diante de inputs razoáveis (--status em vez de --state). Intolerante porque rejeitava sem oferecer alternativa (--project não existe, se vira).
Quando você substitui uma ferramenta frágil por uma tolerante, as instruções se simplificam automaticamente. Não há necessidade de reescrever o manual — ele se reescreve sozinho porque já não há nada que precisa ser advertido.
É o mesmo princípio que explica por que o manual de um iPhone tem 10 páginas e o de uma impressora tem 200. Não é que a Apple escreva melhor documentação. É que o iPhone não precisa explicar como carregar papel, alinhar cabeçotes ou limpar o tambor.
Uma ferramenta tolerante gera documentação curta. Uma ferramenta frágil gera manuais de sobrevivência.
E quando o usuário é um LLM, isso importa ainda mais. Cada linha de instruções é uma linha que pode ser mal interpretada, esquecida ou contradita. Um skill com 150 linhas de gambiarras dá 150 chances de algo sair errado. Um com zero gambiarras dá… zero chances de erro.
O padrão geral
Isso não é exclusivo de CLIs nem do Linear. Esse padrão é universal:
- Você tem uma ferramenta com interface ruim.
- Escreve instruções detalhadas para compensar.
- As instruções viram um manual de sobrevivência.
- Alguém (humano ou IA) ignora parte do manual.
- As coisas quebram.
- Você adiciona mais instruções.
- Volte ao passo 4.
A saída desse ciclo não é escrever instruções melhores. É consertar a ferramenta.
Se seu CLAUDE.md tem mais de 20 linhas explicando como não usar algo, é porque esse “algo” precisa ser reescrito. Se seu skill tem uma seção de “erros comuns e como evitá-los”, esses erros deveriam ser impossíveis, não documentados.
Cada aviso de “cuidado, degrau” é uma confissão de que o degrau não foi consertado.
Sua vez
Da próxima vez que você se pegar escrevendo instruções verbosas para compensar uma ferramenta problemática — seja em um CLAUDE.md, um README ou um wiki interno — pare um momento e pergunte a si mesmo:
- Estou documentando como usar a ferramenta ou como sobreviver à ferramenta?
- Quantas linhas poderiam desaparecer se a ferramenta aceitasse os inputs que o usuário naturalmente tentaria dar?
- Estou colocando um aviso ou consertando o degrau?
Se mais de 30% das suas instruções forem gambiarras, a ferramenta está quebrada. Não é culpa do usuário. Nem da documentação. É da ferramenta.
Conserte o degrau.
Série: Programação Adversarial