🔷 Anatomia do Claude Code

Markdown que o Claude Code injeta no system prompt. Existe em três níveis: ~/.claude/CLAUDE.md (global), ./CLAUDE.md (raiz do projeto) e subdir/CLAUDE.md (escopo de pasta). Tudo é concatenado em ordem.

Errar a hierarquia faz instrução de projeto sobrescrever global sem você perceber. Ou pior: instrução global sufocando preferência específica do projeto.

User CLAUDE.md vs project CLAUDE.md, precedência, "instruções diretas têm precedência sobre tudo", tamanho ideal (<2KB), comandos de build/test no topo.

Pasta com convenção fixa: agents/ (sub-agents .md), skills/ (pastas com SKILL.md), commands/ (slash commands), settings.json, settings.local.json, hooks/.

Quem não conhece a estrutura coloca arquivo no lugar errado e o Claude simplesmente não enxerga. A convenção é rígida: nome certo, pasta certa, ou não funciona.

Convention over configuration, gitignore parcial, separação user vs projeto (mesma estrutura em ~/.claude/ e ./.claude/).

Arquivo JSON com configuração comportamental: permissões (allow/deny por tool), modelo padrão, variáveis de ambiente, hooks, includeCoAuthoredBy, theme, statusLine.

É onde você reduz fricção de permissão (auto-allow comandos comuns), troca modelo (Haiku pra task rápida), e injeta hooks de evento.

Permissões via regex/glob, settings.local.json (não vai pro git), env vars com prefixo CLAUDE_, override em cascata user → project → local.

Shell commands disparados pelo harness em eventos do agente: antes/depois de tool use, ao parar, ao receber prompt, no startup da sessão. Eles RODAM, não dependem do Claude lembrar.

É a única forma de garantir comportamento determinístico ("sempre rodar lint antes de commitar"). Memory/prompt não bastam — Claude pode esquecer. Hook não esquece.

Eventos suportados (PreToolUse, PostToolUse, Stop, SessionStart, UserPromptSubmit), matchers por tool name, exit code 0/non-0, fail-open vs fail-close.

Arquivos markdown em .claude/commands/ que viram comandos slash. O nome do arquivo vira o comando (review.md → /review). Recebem argumentos opcionais ($ARGUMENTS).

Tarefas que você repete viram um comando único. Comitar com mensagem padronizada, abrir PR, gerar changelog — tudo virou um slash.

Frontmatter com description e allowed-tools, namespace global vs projeto, $ARGUMENTS e $1/$2, encadeamento com bash backtick-bang.

Regras em settings.json que controlam quais tools/comandos o Claude pode rodar sem perguntar. Três níveis: allow (libera), deny (bloqueia), ask (pergunta cada vez).

Permissão mal configurada vira fricção (perguntar pra tudo) ou risco (liberar demais). O equilíbrio é liberar leitura/análise, pedir confirmação pra escrita/destrutivo.

Padrão glob (Bash(ls:*), Bash(git status:*)), modos de permissão (default, acceptEdits, plan, bypassPermissions), MCP allowlist (mcp__servidor).

Plan mode é um modo onde Claude planeja sem editar, ideal para refactor grande. Output styles trocam o tom de resposta (verbose, concise, explanatory). Ambos ajustam comportamento sem mudar prompt.

Tarefa complexa começando? Plan mode primeiro, depois execução. Quer respostas curtas? Output style concise. Detalhes? explanatory. É fricção zero pra mudar tom.

/plan, /output-style, customização via .claude/output-styles/*.md, isolamento de modo por sessão.

Pasta em .claude/skills/<nome>/ contendo SKILL.md (com frontmatter YAML: name, description, opcional allowed-tools), e subpastas convencionais scripts/, references/, assets/.

É o jeito moderno de empacotar comportamento. Mais limpo que inflar CLAUDE.md, mais reusável que slash command, ativado por descrição em vez de invocação manual.

Frontmatter mínimo (name + description), tamanho ideal do body, references como deep-dive lazy-loaded, scripts pra ações determinísticas.

O campo description do frontmatter é o que o agente usa pra decidir se invoca a skill. Descrição vaga = skill ignorada. Descrição com gatilhos certos = skill ativada na hora.

A maior causa de skill "não funcionar" é description ruim. Não é bug, é match semântico falhando. Tem padrões claros que funcionam (use when..., trigger phrases, examples).

"Use when X" pattern, listar trigger phrases reais do usuário, exemplos diretos, evitar redundância com nome.

Arquivos em .claude/agents/<nome>.md: frontmatter (name, description, tools, model) + corpo com system prompt da persona. Claude principal delega tarefa via Task tool, sub-agent roda isolado.

Sub-agent isola contexto (não polui o do principal), pode rodar em paralelo, e é como você ganha especialistas (code-reviewer, security-auditor, etc.) sem prompt enorme.

Auto-dispatch via description, paralelismo (vários sub-agents simultâneos), restrição de tools por sub-agent, modelo dedicado (Haiku pra busca, Opus pra análise).

Conectar Claude a serviços externos via Model Context Protocol. Server declarado em .mcp.json (projeto) ou ~/.claude.json (global). Ferramentas viram mcp__server__tool.

MCP é o jeito de dar superpoder ao Claude: acesso a Slack, Gmail, GitHub, banco de dados, sem precisar implementar tool customizada.

stdio vs HTTP transport, allowlist ("enabledMcpjsonServers": [...]), discovery de tools, env vars/secrets via variável.

Sintaxe específica do Claude Code: dentro de SKILL.md ou commands, código entre crase-bang (`!cmd`) é executado pelo shell e o resultado entra no prompt. Codex não suporta.

É o jeito de fazer skill dinâmica: "ler o último log", "listar branches", "pegar versão atual" — sem precisar de tool call adicional. Mas é uma feature exclusiva — atenção ao portar.

Execução em build-time da skill, security implications (não interpolar input não-confiável), polyskill converte em prosa de fallback no Codex.

Campos no frontmatter da skill: disable-model-invocation impede auto-trigger (só roda quando invocada explicitamente); allowed-tools restringe quais ferramentas a skill pode usar.

Skills perigosas (que rodam destrutivos) precisam de invocação explícita. Skills focadas devem ter tool surface restrita pra evitar surpresas.

Princípio do menor privilégio, opt-in invocation, allowlist de tools, model override (rodar skill com Haiku pra economia).

Claude Code suporta plugins (pacote com skills + agents + commands + hooks) instaláveis via marketplace. Cada plugin pode ter namespace próprio (plugin:skill-name).

É como você consome trabalho dos outros (claude-mem, context-mode, superpowers etc.) e como publica o seu. Distribuição padronizada.

plugin.json manifest, marketplace.json, namespace plugin:skill, versioning (npm-style), atualização via /plugins.