Claude Code

Fornecedor: Anthropic Nome de instalação: claude-code Status: GA Configuração nativa: ~/.claude/

InstalaçãoCopy Anchor Link

apothem install --harness claude-code

O adaptador claude-code instala o corpus compartilhado do Apothem na árvore de descoberta nativa do Claude Code. Agentes em Markdown, regras, skills, output-styles e configurações são instalados em seus locais nativos; os prompts de comando são convertidos em skills para que os fluxos de trabalho reutilizáveis continuem visíveis pela superfície de skills atual do Claude Code. O renderizador de statusline é copiado para ~/.claude/statuslines/, mas não é conectado: o Claude Code lê sua linha de status a partir da configuração statusLine, que o adaptador deixa sem definir. Para ativá-lo, adicione ao settings.json uma entrada statusLine de "type": "command" que execute ~/.claude/statuslines/render.py. O valor commandWindows do trecho é executado no Windows e nomeia o interpretador sem aspas. Quando o caminho do interpretador contém um espaço, a instalação grava nesse valor a forma curta 8.3 do Windows, quando o volume a possui. As entradas de hook em settings.json mantêm o caminho completo.

Arquivos gravados: settings.json, o bloco do Apothem em CLAUDE.md, agents/, rules/, skills/, statuslines/, output-styles/ e a subárvore de suporte .apothem/support/ (.apothem/support/hooks/, .apothem/support/conformity/, .apothem/support/schemas/, .apothem/support/templates/) sob ~/.claude/. Os arquivos de comando são convertidos em diretórios de skill filhos. O despachante de hooks e o conformity gate são executados a partir de suas cópias materializadas — as entradas de hook do settings.json invocam ~/.claude/.apothem/support/hooks/dispatch.py e ~/.claude/.apothem/support/conformity/gate.py por caminho absoluto, de modo que nenhum pacote apothem importável é necessário no host.

~/.claude/CLAUDE.md permanece de propriedade do operador. O adaptador grava nele um único bloco do Apothem delimitado por sentinelas, que contém a projeção do perfil (identidade, preferências, regras, seriedade e comportamentos ativados por opção) e uma seção de arquivos de suporte do Apothem, e preserva literalmente cada linha fora das sentinelas. A seção de arquivos de suporte nomeia o diretório absoluto em relação ao qual cada citação no estilo do repositório nas regras, skills e agentes instalados é resolvida: rules/<name>.md sob ~/.claude/rules/, e templates/..., schemas/..., hooks/... e conformity/... sob ~/.claude/.apothem/support/. Ela também aponta para o índice de regras, ~/.claude/rules/apothem-rule-index.md. O restante da superfície de governança do Apothem chega ao Claude Code pela árvore rules/ propagada e pelo hook SessionStart. O OpenCode também carrega ~/.claude/CLAUDE.md quando não existe nenhum ~/.config/opencode/AGENTS.md, então o bloco não nomeia nenhuma ferramenta específica como seu leitor.

Mapeamento do perfil para a configuração nativaCopy Anchor Link

A cada apothem install ou apothem update, o adaptador propaga o corpus compartilhado do apothem para ~/.claude/ conforme o manifesto de propagação. O adaptador usa diretórios nativos diretamente onde possível e converte os prompts de comando em pastas de skill. Os filhos existentes correspondentes gerenciados pelo Apothem recebem backup antes da substituição; as entradas não relacionadas criadas pelo operador são preservadas. O settings.json é mesclado para que as chaves criadas pelo operador permaneçam recuperáveis.

