ECC: um time de engenharia inteiro dentro do Claude Code, Codex e Cursor

O ECC é um complemento grátis e open source (licença MIT) que transforma o agente de código que você já usa num pequeno time de engenharia. Não é um modelo novo nem um app novo: ele se instala por cima do Claude Code, do Codex ou do Cursor e dá ao seu agente especialistas e rotinas. Um agente planeja a feature, uma skill faz ele escrever os testes antes do código, outro agente ataca o seu app procurando falhas, e um comando continua escrevendo testes até a cobertura fechar. O ECC foi criado por Affaan Mustafa e passou de 264 mil estrelas no GitHub em oito meses, mais que o React e mais que o Linux.

Antes de começar

• Claude Code 2.1 ou mais novo (claude --version), Codex ou Cursor.
• Node.js 18 ou mais novo, para o npx (node --version), e Git.
• Um projeto onde você possa experimentar. O passo a passo abaixo usou uma API Node pequena, criada só para este guia.

O que é o ECC, em palavras simples

O ECC é um harness: a camada de instruções e automação em volta do modelo. Ele adiciona quatro tipos de peça:

• Agentes (68). Especialistas para quem o seu agente passa trabalho, cada um com as próprias instruções e ferramentas: planner, tdd-guide, security-reviewer, code-reviewer, build-error-resolver e revisores de Python, Go, Rust, React e outros.
• Skills (292). Manuais que o agente lê quando a tarefa combina: desenvolvimento guiado por testes, revisão de segurança, testes de ponta a ponta, design de API, e muitos pacotes de áreas que você nunca vai usar.
• Hooks. Pequenos scripts que rodam sozinhos antes ou depois de o agente agir: checagens de qualidade depois de uma edição, checagens de segurança antes de um comando no terminal, um resumo da sessão quando você para.
• Regras. Padrões sempre ativos, por linguagem. O plugin do Claude não consegue instalar isso; você copia só os pacotes que quiser.

Ele traz também memória entre sessões, aprendizado contínuo e o AgentShield, um scanner da configuração do próprio agente.

Seja honesto sobre o tamanho. 68 agentes e 292 skills é muita coisa. No plugin do Claude Code, o claude plugin details ecc@ecc mostra cerca de 41.500 tokens de contexto somados a toda sessão. O próprio README do ECC diz para começar pelo fluxo de que você precisa, não pelo catálogo inteiro. Este guia faz exatamente isso: quatro comandos, um para cada papel.

1

Instale o ECC no Claude Code

No terminal, rode a instalação guiada:

TerminalCopiar

npx ecc-universal@2.2.1 setup

Na primeira vez, o npx pede para baixar o ecc-universal; responda y. Depois o assistente procura instalações anteriores e faz duas perguntas:

1. Where should Claude enable ecc@ecc? (onde ativar). Global user deixa disponível em todos os projetos. Shared project grava nas configurações do repositório, para o time. Private project ativa só aqui, sem commitar a escolha. Na dúvida, escolha 1.
2. How should ECC hooks run? (como os hooks rodam). Off, Minimal, Standard (o padrão) ou Strict. Mais sobre isso abaixo; Standard é um bom começo.

Confirme com y e reinicie o Claude Code, ou rode /reload-plugins.

Confira dentro do Claude Code:

Claude CodeCopiar

/plugin list ecc@ecc

Por que 2.2.1 e não 2.2.2? O README do ECC mostra hoje ecc-universal@2.2.2, mas essa versão ainda não foi publicada no npm, então o comando falha. O 2.2.1 é o que o npm entrega. Se o npx reclamar de versão, npm view ecc-universal version mostra a atual.

Prefere os comandos do próprio Claude Code? Dentro dele, /plugin marketplace add https://github.com/affaan-m/ECC e depois /plugin install ecc@ecc instalam o mesmo plugin. Escolha um caminho só. Nunca rode o ./install.sh --profile full do ECC por cima do plugin: instalar duas vezes duplica skills e faz os hooks dispararem em dobro.

Quer mais leve? npx ecc-universal@2.2.1 install --profile minimal --target claude instala as regras, os agentes e os fluxos principais sem nenhum hook.

Depois de instalado, /ecc:configure-ecc dentro do Claude Code reabre a mesma configuração em forma de conversa.

codex plugin marketplace add affaan-m/ECC

codex plugin add ecc@ecc

git clone https://github.com/affaan-m/ECC.git && cd ECC

./install.sh --profile minimal --target cursor

3

Planeje a feature antes de qualquer código

Abra o Claude Code no seu projeto e descreva a feature:

Claude CodeCopiar

/ecc:plan "Deixar o usuário apagar as próprias notas: DELETE /notes/:id, só o dono pode apagar, 404 se a nota não existir"

O planner repete o que você pediu, lê o código atrás de padrões para seguir, quebra o trabalho em passos, lista os riscos com a gravidade de cada um e então para e espera você responder "yes" (ou "modify: …"). Nada é escrito antes de você confirmar.

Instalações pelo plugin usam o prefixo /ecc:. Se você instalou o ECC à mão, pode ser que tenha a forma curta (/plan).

4

Escreva com os testes primeiro

Responda ao plano e peça a skill tdd-workflow:

Copiar

yes. Use a skill tdd-workflow: escreva primeiro os testes que falham, depois o código.

A skill passa o trabalho para o agente tdd-guide, que escreve os testes, roda e vê eles falharem pelo motivo certo, escreve o menor código que faz passar, e mira 80% de cobertura ou mais.

Atenção: ela faz commit. Num repositório Git a skill cria um commit de checkpoint depois de cada etapa (testes falhando, depois código passando), e neste teste ela trabalhou num branch novo. Nada é enviado para o remoto. Comece com a árvore de trabalho limpa para esses commits conterem só essa mudança.

