ECC Everything Claude Code: Guia Completo da Ferramenta que Organiza Agentes, Skills, Hooks e IA para Programar Melhor

ECC, sigla usada para Everything Claude Code, é uma camada de organização para desenvolvimento com agentes de Inteligência Artificial. A ferramenta reúne agentes especializados, skills, comandos, hooks, regras, integração com MCP, memória operacional e auditoria de segurança em um conjunto pensado para projetos reais de software.

O objetivo central do ECC é transformar o uso de IA para programação em um processo mais previsível. Em vez de depender apenas de conversas soltas com um modelo, o projeto cria uma base de trabalho com padrões, verificações e fluxos reutilizáveis. Isso ajuda em tarefas como planejar funcionalidades, escrever testes, revisar código, corrigir builds, aplicar segurança e manter contexto entre sessões.

Resumo didático do ECC

O ECC pode ser entendido como um sistema operacional de trabalho para agentes de programação. Ele não substitui o Claude Code, o Codex, o Cursor ou o OpenCode. Ele adiciona uma camada de organização acima dessas ferramentas, com instruções, automações e padrões prontos para uso.

Essa diferença é importante porque um agente de IA, sozinho, pode responder bem em uma conversa curta, mas perder consistência em projetos longos. Em um sistema real, existe arquitetura, banco de dados, autenticação, deploy, testes, segurança, padrões de escrita e histórico de decisões. O ECC tenta reduzir essa perda de consistência com componentes reaproveitáveis.

O repositório oficial descreve o ECC como um sistema de otimização de performance para harnesses de agentes. A palavra harness significa o ambiente que executa o agente, fornece ferramentas e controla permissões. Claude Code, Codex, Cursor e OpenCode são exemplos de superfícies onde esse tipo de trabalho pode acontecer.

Em termos simples, o ECC organiza três coisas: o que o agente deve saber, como o agente deve trabalhar e quais verificações devem acontecer antes de aceitar uma mudança. O resultado não é uma promessa de código perfeito. O resultado é um fluxo mais disciplinado, auditável e fácil de repetir.

O problema que o ECC tenta resolver

Projetos com IA costumam começar bem e ficar confusos com o passar do tempo. A conversa cresce, o contexto fica pesado, decisões antigas se misturam com novas e o agente pode esquecer regras importantes. Esse problema é conhecido como perda ou degradação de contexto.

Outro problema comum é a falta de processo. Uma pessoa pede uma funcionalidade, o agente escreve código, mas não cria testes, não valida segurança, não confere tipos e não verifica se o projeto ainda compila. O código pode parecer bom em um trecho isolado, mas quebrar quando entra no sistema inteiro.

A lista abaixo mostra as dores mais comuns em projetos reais que usam IA para programar:

• Repetição das mesmas instruções a cada nova conversa.
• Perda de contexto quando uma tarefa é retomada depois de algumas horas ou dias.
• Código criado sem teste automatizado.
• Rotas de API sem validação adequada de entrada.
• Inconsistência entre arquivos TypeScript, Python, Django, FastAPI, React ou banco de dados.
• Uso de padrões diferentes por cada pessoa da equipe.
• Falta de auditoria sobre permissões, hooks, MCPs e segredos.
• Risco de aceitar uma alteração antes de rodar build, lint, typecheck e testes.

O ECC resolve essas dores criando uma biblioteca de práticas. Agentes cuidam de tarefas específicas, skills descrevem fluxos completos, rules definem padrões permanentes e hooks executam verificações automáticas. O AgentShield entra como camada de auditoria de segurança para configurações de agentes.

Termos essenciais antes de entender a ferramenta

Alguns termos aparecem muitas vezes na documentação do ECC. A compreensão desses termos facilita o entendimento da ferramenta inteira. As definições abaixo usam linguagem simples e evitam jargões desnecessários.

• Agente: uma IA especializada em um tipo de tarefa, como revisar código, planejar arquitetura ou procurar falhas de segurança.
• Skill: um pacote de instruções e, às vezes, scripts auxiliares, que ensina o agente a executar um fluxo de trabalho específico.
• Hook: uma automação disparada em algum evento, como antes de executar um comando, depois de editar um arquivo ou no início de uma sessão.
• Rule: uma regra permanente carregada no contexto do agente, como padrões de código, segurança e testes.
• MCP: Model Context Protocol, um padrão de integração que permite conectar o agente a ferramentas, documentação, GitHub, navegador, memória e outros serviços.
• Harness: o ambiente que executa o agente, controla ferramentas e decide como arquivos, comandos e permissões serão usados.
• Contexto: o conjunto de informações que o agente consegue considerar durante a tarefa.
• Instinct: um padrão aprendido pelo sistema de aprendizado contínuo, usado para reaproveitar preferências e decisões recorrentes.

O que o ECC é e o que ele não é

O ECC é uma coleção de componentes para tornar o desenvolvimento com agentes mais organizado. Ele inclui arquivos Markdown, configurações, scripts, comandos, regras e documentação. A ferramenta não é um modelo de IA novo e não é uma IDE completa.

Também não é uma garantia de que o agente sempre criará código correto. O ECC cria um processo melhor, mas a validação humana e os testes continuam importantes. Em projetos profissionais, a função do ECC é reduzir erros repetitivos, não eliminar responsabilidade técnica.

A comparação abaixo ajuda a separar o que pertence ao ECC e o que pertence ao agente base:

• O modelo de IA entende linguagem natural, escreve código e analisa arquivos.
• O harness, como Claude Code ou Codex, fornece terminal, edição de arquivos, permissões e sessão.
• O ECC adiciona agentes especializados, skills, regras, hooks, memória e auditoria.
• O projeto real fornece código, testes, banco de dados, deploy, regras de negócio e histórico.

A história do ECC

O ECC ganhou atenção por estar ligado ao trabalho de Affaan Mustafa, criador do projeto. Materiais públicos associam a origem do conjunto de práticas a um hackathon da Anthropic em Nova York, no qual um produto foi criado rapidamente com Claude Code. Depois disso, a configuração usada em trabalho diário foi evoluindo e acabou aberta em forma de repositório.

A documentação oficial afirma que o conjunto evoluiu durante mais de dez meses de uso intenso na construção de produtos reais. Essa informação ajuda a entender o estilo do projeto. O ECC não nasceu apenas como uma lista decorativa de prompts, mas como uma tentativa de transformar uma rotina prática em infraestrutura reutilizável.

No começo, o foco público era muito ligado ao Claude Code. Com o tempo, o projeto passou a falar em suporte para outros harnesses. A versão 2.0.0-rc.1 reforça essa mudança ao apresentar o ECC como uma base portável para Claude Code, Codex, OpenCode, Cursor, Gemini, Zed, GitHub Copilot e fluxos relacionados.

Essa evolução mostra uma mudança de mentalidade. A pergunta inicial era como melhorar o Claude Code. A pergunta mais recente é como manter workflows de engenharia consistentes mesmo quando a equipe muda de agente, editor ou plataforma.

Linha do tempo do projeto

A linha do tempo abaixo resume marcos importantes citados em fontes públicas e na documentação do projeto. Os números mudam rapidamente, porque o repositório está em desenvolvimento ativo.

• Setembro de 2025: fontes públicas descrevem a origem do projeto a partir de um hackathon ligado à Anthropic e Forum Ventures.
• Janeiro e fevereiro de 2026: o projeto passa a circular como coleção popular de configurações, agentes, comandos e skills para Claude Code.
• Fevereiro de 2026: a documentação registra versões com suporte a Python, Django, Java Spring Boot, gerenciamento de sessão e aprendizado contínuo.
• Fevereiro de 2026: a versão v1.3.0 registra integração com OpenCode, comandos e ferramentas nativas do ecossistema.
• Março de 2026: materiais públicos descrevem crescimento acelerado, suporte a mais linguagens e ampliação de agentes, skills e comandos.
• Abril de 2026: discussões do repositório registram ajustes entre releases do GitHub e publicação no npm, mostrando que as superfícies públicas nem sempre andam no mesmo ritmo.
• Maio de 2026: issues recentes mostram refinamentos em instalação, aprendizado contínuo, isolamento por projeto e compatibilidade com setups mistos.
• Maio de 2026: a versão 2.0.0-rc.1 consolida a direção de sistema cross-harness, isto é, uma base reutilizável para várias ferramentas de agente.

Notícias e movimentos recentes sobre o projeto

As notícias recentes mostram que o ECC saiu do campo de “configuração pessoal” e passou a ser tratado como um projeto de engenharia mais amplo. Artigos técnicos recentes descrevem o ECC como uma plataforma de engenharia com agentes, skills, comandos e scanner de segurança. Essa leitura combina com a própria documentação oficial, que fala em skills, hooks, regras, MCPs e disciplina operacional.

Outro movimento importante é a ligação com o ECC Tools. O ECC OSS continua como repositório aberto e gratuito, enquanto o ECC Tools aparece como camada adicional com GitHub App, geração de skills a partir do histórico do repositório e recursos para times. A separação é relevante porque o núcleo aberto pode ser usado localmente, enquanto a automação hospedada é opcional.

Também existem sinais de maturidade e atrito. Issues recentes indicam problemas com instalações duplicadas, fallback de scripts, separação de instincts por projeto e compatibilidade com diferentes ambientes. Isso não torna o projeto ruim, mas mostra que o crescimento rápido trouxe complexidade real.

