Boas Práticas de CLAUDE.md: 9 Regras Que Impedem o Claude de Te Ignorar (2026)

Boas práticas de CLAUDE.md: 9 regras que impedem o Claude de te ignorar (2026)

A maioria dos artigos sobre boas práticas de CLAUDE.md dá-te um template e fica por aí, mas o ficheiro que escreveste na semana passada provavelmente já está a ser ignorado, e não sabes porquê. A solução raramente é "acrescentar mais regras". Geralmente é o oposto. Implementámos o Claude Code em todos os projetos recentes de clientes, e estas 9 regras são o que realmente faz a diferença: uma hierarquia que corresponde à forma como o Claude carrega os ficheiros, um orçamento de instruções que não podes ultrapassar, a decisão sobre o AGENTS.md e as seis razões pelas quais o Claude descarta silenciosamente o teu ficheiro a meio da sessão.

Principais Conclusões

• O CLAUDE.md é a memória do projeto carregada no contexto do Claude Code; mantenha-o abaixo de 200 linhas, senão as regras começam a ser descartadas.
• Os ficheiros são carregados de cima para baixo: global, raiz do projeto, subdiretório (preguiçoso) e CLAUDE.local.md (pessoal, ignorado pelo git).
• Use o AGENTS.md se também usar o Cursor ou o Copilot; crie um symlink do CLAUDE.md para o AGENTS.md para servir ambos.
• Se o Claude ignorar o seu ficheiro, em 90% dos casos o problema é o comprimento, a vagueza ou a falta de um "porquê".

O Que o CLAUDE.md Realmente Faz (E Porque É Que Isso Importa)

Em resumo: O CLAUDE.md é um ficheiro markdown que o Claude Code lê como memória de projeto no início de cada sessão. Não é um prompt de sistema, um hook, nem uma skill — é contexto consultivo que orienta o Claude em direção às convenções da sua equipa. Pense nele menos como documentação e mais como um ficheiro de configuração que o seu pair programmer de IA realmente lê.

Muitas equipas escrevem o CLAUDE.md como se fosse um README. Esse é o primeiro erro. Um README explica o projeto a humanos que podem folhear e saltar partes. O CLAUDE.md é consumido na íntegra pelo Claude Code no início da sessão, com cada linha a custar tokens e adesão. Está muito mais próximo de um ficheiro de configuração ou de um conjunto de fixtures de teste do que de documentação.

Também não é a única forma de orientar o Claude. Os Hooks executam ações determinísticas (formatação, bloqueio de commits). As Skills agregam fluxos de trabalho reutilizáveis. O CLAUDE.md situa-se entre os dois como contexto consultivo — o Claude avalia-o, por vezes sobrepõe-se-lhe, e esquece-se certamente de partes dele se escrever demasiado. Essa distinção é a base de tudo o que se segue, e é por isso que o CLAUDE.md é uma ferramenta na prática mais ampla de engenharia de contexto, e não uma bala de prata.

Regra n.º 1: Trate-o como código, não como documentação. Versione-o. Reveja-o em PRs. Apare-o como refatoraria um módulo sobrecarregado. De acordo com o guia de CLAUDE.md da Anthropic, o ficheiro é carregado com a mesma prioridade que qualquer instrução de sistema, o que significa que uma regra desatualizada de há seis meses continua a moldar ativamente cada resposta hoje.

Como o CLAUDE.md é carregado: a hierarquia de 4 níveis

Em resumo: o Claude Code carrega o CLAUDE.md a partir de quatro níveis: global (~/.claude/CLAUDE.md), raiz do projeto, CLAUDE.local.md para substituições pessoais, e ficheiros de subdiretório que carregam de forma preguiçosa apenas quando o Claude lê ficheiros dentro desse diretório. Subdiretórios irmãos nunca veem o CLAUDE.md uns dos outros, o que mantém a memória do claude code rigorosamente delimitada.

A hierarquia é a parte mais mal compreendida do CLAUDE.md, e é aquela em que 0 dos 5 principais resultados da SERP se aprofundam. Eis o que realmente acontece nos bastidores:

Dois termos que vale a pena fixar: carregamento preguiçoso e isolamento entre irmãos.

O carregamento preguiçoso significa que o CLAUDE.md de um subdiretório não entra no contexto do Claude até que o Claude abra realmente um ficheiro dentro desse diretório. Se pedires "corrige o bug do login" e o Claude apenas tocar em backend/, o teu frontend/CLAUDE.md nunca é carregado. Isto é bom, mantém a janela de contexto limpa, mas prejudica equipas que colocam regras críticas em subdiretórios à espera que se apliquem sempre.

