Imagine contratar um desenvolvedor sênior que, a cada manhã, chega ao trabalho sem lembrar nada do projeto. Você precisaria re-explicar tudo — a tarefa, os seus padrões, a arquitetura. Esse é exatamente o comportamento padrão de qualquer IA: ela esquece tudo entre conversas.
Aqui, vou mostrar como o IBM Bob resolve esse problema de esquecimento com o AGENTS.md e o comando /init — e como o conceito se compara ao CLAUDE.md do Claude para quem já conhece essa ferramenta.
1) Por que IAs “Esquecem” Tudo?
Modelos de linguagem (LLMs) são stateless por design. Cada nova conversa começa com uma janela de contexto zerada. Não importa o quanto você trabalhou com a IA no dia anterior — ela não tem memória disso. Na prática, isso significa que toda vez que você abre uma nova conversa com o IBM Bob, você está começando do zero.
2) O AGENTS.md: O Ponto de Partida no IBM Bob
O AGENTS.md é um arquivo Markdown que fica na raiz do projeto. O Bob o carrega automaticamente no início de cada conversa, em todos os modos. É o único arquivo que você precisa ter para dar contexto à IA.
O que colocar nele?
- Visão geral — o que o projeto faz em 2–3 frases
- Stack tecnológico — linguagens, frameworks, bancos de dados
- Estrutura de diretórios — onde ficam as principais pastas e o que cada uma contém
- Convenções de código — nomenclatura, padrões arquiteturais, estilo
- Fluxos de trabalho — como rodar localmente, testar, fazer deploy
- Regras de negócio importantes — o que não está óbvio no código
Exemplo:
# Galaxium Travels — Contexto do Projeto
## Visão Geral
Plataforma de reservas de viagens espaciais. Backend em Node.js/TypeScript
com Express, frontend em React 18, banco PostgreSQL.
## Stack
- **Backend**: Node.js 20, TypeScript 5, Express 4, Prisma ORM
- **Frontend**: React 18, Vite, TailwindCSS
- **Banco**: PostgreSQL 16 (dev: Docker Compose)
- **Testes**: Vitest (unit), Playwright (e2e)
## Estrutura de Diretórios
src/
|-- api/ ? Rotas Express (um arquivo por recurso)
|-- services/ ? Lógica de negócio (sem acesso direto ao banco)
|-- repositories/ ? Acesso ao banco via Prisma
|-- models/ ? Tipos e interfaces TypeScript
|-- utils/ ? Helpers genéricos
## Convenções
- Nomes de arquivos: kebab-case (ex: booking-service.ts)
- Funções exportadas: camelCase; Classes: PascalCase
- Nunca usar `any` no TypeScript
- Commits: feat:, fix:, docs:, refactor: (Conventional Commits)
## Como Rodar
```bash
docker compose up -d # sobe PostgreSQL
npm run dev # inicia servidor em localhost:3000
npm test # roda testes unitários
```3) O Comando /init
A grande vantagem do IBM Bob é que você não precisa escrever o AGENTS.md do zero. O comando :
/init escaneia automaticamente o projeto e gera um arquivo estruturado com as informações que o Bob consegue inferir.
O Bob irá:
- Ler os arquivos relevantes do projeto (package.json, estrutura de pastas, etc.)
- Gerar o AGENTS.md principal na raiz do projeto
- Criar a pasta .bob/ com arquivos de contexto específicos por modo
project-root/
|-- AGENTS.md <- Contexto principal (todos os modos)
|-- .bob/
|-- rules-code/
| |-- AGENTS-code.md <- Contexto em estrutura e padrões de código
|-- rules-plan/
| |-- AGENTS-plan.md <- Contexto focado em arquitetura
|-- rules-ask/
|-- AGENTS-ask.md <- Contexto focado em explicaçõesApós rodar o /init, edite o AGENTS.md manualmente para adicionar contexto e deixar mais personalizado.
4) Hierarquia do AGENTS.md
O Bob suporta três níveis de contexto, carregados nesta ordem:
| Nível | Localização | Quando usar |
|---|---|---|
| Global | ~/.bob/AGENTS.md | Preferências pessoais que valem para todos os projetos (estilo de escrita, idioma preferido, etc.) |
| Projeto | AGENTS.md na raiz | Contexto do projeto — stack, convenções, arquitetura |
| Subdiretório | AGENTS.md em subpastas | Contexto específico de um módulo ou serviço (ex: devops/AGENTS.md) |
Ordem de precedência: O contexto mais específico (subdiretório) complementa — mas não sobrescreve — o contexto mais geral (global). O Bob carrega todos os níveis relevantes para a conversa atual.
5) Comparação com o CLAUDE.md
Se você já usa o Claude Code da Anthropic, o conceito de arquivo de contexto é idêntico — só muda o nome. O equivalente do AGENTS.md no Claude é o CLAUDE.md.
Migrando do Claude para o Bob: Se você já tem um CLAUDE.md no projeto, renomeie para AGENTS.md. O conteúdo é compatível — ambos são Markdown puro descrevendo o projeto. Não é necessária nenhuma conversão de formato.
| Aspecto | IBM Bob | Claude Code |
|---|---|---|
| Nome do arquivo | AGENTS.md | CLAUDE.md |
| Localização | Raiz do projeto | Raiz do projeto |
| Formato | Markdown livre | Markdown livre |
| Geração automática | Sim — comando /init | Manual |
| Contexto por modo de trabalho | Sim — AGENTS-code.md, AGENTS-plan.md… | Arquivo único global |
| Hierarquia em subpastas | Sim | Sim |
| Escopo global (todos os projetos) | ~/.bob/AGENTS.md | ~/.claude/CLAUDE.md |
Vantagem do Bob
O /init gera o contexto automaticamente e cria arquivos separados por modo de trabalho — o modo Code recebe contexto focado em código, o modo Plan em arquitetura.
Equivalente no Claude
O CLAUDE.md é criado manualmente. Sem separação por modo nativo — tudo vai para um único arquivo, que você organiza como preferir.
6) Boas Práticas de Manutenção
- Versione no Git — o AGENTS.md é um ativo do projeto tão importante quanto o código
- Prefira listas e headers — estrutura facilita a leitura tanto pela IA quanto pela equipe
- Documente o “porquê”, não só o “o quê” — decisões arquiteturais com justificativa são mais valiosas que apenas listar tecnologias
Comece devagar: Não espere ter um AGENTS.md perfeito. Um arquivo com 10 linhas já é infinitamente melhor do que nenhum contexto.
