- Foi lançado o Agent Skills, que fornece explicitamente regras de banco de dados para resolver o problema de AI agents de programação não lidarem corretamente com Postgres
- O Postgres tem décadas de funcionalidades acumuladas, edge cases e características de desempenho, então os agents podem até funcionar, mas ainda gerar código que provoca full table scans ou deixa políticas de segurança de fora
- É composto por 8 categorias e 30 regras no total, organizadas por prioridade com base no impacto, incluindo desempenho de consultas, gerenciamento de conexões, segurança e RLS, design de schema e mais
- Em vez de documentação para humanos, é oferecido no formato de conjunto de regras consultado diretamente por AI agents
- Quando combinado com um servidor MCP, torna possível montar um agent de banco de dados pronto para uso real, com capacidade de execução e critério de decisão ao mesmo tempo
Reconhecimento do problema: a IA escreve código, mas não entende o sistema
- AI agents de programação geram código sintaticamente correto, mas têm a limitação de não considerar as características internas do Postgres nem os riscos operacionais
- Problemas como consultas que provocam full table scans, sugestões de índices que prejudicam a performance de escrita e ausência de Row Level Security continuam acontecendo repetidamente
- Foram observados diversos casos em que os agents deixam passar fatores críticos de desempenho, segurança e estabilidade em ambientes de produção
Visão geral do Postgres Agent Skills
- Um repositório de conhecimento baseado em regras criado para que AI agents consultem ao escrever código para Postgres
- Composto por 30 regras distribuídas em 8 categorias, ordenadas pelo nível de impacto
- Cada regra inclui título, prioridade, explicação da importância e exemplos de código corretos/incorretos
Estrutura das 8 categorias de regras
- Cada regra segue um formato consistente, com título, impacto, descrição e tags
- Query Performance (Critical): prevenção de full table scans e regras para escrever consultas eficientes
- Connection Management (Critical): connection pooling, ciclo de vida do cliente e limites de recursos
- Security and RLS (Critical): políticas de Row Level Security e padrões de controle de acesso
- Schema Design (High): estrutura de tabelas, tipos de dados e decisões de normalização
- Concurrency and Locking (Medium-High): isolamento de transações, prevenção de deadlocks e gerenciamento de locks
- Data Access Patterns (Medium): paginação, operações em lote e design de padrões de acesso
- Monitoring and Diagnostics (Low-Medium): análise de consultas, rastreamento de desempenho e debugging
- Advanced Features (Low): CTE, window functions, extensões e outros recursos próprios do Postgres
Exemplo de regra de Row Level Security
- Forma incorreta: se depender apenas de filtragem no nível da aplicação, existe risco de exposição de todos os dados por causa de bugs ou bypass
- Se for escrito como
select * from orders where user_id = $current_user_id;, um bypass pode retornar todos os pedidos
- Forma correta: aplicar RLS obrigatoriamente no nível do banco de dados
- Ativar RLS com
alter table orders enable row level security;
- Criar uma política com
create policy para que o usuário veja apenas seus próprios dados
- Forçar RLS até mesmo para o dono da tabela com
alter table orders force row level security;
- Exemplo de política para papel autenticado:
create policy orders_user_policy on orders for all to authenticated using (user_id = auth.uid());
Formato do Agent Skills e ecossistema
- Agent Skills é um formato aberto de documentação voltado a AI agents que fornece especialização de domínio ao agent, podendo ser lido e aplicado diretamente quando necessário
- Compatível com Claude Code, Cursor, GitHub Copilot, VS Code, Gemini CLI e outros
- É fornecido na forma de uma pasta com instruções e exemplos que o agent pode descobrir e usar quando precisar
- Em vez de esperar que o agent tenha aprendido os padrões corretos nos dados de treinamento, ele recebe regras explícitas
- É um padrão aberto definido pela Anthropic e vem sendo adotado em toda a indústria
- A Vercel lançou o react-best-practices, que empacota 10 anos de conhecimento de otimização em React e Next.js em 40 regras
- A Cloudflare lançou Skills para mais de 40 serviços, incluindo Workers, Pages, D1 e R2
Por que a Supabase criou essas regras
- A Supabase opera Postgres em centenas de milhares de projetos e testemunhou a repetição dos mesmos erros
- Índices ausentes em foreign keys
- Consultas que contornam RLS por engano
- Migrações que bloqueiam tabelas em produção
- Esgotamento do pool de conexões causado por clientes mal gerenciados
- Full table scans escondidos atrás de ORMs
- O conhecimento já existente no time de suporte, no Database Advisor e na documentação foi reorganizado em um formato amigável para agents e empacotado
Relação com o servidor MCP
- O servidor MCP da Supabase permite que AI agents se conectem diretamente a projetos Supabase para criar tabelas, executar consultas, gerenciar schemas e configurar definições em linguagem natural
- O servidor MCP dá ao agent a capacidade de realizar tarefas de banco de dados, e as melhores práticas o ensinam a fazê-las corretamente
- Analogia: o servidor MCP é o volante, e as melhores práticas são a autoescola
- Um agent com apenas acesso ao MCP pode executar qualquer consulta solicitada
- Um agent com acesso ao MCP e às regras pode alertar antes de criar um índice que bloqueia tabelas, sugerir políticas de RLS antes de implantar código inseguro e estruturar consultas para evitar problemas de desempenho
- O servidor MCP cuida da conexão e da execução; estas melhores práticas cuidam do julgamento
- O Agent Skills avisa sobre riscos antes da execução e induz escolhas melhores
- Ao separar capacidade de execução e critério de decisão, é possível montar um ambiente de automação seguro e confiável
Como instalar
- Local do repositório: github.com/supabase/agent-skills
- É possível instalar interativamente usando o pacote npm skills da Vercel
npx skills add supabase/agent-skills
- Ao usar Claude Code, é possível instalar como plugin
/plugin marketplace add supabase/agent-skills/plugin install postgres-best-practices@supabase-agent-skills
Ainda não há comentários.