Comandos, Skills, Subagentes, Regras: O que aprendi organizando 139 extensões

Depois de criar 95 hooks, 44 skills, 85 comandos e 11 arquivos de regras para o Claude Code, aprendi que escolher a abstração errada desperdiça mais tempo do que construir a funcionalidade errada. Uma skill que deveria ter sido uma regra inflou meu contexto em 40%. Um comando que deveria ter sido uma skill exigia que eu lembrasse de digitar /fastapi toda vez que tocava em um endpoint de API.¹

Resumo

Claude Code oferece quatro formas de estender comportamento: Comandos (prompts disparados pelo usuário), Skills (contexto invocado automaticamente), Subagentes (executores de tarefas delegadas) e Regras (restrições sempre ativas). Depois de organizar 139 extensões, descobri que o framework de decisão é simples: Regras para invariantes, Skills para expertise de domínio, Comandos para fluxos de trabalho, Subagentes para isolamento. A parte difícil é reconhecer quando você escolheu errado e migrar.

As quatro abstrações (com exemplos reais)

Comandos: “/commit” e outros 84

Comandos são ativados quando digito /nome-do-comando. Cada um se expande em um template de prompt.²

Meus 85 comandos incluem /commit (commit git inteligente), /review (lançar agentes de revisão de código), /deploy (checklist de deploy), /publish-check (validação pré-publicação de blog) e /deliberate (pesquisa multi-agente).

O erro que cometi: Criei /fastapi como um comando que injetava padrões FastAPI sob demanda. O problema: eu esquecia de digitá-lo metade das vezes. Cada invocação esquecida significava que o agente perdia padrões que eu queria aplicados. A solução foi migrar /fastapi para uma Skill com ativação automática.

Skills: 44 módulos de conhecimento com ativação automática

Skills são ativadas automaticamente quando a conversa corresponde à descrição da skill. Eu nunca digito um comando; o sistema injeta expertise relevante com base no contexto.³

---
description: FastAPI backend development patterns and conventions
---
# FastAPI Skill
When working on FastAPI endpoints, follow these patterns...

Minhas 44 skills cobrem: - Conhecimento de domínio (8): FastAPI, SwiftUI, HTMX/Alpine, database, testing, debugging, architecture, security - Infraestrutura de blog (7): blog-writer-core, blog-evaluator, citation-verifier, SEO playbook - Filosofia/qualidade (5): Shokunin (Jiro), No Shortcuts, Rubin essence, design principles - Multi-agente (3): deliberação, revisão, criação de conteúdo - Específicas de projeto (4): conteúdo do site pessoal, blog ResumeGeni, captura Obsidian

O incidente de 40% de inflação de contexto: No início, coloquei meu guia completo de padrões FastAPI (800 linhas) em um arquivo de Regra. Regras são carregadas em todas as sessões. Quando eu trabalhava em apps iOS, CSS ou conteúdo de blog, 800 linhas de padrões FastAPI irrelevantes consumiam tokens de contexto. Mover o conteúdo para uma Skill com a descrição “FastAPI backend development” resolveu o problema: a skill só era carregada durante trabalho com API.⁴

Subagentes: revisores isolados

Subagentes rodam em sua própria janela de contexto com acesso restrito a ferramentas e permissões independentes.⁵

Meus subagentes incluem security-reviewer (acesso somente leitura, varredura de vulnerabilidades OWASP), test-runner (executa testes, analisa falhas) e conventions-reviewer (verificação de padrões do projeto).

Por que o isolamento importa: Durante a revisão de código, o revisor não deveria poder editar arquivos. Uma Skill pode injetar conhecimento de revisão, mas a revisão ainda acontece no contexto principal com permissões totais de escrita. Um Subagente impõe acesso somente leitura de forma arquitetural.

Regras: 11 arquivos de restrições sempre ativos

Regras são carregadas em toda conversa automaticamente. Meus 11 arquivos de regras cobrem:⁶

~/.claude/rules/
├── security.md        # Never commit secrets, parameterized queries
├── git-workflow.md    # Conventional commits, branch naming
├── corrections.md     # Always use Claude (not OpenAI), current date
├── quality-loop.md    # Quality review loop, pride check
├── api-design.md      # REST conventions, response format
├── testing.md         # pytest conventions, coverage targets
└── aio.md             # AI Overview optimization for web content

