Skip to main content

Criação de arquivos de contexto AGENTS.md

Este guia explica como criar, refatorar e manter arquivos de roteamento de contexto AGENTS.md em todo o monorepo.

1. Determinação da camada apropriada​

Antes de criar um arquivo AGENTS.md, identifique a camada de destino:

  1. Raiz do Monorepo: Camada 1 (/AGENTS.md). Existe apenas um arquivo nesta camada.
  2. Raiz de Contexto Delimitado: Camada 2 (/[context]/AGENTS.md). Criado para raízes de domínio (cortex, hub, platform, studio, tools, renderer, docs).
  3. Subdominídio Técnico: Camada 3 (/[context]/[sub]/AGENTS.md). Criado apenas para sub-workspaces com regras técnicas exclusivas e não duplicativas (por exemplo, services/api, packages/core).

2. Workflow de criação passo a passo​

Passo 1: Adicione a diretiva de hierarquia de contexto​

Para arquivos da Camada 2 e da Camada 3, coloque o bloco XML \<context-hierarchy> bem no topo:

<context-hierarchy>
  <parent src="../AGENTS.md" type="global-rules" />
  <system-instruction>
    AGENT: If you have not read "../AGENTS.md" in this session, stop now and read it using your
    file-reading tools before proceeding. Global constraints are mandatory.
  </system-instruction>
</context-hierarchy>

Passo 2: Defina a linguagem ubíqua (apenas para a Camada 2)​

Inclua uma tabela definindo os termos do domínio e sinônimos proibidos:

## Ubiquitous Language

| Term       | Definition                 | Forbidden Synonyms   |
| :--------- | :------------------------- | :------------------- |
| `Customer` | The authenticated hub user | user, person, member |

Passo 3: Escreva diretrizes imperativas​

Use palavras-chave imperativas estritas (MUST, NEVER, ALWAYS) em vez de prosa descritiva:

  • Correto: Controllers MUST inject Mongoose models into the repository constructor.
  • Incorreto: Controllers should probably use repositories.

Passo 4: Valide o limite de linhas​

  • Camada 1: Máximo de 80 linhas.
  • Camada 2: Máximo de 120 linhas.
  • Camada 3: Máximo de 100 linhas.

Passo 5: Formate com o Prettier​

Execute o Prettier para formatar o markdown e os blocos de código:

pnpm exec prettier --write <path/to/AGENTS.md>