CLAUDE.md, AGENTS.md e Steering Files: O Novo README do Projeto Agêntico

Todo projeto de software que se preza tem um README.md. É onde você explica o que o projeto faz, como configurar o ambiente, como rodar os testes, as convenções de código. É o contrato entre os humanos que vão trabalhar no projeto.

Agora que agentes de IA são colaboradores de fato em muitos projetos — lendo código, escrevendo testes, abrindo PRs, refatorando módulos — surgiu uma nova camada: o contrato entre o projeto e os agentes.

É para isso que servem o CLAUDE.md, o AGENTS.md, os .kiro/steering/ files, e outros formatos similares que estão emergindo no ecossistema. Eles não são documentação para humanos — são instruções de sistema para agentes que vão trabalhar no repositório.

A diferença prática é enorme. Um agente que lê um arquivo de steering bem escrito antes de começar a trabalhar produz resultados substancialmente melhores do que um agente operando só com o contexto da pergunta atual.

Por Que Isso Existe

Quando você usa Claude Code, Cursor, Kiro ou qualquer outro agente de coding, o modelo recebe três tipos de contexto:

1. O que você pediu agora: "adiciona validação no endpoint de criação de usuário"
2. O código que o agente consegue ver: os arquivos relevantes no repositório
3. O contexto de projeto que você forneceu: as convenções, restrições, arquitetura, preferências

O terceiro ponto é o que os steering files resolvem. Sem eles, o agente opera com 1 e 2 — e frequentemente faz escolhas que fazem sentido genericamente mas não no contexto do seu projeto específico. Com eles, o agente tem o contexto que um dev novo levaria semanas para absorver.

Exemplos reais do que acontece sem steering files:

• O agente adiciona validação usando class-validator mas o projeto usa zod
• O agente escreve testes com jest mas o projeto migrou para vitest
• O agente usa snake_case para variáveis mas a convenção do projeto é camelCase
• O agente cria um novo serviço sem saber que existe um módulo de infraestrutura compartilhado que deveria ser reutilizado
• O agente escreve comentários em inglês mas toda a base de código tem comentários em português

Cada um desses erros é um PR que vai ser rejeitado no review e precisa ser refeito. Steering files evitam isso antes de acontecer.

Os Quatro Formatos Principais

CLAUDE.md — Para Claude Code e Cowork

O formato nativo do Claude Code. É carregado automaticamente quando o Claude Code é iniciado em um diretório que contém esse arquivo. Pode existir na raiz do projeto e em subdiretórios (o Claude lê ambos, com o subdiretório tendo precedência).

Localização: raiz do projeto ou subdiretórios relevantes Lido por: Claude Code, Claude Cowork Formato: Markdown livre

# Contexto do Projeto

Este é o blog pessoal do Elton José (eltonjose.com.br), construído com
Next.js 14, TypeScript, Tailwind CSS e Contentlayer para gestão de posts MDX.

## Stack Técnica

- **Framework**: Next.js 14 com App Router
- **Linguagem**: TypeScript strict mode
- **Estilização**: Tailwind CSS (sem CSS modules, sem styled-components)
- **Conteúdo**: MDX via Contentlayer — posts ficam em `content/{slug}/index.mdx`
- **Deploy**: Vercel (produção) e preview por branch
- **Banco**: Supabase para newsletter e analytics

## Comandos Essenciais

