Estruturando Agentes Claude com .claude/ e CLAUDE.md

Estrutura do Diretório do Agente

A configuração envolve criar diretórios separados para cada agente em ~/Documents/. O exemplo mostra cinco agentes: planejador (função executiva, roteamento, responsabilidade), conteúdo (pipeline de conteúdo), youtube (produção do YouTube), vida (domínios pessoais) e centro de controle (painel, banco de dados, API).

Cada agente segue esta estrutura de modelo:

nome-do-agente/
├── CLAUDE.md # Identidade + missão + capacidades
├── .claude/
│   ├── rules/ # Contexto carregado automaticamente (sempre ativo)
│   └── skills/ # Fluxos de trabalho sob demanda
├── inbox/ # Entrada de outros agentes
├── outputs/ # Saída gerada
└── archive/ # Nada é excluído sem arquivamento

Distinção entre Regras e Habilidades

Os arquivos .claude/rules/ são carregados automaticamente no início de cada sessão. O Claude os lê como parte de sua janela de contexto. É aqui que você coloca coisas que o agente precisa saber sempre — seu escopo, contexto de negócios, como deve se comportar.

Os arquivos .claude/skills/ são sob demanda. Eles só carregam quando você os invoca com /nome-da-habilidade. É aqui que você coloca fluxos de trabalho específicos, como processos de várias etapas, modelos, rotinas estruturadas.

Os arquivos de regras são carregados na sua janela de contexto no início da sessão e permanecem lá. O Claude Code usa cache de prompt para que o conteúdo repetido não seja cobrado pelo preço total a cada turno, mas arquivos de regras grandes ainda aumentam a pressão do contexto e podem causar degradação na resposta. Com as habilidades, apenas o nome e a descrição ficam no contexto por padrão; o fluxo de trabalho completo é carregado sob demanda, seja quando você o chama ou quando o Claude decide que é relevante.

Regra Geral

Regras (sempre ativas): Limites de escopo, contexto de negócios, lógica de roteamento, convenções de nomenclatura — coisas que afetam cada decisão
Habilidades (sob demanda): Fluxos de trabalho passo a passo, modelos, operações em lote. Coisas que você faz ocasionalmente (Nota: as descrições das habilidades estão sempre no contexto para que o Claude saiba o que está disponível; apenas o conteúdo completo é sob demanda)

Conteúdo do CLAUDE.md

O arquivo CLAUDE.md deve ser mantido em até 120 linhas e cobre:

Identidade (2-3 linhas): quem é este agente e o que ele faz
Fase atual (2-3 linhas): no que estamos trabalhando agora
Capacidades principais (10-15 linhas): quais habilidades estão disponíveis, o que ele pode fazer
Localizações-chave (10-15 linhas): caminhos de arquivos que ele precisa referenciar
O que foi construído (10-20 linhas): histórico de trabalhos concluídos
Próximos passos (5-10 linhas): prioridades imediatas
Princípios (5-10 linhas): diretrizes comportamentais

Exemplo de Estrutura de Regras

Para um Agente de Planejamento, o diretório .claude/rules/ contém arquivos numerados que controlam a ordem de carregamento:

.claude/rules/
├── 01-business-context.md # Modelo de receita, posicionamento, clientes-alvo
├── 02-agent-ecosystem.md # Todos os agentes, suas missões, como se conectam
├── 03-roadmap.md # Fase atual, marcos, critérios de saída
├── 04-content-architecture.md # Canais de conteúdo, pilares, fluxo de trabalho
├── 05-daily-routine.md # Agenda, filtragem de ideias, regras anti-distração
├── 07-godin-strategy.md # Princípios de marketing, acompanhamento de marcos
├── 08-control-center.md # Referência de ferramentas CLI, esquema do banco de dados
├── 98-end-of-session.md # Ritual: atualizar roteiro, capturar conhecimento
└── 99-content-capture.md # Extração automática de sinais de conteúdo de cada sessão

Comunicação entre Agentes

Os agentes não se chamam diretamente. Eles se coordenam através de:

Banco de dados SQLite: Fonte da verdade para tarefas, estado do pipeline de conteúdo, sessões, métricas
Arquivos de caixa de entrada: Quando um agente precisa passar contexto para outro, ele coloca um arquivo markdown na inbox/ do destino
Endpoints de API: Leituras do painel

📖 Leia a fonte completa: r/ClaudeAI