Primeiros passos
O que é o Code
Addiction?
O Code Addiction é um framework spec-driven para assistentes de código com IA. Ele padroniza o caminho de uma feature, da ideia até a produção, com fluxos estruturados e repetíveis. Entra em qualquer projeto com um único comando.
Núcleo compartilhado: commands, scripts, skills, templates
Claude, Codex, Antigravity, Cursor, OpenCode, ZCode
install, update, uninstall, doctor, validate, features, plugins, providers, modify, config
Instalação
Precisa do Node.js 22.19.0 ou mais novo (recomendamos o Node 24 LTS). Funciona no Windows, macOS e Linux — sem Bash, WSL ou Git-Bash.
O que é instalado
├── .codeadd/← núcleo (sempre)
├── .claude/← Claude Code
├── .agents/← Codex (OpenAI) + ZCode (Z.ai)
├── .codex/← Codex (OpenAI) agents
├── .cursor/← Cursor
├── .agent/← Google Antigravity
├── .opencode/← OpenCode
└── .zcode/← ZCode (Z.ai) agents
Os scripts do framework são entradas Node — node .codeadd/scripts/<entry>.cjs — então não precisa de Bash, WSL ou Git-Bash em nenhuma plataforma.
Início rápido
Depois de instalar, use estes comandos da CLI para cuidar do seu setup:
providers list|add <name>|remove <name> [--force]. Aceita --global / --user--global / --user--verbose para checar se há atualizaçãoSetup guiado
/add-setup é o onboarding guiado para uma instalação nova ou atualizada. Ele olha o seu projeto e depois oferece cada feature e plugin com o benefício de cada um, numa única lista numerada, com uma resposta recomendada para cada item. Responda uma vez, por exemplo 1 sim, 2 não ou tudo recomendado.
Lê o projeto (código, frontend, wiki, setup de QA) e o que já está ligado. Não muda nada.
Uma lista numerada. O que já está ligado, ou que você recusou antes, não é perguntado de novo.
Só os itens que você aceitar: instalação de ferramentas, um codeadd modify, /add-qa-setup e /add-wiki.
codeadd install ou codeadd update. Depois de um update, ele pergunta só dos itens que são novos naquela versão..codeadd/settings.json. Faça commit desse arquivo para o time e os próximos updates verem o que foi ligado e por quê./add-brainstorm. Rode de novo quando as fundações existirem.Referência
Comandos
Todo comando é um slash command que você digita no seu assistente de código com IA. Eles cuidam da descoberta, do planejamento, da implementação e da entrega.
Descoberta
/add-brainstormExplora ideias (só leitura); define as bases da stack num repositório vazio
/add-newDescoberta de feature guiada por IA → about.md
/add-wikiGera uma wiki portátil do projeto (.codeadd/wiki/)
Planejamento
/add-planOrquestrador de planejamento técnico — aciona os agents de UX Design, Database, Backend e Frontend. Único que escreve o design.md (STEP 8.1) em features com interface
Implementação
/add-buildEspecialista em execução do desenvolvimento — fecha cada unidade de entrega com o seu próprio Final Review
Qualidade
/add-reviewEspecialista em review de feature — code review só de leitura e auditoria de conformidade com a spec; com a feature qa-pipeline ligada, também faz QA julgado por agents (painel de dois juízes sobre as evidências guardadas da execução). Roda uma checagem OWASP Top 10 junto do review da área quando o diff toca numa área sensível (auth, pagamento, upload, tratamento de entrada, sessão/token). Junta todos os achados numa tabela ## Fix Routing e escreve um review-NNN.md versionado. Encaminha os achados, nunca aplica. Opcional — o /add-build já roda o próprio Final Review, e o /add-done aceita o veredito mais recente
/add-auditAnálise completa da saúde do projeto
/add-diagnoseTriagem antes da decisão para sintomas ambíguos (só leitura); guarda o diagnóstico para o /add-hotfix reaproveitar
/add-qa-setupBootstrap de QA verificado de ponta a ponta — verifica e instala o runner de QA, gera o qa-project, cria config/screens, ignora a evidência temporária de trabalho sob um setup contract, migra o QA existente e faz um smoke test do julgamento de QA via /add-review
Entrega
/add-doneFechamento da branch e merge - promove a evidência de QA revisada, finaliza changelog e documentação, e faz o merge. O fechamento de um hotfix exige um recibo de Review aprovado no about.md. O deploy não faz parte da entrega - ele roda depois do /add-done, pelo seu próprio processo de deploy
/add-pull-requestPR idempotente - cria um PR novo ou acrescenta uma seção de atualização se já houver um aberto. Gera o changelog da feature em branches de feature
/add-hotfixCorreção de emergência com ID global (H[NNNN]) — reaproveita um /add-diagnose aceito quando existe
Utilitários
/add-helpGuia de ajuda — qual comando usar, features e plugins, modo bot, CLI
Onboarding guiado — oferece cada feature e plugin com o seu benefício e configura os que você aceitar
/add-uxUX rápido — carrega o ux-design para dar contexto sem custo
Referência
Grafo de artefatos
Como os comandos passam o trabalho de um para o outro. O build gera isso a partir da declaração de cada comando, então não foge do que é entregue — um teste falha se esta imagem e o grafo divergirem.
Só comandos, um salto de cada vez. O grafo completo tem 247 artefatos e 972 relações; desenhado de uma vez vira um emaranhado que não diz nada. Skills, agents e scripts ficam acessíveis pela consulta logo abaixo.
Carregando o diagrama…
Consulte direto: node scripts/graph.js impact add--doc-schemas
Referência
Fluxos
Escolha o caminho mais curto que serve. Menos cerimônia, mesma qualidade.
Fluxo completo
Features complexas com interface — descoberta completa, planejamento (o design sai dentro do /add-plan STEP 8.1), implementação, review.
/add-brainstorm→Novo
/add-new→Plano
/add-plan→Código
/add-build→Revisão
/add-review→Concluir
/add-done
Fluxo padrão
Features sem interface complexa — pula o brainstorm e o design
/add-new→Plano
/add-plan→Código
/add-build→Concluir
/add-done
Fluxo enxuto
Mudanças pequenas, tarefas rápidas — o mínimo de cerimônia
/add-new→Código
/add-build→Concluir
/add-done
Fluxo automático
Uma aprovação no brainstorm — cada etapa passa para a próxima, o build fecha cada unidade de entrega com a sua própria Final Review e pergunta antes de abrir o PR. O merge continua com você
/add-brainstorm→Novo
/add-new→Plano
/add-plan→Build (revisão final)
/add-build→Pergunta do PR
Fluxo de emergência
Bug crítico em produção — caminho rápido até a correção
/add-hotfix→Concluir
/add-done
Fluxo de exploração
Não sabe por onde começar? Faça o brainstorm primeiro e depois escolha qualquer fluxo acima
/add-brainstorm→Novo
/add-new→...escolha o seu fluxo
Referência
Cenários
Exemplos do dia a dia de quando usar cada fluxo.
"Criar um painel de usuário com gráficos e filtros"
Feature complexa com interface, vários fluxos de usuário, pede descoberta e design.
/add-new → define requisitos e critérios de aceite
/add-plan → arquitetura técnica, contrato de UX, quebra em tarefas
/add-build → implementação conduzida por subagents
/add-review → code review automatizado
/add-done → changelog, docs e merge
"Adicionar e-mails de notificação para o status do pedido"
Feature de backend, sem interface complexa. Precisa de planejamento, mas não de fase de design.
/add-plan → arquitetura do serviço, estratégia da fila
/add-build → implementa
/add-done → finaliza
"Adicionar um spinner de carregamento no botão de enviar"
Mudança pequena e bem definida. O mínimo de cerimônia.
/add-build → implementa
/add-done → finaliza e faz o merge
"Implementar os 5 endpoints da API descritos na spec"
Trabalho bem especificado. Aprove uma vez, deixe as etapas passarem o bastão e tome a decisão do merge você mesmo.
new → plan → build (revisão final) → roda sem acompanhamento até a pergunta do PR
/add-done → finaliza
"Os usuários não conseguem entrar — a validação do token de autenticação quebrou"
Bug crítico em produção. Correção rápida, com rastreio.
/add-done → finaliza e faz o merge
"Quero colocar IA no produto, mas não sei por onde começar"
Escopo ainda confuso. Comece pelo brainstorm e depois escolha um fluxo.
/add-new → fecha o que você vai construir
→ ...a partir daqui escolha Completo, Padrão ou Enxuto
Aprofundando
Skills
Skills são módulos de conhecimento especializado que os comandos carregam. Elas trazem domínio de backend, frontend, banco de dados, UX, segurança e mais.
backend-developmentSOLID, Clean Arch, DTOs, Services, Repository — independente de stackfrontend-developmentEstado, busca de dados, componentes, formulários, rotas — independente de stackdatabase-developmentEntidades, repositórios, migrations, nomenclatura — independente de stackux-designDireção de design, leis de UX, contrato de layout, régua de crítica, padrões de SaaS, mobile-firstsecurity-auditChecklist OWASP, RLS, segredos, multi-tenancycode-reviewCode review: IoC, RESTful, Contratos, Segurança (OWASP), Clean Architecture, SOLIDfeature-discoveryProcesso de descoberta, análise do códigofeature-specificationÚnico autor do about.md - lê o arquivo de intenção do brainstorm, extrai o objetivo e as decisões já fechadas sem perguntar, e pergunta só o que ainda está em aberto. Carregada pelo /add-new.architecture-discoveryUse ao documentar a arquitetura do projeto - gera a seção Technical Spec no AGENTS.mddelivery-validationValidação de produto: Requisitos 100% implementados, pré-requisitos existem, critérios de aceite passamsubagent-driven-developmentCoordena subagents com gates de qualidadeadd--tasks-checklistUse ao gerar, ler ou marcar o tasks.md - define o schema canônico de 5 seções, as regras de marcação por seção, a semântica da marca de falha, a regra de 'mudança não trivial' e o template de prompt do subagent arquitetotoken-efficiencyUse ao criar comandos, skills ou docs - define padrões genéricos de compressão (JSON minificado, abreviações, glob patterns, quebras únicas). Carregue antes de qualquer escrita em que a densidade de tokens importa.commitCommit inteligente com mensagens Conventional Commits geradas automaticamentehealth-checkSuíte de health check técnico: docs, segurança, arquitetura, análise de dadosdev-environment-setupUse quando faltar Node, git ou gh CLI, ou o Node for mais antigo que 22.19.0 - detecta o SO, diagnostica as lacunas e instala o que falta.backend-architectureOrienta decisões de arquitetura de backend - excesso de engenharia, estrutura de pastas, slices, camadas, organização por feature, onde o código vai.frontend-architectureConsultor de arquitetura de frontend para estrutura de projeto, organização de pastas, limites entre features e decisões de escala. Conhece frameworks (React, Vue, Angular). Use quando o usuário perguntar sobre a estrutura de pastas do frontend, "a pasta de componentes virou uma bagunça", "onde isso deve ficar", excesso de engenharia, slices, pastas por feature, ou ao iniciar/refatorar um projeto de frontend. Só orienta decisões - não implementa (use add--frontend-development) nem desenha UI (use ux-design).ecosystemMapa do ecossistema ADD e visão geral do frameworkinvestigationInvestigação diagnóstica profunda para achados ambíguosresource-path-conventionUse ao escrever comandos ou skills que referenciam outros comandos, skills ou scripts - garante que os caminhos resolvam certo em todos os providers depois da instalaçãoid-conventionUse ao alocar IDs de feature/hotfix/refactor/chore/docs ou ao criar branches - formato canônico [NNNN][L] que os scripts (next-id.cjs, get-branch-metadata.cjs, build-setup.cjs, done.cjs) esperamagents-md-styleUse ao gerar ou atualizar o AGENTS.md do projeto - antes migra qualquer arquivo de contexto antigo para ele, depois define o que entra e o que fica em skills/docs, as regras de formato (JSON para dados, markdown para regras/instruções) e o limite de linhas. Carregue antes de qualquer escrita no AGENTS.md.add--tddDisciplina de execução RED-GREEN-REFACTOR para agents de IA. Use ao implementar qualquer feature ou bugfix que tenha (ou deveria ter) testes - força um teste falhando, confirmado pelo motivo certo, antes de qualquer código de produção. Carregada pelo add-build.add--test-specificationGera casos de teste de contrato a partir dos requisitos da feature (RFs/RNs) e dos contratos técnicos. Use quando o add-plan precisa produzir o plan-test-spec.md ligando cada requisito a casos testáveis antes da implementação.add--qa-specGera uma especificação de QA/E2E sem código (intenção de alcance, critérios de aceite de UX, cenários E2E funcionais, estados de captura, viewports alvo, expectativas de a11y) a partir de about.md + design.md + plan-*.md, e cria o catálogo _tests/screens.json (design: só o caminho - sem expect). Carregada pelo passo QA-Spec do qa-pipeline do add-plan.add--qaUse ao rodar a validação de QA julgada por agent (read-PNG por padrão; o plugin playwright adiciona a navegação ao vivo) - a régua do juiz de Nível C, a taxonomia de severidade, o método de juiz duplo (@ux-agent review ∥ @qa-agent), o schema/template do relatório e os formatos de config.json/screens.json. Consumida pelo /add-review e pelos dois juízes.add--qa-migrationUse quando um projeto já roda um fluxo de QA/testes (Cypress, Jest, Vitest, customizado) e quer adotar o pipeline de QA do code-addiction em vez de recomeçar - define a sequência autônoma de dogfooding (add-new → add-plan → add-build → add-review) e os seus checkpoints. Consumida pelo /add-qa-setup quando a migração é detectada e confirmada.add--knowledge-discoveryUse no passo de contexto/descoberta do add-plan, add-hotfix, add-new, add-diagnose, add-review, add-brainstorm - consulte o índice de entregas, depois a wiki do projeto (e o grafo de conhecimento do código), com o menor custo de tokens, antes de acionar agents.add--wiki-maintenanceUse para atualizações incrementais da wiki do projeto - carregada pelo /add-wiki update (desvio manual) e pelo add-done STEP 4.9 (antes do merge, automático). Só edições cirúrgicas guiadas pelo diff, nunca reescrita completa.add--setup-contractUse quando um comando que materializa estado começa - compara o setup-shape do recibo com o shape do sidecar entregue e roteia FIRST-RUN / CURRENT / STALE. Consumida pelo /add-qa-setup STEP 1.5 e STEP 12.add--settingsUse quando um comando lê ou escreve o arquivo de configuração do projeto .codeadd/settings.json - dono, leitura/merge/escrita, a regra de conteúdo, os schemas das seções qa e setup e os campos do recibo. Consumida pelo /add-qa-setup e pelo /add-setup.add--feature-readbackUse quando os docs de uma feature estão fechados e você precisa de um leitor frio dizendo o que entendeu antes de qualquer um construir - pega docs que passam em todas as reviews e ainda assim fazem o leitor construir a coisa errada.add--final-reportUse no passo final de um comando - os sete blocos em que todo comando que termina reporta, o handoff opcional de continuação em contexto novo e o seu contrato de duas respostas, as frases proibidas e o autoteste. Carregue no último passo, não no primeiro.add--review-disciplineUse quando um comando aciona um reviewer ou um leitor frio sobre um documento - quantas vezes cada um roda, o que torna legal uma segunda chamada, como uma divergência é tratada em cada ponto e onde um veredito pode chegar ao disco.add--delivery-modeUse quando um comando do pipeline chega a uma parada ou ao handoff final - os dois modos de entrega e onde cada um é carregado, quais paradas esperam em cada modo, a quem se oferece a continuação opcional em contexto novo e por quê, como um comando passa para o próximo e onde o caminho automático termina.add--cross-sf-consistencyUse ao julgar a consistência de contratos entre os planos das subfeatures de um épico - a régua de cinco dimensões, as regras de deduplicação e as rotas dos achados.add--doc-schemasSchemas e convenções de documentação para projetos ADDadd--plan-reviewReview de executabilidade antes da entrega para about.md e plan.md recém-gerados - veredito (ok / fix-then-ok / blocked) mais as correções necessárias, não perguntas. Carregue antes de acionar o plan-reviewer-agent, ou ao aplicar a régua dele inline como alternativa.add--human-interactionComo um comando fala com uma pessoa (slot de interação padrão)add--agent-interactionComo um comando fala com um bot via claude -p, injetada pela feature agent-modeFeatures opcionais
Features são comportamentos que você liga e desliga, injetados nos comandos por arquivos de fragmento. Ative ou desative com npx codeadd features enable|disable <name>.
tdd-pipelineativada por padrãoPipeline de TDD (ordem com o teste primeiro + geração de testes unitários e de integração)
Injetada em: add-plan, add-build, add-review, add-hotfix
qa-pipelinedesativada por padrãoPipeline de QA (escrita da spec E2E + correção de QA roteada + o julgamento de QA do agent no add-review)
Injetada em: add-plan, add-build, add-review
docs-pruningdesativada por padrãoLimpa a estrutura da feature depois do merge (descoberta, tarefas, épico, reviews) assim que a entrada do índice de entregas é escrita
Injetada em: add-done
agent-modedesativada por padrãoTexto pensado para bots em execução headless (um lote único de perguntas numeradas, sem oferta de continuar). Saiba mais
Injetada em: add-brainstorm, add-new, add-plan, add-build, add-review, add-done, add-diagnose, add-hotfix, add-qa-setup, add-pull-request, add-audit, add-wiki
Agent Mode
Entregue ao seu bot um card ou um slug e deixe ele entregar. Com o Agent Mode, um assistente como o Grok Bot faz plan, build, review e release sozinho. Ele pergunta só o que importa, tudo de uma vez, e você aprova o PR.
Como ligar
Já usa o codeadd? Rode npx codeadd modify --providers claude --force --enable-feature agent-mode.
Como funciona
1
Você fala com o seu bot
Aponte para um card, um slug ou uma ideia em uma linha.
2
O bot roda o codeadd
Plan, build, review e done, um comando depois do outro.
3
Você responde uma vez
As perguntas em aberto chegam juntas, cada uma com uma recomendação.
4
Você aprova o PR
O bot faz o merge com o CI verde e pode gerar o release.
Por que é fácil
- Sem paradas interativas. Os comandos nunca esperam um menu ou um sim/não para continuar.
- Perguntas em lote. Tudo o que uma etapa precisa chega numa única mensagem numerada. Responda
recommendedpara aceitar todas. - Status claro no fim. Toda execução termina como done, stopped, needs-approval ou failed, com o motivo e o próximo comando.
- Agents em paralelo, isolados. Cada agent trabalha no seu próprio git worktree e na sua própria sessão, então três ou quatro rodam lado a lado.
O que você diz ao bot
Pegue o card do dark-mode-toggle, implemente e abra o PR para mim.
Funciona no Claude Code, no Cursor e no OpenCode. Está montando o seu próprio bot? O guia técnico (chamadas headless, sessões e o schema do resultado) é instalado em .codeadd/agent-mode/README.md.
Plugins
Plugins ligam ferramentas externas (servidores MCP ou skills que você instala) aos comandos do ADD. O Code Addiction cuida do uso — ele confere se a ferramenta está presente, injeta orientações nos comandos e nos agents, e ativa as skills ligadas ao plugin. Os plugins vêm desligados por padrão e exigem que a ferramenta externa esteja instalada antes.
gitnexusmcpOs agents veem quem chama o quê antes de mexer no código, e assim deixam passar menos efeitos colaterais.
Usado por: add-new, add-plan, add-build, add-diagnose, add-hotfix, add-done, add-wiki
playwrightmcpO review de QA controla o navegador ao vivo (screenshots, console, rede) em vez de ler imagens salvas.
Usado por: add-review
designskillOs planos de UI recebem estilo, paleta e tipografia de uma biblioteca de design, em vez dos padrões.
Usado por: add-plan
Não sabe qual ligar? O /add-setup oferece cada um com uma recomendação para o seu projeto.
gitnexusdesligado por padrãomcpNavegação no código por grafo de conhecimento (call graph, referências, blast-radius) via MCP. Dá navegação estrutural nos comandos de descoberta, planejamento, diagnóstico e hotfix — vai além do grep para entender as cadeias de chamada e o impacto de verdade.
Injeta em: add-new, add-plan, add-build, add-diagnose, add-hotfix, add-done, add-wiki
Injeta no agent: ux-flow-agent
Ativa a skill: add--gitnexus — navegação estrutural/relacional no código (call graph, referências, blast-radius, rastreio de fluxos, refactors seguros)
1 — Instale o GitNexus
Necessário antes de ligar o plugin. O Code Addiction confere isso com gitnexus --version.
2 — Ligue o plugin
3 — Configure e indexe (uma vez por repositório)
Rode estes comandos depois de ligar. Rode o analyze de novo depois de mudanças grandes.
Confira: peça ao Claude para rodar gitnexus list_repos (ou /mcp) — este repositório precisa aparecer indexado. Se não aparecer, os comandos voltam para o grep sem avisar.
playwrightdesligado por padrãomcpSoma controle ao vivo do navegador (screenshots + console/rede) à validação de QA que o agent já faz, via Playwright MCP. O QA funciona de saída com a evidência gravada na execução (screenshots + resultados de asserções/axe) — este plugin deixa a dupla de juízes do /add-review também controlar o app ao vivo, para ter evidência mais rica.
Injeta em: add-review
Injeta no agent: qa-agent
1 — Instale o Playwright MCP
Necessário antes de ligar o plugin. O Code Addiction confere isso com npx --yes @playwright/mcp@latest --version. Rode /add-qa-setup para uma instalação guiada, por sistema operacional, do chromium + servidor Playwright MCP.
2 — Ligue o plugin
3 — Configure e rode o QA (uma vez por projeto)
Monte a configuração de QA depois de ligar e rode a auditoria em cada feature.
Confira: o servidor Playwright MCP precisa estar conectado (por exemplo, /mcp) — se ele não aparecer, o /add-review não consegue controlar o navegador.
designdesligado por padrãoskillFaz a etapa de design do /add-plan usar o ui-ux-pro-max, que você mesmo instala, como fonte de dados para estilo, paleta, tipografia e escolha de gráficos. Os tokens inspecionados do seu projeto e o docs/design-system.md continuam valendo primeiro, e o núcleo de design mantém a sua notação, o rubric e o gate de schema. O Code Addiction não leva cópia da skill e não instala nada.
Injeta em: add-plan
Injeta nos agents: ux-flow-agent, ux-layout-agent, ux-agent (modo crítica)
1 — Instale o ui-ux-pro-max (uma das duas rotas oficiais)
Necessário antes de ligar o plugin. O Code Addiction procura ui-ux-pro-max/SKILL.md nas pastas de skills do projeto e da home de todo provider suportado, e na lista de plugins instalados do Claude. No Claude Code:
Em qualquer provider, com a CLI oficial (não o pacote antigo uipro-cli):
2 — Ligue o plugin
Nota sobre Python: o script de busca da skill precisa do Python 3. Confira com python3 --version (Windows: py --version). Sem Python, os agents pulam a busca e usam o núcleo de design. O Code Addiction nunca instala o Python. Depois de instalar um plugin do Claude, reinicie a sessão ou rode /reload-plugins.
Providers
O Code Addiction gera arquivos específicos de cada provider, para que os mesmos comandos funcionem em vários assistentes de IA.
| Provider | Pasta | Formato |
|---|---|---|
| Claude Code | .claude/ | commands/ |
| Codex (OpenAI) | .agents/ + .codex/ | skills/ |
| Cursor | .cursor/ | commands/ |
| Google Antigravity | .agent/ | skills/ |
| OpenCode | .opencode/ | commands/ |
| ZCode (Z.ai) | .agents/ + .zcode/ | skills/ |
Comandos e skills são gerados para os seis providers. As definições de agent vão para Claude Code, Cursor, OpenCode, Codex e ZCode — o Antigravity fica para depois porque o caminho nativo dele, .agents/agents/, colide com a raiz de skills do Codex. O ZCode lê comandos e skills da mesma árvore .agents/ do Codex e guarda os agents em .zcode/, então os dois nunca duplicam um arquivo no disco.
Estrutura do projeto
O repositório do Code Addiction é organizado assim:
├── cli/← CLI do instalador (npm: codeadd)
├── framwork/← conteúdo do framework
│ └── .codeadd/← núcleo: comandos, skills, scripts
├── web/← este site
├── scripts/← scripts de build e de release
└── docs/← documentação do projeto
Aprofundando
Mapa do ecossistema
Mapa interativo de comandos, skills e agents. Passe o mouse sobre um nó para destacar as conexões. Clique para inspecionar.