O isolamento entre irmãos é o corolário: frontend/CLAUDE.md e backend/CLAUDE.md nunca se carregam um ao outro. Partilham apenas o que está na raiz do projeto. Por isso, se as tuas regras de frontend contradizem as tuas regras de backend, não há problema. Se precisarem de partilhar uma convenção, eleva-a para o ficheiro raiz.

O CLAUDE.local.md é a válvula de escape. É carregado mas não é commitado, perfeito para substituições do estilo "prefiro pnpm mas a equipa padronizou em npm". O senão: não é automaticamente ignorado pelo Git. Tens de o adicionar tu mesmo. Esquece-te disso e vais commitar as tuas regras pessoais no repositório da equipa. Regra n.º 4: Coloque as instruções onde o Claude realmente as lê. As regras de estilo para componentes React pertencem ao frontend/CLAUDE.md, não à raiz. As regras de migrações de base de dados pertencem ao backend/. A documentação de Memória da Anthropic (atualizada em novembro de 2025) confirma isto — o comportamento de carregamento preguiçoso é intencional e essencial para o funcionamento.

O Que Colocar Dentro do CLAUDE.md (E O Que Deixar de Fora)

Em resumo: Dentro do CLAUDE.md vai tudo aquilo que o Claude não consegue inferir do seu código: comandos de build, convenções de nomenclatura, anti-padrões com os quais a sua equipa já se queimou, e o porquê por trás de cada regra. De fora fica tudo o que estiver no README, tudo o que estiver no package.json, e qualquer regra que mude semanalmente. As instruções de claude code devem ser testáveis e específicas.

Aqui está um CLAUDE.md minimalista que realmente tem utilidade:

# Projeto: techsy-app
## Comandos
- Compilação: `pnpm build` (Turbopack — as flags do Webpack não se aplicam)
- Testes: `pnpm test --run` (usamos o Vitest, não o Jest)
- Lint: `pnpm lint` (falha o CI em avisos, não apenas em erros)
## Convenções
- Componentes de servidor por omissão. Adicionar `'use client'` apenas quando for verdadeiramente necessário.
  Porquê: no último trimestre atingimos 8s de LCP devido a excesso de código de cliente.
- Acesso à base de dados apenas através dos helpers de `lib/db/` — nunca SQL direto nas rotas.
  Porquê: as políticas de segurança ao nível da linha estão nesses helpers.
- Os testes são colocados como `*.test.ts` junto do ficheiro em teste.
## O que não fazer
- Não adicione uma nova dependência sem antes abrir um comentário no PR.
- Não use `any` — use `unknown` e restrinja o tipo.
## Onde procurar
- Esquema: `db/schema.ts`
- Fluxo de autenticação: `lib/auth/README.md`

Now compare that to the anti-pattern version most teams ship:

# Project Rules

- Write clean, maintainable code.
- Follow best practices.
- Use TypeScript properly.
- Make sure tests pass.
- Be consistent with existing patterns.
- Document complex logic.

O segundo ficheiro não está errado. É apenas inútil. O Claude já quer escrever código limpo. "Seja consistente" não diz ao Claude com que padrão deve ser consistente. Os exemplos públicos de Boris Cherny, engenheiro da Anthropic, pendem fortemente para o primeiro estilo, comandos concretos, ferramentas nomeadas e o porquê por trás de decisões que não são óbvias apenas a partir da base de código.

Regra n.º 2: Seja específico, não aspiracional. "Escreva código limpo" é aspiracional. "Componentes de servidor por predefinição; adicione 'use client' apenas quando for realmente necessário" é testável. A mesma disciplina sustenta uma boa engenharia de prompts: instruções específicas e testáveis superam aspirações vagas, quer estejam num prompt ou num CLAUDE.md.

Regra n.º 3: Explique por que razão cada regra é importante. O "porquê" não é conversa fiada, é a forma como o Claude decide casos limite. Uma regra com uma razão ("atingimos 8s de LCP devido a excesso de client") generaliza-se para situações semelhantes. Uma regra sem razão é ignorada no momento em que o contexto muda. O padrão também está documentado no guia de CLAUDE.md da Builder.io.

Porque é que o Claude está a ignorar o seu CLAUDE.md? O orçamento de instruções

