Análise da estrutura da pasta .claude/

• A pasta .claude/ é o diretório central de controle do Claude Code, responsável por gerenciar regras, comandos, permissões e estado de memória por projeto
• CLAUDE.md é o arquivo central que define os princípios de comportamento e as regras do projeto para o Claude, aplicando uma mescla de configurações em várias camadas
• As pastas commands/, skills/ e agents/ organizam, respectivamente, comandos personalizados, fluxos de trabalho automáticos e subagentes especializados, aumentando a eficiência da colaboração
• settings.json controla as permissões de execução de comandos e o escopo de acesso a arquivos, e permite sobrescritas individuais com settings.local.json
• A estrutura como um todo funciona como um protocolo que transmite ao Claude a identidade e as regras do projeto, e configurações claras maximizam a produtividade e a eficiência colaborativa

---

Estrutura da pasta .claude/ e seus componentes

• A pasta .claude/ é o diretório central que controla o funcionamento do Claude Code, gerenciando regras, comandos, permissões e estado de memória por projeto
• A pasta na raiz do projeto contém configurações de equipe e é versionada no Git
• A pasta no diretório pessoal (~/.claude/) armazena configurações pessoais e histórico de sessões, incluindo memória automática e comandos pessoais

• CLAUDE.md — o guia de instruções do Claude

  • É o primeiro arquivo lido no início de uma sessão do Claude Code e define os princípios de comportamento e as regras do projeto do Claude
  • O CLAUDE.md na raiz do projeto cuida das regras comuns da equipe, o ~/.claude/CLAUDE.md das regras pessoais globais, e o CLAUDE.md em subpastas das regras específicas de cada pasta
  • O Claude mescla e aplica vários arquivos CLAUDE.md
  • O conteúdo recomendado inclui comandos de build e teste, decisões arquiteturais principais, restrições não intuitivas e regras de nomenclatura e tratamento de erros
  • Recomenda-se manter até 200 linhas, pois um arquivo excessivamente longo reduz a aderência do Claude às instruções

• CLAUDE.local.md — sobrescritas pessoais

  • Arquivo que permite refletir preferências pessoais separadamente das regras comuns da equipe
  • Se você criar CLAUDE.local.md na raiz do projeto, o Claude o lerá junto com os demais
  • É incluído automaticamente no .gitignore e não é commitado no repositório

• Pasta rules/ — gerenciamento modular de regras

  • Quando CLAUDE.md cresce demais, ele pode ser dividido e gerenciado na pasta .claude/rules/
  • Cada arquivo de regra é separado por tema, o que facilita a manutenção
    • Ex.: code-style.md, testing.md, api-conventions.md, security.md
  • Usando o campo paths no frontmatter YAML, é possível definir regras aplicáveis apenas a caminhos específicos
    • Ex.: aplicar regras de API apenas ao caminho src/api/**/*.ts
  • Regras sem definição de caminho são sempre carregadas em todas as sessões

• Pasta commands/ — comandos slash personalizados

  • Cada arquivo Markdown em .claude/commands/ é registrado como um comando slash (/)
    • Ex.: review.md → /project:review, fix-issue.md → /project:fix-issue
  • Com a sintaxe de crase com !, é possível inserir no prompt do Claude o resultado da execução de comandos shell
    • Ex.: !git diff main...HEAD
  • Com a variável $ARGUMENTS, é possível passar argumentos ao executar o comando
    • Ex.: /project:fix-issue 234 → carrega automaticamente o conteúdo da issue 234 do GitHub
  • Comandos do projeto são compartilhados com a equipe, e comandos pessoais ficam em ~/.claude/commands/, podendo ser usados em todos os projetos