Os arquivos escritos pelo operador são mantidos somente fora das pastas abaixo. Cada instalação e cada atualização remove cada uma destas pastas em ~/.claude/ que exista, tenha ela sido escrita pelo Apothem ou não: src/, conformity/, schemas/, hooks/, config/, scripts/, tools/, lib/, templates/, docs/, tests/, packaging/, mcp/, examples/, assets/, site/, public/ e commands/. Também remove statuslines/__init__.py e os arquivos AGENTS.md em agents/, rules/, skills/, statuslines/ e output-styles/. Uma pasta removida é excluída por inteiro, incluindo os arquivos que você colocou nela. Os comandos de barra que você mantém em commands/ também são removidos, e o Apothem instala os próprios prompts de comando como skills em skills/. Um script de hook que você mantém em hooks/ é removido, o que deixa qualquer entrada de settings.json que o chame apontando para lugar nenhum. A varredura roda antes de a instalação gravar os próprios arquivos. Cada caminho removido é copiado primeiro para ~/.apothem/backups/, e o registro da instalação indica essa cópia. A desinstalação não a restaura. Para restaurar um caminho removido, execute apothem rollback --harness claude-code --install-id ID referente à instalação que o removeu, conforme descrito na referência de rollback. Um apothem rollback simples reverte somente a instalação mais recente. Os registros de instalação e as suas cópias são mantidos para as 10 instalações mais recentes; assim, um caminho removido só pode ser restaurado enquanto a sua instalação estiver entre elas. apothem diff --harness claude-code lista essas remoções como Prune stale files antes de você instalar.

As skills instaladas, e as skills empacotadas no plugin do Claude Code, carregam user-invocable em vez do userInvocable do corpus de origem, porque o Claude Code lê apenas a chave hifenizada. Os dois contêineres de templates (plan-suite, research-suite) a definem como false, de modo que ficam fora do menu /. Todo output-style define keep-coding-instructions: true, de modo que selecionar um deles mantém as instruções de engenharia de software integradas do Claude Code.

Ambos também carregam as chaves de frontmatter exclusivas do Apothem (version, updated, archetype, portability) sob um mapa metadata: final de strings entre aspas, nessa ordem fixa. O Claude Code ignora chaves de nível superior desconhecidas, e o formato aberto de skill mantém os extras específicos de cliente em metadata. Os arquivos de origem não mudam. As pastas de skill de nível de usuário (~/.agents/skills/, ~/.codebuddy/skills/, ~/.kiro/skills/ e ~/.trae/skills/) usam a mesma forma metadata, de modo que instalações que compartilham uma pasta nunca reescrevem os arquivos umas das outras. Todos os outros harnesses recebem as chaves no nível superior, como antes.

Regras e o que é carregado na inicializaçãoCopy Anchor Link

O Claude Code carrega um arquivo de regra na inicialização, a menos que seu frontmatter traga uma lista paths: que defina seu escopo. Com paths:, ele carrega a regra quando lê ou edita um arquivo correspondente. Uma lista composta apenas de ** não define escopo algum, então essa regra também é carregada na inicialização; nenhuma regra do Apothem usa uma assim. A instalação converte o pathFilter de cada regra nessa lista. Cinco regras não trazem nenhum e são carregadas em toda sessão: agnostic-posture, authority-inquiry, session-closure, context-management e o índice de regras, apothem-rule-index. Todas as outras regras são instaladas sob ~/.claude/rules/ com paths: e são carregadas quando um arquivo correspondente é tocado.

O Claude Code compara esses globs, com a semântica do .gitignore, ao caminho do arquivo relativo ao diretório de trabalho, e nunca a um arquivo fora dele. O diretório de memória automática fica sob ~/.claude/projects/, então auto-memory e auto-memory-topic-files nunca são carregadas por correspondência de caminho. Editar ~/.claude/CLAUDE.md ou um arquivo sob ~/.claude/rules/ a partir de outro projeto também não carrega as regras com escopo nesses arquivos. Essas regras chegam a uma sessão pelo índice.

O índice nomeia cada regra e a situação que a exige. Uma etapa que cita rules/<name>.md como seu procedimento lê esse arquivo primeiro. Depois de uma compactação de contexto, leia novamente qualquer regra que você estava aplicando: o Claude Code não reinjeta uma regra com escopo de caminho até que um arquivo correspondente seja tocado de novo. O nome apothem-rule-index.md é reservado, porque uma instalação faz backup e sobrescreve um arquivo de regra com esse nome.

As regras que regem as próprias superfícies do Apothem têm escopo em CLAUDE.md, AGENTS.md e no Markdown sob rules/, commands/, skills/, agents/, hooks/ e output-styles/. Um repositório de aplicação raramente contém esses arquivos, então nele essas regras chegam a uma sessão pelo índice, por uma skill, um comando ou um auxiliar que as cita, e pelos hooks, não por uma correspondência de caminho.