A lição sobre dimensionamento: Minhas regras totalizam aproximadamente 180 linhas em 11 arquivos. Cada linha é carregada em toda sessão. Originalmente eu tinha mais de 400 linhas antes de migrar conteúdo específico de tópicos para Skills. O conjunto de 180 linhas de regras cobre invariantes genuínos (restrições de segurança, fluxo de trabalho git, correções). Todo o resto pertence a Skills.

O framework de decisão

O padrão de migração

Minha estrutura .claude/ evoluiu em três fases:

Fase 1 (Mês 1-2): Tudo em Regras. Mais de 400 linhas de contexto carregado permanentemente. Padrões iOS, padrões FastAPI, diretrizes de design, padrões de teste. O contexto ficava inflado em toda sessão.

Fase 2 (Mês 3-4): Migrei conteúdo específico de tópicos para Skills. As Regras caíram para 200 linhas. As Skills cresceram para mais de 20 diretórios. A inflação de contexto caiu 40%.

Fase 3 (Mês 5+): Adicionei Subagentes para tarefas que requeriam isolamento (revisão de código, auditoria de segurança). Os Comandos se estabilizaram em 85 para fluxos de trabalho explícitos. As Skills cresceram para 44 conforme adicionei expertise específica de domínio.⁷

A lição: comece com Regras (baratas, sempre disponíveis), descubra o que é específico de tópico (migre para Skills) e adicione Subagentes somente quando precisar de isolamento.

Skills alimentando Subagentes

Um padrão poderoso: injetar Skills no contexto de Subagentes usando o campo skills no frontmatter:

---
description: Code reviewer with security expertise
allowed-tools: [Read, Grep, Glob]
skills: [security, testing-philosophy]
---
Review code for quality, security, and test coverage...

As skills security e testing-philosophy injetam seu conteúdo no prompt de sistema do subagente. O revisor recebe conhecimento especializado dentro de seu contexto isolado e somente leitura.⁸

Meu pipeline de revisão usa esse padrão: três subagentes (correctness-reviewer, security-reviewer, conventions-reviewer) recebem diferentes injeções de skills. O revisor de corretude recebe debugging-philosophy. O revisor de segurança recebe o conjunto de regras de segurança. O revisor de convenções recebe os padrões de codificação do projeto.

Minha arquitetura de produção

~/.claude/
├── commands/     # 85 — Fluxos de trabalho disparados pelo usuário
│   ├── commit.md, review.md, deploy.md
│   ├── publish-check.md, deliberate.md
│   └── morning.md, analytics.md, plan.md
│
├── skills/       # 44 — Expertise invocada automaticamente
│   ├── fastapi/, swiftui/, htmx-alpine/
│   ├── blog-writer-core/, citation-verifier/
│   └── jiro/, no-shortcuts/, rubin-essence/
│
├── agents/       # Executores de tarefas isolados
│   ├── security-reviewer.md
│   ├── correctness-reviewer.md
│   └── conventions-reviewer.md
│
├── rules/        # 11 arquivos, ~180 linhas — Restrições sempre ativas
│   ├── security.md, git-workflow.md
│   ├── corrections.md, quality-loop.md
│   └── api-design.md, testing.md, aio.md
│
└── hooks/        # 95 — Manipuladores de eventos do ciclo de vida
    ├── git-safety-guardian.sh
    ├── recursion-guard.sh
    └── blog-quality-gate.sh

Principais aprendizados

Para desenvolvedores solo: - Comece com Regras para padrões específicos do projeto (mantenha abaixo de 200 linhas no total) - Adicione Skills para suas stacks de tecnologia mais usadas; a ativação automática elimina o problema de “esqueci de invocar” - Crie Comandos para seus três fluxos de trabalho mais comuns primeiro - Adicione Subagentes somente quando precisar de restrição de ferramentas ou isolamento de contexto

Para equipes: - Padronize Regras no nível do projeto para consistência em toda a equipe - Compartilhe Skills via um repositório comum; a portabilidade das Skills entre projetos é sua principal vantagem sobre configuração no nível de projeto

Referências