• Pasta skills/ — fluxos de trabalho com execução automática

  • Funciona como um fluxo de trabalho semelhante a comandos, mas acionado automaticamente
  • O Claude analisa o conteúdo da conversa e executa automaticamente quando apropriado
  • Cada skill é definida por um arquivo SKILL.md em uma subpasta, com frontmatter YAML para indicar condições de acionamento e ferramentas permitidas
    • Ex.: a skill security-review é executada automaticamente em conversas relacionadas à segurança
  • A pasta da skill pode incluir documentos auxiliares ou arquivos de template, como DETAILED_GUIDE.md
  • Skills pessoais ficam em ~/.claude/skills/ e podem ser usadas globalmente

• Pasta agents/ — subagentes especializados

  • A pasta .claude/agents/ define subagentes (personas) com papéis específicos
  • Cada agente tem seu próprio prompt de sistema, modelo e permissões de acesso a ferramentas
    • Ex.: code-reviewer.md, security-auditor.md
  • Com o campo tools, é possível limitar as ferramentas acessíveis, implementando segurança e separação de funções
  • Com o campo model, é possível escolher o modelo Claude adequado à tarefa, como Haiku, Sonnet ou Opus
  • Quando necessário, o Claude executa esse agente em um contexto separado e reporta apenas um resumo do resultado

• settings.json — permissões e configurações do projeto

  • .claude/settings.json define as permissões de execução de comandos e o escopo de acesso a arquivos do Claude
  • O campo $schema oferece suporte a autocompletar e validação em ferramentas como o VS Code
  • A lista allow define comandos aprovados automaticamente, e a lista deny define comandos totalmente bloqueados
    • Ex.: permitido — Bash(npm run *), Read, Write, Edit
    • bloqueado — Bash(rm -rf *), Bash(curl *), leitura de arquivos .env
  • Comandos que não estão nas listas exigem confirmação do usuário antes da execução
  • Alterações individuais de permissões são salvas em .claude/settings.local.json e não entram no Git

• Pasta ~/.claude/ — configuração global e memória

  • ~/.claude/CLAUDE.md contém instruções pessoais aplicadas a todos os projetos
  • ~/.claude/projects/ armazena histórico de sessões por projeto e memória automática
    • Mantém comandos, padrões e insights estruturais aprendidos pelo Claude
    • É possível consultar e editar com o comando /memory
  • ~/.claude/commands/, ~/.claude/skills/ e ~/.claude/agents/ são repositórios de comandos, skills e agentes pessoais globais

• Exemplo da estrutura completa

  your-project/  
  ├── CLAUDE.md  
  ├── CLAUDE.local.md  
  └── .claude/  
      ├── settings.json  
      ├── settings.local.json  
      ├── commands/  
      ├── rules/  
      ├── skills/  
      └── agents/  
  ~/.claude/  
  ├── CLAUDE.md  
  ├── settings.json  
  ├── commands/  
  ├── skills/  
  ├── agents/  
  └── projects/  
  

• Etapas de configuração inicial

  • Etapa 1: gerar o CLAUDE.md básico com o comando /init e manter apenas o conteúdo essencial
  • Etapa 2: criar .claude/settings.json e definir regras de permissão e bloqueio de execução

  • Etapa 3: adicionar comandos adequados aos fluxos de trabalho usados com frequência (ex.: revisão de código, correção de issues)

    • Etapa 4: quando CLAUDE.md crescer, dividir em .claude/rules/
    • Etapa 5: adicionar regras de preferência pessoal em ~/.claude/CLAUDE.md

Insights principais

• A pasta .claude/ é um protocolo que transmite ao Claude a identidade e as regras do projeto
• CLAUDE.md é o arquivo mais importante, e quanto mais claramente ele for definido, mais a produtividade do Claude será maximizada
• Os demais componentes são camadas de otimização complementares, que podem ser expandidas gradualmente
• Configurações claras levam a menos pedidos de correção ao Claude e colaboração mais eficiente

Discussão adicional

