Agentes de Programação de IA e AGENTS.md

Assistentes de programação por IA — Claude, GitHub Copilot, Cursor e outros — podem construir e personalizar um portal PowerPortalsPro com muito mais precisão quando entendem as convenções do framework. Para tornar isso automático, todo projeto gerado a partir de um template PowerPortalsPro envia um AGENTS.md arquivo em sua raiz.

O que é AGENTS.md?

AGENTS.md é um arquivo de instruções Markdown simples que ferramentas de codificação por IA leem automaticamente para aprender as convenções de um projeto antes de escreverem código. É um padrão emergente entre ferramentas — o mesmo arquivo é captado por Claude, GitHub Copilot, Cursor e outros — então você mantém um conjunto de orientações, não uma por ferramenta. Os templates PowerPortalsPro geram um AGENTS.md modelo personalizado para o framework, de modo que o agente saiba montar recursos a partir de componentes e serviços do framework, em vez de gerenciar manualmente acessos, autenticação ou lógica de salvamento.

Nota

A orientação é específica para stack: um projeto gerado a partir do template React shippa um foco AGENTS.mdem React, e um projeto Blazor traz um foco em Blazor. Cada um descreve os componentes, serviços e padrões para essa pilha.

Onde ela vive

O arquivo fica na raiz da sua solução gerada, junto com seus projetos, então qualquer ferramenta de IA aberta no repositório o encontra sem configuração:

O que tem dentro

O gerado AGENTS.md destila as convenções que este site de documentação cobre em uma referência sempre em contexto que um agente lê em cada tarefa:

• Regras de ouro — não role manualmente o acesso aos dados, a auth, ou a lógica de salvamento; vincular editores a um contexto de registro; Nunca codifique cores ou strings voltadas para o usuário.
• Arquitetura e layout de projetos — como os projetos host e cliente se encaixam e onde suas páginas e componentes estão.
• Padrões de dados e edição — carregando registros, o modelo de contexto de registro + editor de campo, e os componentes da grade.
• Uma referência compacta de componentes — os props/parâmetros dos componentes que você mais alcança, com ponteiros para tipos e IntelliSense para o restante.
• Segurança — filtrar dados na fonte para paginação e desempenho precisos; Os manipuladores de permissões são a camada de fiscalização.
• Localização e tematização — as convenções string-key e regras design-token.
• Workflow de desenvolvimento & pegadinhas — como rodar o projeto e os erros a evitar.

Usando-o de forma eficaz

Alguns hábitos que aproveitam ao máximo o guia:

• Deixe o corretor ler primeiro. A maioria das ferramentas carrega AGENTS.md automaticamente; se não, aponte seu assistente para ela antes de pedir uma funcionalidade.
• Aproveite os tipos e o IntelliSense. O guia é deliberadamente conciso — para toda a superfície de qualquer componente ou serviço, o agente pode ler as definições do TypeScript (React) ou do IntelliSense (Blazor) em XML-doc.
• Consulte este site. Aponte o agente para os exemplos ao vivo e a referência da API aqui na demo para padrões que ele pode copiar.
• Revise a saída. O guia torna o agente mais preciso, mas não substitui sua avaliação — verifique especialmente as regras de segurança geradas e o filtro de dados.

Por exemplo, uma solicitação como essa dá a um agente tudo o que ele precisa para produzir código idiomático:

Faça seu

AGENTS.md é um arquivo comum no seu repositório — edite-o. Adicione suas próprias tabelas e relacionamentos, regras de domínio, convenções de nomes e padrões específicos do projeto para que o agente aprenda seu portal, não apenas o framework. Quanto melhor o arquivo refletir sua base de código, melhor será o código gerado.

Dica

Trate AGENTS.md como documentação viva: quando você estabelecer uma nova convenção ou encontrar um erro recorrente, adicione uma linha ao arquivo para que todas as futuras sessões de IA se beneficiem.