\`\`\`bash
yarn dev          # desenvolvimento local (porta 3000)
yarn build        # build de produção
yarn lint         # ESLint
yarn type-check   # TypeScript sem emitir arquivos
\`\`\`

## Convenções de Código

- **Componentes**: PascalCase, um componente por arquivo
- **Funções utilitárias**: camelCase, exportadas individualmente
- **Tipos**: sempre tipagem explícita, sem `any`
- **Imports**: absolutos com alias `@/` para `src/`
- **Comentários**: em português brasileiro

## Estrutura de Posts

Cada post fica em `content/{YYYYMMDD_slug}/index.mdx` com frontmatter:
- `title`, `description`, `image`, `publishedAt`, `updatedAt`
- `author`: sempre "eltonjose"
- `isPublished`: true para publicado
- `tags`: array de strings, PascalCase

## Restrições Importantes

- NÃO alterar arquivos em `_opensquad/` sem permissão explícita
- NÃO modificar `contentlayer.config.js` sem entender o impacto no build
- NÃO fazer push direto para `main` — sempre via PR
- NÃO instalar dependências sem verificar se já existe algo equivalente no projeto

AGENTS.md — Padrão Emergente Multi-Agente

O AGENTS.md é um padrão mais recente que surgiu da comunidade open source. Enquanto o CLAUDE.md é específico do Claude Code, o AGENTS.md é projetado para ser agnóstico de ferramenta — funciona com Claude Code, Cursor, Aider, e qualquer agente que implemente o padrão.

O GitHub Spec Kit popularizou o formato, e ele foi adotado por vários projetos de alta visibilidade.

Diferença principal do CLAUDE.md: o AGENTS.md tem uma estrutura mais opinionada com seções definidas para diferentes tipos de agente (coding, testing, documentation, etc.) e suporte a permissões granulares.

# AGENTS.md

## Project Overview

Blog pessoal eltonjose.com.br — Next.js 14, TypeScript, MDX.

## Agent Permissions

### Coding Agent
- ✅ Pode criar e editar arquivos em `src/`, `content/`, `public/`
- ✅ Pode rodar `yarn lint`, `yarn type-check`, `yarn build`
- ❌ NÃO pode modificar `package.json` sem aprovação humana
- ❌ NÃO pode fazer commits ou push diretamente

### Testing Agent
- ✅ Pode criar/editar arquivos `*.test.ts` e `*.spec.ts`
- ✅ Pode rodar `yarn test` e `yarn test:coverage`
- ❌ NÃO pode modificar código de produção

### Documentation Agent
- ✅ Pode criar e editar arquivos `.md` e `.mdx`
- ❌ NÃO pode modificar código TypeScript

## Technical Conventions
[mesmas convenções do CLAUDE.md]

## Testing Requirements
- Todo novo componente precisa de teste unitário
- Coverage mínimo de 80% para módulos em `src/lib/`
- Use Vitest + Testing Library (não Jest)

.kiro/steering/ — Para AWS Kiro

O Kiro usa um diretório dedicado para steering files, com múltiplos arquivos .md organizados por tema:

.kiro/
  steering/
    product.md       # visão do produto e objetivos
    tech-stack.md    # tecnologias e ferramentas
    structure.md     # arquitetura e organização de código
    conventions.md   # padrões de código e nomenclatura

A vantagem de múltiplos arquivos é granularidade: o Kiro pode escolher quais steering files incluir no contexto dependendo do tipo de tarefa, evitando poluir o contexto com informação irrelevante.

# .kiro/steering/tech-stack.md

## Core Technologies

- Next.js 14 (App Router)
- TypeScript 5.x — strict mode obrigatório
- Tailwind CSS — utility-first, sem CSS custom exceto em globals.css
- Contentlayer — processamento de MDX

## Package Manager

Yarn (não npm, não pnpm). Sempre `yarn add`, nunca `npm install`.

## Testing

Vitest + React Testing Library. Arquivos de teste colocalizados com o código:
`src/components/Button/Button.test.tsx`

## Important: Do Not Use

- `styled-components` ou `emotion` — use Tailwind
- `jest` — o projeto usa Vitest
- CSS Modules — toda estilização via Tailwind

.cursorrules — Para Cursor

O formato mais antigo, específico do Cursor. Menos estruturado que os outros, mas amplamente usado por times que trabalham com Cursor como IDE principal.

You are an expert in Next.js 14, TypeScript, and Tailwind CSS.

This project is a personal blog (eltonjose.com.br). Posts are MDX files
in content/{YYYYMMDD_slug}/index.mdx. Do not modify contentlayer.config.js.

Always use TypeScript strict mode. Never use `any`. Use Tailwind for styling.
Package manager is Yarn. Testing with Vitest.

When creating components, follow the existing pattern in src/components/.

O Que Colocar em Cada Arquivo

Independentemente do formato, o conteúdo útil de um steering file cobre algumas categorias essenciais.

1. Contexto do Projeto (obrigatório)

O que o projeto faz, para quem, qual o objetivo. Parece óbvio, mas faz diferença: um agente que sabe que está trabalhando em "um blog técnico para devs seniors" vai fazer escolhas diferentes de um agente que acha que está em um "e-commerce genérico".

2. Stack e Ferramentas (obrigatório)

Especifique versões quando relevante. "Usa React" é menos útil do que "Usa React 18 com App Router do Next.js 14 — não usa pages/". A especificidade evita que o agente use padrões de versões antigas.

3. Comandos Essenciais (obrigatório)

Como buildar, testar, rodar localmente. O agente vai precisar executar esses comandos para verificar se o que fez funciona.

4. Convenções de Código (obrigatório)

Naming conventions, organização de arquivos, padrões de import, estilo de comentários. Quanto mais explícito, melhor.

5. Restrições e Permissões (importante)

O que o agente não pode fazer sem aprovação explícita. Arquivos protegidos, operações destrutivas, dependências que não podem ser adicionadas.

6. Arquitetura e Organização (útil para projetos complexos)

Como o código está organizado, onde ficam os módulos principais, quais são as camadas da aplicação. Evita que o agente coloque código no lugar errado.

7. Contexto de Negócio (situacional)

Para projetos onde as decisões técnicas são fortemente influenciadas por regras de negócio, incluir esse contexto ajuda o agente a fazer escolhas mais alinhadas.

Template Prático

Um ponto de partida para qualquer projeto:

# [Nome do Projeto] — Contexto para Agentes

## O Que É Este Projeto

[2-3 frases descrevendo o projeto, para quem é, e qual problema resolve]

## Stack Principal

- **Runtime/Framework**: [ex: Node.js 20 + Express 5]
- **Linguagem**: [ex: TypeScript 5.4 — strict mode]
- **Banco de dados**: [ex: PostgreSQL 16 via Drizzle ORM]
- **Testes**: [ex: Vitest + Supertest para integração]
- **Package manager**: [ex: pnpm 9]

## Comandos

\`\`\`bash
[comando de dev]     # como rodar localmente
[comando de build]   # como buildar
[comando de test]    # como rodar testes
[comando de lint]    # como verificar lint
\`\`\`

## Estrutura de Pastas

\`\`\`
src/
  [pasta]/   # [o que contém]
  [pasta]/   # [o que contém]
\`\`\`

## Convenções

- **Nomenclatura**: [ex: camelCase para variáveis, PascalCase para classes]
- **Imports**: [ex: absolutos via `@/`, sem relative imports além de 1 nível]
- **Comentários**: [ex: em inglês, JSDoc para funções públicas]
- **Commits**: [ex: Conventional Commits — feat/fix/chore/docs]

## ⛔ Restrições

- [lista do que o agente NÃO pode fazer sem aprovação explícita]
- [arquivos protegidos]
- [operações que precisam de review humano]

## Informações Adicionais

[qualquer contexto específico que um dev novo precisaria saber]

Como Manter os Steering Files Atualizados

Um steering file desatualizado é quase tão ruim quanto não ter um. Se o seu CLAUDE.md diz "usamos Jest para testes" e o projeto migrou para Vitest há três sprints, o agente vai continuar gerando código de teste com Jest — e você vai descobrir no review.

Algumas práticas que ajudam:

Trate steering files como documentação de código: inclua na definition of done das tasks a pergunta "essa mudança impacta o steering file?". Novo framework adotado? Atualiza o CLAUDE.md. Convenção de código mudou? Atualiza. Novo módulo importante adicionado? Documenta a arquitetura.

Faça revisão periódica: um sprint de dois meses sem revisar o steering file geralmente significa que ele está desatualizado. Uma review rápida de 15 minutos no fim do sprint identifica o que ficou para trás.

Use o próprio agente para manter: uma instrução de Dispatch recorrente funciona bem aqui:

"Revisa o CLAUDE.md na raiz do projeto. Compare com o package.json,
a estrutura real de pastas, e os arquivos de configuração.
Identifica qualquer desalinhamento e me apresenta as atualizações
sugeridas para eu revisar."

Versione junto com o código: o steering file deve viver no repositório e ser versionado com git como qualquer outro arquivo. Isso permite rastrear quando e por que mudou, e reverter se necessário.

Steering Files em Times Grandes: Hierarquia e Escopo

Para projetos com múltiplos módulos ou times, a estrutura de um único CLAUDE.md na raiz pode não ser suficiente. O Claude Code suporta steering files em subdiretórios — e essa hierarquia é poderosa.

# Estrutura hierárquica de steering files

meu-monorepo/
  CLAUDE.md              # contexto geral do projeto (todos os agentes lêem)
  packages/
    auth-service/
      CLAUDE.md          # contexto específico do serviço de auth
    payment-service/
      CLAUDE.md          # contexto do serviço de pagamentos
    frontend/
      CLAUDE.md          # contexto do frontend (React, componentes, etc.)

Quando o Claude Code é iniciado em packages/auth-service/, ele lê ambos: o CLAUDE.md raiz (contexto geral) e o CLAUDE.md do subdiretório (contexto específico). O subdiretório tem precedência em caso de conflito.

Isso permite separar contexto que é universal (conventions de código, processo de PR, ferramentas de CI) do contexto que é específico por serviço (qual banco de dados usa, quais endpoints existem, quais são as regras de negócio daquele domínio).

Para times grandes, o steering file do subdiretório pode ser responsabilidade do time que cuida daquele serviço — eles conhecem melhor as nuances e são os mais motivados a mantê-lo atualizado.

A Conexão com SDD

Se você acompanha a série sobre SDD (Spec-Driven Development) aqui no blog, vai notar que os steering files são um tipo de spec — especificamente, specs de contexto e comportamento do agente em vez de specs de funcionalidade.

No SDD, a ideia é que especificações são o ponto de partida para qualquer trabalho — você define o que antes de definir o como. Os steering files são exatamente isso aplicado ao contexto de agentes: você define o que o agente precisa saber sobre o projeto antes de ele começar a trabalhar.

O CLAUDE.md na raiz do projeto é a memória procedural do agente para esse contexto específico. É o mesmo conceito que discutimos no post sobre arquitetura de memória para agentes — mas na camada mais simples e operacional.

Qual Formato Usar?

Minha recomendação prática:

Se você usa Claude Code/Cowork como ferramenta principal: comece com CLAUDE.md. É o mais fácil de começar, é nativo da ferramenta, e funciona imediatamente.

Se o time usa múltiplas ferramentas: adicione AGENTS.md para cobrir Cursor, Aider e outros. O esforço marginal é baixo se você já tem um CLAUDE.md.

Se você adotou o Kiro: use .kiro/steering/ como padrão principal. A estrutura em múltiplos arquivos por tema é mais escalável para projetos grandes.

Não escolha apenas um se o time é misto — manter ambos (CLAUDE.md + AGENTS.md) é pouco trabalho e garante que qualquer ferramenta que o time use vai ter o contexto certo.

Recursos

• Claude Code — CLAUDE.md documentation
• GitHub Spec Kit — AGENTS.md standard
• AWS Kiro — Steering files
• Posts relacionados: AWS Kiro + SDD · Ferramentas SDD agêntico · SDD: organização agêntica