O cenário ao redor também mudou. Ferramentas como OpenClaw, Claude Code Channels, Codex, Cursor, OpenCode e integrações do GitHub indicam que agentes de programação estão se tornando parte do fluxo normal de desenvolvimento. O ECC entra nesse cenário como uma camada de padronização, não como a única forma possível de usar IA para código.

Arquitetura geral do ECC

A arquitetura do ECC pode ser dividida em duas camadas. A primeira camada fica no ambiente global da pessoa ou da ferramenta, como pastas dentro de ~/.claude, .codex, .cursor ou .opencode. A segunda camada fica dentro do projeto, com arquivos de contexto e regras específicas daquele repositório.

Essa divisão evita misturar todos os padrões em todos os projetos. Um pacote comum pode viver no ambiente global, enquanto o projeto define seus próprios detalhes, como framework, comandos de teste, banco de dados, limites de cobertura e política de segurança.

O esquema abaixo mostra uma visão simplificada dessa separação:

Camada global: componentes reaproveitáveis do ECC, como agentes, skills, comandos, hooks, regras e scripts.

Camada do projeto: arquivos como CLAUDE.md, AGENTS.md, configurações de harness, regras locais, comandos de build e detalhes da aplicação.

Camada do código: aplicação real, testes, migrations, rotas, componentes, modelos, schemas, scripts e documentação interna.

A vantagem dessa arquitetura é a portabilidade. Um time pode manter regras comuns e adaptar detalhes por projeto. Uma aplicação TypeScript não precisa carregar todos os padrões de Python, e uma API Django não precisa carregar instruções específicas de React se elas não forem usadas.

Principais componentes do ECC

O ECC junta várias peças que normalmente ficam espalhadas. O valor da ferramenta não está em uma peça isolada, mas na combinação delas em um fluxo coerente. A lista abaixo apresenta os componentes principais.

• Agents: especialistas para planejamento, arquitetura, revisão, segurança, testes e linguagens específicas.
• Skills: fluxos reutilizáveis para TDD, padrões de backend, padrões de frontend, segurança, documentação, banco de dados e pesquisa antes de codar.
• Commands: entradas rápidas por barra, como planejar, revisar, corrigir build e atualizar documentação.
• Hooks: automações acionadas por eventos, como edição de arquivo, execução de ferramenta, início de sessão e encerramento.
• Rules: regras permanentes por linguagem e por projeto.
• MCP configs: integração com servidores e ferramentas externas por Model Context Protocol.
• Continuous learning: aprendizado de padrões recorrentes por meio de instincts.
• AgentShield: auditoria de segurança para configurações de agentes, hooks, MCPs e permissões.

Agentes especializados

Agentes são especialistas com escopo limitado. Em vez de uma única conversa tentar fazer tudo, um subagente pode ser acionado para uma tarefa específica. Isso reduz confusão porque cada agente tem ferramentas, objetivo e comportamento próprios.

Um agente de planejamento, por exemplo, pode ter apenas ferramentas de leitura. Isso impede alterações no código durante uma fase em que a tarefa ainda é entender o problema. Já um agente de revisão pode procurar problemas de manutenção, segurança, duplicação e testes ausentes.

A documentação descreve agentes como arquivos Markdown com frontmatter YAML. Esse frontmatter define nome, descrição, ferramentas permitidas, modelo usado e instruções. O exemplo abaixo mostra a estrutura conceitual de um agente:

---
nome: revisor_codigo
descricao: revisa qualidade, seguranca e manutencao antes do merge
ferramentas: ["Read", "Grep", "Glob", "Bash"]
modelo: opus
---

Este agente revisa alteracoes de codigo com foco em testes, seguranca,
legibilidade, padroes do projeto e riscos de regressao.

Na prática, agentes ajudam quando a tarefa é grande demais para uma única resposta. Planejamento, arquitetura, revisão de segurança e depuração de build são exemplos naturais. O uso de agentes também facilita a divisão entre análise e execução.

Skills como superfície principal de trabalho

Skills são pacotes de conhecimento e fluxo de trabalho. Elas indicam como executar uma tarefa do começo ao fim, quais critérios verificar e quais arquivos consultar. Na direção mais recente do ECC, skills são tratadas como a superfície principal, enquanto comandos legados continuam existindo para compatibilidade.

Uma skill de TDD, por exemplo, pode exigir primeiro a definição da interface, depois um teste que falha, depois a implementação mínima, depois a melhoria do código e, por fim, a verificação de cobertura. Esse roteiro evita que o agente pule direto para o código final sem validação.

A lista abaixo mostra exemplos de tipos de skills úteis em projetos reais:

• tdd-workflow: conduz desenvolvimento guiado por testes.
• backend-patterns: organiza APIs, cache, banco de dados e respostas de erro.
• api-design: padroniza REST, paginação, validação e códigos HTTP.
• database-migrations: orienta alterações de schema em Prisma, Drizzle, Django e outras stacks.
• security-review: aplica checklist de segurança antes de produção.
• search-first: força pesquisa antes de implementar algo incerto.
• coding-standards: mantém padrões gerais de escrita e organização.

Comandos de barra

Comandos de barra são atalhos usados dentro do harness. Eles ajudam a chamar fluxos comuns sem escrever uma explicação longa. Em instalações por plugin, a forma namespaced aparece como /ecc:plan; em instalações manuais, nomes curtos podem continuar disponíveis.

Os comandos abaixo representam fluxos comuns que aparecem na documentação e no uso prático do ECC:

# planeja uma funcionalidade antes de alterar arquivos
/ecc:plan "adicionar comentarios nos posts com moderacao e validacao"

# revisa qualidade, manutencao e riscos antes do merge
/code-review

# procura problemas de seguranca em entradas, permissoes e segredos
/security-scan

# analisa erro de build e propõe correcao validavel
/build-fix

# registra um padrao aprendido durante a sessao
/learn "padrao de validacao de comentarios com limite de tamanho"

O uso de comandos não elimina a necessidade de revisar. Eles apenas padronizam o início de cada fluxo. A execução correta continua dependendo dos testes, da leitura dos diffs e das regras do projeto.

Hooks como automação de disciplina

Hooks são automações disparadas por eventos. Um hook pode rodar antes de uma ferramenta ser usada, depois de um arquivo ser editado ou no início de uma sessão. Em desenvolvimento com IA, hooks funcionam como guardrails, ou seja, trilhos de segurança e organização.

Um hook pode avisar quando um arquivo TypeScript contém console.log, pode rodar formatter depois de uma edição ou pode bloquear comandos perigosos. Também pode carregar contexto quando uma sessão começa ou salvar resumo quando ela termina.

O exemplo abaixo mostra uma ideia simples de hook que avisa sobre uso de console.log em arquivos JavaScript e TypeScript:

{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
  "hooks": [
    {
      "type": "command",
      "command": "#!/bin/bash\ngrep -n 'console\\.log' \"$file_path\" && echo '[Hook] remover console.log antes do commit' >&2"
    }
  ]
}

Hooks precisam de cuidado. Uma instalação duplicada pode executar a mesma automação mais de uma vez. Um hook muito agressivo pode atrapalhar a produtividade. Por isso, a documentação recomenda escolher apenas um caminho de instalação e ativar hooks com consciência.

Rules como regras permanentes

Rules são regras carregadas para orientar o agente durante as sessões. Elas podem ser comuns a todos os projetos ou específicas por linguagem. O ECC separa regras comuns de regras para TypeScript, Python, Go, Swift, PHP e outros ecossistemas.

Uma regra comum pode exigir testes antes de finalizar. Uma regra de Python pode reforçar tipagem, Pytest, PEP 8, validação e tratamento de exceções. Uma regra de TypeScript pode exigir modo estrito, validação com Zod, lint e testes de unidade.

A estrutura abaixo mostra uma organização conceitual de rules:

rules/
  common/          # principios universais do projeto
  typescript/      # padroes para ts, js, node, react e next
  python/          # padroes para fastapi, django, pytest e typing
  golang/          # padroes para go
  swift/           # padroes para swift
  php/             # padroes para php

A regra prática é copiar apenas as rules necessárias. Copiar todas as linguagens aumenta contexto sem necessidade. Um projeto FastAPI precisa de common e python; um projeto Next.js precisa de common e typescript; um monorepo pode precisar de mais pastas, mas ainda deve carregar apenas o necessário.

MCP e integração com ferramentas externas

MCP significa Model Context Protocol. É um padrão usado para conectar agentes a ferramentas externas, como GitHub, documentação, navegador, memória e bancos de dados. No ECC, configurações MCP aparecem como parte do ecossistema de automação.

O MCP é útil porque um agente de programação muitas vezes precisa de mais do que arquivos locais. Ele pode precisar consultar uma issue, abrir documentação atualizada, verificar uma API, pesquisar um erro ou usar automação de navegador. O MCP fornece uma forma padronizada de expor essas ferramentas.

Ao mesmo tempo, MCP aumenta a superfície de risco. Uma conexão mal configurada pode expor dados, permissões ou segredos. Por isso, o ECC trata MCP como parte das verificações de segurança e o AgentShield audita riscos nesse tipo de configuração.