As cópias das regras são gravadas sem a seção final ## Bindings, assim como as skills de comando. A seção contém referências recíprocas para mantenedores e para o conformity gate. Os arquivos de origem a mantêm, assim como as cópias que outros harnesses recebem.

Para manter uma regra com escopo ativa em toda sessão, você pode tentar importá-la a partir de um texto fora do bloco do Apothem em ~/.claude/CLAUDE.md, por exemplo @rules/definitiveness.md. A página de memória do Claude Code documenta a importação e diz que um caminho importado é resolvido em relação ao arquivo que o importa. Ela não diz como a lista paths de uma regra importada é tratada, e o Apothem não verificou isso. Confirme com o hook InstructionsLoaded que a regra é carregada na inicialização e não é carregada uma segunda vez por correspondência de caminho.

Skills de comando e arquivos de referênciaCopy Anchor Link

Depois de uma compactação de contexto, o Claude Code reanexa apenas os primeiros 5.000 tokens de cada skill invocada, e recomenda um SKILL.md de cerca de 500 linhas ou menos, com os detalhes em arquivos irmãos. Os prompts de comando chegam a 67 KB, então a emissão para o Claude Code divide cada um em um SKILL.md enxuto mais arquivos sob references/:

• A seção ## Bindings é descartada. Ela é texto de mantenedor para o conformity gate, e o modelo nunca precisa dela.
• O Pipeline Contract, as Foundational Stanzas, a Decision Tree, os exemplos, as seções de modo e alguns inventários citados passam para arquivos de referência. O título permanece, e um ponteiro de uma linha abaixo dele nomeia o arquivo e diz quando lê-lo. Os ponteiros do Pipeline Contract e das Foundational Stanzas também listam o que o arquivo cobre.
• Quando o SKILL.md ainda passa de 15.800 bytes, as maiores etapas do Workflow passam para references/step-NN-<slug>.md, da maior para a menor, até que ele caiba. O slug é o título da etapa sem o prefixo Step N: e sem um id de mandato ou disciplina final entre parênteses. Etapas com menos de 600 bytes permanecem inline. Se isso não bastar, as seções Output, Mandates, Critical Rules e Instructions são movidas, nessa ordem.
• Uma nota curta depois do preâmbulo diz ao modelo onde estão os arquivos (${CLAUDE_SKILL_DIR}/references/) e que ele MUST reler os que regem sua etapa atual depois de uma compactação.

Todo SKILL.md emitido, incluindo a nota ## Installed Reference Paths que a instalação acrescenta, fica em 17.000 bytes ou menos para uma raiz de instalação de até 140 caracteres. O plugin distribui os mesmos arquivos sem essa nota, e seus comandos são skills sob skills/, então ele não tem pasta commands/; a invocação /apothem:<name> não muda. A divisão é determinística e reversível: o texto do SKILL.md e de seus arquivos de referência reconstrói o comando de origem sem Bindings. Os arquivos de origem, e a saída para todos os outros harnesses, não mudam. Outras ferramentas também leem skills de ~/.claude/skills/, então veem os mesmos arquivos; apothem install as nomeia.

Para ver os números de cada comando, execute o script de medição a partir de um checkout:

python scripts/dev/measure_claude_skills.py          # per-command table
python scripts/dev/measure_claude_skills.py --check  # exit 1 on a breach

Ele informa os tamanhos da origem, do SKILL.md e das referências, a folga até o orçamento e uma contagem estimada de tokens, e lista as skills nativas para comparação. research-suite, uma skill nativa cuja origem não é dividida, é a única skill acima do limite.

Notas de compatibilidadeCopy Anchor Link

Os prompts de comando são convertidos em diretórios de skill e as regras são renderizadas como descrito acima; skills e output-styles são copiados como estão, e os agentes são copiados como foram escritos, exceto que um auxiliar listado na chave agent_mcp_servers do perfil ganha uma entrada mcp__<server>__* por servidor nomeado em sua linha tools (consulte Servidores MCP). A instalação valida que o perfil está bem formado e que todas as vinculações de hook em settings.json são resolvíveis. O adaptador não cria nenhuma entrada de servidor MCP: registre os servidores com claude mcp add (consulte Servidores MCP).