• A lista deny de settings.json é segura quando usada por humanos, mas no modo agente exige proteção adicional por causa do acesso ao Bash
• O OneCLI fornece, no nível de rede, uma camada de proxy que substitui tokens de credenciais, evitando exposição de segredos
• No futuro, surge a necessidade de uma configuração .claude exclusiva para o modo agente (com separação de regras, permissões e skills)
• Segundo a documentação mais recente, commands e skills foram unificados: .claude/commands/deploy.md e .claude/skills/deploy/SKILL.md passam a gerar igualmente o comando /deploy, enquanto skills oferecem recursos adicionais, como arquivos auxiliares e acionamento automático

[GN⁺]

Comentários no Hacker News

• Montar um toolkit para agentes de IA parece um pouco como buscar a configuração perfeita de produtividade
  A pessoa vê posts de blog e vídeos no YouTube, monta uma rotina, mas no fim quem avança mais é quem trabalha de forma consistente com uma simples lista de tarefas
  Pela minha experiência, a abordagem simples de pedir ao Claude puro para planejar, revisar e depois executar ainda funciona melhor

  • Em codebases grandes ou sistemas distribuídos, a história é diferente
    As habilidades técnicas do agente para fazer piping de dados, criar requisições, rastrear sistemas e atualizar código aumentam muito a eficiência do desenvolvimento
    Em uma base com 10 milhões de linhas de código, a produtividade melhorou bastante, e a geração de código em si representou menos de 5% disso
    A maior parte veio da capacidade de montar rapidamente uma toolchain para testes e validação
  • Muita gente está caindo nessa armadilha e gastando dinheiro
    Na verdade, se você consegue saber claramente o que quer e comunicar isso bem, já dá para fazer muita coisa com IA
    A maioria não sabe. Por isso, o processo de fazê-la planejar vira um atalho para obter entendimento
  • Como PM, eu queria que agentes economizassem tempo e gerassem efeito composto (compounding) na produção
    Mas há a ineficiência de repetir contexto em toda sessão e ficar copiando arquivos .md
    Meu objetivo agora é eliminar essa repetição.
    Tenho curiosidade sobre como vocês gerenciam um “context bank” que acumula contexto — por exemplo, informações básicas como “meu papel, produto pelo qual sou responsável, documentação mais recente”
    Não dá para simplesmente conectar o Drive inteiro, porque há muita documentação duplicada e desatualizada
    Se um contexto repetido aparece mais de duas vezes, estou em dúvida se devo criar um arquivo de Skill ou reunir os documentos e gerenciá-los em uma pasta
  • Tive uma experiência parecida. A maior parte dos artefatos gerados durante o trabalho acaba sendo descartada
    Configuração excessiva (over-configuration) causa queda de qualidade e problemas de loop
    Como os modelos estão melhorando cada vez mais, instruções que antes eram necessárias podem acabar até prejudicando o desempenho
    Também ouvi dizer que a equipe da Anthropic zera o claude.md a cada 30 dias
  • Por outro lado, estou tocando um projeto que precisa integrar uma API contábil local, e é uma API totalmente customizada que o LLM não conhece
    Então fiz o Claude criar um servidor MCP, e agora ele automatiza as tarefas contábeis
    Depois do fechamento mensal, pedi ao Claude para extrair as tarefas principais e transformá-las em Skills, e ele passou a trabalhar como se eu tivesse um contador júnior
    MCP customizado e Skills parecem realmente muito úteis

• Parece que muita gente cria uma parede enorme de configuração antes mesmo de começar com codificação agentic
  Mas no começo o certo é partir de um .claude vazio e um AGENTS.md e aprender a usar na prática

  • Eu acho até que se deveria usar apenas skills criadas por você mesmo
    Se você sai instalando skills feitas por outras pessoas, a não determinismo (nondeterminism) aumenta e ainda se desperdiça janela de contexto
    Como exceção, eu só recomendaria instalar algo externo como o playwright-cli
  • Em times grandes, é preciso ter guardrails (regras) consistentes
    Por exemplo, configurar para verificar pré-condições com esta regra deixa tudo mais estável
    Acho que times de segurança também tenderiam a preferir esse tipo de abordagem
    Eu também defini regras para que o Claude não faça commit sem assinatura GPG
    Mas essas regras não devem ser fixas; precisam evoluir continuamente
  • O texto não está defendendo uma configuração gigantesca
    Pelo contrário, ele enfatiza repetidamente que é melhor começar pequeno e manter curto
    Mesmo iniciantes, se adicionarem só algumas linhas ao AGENTS.md, já ajudam a IA a entender melhor sua intenção
    Uma configuração simples reduz bastante o mau funcionamento da IA
  • Trabalhar sozinho com código e lidar em equipe com um projeto compartilhado são coisas completamente diferentes
    Quando cada desenvolvedor usa ferramentas agentic, a própria forma de colaboração muda
  • Só de usar o modo plan já se resolve 90%
    Acho que essa discussão sobre configurações complexas vai desaparecer em grande parte dentro de um ano, à medida que os modelos evoluírem