Em ambientes de equipe, MCP deve ser configurado por projeto e com permissões mínimas. Uma ferramenta de leitura não deve receber permissão de escrita se a tarefa exige apenas consulta. Essa mentalidade reduz impacto em caso de erro ou prompt injection.

Memória, sessões e aprendizado contínuo

Memória entre sessões é uma das ideias mais importantes do ECC. Em projetos longos, o trabalho raramente termina em uma única conversa. O ECC tenta salvar informações úteis ao final de uma sessão e restaurar contexto relevante na próxima abertura.

O sistema de aprendizado contínuo usa instincts. Um instinct é um padrão observado, como uma preferência de arquitetura, estilo de validação, política de testes ou forma de organizar arquivos. A ideia é transformar repetição em conhecimento reutilizável.

Os comandos abaixo mostram operações comuns de inspeção e compartilhamento de instincts:

# mostra padroes aprendidos e niveis de confianca
/instinct-status

# exporta padroes para compartilhamento ou revisao
/instinct-export

# importa padroes revisados de outro ambiente
/instinct-import padroes.json

# agrupa padroes relacionados em skills mais formais
/evolve

Esse recurso exige cuidado em monorepos, worktrees e projetos diferentes. Issues públicas recentes mostram debates sobre isolamento por projeto e fragmentação de registros. A recomendação técnica é manter padrões por projeto e revisar o que foi aprendido antes de compartilhar com equipe.

Research-first development

Research-first development significa pesquisar antes de implementar quando existe incerteza. Em projetos modernos, bibliotecas mudam, APIs evoluem e exemplos antigos podem estar errados. O ECC inclui esse princípio para reduzir decisões baseadas em memória desatualizada.

Na prática, isso significa que o agente deve confirmar documentação, versões e comportamento antes de escrever código dependente de ferramenta externa. Isso é especialmente importante em frameworks, SDKs, integrações de pagamento, bibliotecas de autenticação e APIs de nuvem.

O fluxo abaixo mostra como uma equipe pode expressar esse comportamento em uma tarefa:

# pesquisa antes de alterar integracao dependente de versao
/ecc:plan "atualizar autenticacao jwt no fastapi confirmando versoes atuais e riscos de seguranca"

# aplica verificacao de seguranca antes de aceitar a mudanca
/security-scan

# executa gate de qualidade antes do merge
/quality-gate

Esse princípio é um diferencial porque combate o “vibe coding” sem verificação. A IA continua ajudando a escrever código, mas a decisão passa por pesquisa, teste e revisão.

AgentShield como auditor de segurança

AgentShield é a camada de segurança associada ao ECC. Ele audita configurações de agentes e procura vulnerabilidades, más configurações, segredos expostos e riscos de injeção. A documentação descreve verificação em categorias como secrets, permissões, hooks, MCPs e configurações de agentes.

Essa auditoria é relevante porque agentes de código podem editar arquivos, executar comandos e acessar ferramentas. Um arquivo de configuração mal escrito pode dar permissões demais. Um hook inseguro pode permitir command injection. Um MCP muito amplo pode expor recursos que deveriam ficar restritos.

Os comandos abaixo mostram formas comuns de uso do AgentShield:

# faz uma varredura rapida sem instalacao global
npx ecc-agentshield scan

# corrige automaticamente apenas problemas considerados seguros
npx ecc-agentshield scan --fix

# faz analise profunda com agentes especializados
npx ecc-agentshield scan --opus --stream

# gera configuracao segura inicial
npx ecc-agentshield init

# produz relatorio em html para auditoria interna
npx ecc-agentshield scan --format html > relatorio-agentshield.html

O uso em CI também faz sentido. Um pipeline pode bloquear alterações que adicionam segredos, permissões amplas demais ou hooks perigosos. Isso transforma a segurança do agente em parte da engenharia, não em lembrança manual.

ECC Tools e GitHub App

ECC Tools é uma camada complementar ao repositório aberto. O núcleo OSS continua gratuito e licenciado em MIT, enquanto o GitHub App adiciona análise de histórico do repositório, geração de skills personalizadas, auditorias e recursos voltados para equipes.

A diferença é simples. O repositório OSS fornece componentes prontos e copiáveis. O GitHub App tenta aprender padrões do próprio repositório e gerar arquivos de skill ou instincts mais alinhados com a base real de código.

A documentação pública descreve que o GitHub App analisa histórico, commits, diffs e branch info, e pode criar pull requests com conteúdo gerado para revisão. Isso não significa aceitar mudanças automaticamente. O modelo correto é gerar, revisar, testar e só então integrar.

Em equipes pequenas, o OSS pode ser suficiente. Em equipes maiores, o GitHub App pode economizar tempo ao transformar padrões existentes em material reutilizável. A decisão depende do tamanho do repositório, maturidade do processo e necessidade de auditoria.

Diferença entre ECC e OpenClaw

ECC e OpenClaw são frequentemente comparados porque ambos aparecem no universo de agentes. A comparação é útil, mas os dois projetos não têm o mesmo foco. O ECC organiza o trabalho de desenvolvimento dentro de harnesses de programação. OpenClaw é mais amplo: um assistente pessoal auto-hospedado que responde por canais como chats e pode acionar ferramentas.

OpenClaw é descrito como um assistente pessoal que roda nos próprios dispositivos e responde nos canais já usados, como mensageria e plataformas de comunicação. O plugin openclaw-code-agent adiciona sessões de codificação em background com Claude Code e Codex, aprovação de plano, isolamento por worktree e acompanhamento de merge ou PR.

O ECC, por outro lado, não é principalmente um bot de chat. Ele é uma coleção de skills, agentes, regras, hooks e auditorias para tornar o agente de código mais disciplinado. Ele atua mais perto do repositório, dos testes, das regras de linguagem e das verificações de segurança.

A lista abaixo resume a diferença sem tratar um como substituto direto do outro:

• ECC: melhor para padronizar engenharia, testes, segurança, skills, hooks e regras por linguagem.
• OpenClaw: melhor para operar um assistente pessoal por chat, canais, tarefas remotas e sessões persistentes.
• openclaw-code-agent: melhor para iniciar sessões de codificação em background e acompanhar plano, worktree, merge e PR por chat.
• ECC com Claude Code: melhor quando o foco é qualidade da base de código dentro do ambiente de desenvolvimento.
• OpenClaw com agentes de código: melhor quando o foco é controle remoto e orquestração por mensagens.

O diferencial do ECC em relação a outras ferramentas

O diferencial do ECC está na combinação. Existem ferramentas com agentes, ferramentas com comandos, ferramentas com hooks e ferramentas com segurança. O ECC tenta reunir tudo isso em uma base comum e portável.

A lista abaixo apresenta diferenciais práticos do ECC:

• Processo reutilizável: skills transformam tarefas repetidas em fluxos documentados.
• Disciplina automática: hooks lembram, bloqueiam ou verificam ações no momento certo.
• Especialização: agentes com escopo limitado reduzem confusão em tarefas complexas.
• Portabilidade: suporte a múltiplos harnesses reduz dependência de uma única ferramenta.
• Segurança de configuração: AgentShield audita riscos que surgem no próprio ambiente de agentes.
• Aprendizado contínuo: instincts reaproveitam padrões observados em sessões anteriores.
• Regras por linguagem: TypeScript, Python, Go, Swift, PHP e outras stacks podem receber orientações específicas.
• Foco em produção: TDD, revisão, build, lint, typecheck e segurança fazem parte do fluxo.

O ponto forte não é “fazer mais mágica”. O ponto forte é reduzir improviso. Em vez de pedir tudo de novo, o projeto passa a ter uma memória operacional e um conjunto de comportamentos esperados.

Vantagens práticas do ECC

As vantagens aparecem principalmente em projetos que duram mais de um dia. Quanto maior a base de código, mais valioso é ter padrão. Quanto mais pessoas usam IA no mesmo repositório, mais importante é ter regras comuns.

A lista abaixo organiza vantagens por impacto:

• Menos retrabalho: padrões de sessão e memória reduzem repetição.
• Mais segurança: AgentShield e rules reduzem configurações perigosas.
• Mais consistência: regras por linguagem evitam estilos conflitantes.
• Melhor revisão: agentes especializados ajudam a separar planejamento, execução e crítica.
• Mais controle: hooks e perfis permitem escolher quanto automatizar.
• Mais portabilidade: parte do fluxo pode acompanhar diferentes ferramentas de agente.
• Melhor onboarding: novas pessoas entendem como o projeto espera que o agente trabalhe.

Limitações e cuidados

O ECC não deve ser instalado de qualquer forma. A documentação alerta para não empilhar caminhos de instalação. O problema clássico é instalar por plugin e depois rodar instalador completo por cima, gerando duplicações e comportamento inesperado.

Outra limitação é o contexto. Copiar todas as rules e todas as skills pode parecer completo, mas pode carregar informação demais. O caminho mais seguro é começar com common e apenas a linguagem usada pelo projeto.

Também existe variação entre plataformas. Claude Code, Codex, Cursor e OpenCode não possuem exatamente os mesmos recursos. Alguns suportam hooks de maneira diferente, alguns carregam skills por caminhos diferentes e alguns exigem configuração manual adicional.

As limitações abaixo devem ser consideradas antes da adoção:

• Instalações duplicadas podem criar hooks, comandos ou skills repetidos.
• Hooks muito agressivos podem atrapalhar fluxo local.
• Nem todo recurso do Claude Code existe da mesma forma em Codex, Cursor ou OpenCode.
• Comandos multi-model podem exigir runtimes adicionais.
• Contagens de agentes, skills e comandos mudam rapidamente entre releases.
• O agente ainda precisa de teste real, revisão humana e validação de produção.

Requisitos antes da instalação

O primeiro requisito é ter um ambiente de desenvolvimento funcional. Claude Code, por exemplo, pode ser instalado por npm e exige Node.js 18 ou superior segundo a documentação oficial. O próprio ECC exige Claude Code CLI v2.1.0 ou posterior para o caminho de plugin, devido ao comportamento de hooks.

Os comandos abaixo mostram verificações básicas de ambiente:

# verifica versao do node
node -v

# instala claude code por npm quando o ambiente permite
npm install -g @anthropic-ai/claude-code

# verifica versao do claude code
claude --version

# verifica git
git --version

# verifica npm
npm -v

Em projetos Python, também convém ter Python, pip, virtualenv ou uv configurados. Em projetos TypeScript, convém ter npm, pnpm, yarn ou bun escolhido de forma explícita. O ECC consegue detectar package manager, mas uma configuração clara evita decisões ambíguas.

Regra mais importante de instalação

A regra mais importante é escolher apenas um caminho de instalação. A documentação oficial do ECC alerta que o setup mais problemático é instalar o plugin e depois executar o instalador completo por cima. Isso pode duplicar hooks, comandos e arquivos.

Os três caminhos abaixo existem para necessidades diferentes:

• Plugin do Claude Code: caminho recomendado para a maioria dos casos em Claude Code.
• Perfil mínimo manual: caminho mais leve, sem hooks runtime, indicado para começar com menos automação.
• Instalação manual completa: caminho para controle fino, sem usar plugin, com mais responsabilidade sobre arquivos instalados.

A decisão deve considerar maturidade do projeto. Um projeto pequeno pode começar com o perfil mínimo. Um projeto profissional com CI, testes e segurança pode usar plugin mais rules específicas. Uma equipe avançada pode definir instalação manual ou automação por perfil.

Instalação recomendada como plugin no Claude Code

O caminho recomendado no Claude Code é instalar o plugin e depois copiar manualmente apenas as rules necessárias. O plugin fornece comandos, agentes, skills e hooks. As rules ainda precisam ser copiadas porque o sistema de plugins não distribui rules da mesma forma.

O bloco abaixo mostra o caminho recomendado para Claude Code:

# dentro do claude code, adiciona o marketplace do ecc
/plugin marketplace add https://github.com/affaan-m/ECC

# instala o plugin ecc
/plugin install ecc@ecc

# fora do claude code, clona o repositorio para copiar rules
git clone https://github.com/affaan-m/ECC.git
cd ECC

# cria namespace de rules do ecc
mkdir -p ~/.claude/rules/ecc

# copia regras comuns e apenas as linguagens usadas
cp -r rules/common ~/.claude/rules/ecc/
cp -r rules/typescript ~/.claude/rules/ecc/
cp -r rules/python ~/.claude/rules/ecc/

Em um projeto somente TypeScript, a pasta python não deve ser copiada. Em um projeto somente FastAPI ou Django, a pasta typescript pode ficar fora. O namespace ~/.claude/rules/ecc evita colisão com rules próprias.

Instalação mínima sem hooks

O perfil mínimo é útil quando hooks parecem intrusivos ou quando o objetivo inicial é entender agentes, comandos, rules e skills sem automação de runtime. Esse caminho reduz contexto e risco operacional.

O bloco abaixo mostra a instalação mínima:

# linux ou macos
./install.sh --profile minimal --target claude

# windows powershell
.\install.ps1 --profile minimal --target claude

# alternativa por npx
npx ecc-install --profile minimal --target claude

Esse perfil exclui hooks-runtime. Isso significa que verificações automáticas baseadas em eventos não serão ativadas. A vantagem é começar com menos interferência e adicionar hooks depois, quando o fluxo estiver claro.

Instalação manual completa

A instalação manual completa deve ser usada apenas quando o plugin não é desejado ou quando existe necessidade de controle total. Depois desse caminho, o plugin não deve ser instalado por cima.

O bloco abaixo mostra o caminho manual:

# clona o repositorio oficial
git clone https://github.com/affaan-m/ECC.git
cd ECC

# instala dependencias do repositorio
npm install

# executa instalacao completa no linux ou macos
./install.sh --profile full

# alternativa no windows powershell
.\install.ps1 --profile full

O caminho manual copia componentes para locais esperados pelo harness. A responsabilidade de manutenção também aumenta. Mudanças futuras devem ser aplicadas com cuidado para não misturar versões antigas e novas.

Instalação para OpenCode

O ECC também oferece suporte a OpenCode. A documentação indica que o OpenCode possui sistema de plugins com muitos eventos e ferramentas nativas. Mesmo assim, a instalação completa pode exigir copiar configurações do diretório .opencode para o projeto.

O bloco abaixo mostra uma forma simplificada de ativar o plugin npm no OpenCode:

# instala opencode quando necessario
npm install -g opencode

# instala o pacote universal do ecc no projeto
npm install ecc-universal

# inicia opencode na raiz do repositorio
opencode

A entrada no arquivo de configuração pode apontar para o plugin universal. A própria documentação observa que isso ativa o módulo de plugin, mas não adiciona automaticamente todo o catálogo de comandos, agentes e instruções ao projeto. A configuração completa pode exigir copiar assets .opencode e ajustar entries.

Instalação para Codex

O ECC também oferece material para Codex CLI. A documentação descreve suporte com arquivo config.toml, AGENTS.md suplementar, skills portadas, MCPs e perfis. Codex não tem exatamente o mesmo modelo de hooks do Claude Code, então algumas proteções ficam em instruções e permissões.

O bloco abaixo mostra o fluxo conceitual:

# instala codex cli quando o ambiente usa esse harness
pip install openai-codex

# copia configuracao de referencia quando presente
mkdir -p ~/.codex
cp .codex/config.toml ~/.codex/config.toml

# roda codex na raiz do repositorio
codex

Perfis como strict e yolo representam níveis diferentes de risco. Um perfil estrito limita escrita e execução. Um perfil totalmente automático aumenta velocidade, mas só faz sentido em ambiente confiável e isolado.

Remoção e limpeza de instalação duplicada

Quando o ECC parece duplicado, intrusivo ou quebrado, a recomendação não é reinstalar por cima. O caminho correto é remover o que foi instalado e reconstruir com um único método. Isso evita hooks repetidos e comandos apontando para caminhos antigos.

O bloco abaixo mostra comandos úteis de limpeza no caminho manual:

# mostra o que seria removido sem alterar arquivos
node scripts/uninstall.js --dry-run

# remove arquivos gerenciados pelo ecc no caminho manual
node scripts/uninstall.js

# inspeciona instalacao quando disponivel
node scripts/ecc.js list-installed

# diagnostica problemas comuns
node scripts/ecc.js doctor

# tenta reparar arquivos gerenciados
node scripts/ecc.js repair

No caminho por plugin, a limpeza envolve remover o plugin no Claude Code e apagar manualmente apenas as rules copiadas para o namespace do ECC. A remoção deve preservar rules próprias da equipe.

Configuração do projeto com CLAUDE.md

O arquivo CLAUDE.md é um ponto central para orientar o agente dentro de um projeto. Ele explica a stack, os comandos, os padrões, as regras de segurança e os critérios de aceite. Um bom CLAUDE.md evita repetir contexto em toda sessão.

O exemplo abaixo mostra um CLAUDE.md prático para um projeto com frontend TypeScript e backend Python:

# Projeto

Aplicacao web com frontend em TypeScript e backend em Python.

# Stack

- Frontend: TypeScript, React ou Next.js, validacao com Zod.
- Backend: FastAPI ou Django, PostgreSQL, testes com Pytest.
- Qualidade: lint, typecheck, testes unitarios e revisao de seguranca.

# Comandos importantes

- Frontend instalar: npm install
- Frontend testar: npm test
- Frontend checar tipos: npm run typecheck
- Backend instalar: python -m pip install -r requirements.txt
- Backend testar: pytest
- Backend migrar: python manage.py migrate

# Regras de trabalho

- Planejar antes de alterar arquivos grandes.
- Escrever testes antes da implementacao quando a regra de negocio for nova.
- Validar toda entrada externa.
- Nao salvar segredos no repositorio.
- Rodar testes relevantes antes de considerar a tarefa concluida.

# Seguranca

- Dados sensiveis ficam em variaveis de ambiente.
- Erros de API nao devem expor stack trace em producao.
- Rotas autenticadas precisam validar usuario e permissao.
- Webhooks precisam validar assinatura quando o provedor oferecer esse recurso.

Esse arquivo deve ser específico. Um CLAUDE.md genérico demais vira ruído. Um CLAUDE.md bom informa os comandos reais do repositório e descreve padrões que a equipe realmente usa.

Fluxo diário recomendado com ECC

Um fluxo diário organizado separa planejamento, implementação, validação e revisão. A IA não deve saltar direto para mudanças grandes sem entender impacto. O ECC favorece esse processo com agentes, skills e comandos.

As etapas abaixo descrevem um fluxo prático de trabalho:

