Melhores Práticas para Habilidades de Agente

Regras que mantêm as Habilidades de Agente do Postgres precisas, seguras e alinhadas com a política de produção do PostgreSQL 18.4.

Como Usar Esta Lista

• Aplique ao criar ou atualizar qualquer SKILL.md em .cursor/skills/.
• Revise após a atualização menor do Postgres ou mudança no runner de migração principal.
• Aplique via revisão de PR nos arquivos de habilidade, assim como no código da aplicação.
• Verifique os itens ao integrar engenheiros em fluxos de trabalho de DBA assistidos por IA.

A - Estrutura e Fixação

• Bloco de fixação de pilha em cada habilidade. Versões do PostgreSQL 18.4, cliente psql, Patroni/pgBackRest por ADR (Noções Básicas de Habilidades de Agente).
• Seções obrigatórias: O quê, Quando, Entradas, Saídas, Guardrails, Fixação de pilha, Exemplos de prompts.
• Uma habilidade por domínio de decisão. Sem misturar mega-habilidades de incidentes + migração + backup.
• Versionar habilidades quando os guardrails mudam. Semver no README ou tag git na pasta da habilidade.
• Vincular documentação autoritativa humana. Guias de EXPLAIN e cookbooks de migração permanecem a fonte da verdade.

B - Segurança e Governança

• Sem DDL de produção do agente sem ticket. Humano mescla o PR de migração após prova em staging.
• Sem pg_terminate_backend sem evidência de bloqueio. A habilidade de incidente gera o PID; o humano executa.
• Sem DROP SLOT / DROP DATABASE sem aprovador nomeado. Documentar nos guardrails.
• Staging como padrão para EXPLAIN (ANALYZE). EXPLAIN em produção apenas com política de incidente somente leitura.
• SQL de rollback exigido nas saídas da habilidade de migração. Equipes somente para frente ainda documentam o desmonte manual.
• Itens de postmortem se tornam guardrails em até 5 dias. Loop de aprendizado SEV1 fechado.

C - Saídas e Verificação

• Terminar cada saída de habilidade com um bloco de comando. psql, flyway migrate, patronictl list, códigos de saída.
• Rejeitar "concluído" apenas em texto. O agente deve mostrar o template de resultados da consulta de verificação.
• Anexar consultas de escala de tabela para habilidades de migração/explain. Contagens de linhas de pg_class.reltuples.
• A habilidade INCIDENT preserva comandos de bundle de log. df, pg_locks, visualizações de replicação em um único script.
• A habilidade FAILOVER registra timestamps de RTO. Minutos desde o gatilho até a escrita bem-sucedida.

D - Processo da Equipe

• Nomear explicitamente a habilidade no prompt. "Use a Habilidade de Segurança de Migração em V12__..."
• Registro de habilidades com proprietários. O DBA da plataforma mantém docs/skills/README.md.
• Calendário trimestral de revisão de habilidades. Após a varredura das notas de lançamento menor do Postgres 18.x.
• Nunca mesclar automaticamente PRs de agentes. Mesma barra de revisão que SQL escrito por humanos.
• Registrar falhas de habilidade em #database. Melhorar a lista de entradas quando os agentes adivinharem errado.
• Parear usuários de habilidade pela primeira vez. Pareamento em PRs de Consulta para a habilidade EXPLAIN.

E - Limites de Escopo

• Habilidades orquestram; docs ensinam. Páginas de fundamentos não são substituídas por habilidades.
• Não duplicar pganalyze. O ceticismo do consultor permanece na documentação de ferramentas essenciais.
• Ramos gerenciados vs. auto-hospedados. Passos de failover RDS diferem de Patroni; documentar ambos ou dividir habilidades.
• Sites com air-gap omitem passos SaaS. Habilidades funcionam offline apenas com ferramentas de código aberto.

FAQs

Relacionados

• Noções Básicas de Habilidades de Agente - estrutura e invocação
• Habilidade de Revisão EXPLAIN - PRs de consulta
• Habilidade de Segurança de Migração - pontuação de DDL
• Habilidade de Simulação de Failover - simulações de HA
• Habilidade de Triagem de Incidentes - árvore SEV1

Versões da Pilha: Esta página foi escrita para PostgreSQL 18.4, Flyway 10+, Patroni 4.x e pgBackRest 2.55+.