Verboo Code: como dar instruções permanentes ao agente com /memory e AGENTS.md

Toda sessão nova você repete as mesmas coisas: "use pnpm, não npm", "os testes rodam com make test", "não mexa na pasta legacy/". O /memory da Verboo Code acaba com isso: você escreve essas regras uma vez num arquivo Markdown e a CLI carrega o arquivo no começo de toda sessão. Este guia mostra quais arquivos existem, onde cada um fica e como escrever regra que vale só para uma parte do código.

O que o /memory faz na Verboo Code?

Ele abre um seletor com os seus arquivos de instrução e edita o escolhido no seu editor de texto. Se o arquivo ainda não existe, a CLI cria vazio antes de abrir.

/memory

Depois de escolher, a CLI responde Opened memory file at seguido do caminho real do arquivo. O editor usado é o da variável $VISUAL e, se ela não existir, o de $EDITOR. Para trocar:

export EDITOR="code --wait"

Quais arquivos de instrução a Verboo Code lê?

Quatro níveis, carregados nesta ordem. O que é carregado por último pesa mais, então a regra do projeto ganha da regra global, e a pessoal ganha da do projeto.

Nível	Arquivo	Para quê
Managed	CLAUDE.md na pasta gerenciada do sistema	Política da empresa, igual para todo mundo na máquina
User memory	~/.verboo/CLAUDE.md e ~/.verboo/rules/*.md	Suas preferências em todos os projetos
Project memory	AGENTS.md (ou CLAUDE.md se não houver AGENTS.md), .claude/CLAUDE.md e .claude/rules/*.md	Regras do repositório, versionadas no git
Local	CLAUDE.local.md	Regras pessoais só deste projeto, fora do git

Se você define VERBOO_CONFIG_DIR, o arquivo de User memory passa a ficar dentro dessa pasta em vez de ~/.verboo/.

AGENTS.md ou CLAUDE.md?

Prefira AGENTS.md. Na raiz de cada pasta, a Verboo Code procura primeiro o AGENTS.md e só usa o CLAUDE.md quando o AGENTS.md não existe. Os dois não somam: se o repositório tem os dois na mesma pasta, só o AGENTS.md entra. Quando você escolhe Project memory no /memory, o arquivo criado é o AGENTS.md da pasta atual.

Como a CLI acha os arquivos do projeto?

Ela sobe da pasta onde você abriu a sessão até a raiz do disco e lê o arquivo de instrução de cada nível. Num monorepo, isso permite uma regra geral na raiz e outra mais específica em packages/api/: abrindo a sessão em packages/api/, as duas entram, e a mais próxima pesa mais.

meu-monorepo/
├── AGENTS.md              # regras gerais
└── packages/
    └── api/
        ├── AGENTS.md      # regras da API, pesam mais
        └── CLAUDE.local.md  # suas notas, fora do git

Coloque CLAUDE.local.md no .gitignore. Ele existe justamente para o que não deve ir para o time: caminho da sua máquina, credencial de teste local, preferência pessoal.

O que escrever no AGENTS.md?

Só o que o agente erraria sem ler. Comando de build e teste que não é o óbvio, convenção do time, pasta que não pode ser tocada. O código define 40.000 caracteres como tamanho máximo recomendado por arquivo, e tudo isso entra no contexto de toda sessão, então curto é melhor.

# Projeto

- Gerenciador de pacotes: pnpm. Nunca rode npm install.
- Testes: make test. Rode antes de dizer que terminou.
- Não edite nada em legacy/, o time está migrando.
- Commits em português, no imperativo.

@docs/arquitetura.md

Para gerar um primeiro rascunho a partir do código, rode /init: ele analisa o repositório e propõe o arquivo de instruções. Depois revise e corte o que for óbvio.

Como importar outro arquivo com @?

Escreva @ seguido do caminho numa linha de texto do arquivo de instrução. O arquivo importado entra no contexto antes do arquivo que o importou. Assim você reaproveita a documentação que já existe em vez de copiar.

Sintaxe	Resolve para
@docs/stack.md	Caminho relativo (igual a @./docs/stack.md)
@~/notas/padroes.md	Caminho a partir da sua pasta home
@/etc/time/regras.md	Caminho absoluto

Três detalhes do código que evitam dor de cabeça: o @ não funciona dentro de bloco de código, arquivo que não existe é ignorado sem erro, e só entram arquivos de texto (.md, .txt, .json, .yaml, código-fonte e similares). Imagem e PDF ficam de fora. Importação circular não trava nada: cada arquivo entra uma vez só.

Como criar uma regra que vale só para uma pasta?

Crie um .md em .claude/rules/ com paths: no frontmatter. Essa regra não entra no começo da sessão: ela só é carregada quando o agente lê um arquivo que casa com o padrão.

mkdir -p .claude/rules

---
paths: src/api/**/*.ts, src/api/**/*.test.ts
---

- Todo endpoint novo precisa de teste de contrato.
- Erros saem no formato { code, message }, nunca string solta.

O campo aceita vários padrões separados por vírgula, ou uma lista YAML, e entende chaves: src/*.{ts,tsx} vira src/*.ts e src/*.tsx. Arquivo em .claude/rules/ sem paths: vale sempre, como se fosse parte do AGENTS.md. As subpastas de rules/ também são lidas, então dá para organizar por assunto.

E a memória automática?

É outra coisa. Além dos arquivos que você escreve, a Verboo Code tem uma memória automática, ligada por padrão, em que o próprio agente guarda o que aprendeu sobre você e o projeto. No seletor do /memory aparecem a linha Auto-memory: on para ligar ou desligar e a opção Open auto-memory folder para ver o que foi salvo. Para desligar por variável de ambiente:

export CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

Regra do time vai no AGENTS.md, que é revisável no git. A memória automática serve para o que o agente descobre trabalhando, não para substituir a instrução escrita.

Como isso se encaixa com os outros comandos?

• O /plan segue as regras do AGENTS.md ao montar o plano, então convenção escrita ali já sai no plano.
• O /compact resume a conversa, mas os arquivos de instrução continuam no disco.
• Instrução é pedido, não trava. Para impedir de verdade um comando, use o /permissions ou um hook.
• Para fixar o idioma das respostas, veja como travar um idioma fixo.