1. Definição do objetivo da funcionalidade em uma frase clara.
2. Planejamento com leitura de arquivos relevantes e divisão em subtarefas.
3. Criação ou atualização de testes antes da implementação quando houver regra de negócio.
4. Implementação mínima para passar nos testes.
5. Refatoração para legibilidade, organização e manutenção.
6. Execução de testes, lint, typecheck e build.
7. Revisão de segurança e revisão de código.
8. Registro de padrões aprendidos quando a solução for reutilizável.

O bloco abaixo mostra como esse fluxo aparece em comandos:

# planeja antes de alterar
/ecc:plan "criar endpoint de comentarios com validacao, moderacao e testes"

# aplica fluxo guiado por testes
# skill: tdd-workflow

# revisa qualidade do resultado
/code-review

# verifica seguranca da entrada publica
/security-scan

# salva um padrao reutilizavel quando fizer sentido
/learn "comentarios publicos exigem limite de tamanho, sanitizacao e status de moderacao"

Caso real em TypeScript: API de comentários com validação

Um caso real em TypeScript envolve criar uma API de comentários para posts. A funcionalidade precisa receber nome, mensagem e identificador do post. O risco principal é aceitar texto inválido, permitir conteúdo excessivo, gravar dados sem sanitização ou retornar erros confusos.

O fluxo com ECC começaria pelo planejamento. O agente deve procurar estrutura de rotas, padrões de validação, testes existentes e forma de persistência. Depois disso, a skill de TDD cria testes para entradas válidas e inválidas.

O bloco abaixo mostra um exemplo simplificado de schema e serviço em TypeScript:

import { z } from "zod";

export const esquemaComentario = z.object({
  idPostagem: z.string().uuid("postagem invalida"),
  nomeAutor: z.string().trim().min(2, "nome muito curto").max(80, "nome muito longo"),
  mensagem: z.string().trim().min(5, "mensagem muito curta").max(1000, "mensagem muito longa"),
});

export type EntradaComentario = z.infer<typeof esquemaComentario>;

export type Comentario = {
  id: string;
  idPostagem: string;
  nomeAutor: string;
  mensagem: string;
  status: "pendente" | "aprovado" | "rejeitado";
  criadoEm: Date;
};

export function prepararComentario(entrada: EntradaComentario): Comentario {
  const dadosValidados = esquemaComentario.parse(entrada);

  return {
    id: crypto.randomUUID(),
    idPostagem: dadosValidados.idPostagem,
    nomeAutor: dadosValidados.nomeAutor,
    mensagem: dadosValidados.mensagem,
    status: "pendente",
    criadoEm: new Date(),
  };
}

Esse exemplo mostra um princípio importante: a validação vem antes da persistência. O status inicial é pendente porque comentários públicos geralmente precisam de moderação. Em produção, também entrariam autenticação, rate limit, proteção contra spam e logs de auditoria.

Teste em TypeScript para o caso de comentários

O teste garante que entradas inválidas sejam recusadas e que comentários válidos recebam status inicial correto. O objetivo não é testar detalhes internos da biblioteca Zod. O objetivo é proteger a regra de negócio do projeto.

O bloco abaixo mostra um teste com Vitest:

import { describe, expect, it } from "vitest";
import { prepararComentario } from "./comentarios";

describe("prepararComentario", () => {
  it("cria comentario pendente quando os dados sao validos", () => {
    const comentario = prepararComentario({
      idPostagem: "550e8400-e29b-41d4-a716-446655440000",
      nomeAutor: "Ana Silva",
      mensagem: "Gostei muito do conteudo publicado.",
    });

    expect(comentario.status).toBe("pendente");
    expect(comentario.nomeAutor).toBe("Ana Silva");
    expect(comentario.id).toBeTruthy();
  });

  it("recusa mensagem muito curta", () => {
    expect(() =>
      prepararComentario({
        idPostagem: "550e8400-e29b-41d4-a716-446655440000",
        nomeAutor: "Ana Silva",
        mensagem: "ok",
      }),
    ).toThrow();
  });
});

Com ECC, a tarefa não terminaria no código. A sequência correta incluiria typecheck, testes, revisão e scan de segurança. O agente também deveria verificar se existe padrão de resposta de erro na API antes de criar um formato novo.

Roteiro ECC para o caso TypeScript

O roteiro abaixo mostra como a mesma tarefa ficaria organizada com ECC. A ideia é fazer o agente pesquisar o projeto, planejar, escrever teste, implementar e verificar.

# 1) planejamento com leitura do projeto
/ecc:plan "adicionar comentarios em TypeScript com Zod, testes e status de moderacao"

# 2) fluxo tdd
# skill: tdd-workflow

# 3) verificacoes locais
npm test
npm run typecheck
npm run lint

# 4) revisoes do ecc
/code-review
/security-scan

# 5) aprendizado reutilizavel
/learn "comentarios publicos devem nascer pendentes e sempre passar por validacao de tamanho"

Esse roteiro cria uma sequência compreensível para equipes. O agente não recebe apenas “crie comentários”. Ele recebe um fluxo com planejamento, validação, testes e segurança.

Caso real em FastAPI: cadastro de comentários moderados

FastAPI combina bem com o ECC porque já trabalha com tipagem, modelos de entrada e validação. Em uma API de comentários, o fluxo precisa validar payload, aplicar regra de status, persistir dados e retornar uma resposta previsível.

O bloco abaixo mostra um exemplo simplificado de rota FastAPI:

from datetime import datetime
from uuid import UUID, uuid4

from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel, Field

aplicacao = FastAPI(title="api de comentarios")

class EntradaComentario(BaseModel):
    id_postagem: UUID
    nome_autor: str = Field(min_length=2, max_length=80)
    mensagem: str = Field(min_length=5, max_length=1000)

class Comentario(BaseModel):
    id: UUID
    id_postagem: UUID
    nome_autor: str
    mensagem: str
    status: str
    criado_em: datetime

comentarios: list[Comentario] = []

@aplicacao.post("/comentarios", response_model=Comentario, status_code=status.HTTP_201_CREATED)
def criar_comentario(entrada: EntradaComentario) -> Comentario:
    if "http://" in entrada.mensagem.lower() or "https://" in entrada.mensagem.lower():
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="comentarios com links precisam de revisao manual",
        )

    comentario = Comentario(
        id=uuid4(),
        id_postagem=entrada.id_postagem,
        nome_autor=entrada.nome_autor.strip(),
        mensagem=entrada.mensagem.strip(),
        status="pendente",
        criado_em=datetime.utcnow(),
    )

    comentarios.append(comentario)
    return comentario

O exemplo usa lista em memória apenas para demonstrar a regra. Em produção, o armazenamento seria banco de dados, como PostgreSQL. Também entrariam autenticação, rate limit, logs, migração, paginação e tratamento de erros padronizado.

Teste em FastAPI

O teste de FastAPI confirma o comportamento da rota. Ele verifica criação bem-sucedida e rejeição de mensagem com link. Essa regra é simples, mas representa o tipo de proteção que evita abuso em campos públicos.

from fastapi.testclient import TestClient

from app import aplicacao

cliente = TestClient(aplicacao)

def test_cria_comentario_pendente():
    resposta = cliente.post(
        "/comentarios",
        json={
            "id_postagem": "550e8400-e29b-41d4-a716-446655440000",
            "nome_autor": "Ana Silva",
            "mensagem": "Conteudo muito bem explicado.",
        },
    )

    assert resposta.status_code == 201
    dados = resposta.json()
    assert dados["status"] == "pendente"
    assert dados["nome_autor"] == "Ana Silva"


def test_recusa_comentario_com_link():
    resposta = cliente.post(
        "/comentarios",
        json={
            "id_postagem": "550e8400-e29b-41d4-a716-446655440000",
            "nome_autor": "Ana Silva",
            "mensagem": "acesse https://exemplo.com",
        },
    )

    assert resposta.status_code == 400

Com ECC, o agente deve localizar a pasta de testes existente antes de criar uma nova estrutura. Também deve respeitar convenções do projeto, como nome de módulos, fixture de banco, factory de usuário e formato de erro.

Roteiro ECC para o caso FastAPI

O roteiro abaixo mostra como organizar a tarefa com ECC em um backend FastAPI:

# 1) planejamento orientado ao backend python
/ecc:plan "criar comentarios moderados no fastapi com pydantic, testes e seguranca"

# 2) skill de padroes python e backend
# skills sugeridas: backend-patterns, python rules, tdd-workflow, security-review

# 3) validacao local
pytest
ruff check .
python -m mypy .

# 4) revisao final
/python-review
/security-scan
/quality-gate

Esse fluxo reduz a chance de criar uma rota isolada e fora do padrão. A tarefa fica ligada aos testes, à tipagem, à revisão e à segurança.

Caso real em Django: comentários com model, serializer e view

Django exige atenção diferente de FastAPI. Em Django, a estrutura envolve model, migration, serializer, view e rotas. O ECC ajuda porque pode planejar a alteração em várias camadas antes de escrever código.

O bloco abaixo mostra um model simplificado para comentários moderados:

from django.db import models