Em resumo: O Claude não é malicioso — está a ficar sem atenção. A partir de aproximadamente 80 linhas, começará a notar que algumas regras são ignoradas; acima das 200 linhas, blocos inteiros são completamente desconsiderados; com mais de 500 palavras de regras densas, o cumprimento entra em colapso. A solução é um orçamento de instruções. Trate cada linha como um custo sobre a memória do claude code e sobre o cumprimento de cada regra.

Investigação recente confirma aquilo que os utilizadores em produção continuam a constatar: o cumprimento de instruções degrada-se de forma não linear à medida que o número de regras aumenta. O artigo 2507.11538 no arxiv sobre a capacidade de seguir instruções demonstra que o cumprimento por regra diminui à medida que se acumulam mais regras, e a análise da HumanLayer sobre o CLAUDE.md em produção ecoa a mesma conclusão.

Traduzindo: cada regra que acrescenta torna todas as outras ligeiramente menos propensas a serem cumpridas. Por isso, um CLAUDE.md de 400 linhas não é 4x mais eficaz do que um de 100 linhas. Muitas vezes é menos eficaz, porque as regras com que realmente se importa ficam diluídas por aquelas que escreveu numa sexta-feira há três meses e nunca apagou.

Nos nossos ficheiros CLAUDE.md, tudo o que passa da linha 150 começa a perder cumprimento de forma visível. Perto da linha 250, já vimos o Claude saltar secções inteiras. Por isso, impomos um limite.

wc -l CLAUDE.md

É esta a ferramenta completa. Execute-a. Se ultrapassar as 200 linhas, ultrapassou o orçamento. A regra rígida que entregamos aos clientes:

Trate o CLAUDE.md como um orçamento de 200 linhas. Cada linha custa cumprimento. Gaste-o onde importa.

Regra n.º 1 reforçada: Mantenha-o curto. Menos de 200 linhas. Menos de 500 palavras de regras densas. Se se vir tentado a acrescentar regras de automatização ("executa sempre o prettier depois das edições"), essas provavelmente pertencem aos hooks do Claude Code — os hooks são determinísticos e não consomem tokens do orçamento de instruções.

Devo usar CLAUDE.md, AGENTS.md, .cursorrules ou copilot-instructions?

Em resumo: Se usa apenas o Claude Code, o CLAUDE.md chega. Se usa duas ou mais CLIs de agentes (Codex, Cursor, Copilot, Sourcegraph), mude para o AGENTS.md e crie um symlink de CLAUDE.md para AGENTS.md. O AGENTS.md surgiu no final de 2025 como um padrão transversal entre ferramentas, e a maioria dos agentes modernos recorre a ele como fallback, pelo que um único ficheiro alimenta todos os ecossistemas.

Esta é a pergunta 0 que os 5 primeiros resultados realmente respondem. Eis a matriz:

O truque do duplo alvo é uma só linha:

ln -s AGENTS.md CLAUDE.md

E está feito. Agora o Claude Code, o Codex e qualquer ferramenta compatível com AGENTS.md leem o mesmo ficheiro. Atualize uma vez, e todos os agentes ficam sincronizados. A especificação do AGENTS.md é aberta e intencionalmente minimalista — é apenas markdown com secções convencionais.

Dois senões práticos. Primeiro: se a sua equipa tiver um utilizador avançado do Cursor, o .cursorrules do Cursor segue uma abordagem diferente — ficheiro único, sem hierarquia, formato mais rígido. Algumas equipas mantêm ambos: AGENTS.md para as regras partilhadas, .cursorrules para as especificidades do Cursor. Segundo: o .github/copilot-instructions.md do Copilot não recorre ao AGENTS.md como fallback, pelo que equipas muito dependentes do Copilot precisam de um ficheiro separado.

Se está a escolher uma stack de agentes de raiz, a nossa análise Claude Code vs Cursor vs Copilot cobre os compromissos ao nível da utilização. A versão curta: a hierarquia do Claude Code é a mais poderosa para monorepos, a UX do Cursor ganha para trabalho individual, e a integração do Copilot no IDE continua a ser a mais fluida para adoção incremental.

Regra #9: Use AGENTS.md se executar mais do que uma CLI de agentes. Não mantenha dois ficheiros a dizer o mesmo. Escolha o ficheiro que a maioria da sua stack lê e crie symlinks para o resto.

CLAUDE.md vs Hooks vs Skills: O Triângulo da Decisão

