Instruções para agentes
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
Um bloco curto no arquivo de instruções de um agente diz a ele quando carregar o contexto do Loom, salvar um fato e usar o índice de código em vez de usar grep ou ler arquivos. Esta página traz esse bloco uma única vez, junto com o arquivo de onde cada cliente o lê; cole-o, preencha seus dois namespaces a partir de code.repos (abaixo) e faça o commit junto com o repositório.
Os plugins do Claude Code e do Codex já fazem isso por meio de seus hooks e skills (Claude Code, Codex); o bloco serve para todos os outros clientes, e para o Claude Code ou o Codex conectados sem o plugin. Ele cita as ferramentas listadas pelo toolset coding, então conecte o cliente em ?toolset=coding: loom install --client <name> --toolset coding para os clientes que ele cobre, ou ?toolset=coding na URL (clientes MCP).
O bloco
Com os hooks do Cline, substitua, na sua cópia, o parágrafo do bloco que começa com “Every task:” por “Every task: make these two calls.”, para que as duas chamadas continuem obrigatórias. O Cline mostra o texto de um hook ao modelo somente depois da ferramenta para a qual ele foi executado, então o primer chega depois da primeira chamada de ferramenta da tarefa e o bloco de arquivo de uma edição chega depois da edição.
## Loom: memory and code index
Loom is connected as an MCP server; its tools are named `loom_*`. A tool you do not see
listed runs through `loom_op` with the op's dotted name: on a connection without the
coding toolset, `loom_code_symbol` is `code.symbol` and `loom_working_memory_set` is
`working_memory.set`. `loom_op` with `{"op": "help", "query": "<words>"}` finds them.
Every task: make these two calls unless a Loom hook already put Loom's context in this
session (the Claude Code and Codex plugins do). Without one they are not optional.
- At the start of each task, before planning: `loom_context_pack` with the task as
`query`. It returns the decisions, constraints and memories that bear on it.
- Before editing a file: `loom_op` with `op` set to `memory.for_file` and `arguments`
holding `path` (the file's repo-relative path) and `extra_namespaces`
(`["<team-namespace>"]`). Follow every constraint and decision it returns.
Memory
- To recall something mid-task, call `loom_search` with the topic, file or error. Treat
`abstain` as "nothing relevant". A hit whose `code_state` is `changed`, `unresolved`
or `missing` is about code that changed or went away since it was written: check the
code before relying on it.
- When the user states a decision, preference, constraint or correction, save it with
`loom_memory_set` right away: one plain-text fact per call under a readable key
(`<scope>/<kind>/<id>`), dates as calendar dates. Never save a guess, your reasoning or
the conversation.
- A rule the user states for the whole team about a file: `loom_memory_set` with
`namespace` `<team-namespace>`, the file in `files` and the tag `constraint`.
- A fact that changed: `loom_memory_update` on the same key, in the namespace the row
lives in, never a second copy. A team rule or decision someone else wrote is not yours
to update: follow the refusal's `hint`.
- Your plan and checklist for this task: `loom_working_memory_set`, not `loom_memory_set`.
- Before reporting done, one pass over what should outlive the session.
Code
- This repository's code namespace is `<code-namespace>`; pass it as `namespace` on
every `loom_code_*` call.
- Where X is defined: `loom_code_symbol`. Who calls X: `loom_code_callers`. A concept
with no exact keyword: `loom_code_search`. An exact string: `loom_code_grep`. What is
in a file: `loom_code_outline`, then read one span. What a change breaks:
`loom_code_impact`.
- Grep your own uncommitted files and repositories the index does not cover. When a code
tool answers `abstain: true`, grep instead of retrying with synonyms.
- A code answer's `lessons` are memories about its top files: follow them, and check the
code of one whose `code_state` is `changed`, `unresolved` or `missing` before relying on
it.
code.repos lista os repositórios que o token pode ler ou pedir para participar, uma linha por
branch indexada:
curl -s -X POST https://loom.example.com/v1/code.repos \
-H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"repo": "<owner>/<name>", "fields": ["branch", "primary_namespace", "readable"]}'
Substitua <code-namespace> pelo namespace da linha da branch em que esta cópia do
arquivo está commitada e <team-namespace> pelo primary_namespace dela (o da branch principal, onde ficam as regras e decisões de arquivo da equipe); para a branch principal, os dois são
iguais. Um repositório sem linha (não indexado, ou em que code.repos responde que a inteligência de código está desativada), ou cuja linha diz readable: false (um repositório que este token
não pode ler, listado para que você possa pedir acesso ou adotá-lo), usa o bloco sem extra_namespaces, sem a linha de regra da equipe e sem a seção Code.
Onde cada cliente lê o bloco
O bloco é o mesmo em todos os lugares (exceto pela mudança de um parágrafo nos hooks do Cline
acima); só o arquivo e o cabeçalho mudam. A maioria desses clientes também lê
AGENTS.md, então mantenha uma única cópia quando um arquivo atender a vários deles; um cliente que lê
dois arquivos com o bloco o vê duas vezes, o que consome contexto, mas não muda nada.
| Cliente | Arquivo | Cabeçalho antes do bloco |
|---|---|---|
Codex sem o plugin, e qualquer agente que leia AGENTS.md |
AGENTS.md na raiz do repositório |
nenhum |
| Zed | o primeiro arquivo de instruções que ele encontrar (abaixo) | nenhum |
| Claude Code sem o plugin | CLAUDE.md na raiz do repositório (abaixo) |
nenhum |
| Cursor | .cursor/rules/loom.mdc |
---, description: Loom memory and code index, alwaysApply: true, --- |
| Devin Desktop (ou Windsurf) | .devin/rules/loom.md (.windsurf/rules/loom.md em um build do Windsurf) |
---, trigger: always_on, --- |
| Cline | .clinerules/loom.md |
nenhum |
| VS Code (GitHub Copilot) | .github/copilot-instructions.md |
nenhum |
O Zed lê apenas o primeiro arquivo de instruções que encontra (.rules, .cursorrules e outros
antes de AGENTS.md), então o bloco vai nesse arquivo, ou em AGENTS.md quando o repositório
não tem nenhum.
O Claude Code não lê AGENTS.md: se houver um no repositório, coloque o bloco em
AGENTS.md e faça o CLAUDE.md importá-lo com a linha @AGENTS.md.
Cada linha do cabeçalho vai em sua própria linha. O arquivo do Cursor, por exemplo, começa assim:
---
description: Loom memory and code index
alwaysApply: true
---
## Loom: memory and code index
Um AGENTS.md, CLAUDE.md ou arquivo do Copilot já existente mantém seu conteúdo: adicione o bloco como
uma seção dele.
Por que estas regras
Nada em uma sessão sem hooks provoca uma recuperação de memória, e uma ferramenta de memória listada é uma escolha entre muitas, então o bloco faz o carregamento de contexto parte de cada tarefa, como fazem os hooks dos plugins.
Cada linha é a forma curta do que os plugins ensinam, ou do que as respostas do Loom trazem:
- carregar contexto no início de uma tarefa e antes de uma edição: os hooks de início de sessão e de contexto de arquivo dos plugins, que chamam
context.packememory.for_file; - recuperar e salvar fatos declarados à medida que surgem: a skill
loom-memory; - o índice de código antes do grep, e o grep onde o índice não consegue responder: a skill
loom-code, que o desvio de código (code shunt) dos plugins impõe; - ler as memórias que uma resposta de código traz: seus
lessons(memórias vinculadas ao código), que uma sessão com plugin recebe nas mesmas respostas.
A última linha de memória do bloco representa a revisão ao fim da tarefa; para detalhá-la, copie suas perguntas do guia de integração de agentes para baixo do bloco. As skills trazem o detalhe que o bloco deixa de fora: os campos do recibo, documentos versus memórias, as regras de parada. As skills loom e loom-code podem ser instaladas junto ao bloco para esse detalhe (agentes de código); loom cobre o ciclo de memória, os formatos de escrita, os recibos e a revisão ao fim da tarefa. Elas não têm hooks, então não substituem as duas chamadas do bloco.
Relacionados
- Clientes MCP: como conectar cada cliente.
- Como escolher um conjunto de ferramentas.
- Integrações.