class Comentario(models.Model):
    STATUS_PENDENTE = "pendente"
    STATUS_APROVADO = "aprovado"
    STATUS_REJEITADO = "rejeitado"

    OPCOES_STATUS = [
        (STATUS_PENDENTE, "Pendente"),
        (STATUS_APROVADO, "Aprovado"),
        (STATUS_REJEITADO, "Rejeitado"),
    ]

    id_postagem = models.UUIDField()
    nome_autor = models.CharField(max_length=80)
    mensagem = models.TextField(max_length=1000)
    status = models.CharField(max_length=20, choices=OPCOES_STATUS, default=STATUS_PENDENTE)
    criado_em = models.DateTimeField(auto_now_add=True)

    class Meta:
        ordering = ["-criado_em"]

O model define regra padrão no banco. O status pendente não depende apenas da view. Isso é importante porque a regra continua válida mesmo se o comentário for criado por outro fluxo interno.

O bloco abaixo mostra um serializer com validação básica:

from rest_framework import serializers

from .models import Comentario

class ComentarioSerializer(serializers.ModelSerializer):
    class Meta:
        model = Comentario
        fields = ["id", "id_postagem", "nome_autor", "mensagem", "status", "criado_em"]
        read_only_fields = ["id", "status", "criado_em"]

    def validate_mensagem(self, valor):
        mensagem = valor.strip()

        if "http://" in mensagem.lower() or "https://" in mensagem.lower():
            raise serializers.ValidationError("comentarios com links precisam de revisao manual")

        return mensagem

O serializer protege o endpoint contra entrada ruim. O campo status fica somente leitura para impedir que uma pessoa envie um comentário já aprovado. Esse detalhe é uma regra de segurança de negócio.

O bloco abaixo mostra uma view simples com Django REST Framework:

from rest_framework import generics

from .models import Comentario
from .serializers import ComentarioSerializer

class CriarComentarioView(generics.CreateAPIView):
    queryset = Comentario.objects.all()
    serializer_class = ComentarioSerializer

Em produção, permissões, throttling e autenticação podem ser adicionados conforme a regra do sistema. O ECC deve verificar padrões já usados no projeto antes de sugerir permissões novas.

Roteiro ECC para o caso Django

O roteiro abaixo mostra como organizar a mudança em Django sem pular etapas importantes:

# 1) planeja model, serializer, view, urls, admin, testes e migracao
/ecc:plan "adicionar comentarios moderados no django rest framework"

# 2) cria testes antes da implementacao
# skill: django-tdd

# 3) cria e revisa migracao
python manage.py makemigrations
python manage.py migrate

# 4) executa testes
pytest

# 5) revisoes especificas
/python-review
/security-scan
/quality-gate

Esse fluxo ajuda a evitar mudanças incompletas. Em Django, uma funcionalidade frequentemente precisa de model, migration, admin, serializer, view, urls e testes. O planejamento impede que uma dessas camadas seja esquecida.

Como o ECC ajuda em TDD

TDD significa Test-Driven Development, ou desenvolvimento orientado por testes. A ideia é escrever primeiro um teste que falha, implementar o mínimo para passar e depois melhorar o código. O ECC incorpora esse ciclo em skills e regras.

O ciclo usado em muitas descrições do ECC segue uma sequência simples:

1. Definir a interface ou comportamento esperado.
2. Escrever um teste que falha.
3. Implementar o mínimo necessário para o teste passar.
4. Refatorar sem mudar o comportamento.
5. Verificar cobertura, lint, types e segurança.

O ganho principal é impedir que o agente entregue apenas código visualmente convincente. O teste força uma evidência. A revisão humana continua necessária, mas o risco de regressão diminui.

Como o ECC ajuda em segurança de APIs

APIs recebem dados externos. Por isso, toda rota precisa validar entrada, autorização, formato, tamanho, limites de uso e mensagens de erro. O ECC inclui skills e checklists que reforçam essas práticas.

Os pontos abaixo aparecem como verificação mínima em APIs:

• Entrada validada com schema, serializer ou model adequado.
• Autenticação clara quando a rota não for pública.
• Autorização por usuário, função ou dono do recurso.
• Proteção contra SQL injection por uso de ORM ou queries parametrizadas.
• Proteção contra XSS em campos que podem virar HTML.
• Rate limit em rotas públicas ou caras.
• Erros sem vazamento de segredo, stack trace ou dados internos.
• Segredos em variáveis de ambiente, nunca no repositório.

O AgentShield verifica a segurança da configuração do ambiente de agentes. Já as skills de segurança verificam o código e a arquitetura da aplicação. As duas camadas são complementares.

Como o ECC ajuda em revisão de código

Revisão de código com IA fica melhor quando existe papel definido. Um agente de revisão não deve apenas elogiar a solução. Ele deve procurar riscos, inconsistências, complexidade desnecessária, testes ausentes e problemas de segurança.

Uma revisão útil deve cobrir os pontos abaixo:

• Comportamento esperado e casos de borda.
• Consistência com padrões do projeto.
• Testes suficientes para a regra de negócio.
• Erros, exceções e mensagens retornadas.
• Impacto em performance, banco de dados e cache.
• Riscos de segurança, permissões e exposição de dados.
• Legibilidade e manutenção futura.

O comando de revisão do ECC ajuda a tornar esse processo repetível. A equipe pode usar sempre a mesma base de critérios, em vez de depender do humor ou do nível de detalhe de cada prompt.

Como o ECC ajuda em build quebrado

Build quebrado é uma das tarefas mais comuns em projetos com IA. O agente pode alterar muitos arquivos e deixar um erro de typecheck, lint, import ou teste. O comando de build-fix cria um fluxo específico para diagnosticar e corrigir.

O processo adequado para corrigir build quebrado tem uma sequência clara:

1. Ler a mensagem completa do erro.
2. Identificar se o problema é sintaxe, tipo, import, teste ou dependência.
3. Procurar a menor alteração possível.
4. Rodar novamente o comando que falhou.
5. Evitar mudanças amplas que mascaram a causa original.

O bloco abaixo mostra um fluxo comum:

# comando que falhou no projeto typescript
npm run typecheck

# aciona fluxo de correcao
/build-fix

# valida novamente
npm run typecheck
npm test

Em Python, a mesma lógica se aplica a pytest, mypy, ruff, migrations e imports. O ponto central é corrigir a causa, não reescrever a funcionalidade inteira.

Como o ECC ajuda em documentação

Documentação deve refletir o comportamento real do projeto. O ECC inclui comandos e skills para atualizar documentação depois de alterações. Isso é importante porque agentes podem criar código sem explicar como a equipe deve operar a mudança.

Uma boa atualização de documentação deve cobrir:

• O que mudou na funcionalidade.
• Como configurar variáveis de ambiente novas.
• Como rodar testes relacionados.
• Como usar endpoints, comandos ou telas novas.
• Quais limites e regras de segurança foram adicionados.

A documentação também ajuda o próprio agente no futuro. Um README atualizado, um CLAUDE.md específico e exemplos de uso reduzem perda de contexto nas próximas sessões.

Como o ECC ajuda equipes

Em equipe, o maior valor do ECC é padronização. Sem padrões, cada pessoa ensina a IA de um jeito. Isso cria variação no código, nos testes, nos nomes, nos commits e nas decisões de arquitetura.

Com ECC, a equipe pode definir regras comuns e skills por projeto. O mesmo fluxo de TDD pode valer para todos. O mesmo checklist de segurança pode ser exigido antes de merge. O mesmo padrão de API pode ser aplicado em novas rotas.

A lista abaixo mostra práticas de adoção em equipe:

• Manter CLAUDE.md versionado no repositório.
• Carregar apenas rules usadas pela stack do projeto.
• Registrar comandos reais de teste, lint, typecheck e build.
• Usar AgentShield no CI para auditar configurações.
• Revisar skills geradas antes de incorporá-las ao projeto.
• Evitar segredos em arquivos de configuração de agentes.
• Registrar decisões arquiteturais importantes em documentação interna.

Perfis de instalação e níveis de rigor

O ECC trabalha com perfis de instalação. A ideia é instalar apenas o necessário para cada nível de maturidade. Um perfil mínimo carrega menos automação; um perfil completo entrega mais recursos e mais responsabilidade.

A lista abaixo mostra uma leitura prática dos perfis:

• Minimal: bom para começar, aprender e evitar hooks automáticos.
• Core: bom para projetos reais que precisam de agentes, skills, rules e parte do fluxo de qualidade.
• Full: bom para ambientes avançados que aceitam automação mais ampla.
• Component scoped: bom quando apenas uma parte é necessária, como hooks-runtime ou skills específicas.

O melhor perfil não é sempre o maior. O melhor perfil é o menor que resolve o problema atual sem gerar ruído. Essa lógica mantém o agente mais focado.

Controle de custo e contexto

Agentes de IA podem consumir muitos tokens. Tokens são unidades de texto processadas pelo modelo. Quanto maior o contexto e mais agentes paralelos, maior tende a ser o custo e a latência.

O ECC inclui ideias de otimização de contexto, seleção de modelo e compactação. Uma tarefa simples pode usar um modelo mais barato. Uma decisão complexa de arquitetura pode justificar um modelo mais forte. Uma sessão longa pode precisar de compactação para não carregar histórico excessivo.

O bloco abaixo mostra comandos e variáveis úteis em ambientes Claude Code:

# acompanha custo da sessao quando o harness oferece esse comando
/cost

# usa modelo mais economico para tarefas rotineiras
/model sonnet

# reserva modelo mais forte para arquitetura ou bugs complexos
/model opus