Resumindo: CLAUDE.md = contexto consultivo. Hooks = ações determinísticas. Skills = capacidades empacotadas. Escolha a ferramenta errada e estará a desperdiçar orçamento de instruções em algo que um hook deveria tratar, ou a escrever uma regra no CLAUDE.md para algo que só um skill consegue entregar. O triângulo é a forma mais económica de manter o CLAUDE.md enxuto.

Três ferramentas, três funções. O erro que vemos com mais frequência: colocar "executar sempre o prettier depois de editar" no CLAUDE.md. O Claude lê-a. O Claude por vezes executa o prettier. Você fica frustrado. A solução é tirar essa linha do CLAUDE.md e colocá-la num hook, porque os hooks disparam de forma determinística todas as vezes, sem qualquer margem de manobra consultiva.

Se uma regra tem de disparar sempre, pertence a um hook. Se for uma preferência de estilo que o Claude pode avaliar em função do contexto, pertence ao CLAUDE.md. Se for um fluxo de trabalho multi-passo com recursos empacotados (templates, scripts, prompts), pertence a um skill.

Regra #8: Escolha corretamente entre CLAUDE.md, hooks e skills — colocar um hook no CLAUDE.md é o desperdício mais comum de orçamento de instruções. Configure ações determinísticas com hooks do Claude Code e empacote fluxos de trabalho reutilizáveis como skills do Claude. O seu CLAUDE.md fica mais curto, as suas salvaguardas ficam mais firmes e o Claude deixa de "esquecer" as regras que importam.

Padrões de Monorepo: CLAUDE.md aninhados, @imports e .claude/rules/

