> ## Documentation Index
> Fetch the complete documentation index at: https://docs.windsurf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AGENTS.md

> Crie arquivos AGENTS.md para fornecer ao Cascade instruções com escopo de diretório. As instruções são aplicadas automaticamente com base na localização do arquivo no seu projeto.

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.

<div id="how-it-works">
  ## Como funciona
</div>

Quando você cria um arquivo `AGENTS.md` (ou `agents.md`), o Windsurf o descobre automaticamente e o envia para o mesmo mecanismo de [Rules](/pt-BR/windsurf/cascade/memories#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.

<div id="creating-an-agentsmd-file">
  ## Criando um arquivo AGENTS.md
</div>

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

<div id="example-structure">
  ### Exemplo de estrutura
</div>

```
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
```

<div id="example-content">
  ### Exemplo de conteúdo
</div>

Segue um arquivo `AGENTS.md` de exemplo para um diretório de componentes React:

```markdown theme={null}
# 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
```

<div id="discovery-and-scoping">
  ## Descoberta e Escopo
</div>

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

<div id="automatic-scoping">
  ### Escopo automático
</div>

O principal benefício de `AGENTS.md` é o escopo automático com base no local do arquivo:

| Local do arquivo        | Escopo                                                           |
| ----------------------- | ---------------------------------------------------------------- |
| Raiz do workspace       | Aplica-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.

<div id="best-practices">
  ## Melhores práticas
</div>

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

<div id="content-guidelines">
  ### Diretrizes de Conteúdo
</div>

```markdown theme={null}
# 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
```

<div id="comparison-with-rules">
  ## Comparação com Rules
</div>

Embora tanto `AGENTS.md` quanto [Rules](/pt-BR/windsurf/cascade/memories#rules) forneçam instruções para o Cascade, eles têm finalidades diferentes:

| Recurso             | AGENTS.md                                     | Rules                                                  |
| ------------------- | --------------------------------------------- | ------------------------------------------------------ |
| Local               | Em diretórios do projeto                      | `.windsurf/rules/` ou global                           |
| Definição de escopo | Automático com base na localização do arquivo | Manual (glob, sempre ativo, decisão do modelo, manual) |
| Formato             | Markdown simples                              | Markdown com frontmatter                               |
| Melhor para         | Convenções específicas de diretório           | Questõ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.