# compacta contexto quando a sessao cresceu demais
/compact

# limita contexto restaurado no inicio da sessao
export ECC_SESSION_START_MAX_CHARS=4000

# desativa contexto automatico quando necessario
export ECC_SESSION_START_CONTEXT=off

O controle de custo também é um cuidado de segurança operacional. Um agente autônomo sem limite pode executar loops caros. Por isso, tarefas longas devem ter critérios claros de parada.

Uso com monorepos

Monorepo é um repositório que guarda vários projetos ou pacotes. Esse cenário exige atenção porque frontend, backend, biblioteca compartilhada e infraestrutura podem ter regras diferentes. O ECC ajuda quando as rules são organizadas por escopo.

Uma organização comum em monorepo pode separar instruções assim:

repositorio/
  .claude/
    CLAUDE.md
    rules/
      common/
      frontend-typescript/
      backend-python/
  apps/
    web/
    api/
  packages/
    ui/
    shared/
  infra/
    docker/
    terraform/

O CLAUDE.md deve explicar quais comandos pertencem a cada pacote. O agente não deve rodar testes do backend quando a mudança afeta apenas frontend, exceto quando existe contrato compartilhado. Essa distinção economiza tempo e reduz confusão.

Uso com Docker

Projetos com Docker precisam de regras claras para build, rede, variáveis de ambiente e volumes. O ECC pode ajudar com skills de docker-patterns e checklists de segurança. O agente deve entender que container não é apenas “rodar local”; ele também define ambiente de produção ou staging.

O bloco abaixo mostra um exemplo de comandos que poderiam entrar no CLAUDE.md de um projeto Docker:

# sobe ambiente local
docker compose up -d

# roda testes do backend dentro do container
docker compose exec api pytest

# roda migracoes do django
docker compose exec api python manage.py migrate

# verifica logs do servico api
docker compose logs -f api

Ao usar agentes com Docker, segredos não devem ser colocados em Dockerfile nem no repositório. Variáveis sensíveis devem ser injetadas pelo ambiente, por arquivo local ignorado pelo Git ou pela plataforma de deploy.

Uso com banco de dados e migrations

Migrations são alterações controladas no schema do banco de dados. Em Django, elas ficam em arquivos de migration. Em TypeScript, podem aparecer em Prisma, Drizzle, TypeORM ou outras ferramentas. O ECC ajuda o agente a tratar migrations como parte crítica da mudança.

Uma migration deve ser pequena, reversível quando possível e compatível com dados existentes. O agente precisa avaliar impacto em produção, valores padrão, índices, constraints e tempo de execução. Mudanças em tabelas grandes exigem cautela.

O fluxo abaixo mostra uma abordagem segura:

1. Identificação do campo ou tabela necessária.
2. Verificação de dados existentes e impacto da mudança.
3. Criação de migration pequena e revisável.
4. Teste local da migration em banco de desenvolvimento.
5. Teste da aplicação com schema atualizado.
6. Revisão de rollback ou plano de mitigação.

Uso com autenticação e autorização

Autenticação confirma identidade. Autorização confirma permissão. Uma rota pode saber quem é a pessoa e ainda assim não permitir a ação. O ECC deve reforçar essa diferença em APIs e painéis administrativos.

Em tarefas de autenticação, o agente deve verificar os pontos abaixo:

• Formato do token ou sessão.
• Expiração e renovação de credenciais.
• Proteção contra acesso a dados de outra conta.
• Permissões por função ou dono do recurso.
• Mensagens de erro sem vazamento de existência de usuário.
• Testes para acesso permitido e acesso negado.

Esse é um campo em que a IA precisa ser controlada por regras. Um endpoint funcional, mas sem autorização correta, pode criar falha grave em produção.

Uso com frontend TypeScript

No frontend, o ECC pode ajudar a manter tipagem, validação, acessibilidade, testes e consistência visual. Um agente sem regras pode criar componentes bonitos, mas difíceis de manter. Rules e skills de frontend reduzem esse risco.

Um fluxo de frontend deve verificar:

• Componentes pequenos e com responsabilidade clara.
• Tipagem explícita em props e estados importantes.
• Tratamento de loading, erro e estado vazio.
• Validação de dados vindos da API.
• Acessibilidade em botões, labels e navegação por teclado.
• Testes de comportamento quando a tela tem regra de negócio.

O ECC não substitui design system. Ele ajuda o agente a respeitar o design system quando ele está documentado. Por isso, CLAUDE.md deve indicar biblioteca de componentes, tokens, padrões de layout e restrições visuais.

Uso com backend Python

No backend Python, o ECC pode reforçar organização por camadas, validação, testes e segurança. FastAPI e Django possuem estilos diferentes, mas os princípios são parecidos: entrada validada, regra de negócio testada, persistência previsível e erro claro.

Um fluxo backend deve verificar:

• Schema de entrada ou serializer.
• Service ou camada de regra quando a lógica cresce.
• Transação de banco quando há múltiplas gravações.
• Teste de caso feliz e casos de erro.
• Permissões de usuário e proteção de dados.
• Logs úteis sem exposição de segredo.

Rules de Python podem reforçar type hints, Pytest, formatação, exceções específicas e cuidado com dependências. Em Django, também podem reforçar migrations, admin, querysets e serializers.

Como criar uma skill própria

Uma skill própria transforma um processo repetido em instrução reutilizável. Por exemplo, uma equipe pode criar uma skill para “criar endpoint DRF com serializer, permission, teste e documentação”. Isso evita reexplicar o mesmo padrão toda semana.

A estrutura conceitual de uma skill é simples:

minha-skill/
  SKILL.md
  scripts/
    verificar.sh
  references/
    exemplo-endpoint.md

O SKILL.md descreve quando a skill deve ser usada, quais passos seguir, quais arquivos consultar e quais critérios de aceite verificar. Scripts e referências são opcionais, mas ajudam quando a tarefa exige comandos repetidos.

O ECC também oferece caminho de criação de skills a partir do repositório. A documentação cita o comando /skill-create para análise local e uma opção com GitHub App para casos avançados. Em qualquer caso, uma skill gerada deve ser revisada antes de entrar no fluxo oficial.

Exemplo de SKILL.md para endpoint Django

O exemplo abaixo mostra uma skill curta para padronizar endpoints Django REST Framework. Ela serve como modelo didático e pode ser adaptada conforme o projeto.

---
nome: endpoint-django-drf
descricao: cria endpoint django rest framework com serializer, view, urls e testes
---

# Objetivo

Criar endpoints DRF seguindo o padrao do projeto.

# Fluxo

1. Ler models, serializers, views e urls existentes.
2. Identificar padrao de permissao usado na aplicacao.
3. Escrever testes de caso valido e acesso negado.
4. Criar ou atualizar serializer.
5. Criar view com menor responsabilidade possivel.
6. Registrar rota no arquivo de urls correto.
7. Rodar pytest.
8. Revisar seguranca, mensagens de erro e autorizacao.

# Criterios de aceite

- Entrada externa validada.
- Permissao aplicada.
- Testes cobrindo sucesso e erro.
- Nenhum segredo no codigo.
- Padrao de resposta igual ao restante da API.

Uma skill assim reduz improviso. O agente recebe um caminho claro e critérios objetivos. Em equipe, isso ajuda a manter endpoints parecidos mesmo quando várias pessoas usam IA.

Como usar o dashboard

O repositório do ECC inclui um dashboard de desktop para explorar componentes. Ele permite visualizar agentes, skills, comandos, rules e configurações. Esse recurso é útil quando o catálogo cresce e a pessoa precisa descobrir o que está disponível.

O bloco abaixo mostra comandos de abertura citados na documentação:

# abre dashboard via npm
npm run dashboard

# alternativa via python
python3 ./ecc_dashboard.py

O dashboard não substitui a leitura das regras do projeto. Ele funciona como navegador visual do ecossistema. Em projetos grandes, pode ajudar a encontrar skills específicas sem procurar manualmente em várias pastas.

Como decidir entre ECC, OpenClaw e uso puro do Claude Code

A escolha depende do objetivo. Quando o problema é qualidade de engenharia dentro de um repositório, o ECC tende a fazer mais sentido. Quando o problema é controlar tarefas por chat e operar um assistente pessoal contínuo, OpenClaw tende a fazer mais sentido. Quando o projeto é pequeno e experimental, Claude Code puro pode ser suficiente.

A lista abaixo resume cenários comuns:

• Claude Code puro: bom para tarefas pequenas, exploração e mudanças simples.
• Claude Code com ECC: bom para projetos com testes, segurança, regras e repetição de workflow.
• OpenClaw: bom para assistente pessoal, canais de mensagem, automações remotas e tarefas contínuas.
• OpenClaw Code Agent: bom para sessões de codificação em background com aprovação de plano e worktree.
• ECC Tools: bom para equipe que quer gerar skills a partir do histórico real do repositório.

Essas opções podem coexistir, mas devem ser integradas com cuidado. Misturar automações sem política clara pode criar mais risco do que benefício.

Riscos de segurança em agentes de código

Agentes de código têm poder para ler arquivos, executar comandos e modificar projetos. Isso cria riscos diferentes de uma conversa comum. Um prompt malicioso em um arquivo, uma dependência comprometida ou uma configuração ampla demais pode causar problemas.