• A pasta ~/.claude/projects é a parte realmente interessante

• Para mim, quanto menos configuração desnecessária, melhor foi o resultado
  As pessoas tentam regular demais a documentação, mas a IA é como um adulto competente, porém nervoso
  Se você dá instruções demais, ela acaba ficando mais burra

• Este texto parece mais gerado do que baseado em experiência real
  É melhor manter o Claude.md curto, com só alguns links
  Conforme o contexto se acumula, o desempenho piora, então é preciso separar planejamento e implementação e reiniciar sempre

  • A abertura soa tanto como o estilo do Claude que eu também achei que talvez bastasse perguntar direto para ele
  • A diferença entre skills e comandos é confusa
    Não fica claro se skills estão sempre no contexto e comandos só podem ser chamados manualmente

• Seria bom se todos os provedores de modelo compartilhassem um conjunto padrão de arquivos
  Aí seria mais fácil alternar entre Claude, Codex, Cursor e Opencode

  • Mas a combinação de modelo com harness impacta muito o resultado
    Mesmo com o mesmo prompt, cada modelo reage de um jeito, então o ajuste de prompt precisa variar por modelo
  • Dá para criar um único agents.md, fazer o Claude.md referenciá-lo e conectar tudo entre pastas com symlink (sync)
    Não é perfeito, mas funciona bem razoavelmente
  • Estamos agora como na era inicial dos navegadores. Justamente por não haver padronização, surgiram inovações como AJAX
    Então essa diversidade atual é até positiva
  • Eu estou resolvendo isso por enquanto com o dotagents by Sentry
  • Não acho que os provedores de modelo tenham qualquer motivo para facilitar a troca entre plataformas

• A documentação alternativa do Claude Fast é muito útil
  Não vejo motivo para odiar a definição da pasta .claude
  Você pode fazer o agente principal escrever os próprios arquivos, atualizá-los repetidamente e construir um sistema autossupervisionado de melhoria
  Agora o .claude se replica, se avalia e se atualiza sozinho — em vez de programar código, é como se eu estivesse programando o .claude

  • Em resumo, o CLAUDE.md não é apenas um documento; é o sistema operacional do Claude
    A ideia é definir comportamentos, delegar conhecimento em skills e montar um sistema que melhora sozinho com o tempo

• Um obstáculo que muita gente não percebe é que, mesmo fazendo o Claude editar um arquivo, isso não é refletido a menos que você mande reler
  Por exemplo, se você acabou de escrever um novo CLAUDE.md, precisa recarregar para que o Claude reconheça aquilo como nova instrução

• Na pasta ~/.claude/plans ficam os arquivos de plano gerados ao executar o modo plan
  Eu costumo abrir esse diretório com frequência para fazer backup ou consultar algo

• Eu organizo tudo em torno de servidores MCP globais e um agente composto (composite agent)
  Cada servidor MCP define um conjunto de ferramentas, e o agente trabalha de forma autônoma dentro disso
  O .agent.md é apenas um documento que descreve as ferramentas disponíveis, então não é necessário uma configuração complexa
  Acho que skills ou prompts reutilizáveis têm pouco valor
  Os modelos já são inteligentes o bastante; o que eles precisam é de orientação