5

Ataque o seu próprio app, depois a configuração do agente

Este é o "ataca o seu próprio app antes do invasor" do reel. Peça o revisor de segurança:

Copiar

Use o agente security-reviewer para revisar src/ atrás de vulnerabilidades. Liste o que achar por gravidade; não mude nenhum código ainda.

O agente security-reviewer procura segredos no código, injeção, SSRF, criptografia insegura e o OWASP Top 10 e, quando consegue, prova o problema. Na API de exemplo ele mandou ?file=../../../../etc/hosts para a rota de exportação e leu arquivos fora da pasta.

Depois escaneie o próprio agente:

Claude CodeCopiar

/ecc:security-scan

O /security-scan roda o AgentShield na configuração do seu agente, não no app: permissões no .claude/settings.json, hooks, servidores MCP e segredos. A configuração do agente também é superfície de ataque. No exemplo ele pegou uma chave de API commitada no arquivo de configurações, uma regra Bash(*) que libera tudo sem lista de bloqueio, e um servidor MCP instalado com @latest, sem versão fixa.

6

Teste até a cobertura fechar

Claude CodeCopiar

/ecc:test-coverage

Ele roda a ferramenta de cobertura, lista cada arquivo abaixo de 80%, escreve os testes que faltam (caminho feliz, erros, casos extremos, desvios), roda a suíte inteira de novo e mostra uma tabela de antes e depois. Para fluxos de usuário num navegador de verdade, peça a skill e2e-testing, que usa o agente e2e-runner com Playwright.

Outras entradas que valem conhecer: /ecc:code-review (uma revisão das suas mudanças com contexto limpo), /ecc:build-fix (conserta um build quebrado com mudanças pequenas), /ecc:refactor-clean (tira código morto), /ecc:context-budget (mostra o que está comendo o seu contexto), e /ecc:save-session, /ecc:resume-session e /ecc:learn-eval para trabalhos longos, de vários dias.

Atualizar, ajustar os hooks, desinstalar

Atualizar. Rode o mesmo comando de instalação de novo. Ele atualiza o plugin onde ele está, e é também como você muda o escopo ou o perfil de hooks:

npx ecc-universal@2.2.1 setup

No Codex: codex plugin marketplace upgrade ecc, depois codex plugin add ecc@ecc.

Perfis de hook. Hooks são código que roda na sua máquina sem perguntar, então escolha de propósito:

• Minimal: só os hooks essenciais de ciclo de vida e segurança.
• Standard (padrão): checagens de qualidade e segurança, incluindo o GateGuard (abaixo).
• Strict: lembretes extras e proteções mais rígidas.
• Off: só skills e comandos, sem automação de hooks.

ECC_HOOK_PROFILE e ECC_DISABLED_HOOKS deixam você mudar isso por sessão sem rodar a instalação de novo. A lista completa de hooks está no hooks/README.md do repositório.

Desinstalar. Para o plugin do Claude Code:

claude plugin uninstall ecc@ecc

Adicione --scope project ou --scope local se instalou lá, e apague as pastas de regras que você copiou à mão. Se instalou com install --profile … em vez do plugin, veja o que sai e remova da mesma pasta com npx ecc-universal@2.2.1 uninstall --dry-run e npx ecc-universal@2.2.1 uninstall; list-installed, doctor e repair também ficam ali.

Problemas comuns

• O agente para e pede "fatos" antes de um comando ou de uma edição. É o GateGuard, que vem nos perfis Standard e Strict. Antes do primeiro comando de terminal da sessão, e da primeira edição ou arquivo novo, ele faz o agente dizer o que você pediu e o que a ação vai fazer; comandos destrutivos (apagar pastas, resets forçados) são checados sempre. Parece chato e quase nunca é: faz o agente olhar antes de digitar. Para afrouxar, GATEGUARD_BASH_ROUTINE_DISABLED=1 pula a checagem de rotina do terminal, GATEGUARD_EXEMPT_GLOBS pula caminhos como **/tests/**, e ECC_GATEGUARD=off desliga na sessão. O perfil Minimal não inclui o GateGuard.
• npx ecc-universal@2.2.2 falha com E404. Essa versão ainda não está no npm. Use @2.2.1, ou veja a atual com npm view ecc-universal version.
• npx ecc-install não funciona. O ecc-install é um programa dentro do ecc-universal, não um pacote próprio. Use os comandos npx ecc-universal@… acima.
• Skills aparecem duplicadas ou hooks disparam duas vezes. Você empilhou dois métodos de instalação. Desinstale o plugin, rode o uninstall --dry-run acima e reinstale uma vez só.
• /ecc:plan não é encontrado. Reinicie o Claude Code ou rode /reload-plugins, e confira /plugin list ecc@ecc. Instalações manuais podem usar /plan.
• As sessões ficaram lentas ou caras. É o contexto sempre ativo. Escolha o perfil Minimal ou a instalação sem hooks, e rode /ecc:context-budget.

O ECC é open source sob a licença MIT, criado por Affaan Mustafa com centenas de colaboradores: github.com/affaan-m/ECC. O repositório tem mais para ler (em inglês): the-shortform-guide.md (o autor diz para ler primeiro), the-longform-guide.md, the-security-guide.md, TROUBLESHOOTING.md e COMMANDS-QUICK-REF.md. O projeto open source é grátis; o ECC Pro, um GitHub App hospedado para repositórios privados, é pago. Comandos conferidos em 21 de setembro de 2026 com o ecc-universal 2.2.1 e o plugin 2.2.2.