~/.claude/agents/ é uma raiz compartilhada que pertence ao Claude Code, assim como ~/.claude/skills/: outras ferramentas suportadas carregam essas pastas, então os agentes e as skills que uma instalação do Claude Code grava ali também aparecem nessas ferramentas, e a instalação exibe uma nota que as nomeia. O registro de harnesses lista os leitores de cada raiz.

O Claude Code aplica todas as vinculações de hook em settings.json a cada início de sessão. Cada adaptador é verificado contra seu próprio harness nativo — não existe um harness "de referência" privilegiado.

Limites das regras de permissãoCopy Anchor Link

O template de configurações nega Read(...) em caminhos de segredos e de cache, como .env* e ~/.ssh/**. O Claude Code aplica uma negação de Read às suas ferramentas de arquivo, aos comandos de arquivo que reconhece no Bash (cat, head, tail, sed, tee) e aos alvos de redirecionamento. Ele não aplica a negação a uma busca que lê arquivos sem nomeá-los, como grep -r pattern ., nem a um script que abre arquivos por conta própria (referência de permissões). No macOS, no Linux e no WSL, o Claude Code deixa as ferramentas Glob e Grep fora do conjunto de ferramentas padrão e, em vez disso, faz as buscas pelo Bash, de modo que as entradas do template que permitem Glob e Grep só têm efeito onde essas ferramentas estão presentes. Para impedir que qualquer processo leia um caminho, habilite o sandbox do Claude Code.

As skills e as definições de auxiliares que nomeiam TodoWrite também nomeiam TaskCreate, TaskGet, TaskList e TaskUpdate, porque o Claude Code desativa TodoWrite por padrão em favor dessas ferramentas.

VerificaçãoCopy Anchor Link

apothem verify --harness claude-code

O comando verify confirma que:

1. A configuração nativa existe no caminho esperado.
2. Cada destino gerenciado existe; os arquivos gerenciados não estão vazios, e as configurações JSON ou YAML são analisadas sem erros. Adicione --profile PATH para também confirmar que os arquivos instalados correspondem a esse perfil.
3. A rotina de verificação específica do adaptador informa sucesso.

AtualizaçãoCopy Anchor Link

apothem update --harness claude-code

Deriva novamente a configuração nativa a partir do perfil compartilhado atual. Execute depois que o pacote apothem instalado for atualizado, para que a superfície de convenções propagada (agentes, regras, skills, statuslines, output-styles) reflita a nova versão. No CLAUDE.md, o update reescreve apenas o bloco do Apothem entre suas sentinelas.

DesinstalaçãoCopy Anchor Link

apothem uninstall --harness claude-code

Remove o bloco do Apothem de ~/.claude/CLAUDE.md e mantém qualquer outro texto nele. O arquivo é excluído somente quando nada mais resta nele. Remove as entradas que o adaptador adicionou a ~/.claude/settings.json (as suas próprias regras de permissão, chaves e manipuladores de hook permanecem, e o arquivo é excluído somente quando o Apothem o criou e nada seu restou). Também remove os arquivos do Apothem em ~/.claude/agents/, ~/.claude/rules/, ~/.claude/skills/, ~/.claude/statuslines/, ~/.claude/output-styles/ e ~/.claude/.apothem/support/; os demais arquivos dessas pastas permanecem. Cada arquivo recebe backup em ~/.apothem/backups/ antes de ser alterado ou removido. O pacote apothem instalado e o repositório de código-fonte não são afetados.

Conformity gateCopy Anchor Link

python -m apothem.conformity.gate --all .

Executado contra o repositório, o gate exige a seção ## Bindings em toda regra, comando, auxiliar e skill. Executado contra uma árvore ~/.claude/ instalada, ele aceita uma cópia de regra ou de skill que não tem essa seção, porque a instalação a omite, e ainda verifica uma seção que esteja presente.

Solução de problemasCopy Anchor Link

Ajustes de configuraçãoCopy Anchor Link

Veja tambémCopy Anchor Link

• Todos os harnesses — o catálogo completo de ferramentas suportadas
• Guia de instalação — instale o Apothem neste harness
• Referência de apothem harnesses — liste e inspecione adaptadores pela CLI