AGENTS.md fornecem uma maneira simples de dar ao Cascade instruções sensíveis ao contexto que são aplicadas automaticamente com base em onde o arquivo está localizado no seu projeto. Isso é particularmente útil para fornecer diretrizes de código específicas de diretório, decisões de arquitetura ou convenções do projeto.
Como funciona
AGENTS.md (ou agents.md), o Windsurf o descobre automaticamente e o envia para o mesmo mecanismo de Rules que alimenta .windsurf/rules/ — só que com o modo de ativação inferido com base na localização do arquivo, em vez do frontmatter:
- Diretório raiz: Tratado como uma regra sempre ativa — todo o conteúdo é incluído no prompt de sistema do Cascade em cada mensagem.
- Subdiretórios: Tratados como uma regra glob com um padrão gerado automaticamente de
<directory>/**— o conteúdo é aplicado apenas quando o Cascade lê ou edita arquivos dentro desse diretório.
AGENTS.md ideal para fornecer orientações direcionadas sem sobrecarregar um único arquivo de configuração global.
Criando um arquivo AGENTS.md
AGENTS.md ou agents.md no diretório desejado. O arquivo usa markdown simples, sem precisar de frontmatter especial.
Exemplo de estrutura
Exemplo de conteúdo
AGENTS.md de exemplo para um diretório de componentes React:
Descoberta e Escopo
AGENTS.md em todo o seu workspace:
- Varredura do workspace: Todos os arquivos
AGENTS.mddentro do seu workspace e de seus subdiretórios são descobertos - Suporte a repositórios Git: Para repositórios Git, Windsurf também pesquisa diretórios pai até a raiz do repositório
- Não diferencia maiúsculas de minúsculas: Tanto
AGENTS.mdquantoagents.mdsão reconhecidos
Escopo automático
AGENTS.md é o escopo automático com base no local do arquivo:
Isso significa que você pode ter vários arquivos
AGENTS.md em diferentes níveis, cada um fornecendo orientações cada vez mais específicas para seus respectivos diretórios.
Melhores práticas
AGENTS.md:
- Mantenha as instruções focadas: Cada
AGENTS.mddeve conter instruções relevantes à finalidade do diretório - Use formatação clara: Listas, títulos e blocos de código tornam as instruções mais fáceis de o Cascade seguir
- Seja específico: Exemplos concretos e convenções explícitas funcionam melhor do que diretrizes vagas
- Evite redundância: Não repita instruções globais em arquivos de subdiretórios; eles herdam as instruções dos diretórios pai
Diretrizes de Conteúdo
Comparação com Rules
AGENTS.md quanto Rules forneçam instruções para o Cascade, eles têm finalidades diferentes:
Use
AGENTS.md quando quiser instruções simples baseadas em localização. Use Rules quando precisar de mais controle sobre quando e como as instruções serão aplicadas.