---
title: "Regras do agente"
description: "Como fixar o Notarium no arquivo de regras do seu agente (CLAUDE.md, AGENTS.md, Cursor rules) para que a sessão comece com start_session."
---

# Regras do agente

Conectar o endpoint MCP é metade do trabalho. A outra metade é fazer o agente começar **sozinho** pela base de conhecimento, em vez de esperar o seu "dá uma olhada no Notarium primeiro". Esta página é sobre deixar isso resolvido de uma vez.

## Por que só conectar não basta

Qual ferramenta chamar é decisão do modelo. Do lado do servidor, o Notarium faz tudo o que pode: na inicialização, entrega `instructions` ("chame `start_session` primeiro"), e a descrição da própria ferramenta diz sem rodeios que ela é idempotente e segura para chamar de novo. Isso aumenta bastante as chances, mas **não é garantia** — e, pelo desenho do protocolo, não tem como ser.

A garantia está do seu lado: na instrução permanente do agente. O efeito prático é simples — ou o agente abre a sessão com o contexto do projeto, ou você lembra disso na mão toda vez, e a interação deixa de parecer nativa.

> [!note] Pular a chamada não quebra nada
> Deixar de chamar `start_session` não quebra o trabalho: as demais ferramentas se bastam, e os limites de acesso são mantidos pelo token, não pela disciplina do agente. A diferença está só no contexto — o agente não vai ver o seu perfil, o delta de mudanças nem o dicionário de categorias já acordadas, o que aumenta a chance de ele criar uma duplicata ou nomear as coisas do jeito dele.

## Onde escrever isso

Quase todo cliente de agente tem um arquivo de instruções permanentes que é injetado em toda sessão:

| Cliente | Onde costuma ficar |
|---|---|
| Claude Code | `CLAUDE.md` na raiz do repositório (e um global, no seu diretório home) |
| Codex | `AGENTS.md` na raiz do repositório |
| Cursor | regras do projeto em `.cursor/rules` |
| Seu próprio agente ou uma integração via API | o prompt de sistema |

O formato e os caminhos exatos são definidos pelo cliente e mudam sem depender de nós — confira a documentação dele. O Notarium não exige nada do arquivo: é texto puro, lido pelo seu agente.

## O bloco mínimo

Três regras cobrem o cenário principal — começar pelo contexto, não criar duplicatas e colocar o conhecimento no lugar certo:

```markdown
## Notarium — a base de conhecimento do projeto

- No início de uma nova sessão, chame `start_session(project: "acme/website")`
  no servidor MCP `notarium` — perfil, projetos disponíveis, índice deste
  projeto, delta de mudanças desde a última visita e dicionário de categorias.
- **Busque antes de gravar:** `search("<tema>", project: "acme/website")` —
  a busca cobre também a sua própria memória, então duplicatas são pegas.
- Registre fatos duradouros sobre o projeto com `remember_about_project`,
  sobre o dono com `remember_about_user`, e conhecimento compartilhado
  visível com `create_note`.
```

Substitua pelo handle do seu projeto. Ele costuma ter o formato `space/project`, mas, no projeto raiz de um espaço, se reduz a um único segmento — só `space`. Não deduza o handle por regra: `get_my_projects` devolve a lista pronta, então pegue dali, literalmente. Num arquivo de regras, é melhor deixar o valor exato fixo, para o agente não sair procurando toda vez.

> [!tip] Uma chamada em vez de cinco
> `start_session` foi feito exatamente para isso: em uma única requisição, devolve o que de outro modo custaria várias chamadas exploratórias e contexto extra. É idempotente — chamar de novo depois de uma compactação de contexto é seguro e não tem efeitos colaterais. A única coisa que não se repete é o delta de mudanças: por padrão, a primeira chamada move o marcador da "última visita", então a segunda volta vazia. Para espiar o delta sem mover o marcador, chame com `acknowledge: false`.

## O bloco estendido: um mapa do cânone

Se o projeto tem notas que precisam ser lidas para um papel ou uma tarefa específicos, não faça o agente caçá-las de novo a cada sessão — dê um mapa. Carregar algumas notas específicas sai mais barato que "leia o projeto inteiro":

```markdown
## Notarium

- Primeira chamada — `start_session(project: "acme/website")`.
- Depois disso, carregue notas específicas em vez de ler o projeto inteiro:
  - convenções de desenvolvimento — `get_note("<id>")`;
  - checklist de revisão — `get_note("<id>")`;
  - contexto em torno de um tema — `recall("<tema>", project: "acme/website")`.
- Antes de qualquer gravação — `search("<tema>", project: "acme/website")`.
- Mantenha o log de trabalho e as decisões de uma tarefa no Notarium,
  e não em arquivos do repositório.
```

Os ids das notas são estáveis: sobrevivem a uma renomeação e a uma mudança de lugar, então o mapa não apodrece quando você reorganiza a base. Um link `[[por título]]` também não quebra numa renomeação — o título antigo vai para o histórico de aliases.

## Duas camadas de regras

Separe as instruções por tempo de vida — assim você não precisa duplicá-las em cada repositório:

- **A camada global** (um arquivo de regras compartilhado ou o prompt de sistema) — o que vale sempre: chamar `start_session` primeiro, buscar antes de gravar, onde vão os fatos sobre o dono. Aqui não entra handle de projeto.
- **A camada do projeto** (um arquivo no repositório) — o handle deste projeto específico, o mapa do cânone, os acordos locais.

Aí conectar um repositório novo à base de conhecimento vira umas poucas linhas com um único handle, enquanto as regras compartilhadas ficam num lugar só.

## O que não cabe nas regras

> [!warning] Regras de agente não são um mecanismo de segurança
> Um arquivo de regras é uma dica, não um limite. O que o agente **pode** fazer é definido pelas permissões do token e pelo conjunto de ferramentas: um token de leitura simplesmente não enxerga as ferramentas de escrita, e o espaço de outra pessoa é inalcançável por princípio. Não tente cercar o agente com texto onde o que resolve é o escopo do token — veja [Segurança e visibilidade](/docs/agents/security/).

Mais duas coisas que não devem parar ali:

- **Tokens.** Um arquivo de regras normalmente vive no git. Um token pessoal se define na configuração do seu cliente MCP, não numa instrução.
- **Repetir a referência de ferramentas.** O agente já vê os nomes e as descrições em `tools/list`, que são estáticos e sempre atuais. Uma cópia no arquivo de regras se descola da realidade rapidamente — escreva intenções e acordos, não uma duplicata da documentação.

## Como isso se combina com a curadoria de contexto

Duas metades de um mesmo trabalho, e uma não substitui a outra:

- **O arquivo de regras** garante que a chamada de `start_session` **aconteça**.
- **A seção Agents → Context** decide **o que** essa chamada traz de volta: fixações always-load, conjuntos de contexto e silenciamento de categorias de memória barulhentas — tudo dentro de um orçamento de tokens comum.

Ou seja: se o agente começa com contexto, mas não com o contexto certo, o conserto não está no arquivo de regras — está nos [conjuntos de contexto e fixações](/docs/agents/context-pins/).

## A seguir

- [Conectando um agente](/docs/agents/connect/) — token, conector OAuth, transporte.
- [Conjuntos de contexto e fixações](/docs/agents/context-pins/) — o que entra no `start_session`.
- [Ferramentas de intenção](/docs/agents/intent-tools/) — o conjunto completo e a ordem das chamadas.
- [Memória do agente](/docs/agents/memory/) — como `remember_*` difere de `create_note`.