🎯 Briefing do projeto
Antes do /printing-press, escreva 1 paragrafo definindo escopo, persona e endpoints minimos. CLI bem definida sai redondinha no primeiro generate.
Briefing pronto
CLI: brasil-api-pp-cli
Skill: pp-brasil-api
Persona: dev brasileiro usando Claude Code, n8n ou Supabase Edge Function
Endpoints (v1):
- GET /cep/v2/{cep}
- GET /cnpj/v1/{cnpj}
- GET /banks/v1
- GET /feriados/v1/{ano}
- GET /ddd/v1/{ddd}
Auth: nenhuma (API publica)
Output padrao: texto humano. Flag --json para n8n.
Cache: SQLite (CEP/CNPJ: 30 dias; bancos/feriados: 24h)💡 Por que escrever isso
O factory faz a entrevista, mas se voce ja chega com decisoes, ele pula perguntas e gera direto. Escopo aberto vira CLI gigante com endpoints que ninguem usa.
📮 CEP: o subcomando mais simples
Caso base: 1 input, 1 output, sem auth, sem paginacao. Ideal para entender o pipeline inteiro.
Comando final
$ brasil-api cep 01310100
Av. Paulista, Bela Vista, Sao Paulo/SP
$ brasil-api cep 01310100 --json
{"cep":"01310-100","logradouro":"Av. Paulista","bairro":"Bela Vista","cidade":"Sao Paulo","uf":"SP"}
# Cache: segunda chamada e instantanea
$ brasil-api cep 01310100
Av. Paulista, Bela Vista, Sao Paulo/SP (cache 3 ms)📊 Antes vs depois
- JSON cru da API: ~280 bytes / ~80 tokens
- Output da CLI (texto): ~50 bytes / ~15 tokens
- Reducao: 5x em uma chamada trivial. Imagine em 100 CEPs.
🏢 CNPJ com --fields
A resposta de CNPJ traz 40+ campos. A flag --fields deixa o agente filtrar antes de receber.
Padrao: tudo
$ brasil-api cnpj 00000000000191
Razao social: BANCO DO BRASIL SA
Nome fantasia: BANCO DO BRASIL
Situacao: ATIVA
Abertura: 1966-08-01
... (38 linhas)🎯 Com filtro
$ brasil-api cnpj 00000000000191 --fields razao_social,situacao
BANCO DO BRASIL SA | ATIVAO agente economiza 90% dos tokens quando so precisa confirmar se a empresa esta ativa.
💡 Padrao adotar em toda CLI
Sempre que o endpoint retornar muitos campos, ofereca --fields. O agente quase nunca quer tudo.
🏦 Bancos, Feriados e DDD
Tres endpoints com listas estaveis. Sao ideais para cache agressivo (24h+) e busca local via FTS5.
Exemplos
$ brasil-api bancos --search "itau"
341 ITAU UNIBANCO S.A.
652 ITAU UNIBANCO HOLDING S.A.
184 ITAU BBA S.A.
$ brasil-api feriados 2026
2026-01-01 Confraternizacao Universal
2026-02-17 Carnaval
... (12 linhas)
$ brasil-api ddd 11
Sao Paulo (SP) + 38 cidades da regiao metropolitana✓ O que fazer
- ✓Cache 24h em listas estaveis
- ✓FTS5 para busca em bancos
- ✓Output em tabela compactada
✗ O que NAO fazer
- ✗Cache permanente (lista de bancos muda)
- ✗Devolver JSON cru sem filtro
- ✗Fazer pull online em loop
💾 Cache SQLite offline
O SQLite local guarda o JSON cru. Queries seguintes leem do disco. Funciona offline e elimina latencia.
Schema gerado pelo factory
CREATE TABLE queries (
hash TEXT PRIMARY KEY, -- sha256 de metodo+url+params
endpoint TEXT, -- ex: 'cep', 'cnpj'
payload TEXT, -- JSON cru
fetched_at INTEGER, -- timestamp
ttl_seconds INTEGER -- TTL por endpoint
);
CREATE INDEX idx_endpoint ON queries(endpoint, fetched_at);
CREATE VIRTUAL TABLE queries_fts USING fts5(payload, content='queries');⏱️ TTL por endpoint
- · CEP: 30 dias (raramente muda)
- · CNPJ: 7 dias (situacao muda eventualmente)
- · Bancos: 24h
- · Feriados: 30 dias (ano todo previsivel)
- · DDD: 30 dias
💡 Flag --refresh
Sempre exponha --refresh para forcar nova chamada ignorando cache. Util quando o usuario sabe que o dado mudou (ex: empresa acabou de ser ativada).
🎁 Empacotar a skill pp-brasil-api
A CLI esta pronta. Falta criar a skill em PT-BR para o Claude Code rotear linguagem natural.
SKILL.md gerado
---
name: pp-brasil-api
description: BrasilAPI CLI. Consulta CEP, CNPJ, bancos, feriados e DDD.
Trigger phrases: "CEP de X", "essa empresa esta ativa?", "lista de
bancos com Itau no nome", "feriados de 2026", "que cidades sao DDD 11".
---
# pp-brasil-api
## Exemplos
- "qual o CEP da Av. Paulista?" -> `brasil-api cep 01310100`
- "essa empresa CNPJ 00.000.000/0001-91 esta ativa?" ->
`brasil-api cnpj 00000000000191 --fields razao_social,situacao`
- "lista bancos brasileiros com 'Itau'" -> `brasil-api bancos --search itau`🧪 Teste rapido no Claude Code
Depois de instalar a skill, abra o Claude Code e pergunte:
- · "qual o CEP da Avenida Brasil 1000 em Sao Paulo?"
- · "verifica se o CNPJ 00.000.000/0001-91 esta ativo"
- · "quais os feriados nacionais de 2026?"
Se o agente invocar brasil-api, a integracao esta perfeita.
🇧🇷 Dica de PT-BR
Sempre inclua trigger phrases em portugues do Brasil coloquial. "essa firma ta ativa?", "tem CEP do bairro tal" — o agente brasileiro fala assim.
✅ Resumo do Modulo
Proximo Modulo:
1.6 — Integracoes: n8n + Supabase