Os riscos abaixo devem ser considerados em qualquer setup com agentes:

• Segredos gravados em arquivos lidos pelo agente.
• Hooks que executam comandos com variáveis não sanitizadas.
• MCPs com permissões maiores que o necessário.
• Dependências instaladas por comandos automáticos sem revisão.
• Prompt injection escondido em documentação, issue, comentário ou arquivo externo.
• Automação que aprova mudanças sem testes.

O ECC reduz parte desses riscos com regras, hooks e AgentShield. Mesmo assim, o princípio de menor privilégio continua essencial. O agente deve receber apenas as permissões necessárias para a tarefa.

Checklist de segurança para usar ECC em projeto real

O checklist abaixo resume uma política mínima para usar ECC em aplicações reais:

• Manter segredos fora do repositório.
• Rodar AgentShield antes de aceitar configurações novas de agentes.
• Usar rules específicas da stack, sem copiar tudo.
• Evitar perfil totalmente automático em repositórios sensíveis.
• Rodar testes e typecheck antes de merge.
• Revisar hooks que executam shell.
• Auditar MCPs e permissões.
• Isolar worktrees quando houver execução autônoma.
• Registrar decisões importantes em CLAUDE.md ou documentação interna.

Esse checklist não é burocracia. Ele existe porque a velocidade de agentes aumenta também a velocidade de erros. Quanto mais automático o fluxo, mais fortes devem ser as proteções.

Boas práticas para prompts com ECC

Mesmo com ECC, a forma de descrever uma tarefa continua importante. Um prompt claro deve dizer objetivo, restrições, arquivos relevantes e critérios de aceite. O ECC reduz repetição, mas não adivinha regra de negócio não documentada.

A lista abaixo mostra elementos de um bom pedido técnico:

• Objetivo funcional em uma frase.
• Stack e camada afetada.
• Arquivos ou módulos prováveis.
• Regras de validação.
• Comandos de teste esperados.
• Critérios de segurança.
• Limite de escopo para evitar reescrita ampla.

Um exemplo de pedido adequado seria: “Planejar e implementar comentários moderados no backend Django, mantendo status pendente por padrão, criando serializer, view, urls, testes de sucesso e erro, sem alterar autenticação existente”. Esse tipo de descrição combina bem com /ecc:plan e TDD.

Erros comuns ao começar com ECC

Os erros comuns geralmente vêm de pressa. Instalar tudo, copiar todas as rules e ativar todo hook parece completo, mas pode gerar ruído. O ideal é começar com escopo pequeno e aumentar apenas quando houver necessidade.

A lista abaixo mostra erros frequentes:

• Instalar plugin e instalador completo ao mesmo tempo.
• Copiar todas as rules de todas as linguagens.
• Rodar hooks sem entender o que cada um executa.
• Colocar segredos em CLAUDE.md ou settings.json.
• Usar perfil automático em projeto sensível.
• Ignorar testes porque o agente “pareceu confiante”.
• Gerar skill própria sem revisão humana.
• Comparar ECC com OpenClaw como se tivessem o mesmo objetivo.

Como medir se o ECC está ajudando

A adoção de uma ferramenta deve ter evidências. O ECC está ajudando quando reduz retrabalho, melhora testes, diminui regressões e torna a revisão mais previsível. A percepção subjetiva é útil, mas métricas simples ajudam mais.

A lista abaixo apresenta indicadores práticos:

• Menos prompts repetidos para explicar padrões do projeto.
• Mais funcionalidades entregues com testes desde o início.
• Menos pull requests quebrando build.
• Menos inconsistência entre endpoints parecidos.
• Menos segredos e permissões problemáticas em configurações.
• Mais rapidez para retomar tarefas interrompidas.
• Revisões de código com critérios mais estáveis.

Quando esses sinais não aparecem, o problema pode estar na instalação, no excesso de componentes ou na falta de CLAUDE.md específico. O ECC depende de contexto correto para produzir valor.

Glossário simples

O glossário abaixo reúne termos técnicos usados no artigo:

• API: interface usada por sistemas para trocar dados.
• Build: processo de preparar o projeto para execução ou produção.
• CI: integração contínua, processo automático que roda testes e verificações.
• Coverage: porcentagem do código exercitada por testes.
• DRF: Django REST Framework, biblioteca para criar APIs em Django.
• Lint: verificação de estilo e problemas comuns no código.
• Migration: arquivo que altera estrutura do banco de dados.
• Monorepo: repositório que contém vários projetos ou pacotes.
• Prompt injection: tentativa de inserir instruções maliciosas em texto lido pelo agente.
• Typecheck: verificação de tipos em linguagens como TypeScript ou Python tipado.
• Worktree: cópia isolada de uma branch Git para trabalhar sem afetar a pasta principal.

Síntese final

O ECC representa uma mudança no uso de IA para desenvolvimento. A conversa isolada dá lugar a um ambiente com regras, skills, agentes, hooks, memória e segurança. Essa mudança não torna o agente infalível, mas torna o trabalho mais organizado.

O principal diferencial é transformar práticas repetidas em infraestrutura. Planejamento, TDD, revisão, segurança e documentação deixam de depender apenas de lembrança manual. Em projetos TypeScript, FastAPI ou Django, isso aparece em APIs mais consistentes, validações mais claras e verificações antes de aceitar mudanças.

OpenClaw e ECC pertencem ao mesmo movimento de agentes, mas resolvem problemas diferentes. OpenClaw é mais voltado a assistente pessoal e controle por canais. ECC é mais voltado a disciplina de engenharia dentro do repositório e do harness de programação.

A adoção mais segura começa pequena. Um projeto deve carregar apenas as regras necessárias, manter CLAUDE.md específico, rodar testes, auditar configurações com AgentShield e evitar instalações duplicadas. Assim, o ECC funciona como uma base de trabalho compreensível, controlada e útil para projetos reais.

Referências utilizadas

As fontes abaixo foram usadas para compor a explicação técnica, histórica e comparativa do artigo.

• Repositório oficial do ECC no GitHub: https://github.com/affaan-m/ECC
• README em português do ECC: https://github.com/affaan-m/ECC/blob/main/docs/pt-BR/README.md
• AGENTS.md do ECC com contagens e visão do projeto: https://github.com/affaan-m/ECC/blob/main/AGENTS.md
• Release notes do ECC v2.0.0-rc.1: https://github.com/affaan-m/ECC/blob/main/docs/releases/2.0.0-rc.1/release-notes.md
• Releases oficiais do ECC: https://github.com/affaan-m/ECC/releases
• Documentação do AgentShield no ECC: https://affaan-m-everything-claude-code.mintlify.app/reference/agentshield
• Repositório AgentShield: https://github.com/affaan-m/agentshield
• ECC Tools: https://ecc.tools/
• Página de segurança do ECC Tools: https://ecc.tools/security
• Documentação de agentes do ECC: https://affaan-m-everything-claude-code.mintlify.app/concepts/agents
• Documentação de suporte ao Claude Code no ECC: https://affaan-m-everything-claude-code.mintlify.app/platforms/claude-code
• Documentação de suporte ao Codex no ECC: https://affaan-m-everything-claude-code.mintlify.app/platforms/codex
• Documentação de suporte ao OpenCode no ECC: https://affaan-m-everything-claude-code.mintlify.app/platforms/opencode
• Documentação de segurança do ECC: https://affaan-m-everything-claude-code.mintlify.app/guides/security-best-practices
• Pacote npm ecc-universal: https://www.npmjs.com/package/ecc-universal
• Package.json do ECC: https://github.com/affaan-m/ECC/blob/main/package.json
• Documentação oficial do Claude Code para instalação: https://docs.anthropic.com/en/docs/claude-code/getting-started
• Documentação oficial de plugins do Claude Code: https://code.claude.com/docs/en/discover-plugins
• Documentação oficial de hooks do Claude Code: https://code.claude.com/docs/en/hooks
• Guia oficial de hooks do Claude Code: https://code.claude.com/docs/en/hooks-guide
• Documentação oficial de skills do Claude Code: https://docs.anthropic.com/en/docs/claude-code/skills
• Repositório oficial do OpenClaw: https://github.com/openclaw/openclaw
• Site oficial do OpenClaw: https://openclaw.ai/
• OpenClaw Code Agent: https://github.com/goldmar/openclaw-code-agent
• Documentação ACP Agents do OpenClaw: https://docs.openclaw.ai/tools/acp-agents
• SitePoint sobre ECC como plataforma de engenharia: https://www.sitepoint.com/everything-claude-code-ecc-production-engineering-platform/
• Augment Code sobre crescimento do ECC e release v1.9.0: https://www.augmentcode.com/learn/everything-claude-code-github
• APIYi sobre origem do Everything Claude Code: https://help.apiyi.com/en/everything-claude-code-plugin-guide-en.html
• DevSecOps Puziol sobre Everything Claude Code: https://devsecops.puziol.com.br/blog/everything-claude-code-plugin
• Business Insider sobre mudança de suporte da Anthropic ao OpenClaw por assinaturas Claude: https://www.businessinsider.com/anthropic-cuts-off-openclaw-support-claude-subscriptions-2026-4
• The Verge sobre mudança de uso do OpenClaw com assinaturas Claude: https://www.theverge.com/ai-artificial-intelligence/907074/anthropic-openclaw-claude-subscription-ban