Introdução

Atualmente com o desenvolvimento utilizando Inteligência Artificial, e sendo o Claude uma das ferramentas mais utilizadas, é importante saber e entender o que é esse arquivo e a melhor forma de mantê-lo no projeto.

O arquivo claude.md de forma geral é utilizado para documentar o projeto e essa documentação é passada como contexto para o Claude em cada chat.

Onde colocar o arquivo claude.md

Esse arquivo pode ser utilizado para documentar regras gerais do projeto, regras gerais do usuário (preferências pessoais) e regras gerais de uma empresa.

Vou focar aqui nas instruções de projeto e módulos de um projeto, que foi o que eu mais utilizei e mais testei.

Para isso, o ideal é colocar o arquivo claude.md na raiz do projeto ou dentro do diretório .claude/claude.md.

Boas práticas

Manter o arquivo curto

O ideal é manter o arquivo claude.md com até cerca de 200 linhas, isso porque como é carregado em todo chat, o contexto pode ficar muito grande, ocupando muito espaço e deixando o Claude sem espaço para outras informações relevantes.

Separar em arquivos

Para resolver o item acima, o ideal é referênciar outros arquivos dentro do claude.md, como por exemplo:

Regras do projeto
- [Regras de commit](./claude/rules/commits.md)
- [Estilos de código](./claude/rules/code-styles.md)
- [Database](./claude/rules/database.md)
- [Testes](./claude/rules/tests.md)

Dessa forma o Claude irá carregar esses subarquivos somente quando for necessário para a implementação.

Outra forma, é criar mais arquivos claude.md dentro de cada módulo, como por exemplo:

- modules
  - auth
    - claude.md
  - users
    - claude.md
- database
    - claude.md

Dessa forma também o Claude irá carregar o arquivo claude.md específico do módulo quando for necessário, e não o arquivo geral do projeto, que pode ser mais extenso e conter informações que não são relevantes para aquele módulo específico.

Isso ajuda a economizar tokens e a manter o contexto mais relevante para o que está sendo implementado.

Quanto maior o contexto, mais tokens é utilizado.

Agentes e Skills

Se o repositório tiver agentes e skills, o ideal é deixar claro dentro do claude.md que existem essas ferramentas e que ele pode utilizar.

Faça o vínculo como por exemplo:

Agents

- [Frontend Agent](.\claude\agents\frontend.md)

Skills

- [Commit helper](.\claude\skills\commit-helper\SKILL.md)

Comentários

É possível colocar comentários no arquivo claude.md utilizando a sintaxe de comentários do Markdown, que é .

Isso é útil para humanos, deixar anotações e entre outras informações relevantes.

Esses comentários não consomem tokens e não vão ao contexto.

Escrita

O ideal é escrever o arquivo claude.md de forma clara e objetiva, utilizando uma linguagem simples e direta, para facilitar a compreensão do Claude e evitar ambiguidades.

Evite criar longos parágrafos, o ideal é utilizar listas, tabelas e outros recursos visuais para organizar as informações de forma mais clara e fácil de entender.

Conclusão

Esse assunto é bastante extenso e sobretudo há muitas novidades a cada dia, novas formas de fazer ou utilizar os recursos da inteligência artificial.

O importante é manter o arquivo claude.md sempre atualizado com novas regras quando tiver, sempre conciso para garantir um bom resultado.

Caso tenha alguma sugestão de melhoria nesse artigo, entre em contato comigo no Linkedln :)

Boas práticas para o arquivo claude.md