Em resumo: Num monorepo, mantém o CLAUDE.md raiz minimalista, apenas com apontadores e convenções partilhadas. Empurra as especificidades para apps/*/CLAUDE.md, de modo que cada subárvore tenha regras com âmbito próprio. Usa @imports para partilhar ficheiros de regras modulares através de .claude/rules/. Isto é divulgação progressiva — o Claude obtém cada parte apenas quando é relevante.

Uma árvore típica de CLAUDE.md num monorepo:

.
├── CLAUDE.md                        # 30 lines — points to subdirs and shared rules
├── .claude/
│   └── rules/
│       ├── style.md
│       ├── testing.md
│       └── security.md
├── apps/
│   ├── web/
│   │   └── CLAUDE.md                # Next.js-specific rules
│   └── api/
│       └── CLAUDE.md                # Fastify-specific rules
└── packages/
    └── shared/
        └── CLAUDE.md                # Library author rules

A sintaxe @import permite que o ficheiro raiz incorpore blocos de regras partilhadas sem ter de os repetir:

# CLAUDE.md raiz

Isto é um Turborepo. Consulta o CLAUDE.md do subdiretório para as regras específicas da aplicação.

@import .claude/rules/style.md
@import .claude/rules/testing.md
@import .claude/rules/security.md
## Comandos de topo
- `pnpm dev` executa todas as apps em paralelo
- `pnpm test` executa o script de testes de cada workspace

Isto é revelação progressiva na prática. O ficheiro raiz é um ponteiro de 30 linhas. Cada CLAUDE.md de subdiretório acrescenta 50–80 linhas de regras focadas. Os ficheiros em .claude/rules/ contêm blocos de convenções que vários subdiretórios podem importar. Nada é duplicado, nada fica esquecido e nenhum ficheiro individual excede o orçamento de instruções.

A regra de lazy-loading referida anteriormente é ainda mais importante aqui: quando o Claude trabalha em apps/web/Button.tsx, vê o ficheiro raiz, mais o apps/web/CLAUDE.md, mais os ficheiros de regras importados via @import. Não vê o apps/api/CLAUDE.md. É exatamente esse o ponto: as convenções de backend não poluem o contexto de frontend, e a tua janela de contexto mantém-se utilizável.

Regra #6: Usa @imports para manter o ficheiro raiz abaixo das 200 linhas. O guia Anthropic Best Practices for Claude Code trata isto como o padrão standard de monorepo. Os subagentes também herdam o contexto do CLAUDE.md pai, o que vale a pena saber se estiveres a aninhar fluxos de trabalho — vê engenharia de contexto para perceberes como isso interage com o design de subagentes.

6 Razões Pelas Quais o Claude Ignora o Seu Ficheiro (E a Solução Para Cada Uma)

Em resumo: Quando o Claude ignora o CLAUDE.md, a causa é quase sempre uma de seis: ficheiro demasiado longo, formulação vaga, falta do "porquê", compactação de contexto, ficheiro pai em conflito ou nome de ficheiro incorreto. Cada uma tem uma solução de 60 segundos. Teste numa nova sessão após cada alteração — esta é a Regra #7.

1. Ficheiro demasiado longo (>200 linhas / >500 palavras)

Execute wc -l CLAUDE.md. Se tiver mais de 200, reduza drasticamente. Mova as regras de automação para hooks. Mova os fluxos de trabalho para skills. Divida os blocos partilhados em .claude/rules/ e importe-os com @import. O motivo mais comum para o Claude "deixar de seguir" as suas regras é o ficheiro se ter tornado demasiado longo ao longo do tempo, e a adesão ter colapsado silenciosamente.

2. Formulação vaga ("escreve código limpo")

Substitui cada regra aspiracional por uma regra específica e testável. "Sê consistente" é invisível para o Claude. "Usa componentes de servidor por predefinição; adiciona apenas 'use client' para formulários ou interfaces interativas" é algo que o Claude consegue realmente aplicar.

3. Falta do "porquê"

Regras sem motivos não se generalizam. O Claude não consegue inferir quando contornar a regra, porque não sabe contra o que a regra está a proteger. Cada regra não óbvia recebe uma explicação de uma linha: "usamos unknown e não any porque tivemos três falhas em tempo de execução no último trimestre devido a respostas de API tipadas como any."

4. A compactação do contexto descartou-o

Sessões longas desencadeiam a compactação, o Claude resume o contexto anterior para caber na janela, e o conteúdo do CLAUDE.md por vezes acaba resumido até ao esquecimento. A solução: /clear após grandes consumos de contexto, ou reiniciar a sessão por completo. É exatamente isto que a Issue #17530 do GitHub continua a trazer à tona.

5. CLAUDE.md superiores em conflito

O global diz "usa 4 espaços." A raiz do projeto diz "usa 2 espaços." O subdiretório não diz nada. O Claude escolhe um, por vezes o errado. Audita o ~/.claude/CLAUDE.md e a raiz do projeto à procura de contradições. O que for mais específico deve prevalecer, mas só se tornares isso explícito.

6. Localização errada do ficheiro ou capitalização do nome

Claude.md e CLAUDE.md são ficheiros diferentes no Linux e no macOS. O mesmo acontece com claude.md e CLAUDE.md. Confirme que o caminho é exatamente ./CLAUDE.md (tudo em maiúsculas) e confirme que o Claude Code é iniciado a partir do diretório que o contém. O GitHub Issue #668 está cheio de casos em que o ficheiro existia, mas o Claude não o conseguia ver devido a problemas de caminho.

Regra #7: Teste numa sessão nova. Após qualquer alteração ao CLAUDE.md, abra uma nova sessão e peça ao Claude para "resumir as regras no CLAUDE.md". Se o resumo omitir algo, o ficheiro não está a cumprir a sua função.

O Teu Primeiro CLAUDE.md em 10 Minutos: Um Guia de Iniciação em 5 Passos

Em resumo: Executa /init para gerar um rascunho inicial, reduz para 6–10 regras reais com justificações, adiciona 3 comandos que o Claude deve conhecer, adiciona 2 anti-padrões que a tua equipa já encontrou e, depois, testa numa sessão nova pedindo ao Claude para resumir o ficheiro. Tempo total: cerca de 10 minutos. A receita de 5 passos é o que usamos no dia 1 de cada repositório novo.

1. Executa /init para gerar um rascunho inicial. O comando /init do Claude Code analisa o teu repositório e escreve um CLAUDE.md inicial. Não publiques o que ele escreve. O resultado do /init é um ponto de partida, não um ficheiro terminado, e, francamente, a maior parte do que ele gera pode ser eliminada.

2. Reduz para 6–10 linhas de regras reais com justificações. Elimina tudo o que for genérico. Elimina tudo o que estiver no README. Mantém apenas as regras que o Claude não consegue inferir a partir do próprio código.

3. Adiciona 3 comandos que o Claude deve conhecer. Build, test, lint. Inclui o comando exato e quaisquer flags não óbvias. Se usas Vitest em vez de Jest, diz isso.

4. Adiciona 2 anti-padrões que esta equipa já encontrou. Reais. "Não uses any porque tivemos três falhas em tempo de execução" é sempre melhor do que "usa TypeScript corretamente".

5. Abre uma sessão nova e verifica. Pede ao Claude para "resumir as regras no CLAUDE.md". Se ele falhar alguma coisa, o ficheiro é demasiado longo, demasiado vago, ou falta um "porquê". Corrige e repete.

Regra #5: Não geres automaticamente apenas a partir do /init. O /init é um ponto de partida, não um ficheiro terminado. Os 8 minutos que gastas a reduzi-lo são onde está o valor.

Perguntas Frequentes

O que é um ficheiro CLAUDE.md?

Um ficheiro CLAUDE.md é um ficheiro markdown que o Claude Code lê como memória do projeto no início de cada sessão. Indica ao Claude as suas convenções, comandos e anti-padrões, para que não tenha de adivinhar. Funciona a quatro níveis: global, raiz do projeto, subdiretório (de carregamento preguiçoso) e um CLAUDE.local.md pessoal que mantém no gitignore.

Qual deve ser o tamanho de um ficheiro CLAUDE.md?

Menos de 200 linhas e menos de 500 palavras de regras densas. Acima desses limites, a capacidade do Claude de seguir instruções degrada-se: cada regra que acrescenta torna todas as outras ligeiramente menos prováveis de serem cumpridas. Trate-o como um orçamento fixo. Se precisar de mais, divida em ficheiros CLAUDE.md em subdiretórios e use @import para os blocos partilhados.

Onde devo colocar o CLAUDE.md?

O principal fica na raiz do teu projeto (./CLAUDE.md) e é commitado. Em monorepos, adiciona ficheiros CLAUDE.md em subdiretórios para regras específicas de cada aplicação. Coloca as preferências transversais a vários projetos em ~/.claude/CLAUDE.md. Usa o CLAUDE.local.md para configurações pessoais que não queres commitar, mas lembra-te de o adicionar manualmente ao gitignore.

Porque é que o Claude está a ignorar o meu CLAUDE.md?

90% das vezes é uma de três coisas: o ficheiro é demasiado longo (mais de 200 linhas), as regras são vagas ("escreve código limpo") ou falta às regras um "porquê" que o Claude possa usar para as aplicar. Executa wc -l CLAUDE.md e depois verifica a especificidade. Testa as alterações numa nova sessão, pedindo ao Claude para resumir o ficheiro.

Devo usar CLAUDE.md ou AGENTS.md?

Se a tua equipa usa apenas o Claude Code, fica com o CLAUDE.md. Se usares duas ou mais CLIs de agentes (Codex, Cursor, Sourcegraph), muda para AGENTS.md e cria um symlink do CLAUDE.md para ele: ln -s AGENTS.md CLAUDE.md. A maioria das CLIs de agentes modernas recorre ao AGENTS.md como fallback, pelo que um único ficheiro alimenta todas as ferramentas.

Devo executar o /init para gerar o CLAUDE.md?

Sim, como rascunho. Não, como ficheiro final. O /init analisa o teu repositório e gera um ponto de partida, mas é verboso e genérico. Tanto a Anthropic como a HumanLayer recomendam cortar agressivamente depois de executar o /init. São os 8 minutos que gastas a cortar e a acrescentar linhas de "porquê" que tornam o ficheiro realmente útil.

Como funcionam os ficheiros CLAUDE.md num monorepo?

O CLAUDE.md raiz deve ser minimalista, apenas com apontadores e regras partilhadas. Cada aplicação tem o seu próprio apps/*/CLAUDE.md com convenções específicas. Os ficheiros em subdiretórios são carregados de forma preguiçosa apenas quando o Claude lê ficheiros dentro dessa subárvore, mantendo os diretórios irmãos isolados. Utilize @import .claude/rules/style.md para partilhar blocos de regras modulares sem os duplicar entre aplicações.

Qual é a diferença entre CLAUDE.md, hooks e skills?

CLAUDE.md é contexto consultivo — o Claude lê-o e geralmente segue-o. Hooks são ações determinísticas que são sempre executadas (formatação, bloqueio de commits). Skills são capacidades agrupadas para fluxos de trabalho reutilizáveis com recursos. Usa o CLAUDE.md para orientações de estilo, hooks para regras rígidas e skills para tarefas de vários passos que vais repetir em vários projetos.

Como a Techsy Aborda Isto

Na Techsy, todos os projetos de Claude Code que entregamos incluem um CLAUDE.md com menos de 150 linhas e um symlink AGENTS.md. Tratamos o ficheiro como código, controlamos a sua versão, revemos as alterações em PRs e voltamos a testar em sessões novas antes de fazer merge. Precisa de ajuda para integrar agentes de IA no seu fluxo de trabalho de desenvolvimento? Obtenha uma consulta gratuita.