Pular para o conteúdo principal
Arquivos 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

Quando você cria um arquivo 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.
Esse escopo baseado na localização torna o AGENTS.md ideal para fornecer orientações direcionadas sem sobrecarregar um único arquivo de configuração global.

​
Criando um arquivo AGENTS.md

Basta criar um arquivo chamado AGENTS.md ou agents.md no diretório desejado. O arquivo usa markdown simples, sem precisar de frontmatter especial.

​
Exemplo de estrutura

my-project/
├── AGENTS.md                    # Instruções globais para todo o projeto
├── frontend/
│   ├── AGENTS.md                # Instruções específicas para o código do frontend
│   └── src/
│       └── components/
│           └── AGENTS.md        # Instruções específicas para os componentes
├── backend/
│   └── AGENTS.md                # Instruções específicas para o código do backend
└── docs/
    └── AGENTS.md                # Instruções para a documentação

​
Exemplo de conteúdo

Segue um arquivo AGENTS.md de exemplo para um diretório de componentes React: 
# Component Guidelines

When working with components in this directory:

- Use functional components with hooks
- Follow the naming convention: ComponentName.tsx for components, useHookName.ts for hooks
- Each component should have a corresponding test file: ComponentName.test.tsx
- Use CSS modules for styling: ComponentName.module.css
- Export components as named exports, not default exports

## File Structure

Each component folder should contain:
- The main component file
- A test file
- A styles file (if needed)
- An index.ts for re-exports

​
Descoberta e Escopo

Windsurf descobre automaticamente arquivos AGENTS.md em todo o seu workspace:
  • Varredura do workspace: Todos os arquivos AGENTS.md dentro 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.md quanto agents.md são reconhecidos

​
Escopo automático

O principal benefício de AGENTS.md é o escopo automático com base no local do arquivo:
Local do arquivoEscopo
Raiz do workspaceAplica-se a todos os arquivos (sempre ativo)
/frontend/Aplica-se ao trabalhar com arquivos em /frontend/**
/frontend/components/Aplica-se ao trabalhar com arquivos em /frontend/components/**
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

Para aproveitar ao máximo os arquivos AGENTS.md:
  • Mantenha as instruções focadas: Cada AGENTS.md deve 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

# Bom Exemplo
- Use o modo strict do TypeScript
- Todas as respostas da API devem incluir tratamento de erros
- Siga as convenções de nomenclatura REST para endpoints

# Exemplo Menos Eficaz
- Escreva código de qualidade
- Tenha cuidado com erros
- Use as melhores práticas

​
Comparação com Rules

Embora tanto AGENTS.md quanto Rules forneçam instruções para o Cascade, eles têm finalidades diferentes:
RecursoAGENTS.mdRules
LocalEm diretórios do projeto.windsurf/rules/ ou global
Definição de escopoAutomático com base na localização do arquivoManual (glob, sempre ativo, decisão do modelo, manual)
FormatoMarkdown simplesMarkdown com frontmatter
Melhor paraConvenções específicas de diretórioQuestões transversais, lógica de ativação complexa
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.