# ContextDevKit — Guia de Uso (pt-BR) > Guia prático em português. **Comandos, caminhos e chaves de config** ficam em > inglês de propósito (é o "principal" do projeto) — só a explicação é em pt-BR. ## O que é O ContextDevKit transforma "AI-assisted coding" em **engenharia**: em vez de torcer pra IA lembrar do contexto, o ambiente (hooks do Claude Code) **força** boas práticas e guarda o histórico no próprio repositório. ## Primeiro uso Abra o projeto no Claude Code, aprove os hooks, e rode **`/setupcontextdevkit`** — ele detecta a stack, ajusta o config, preenche o `CLAUDE.md`, marca paths de risco, cria um ADR base e registra a sessão. Um banner de "first run" aparece no boot até você rodá-lo. Projeto vazio (greenfield)? Use **`/aidevtool-from0`** — questionário interativo de produto → visão, stack, roadmap, boas práticas e DevPipeline montados num único passo. ## Personalização do projeto Coloque instruções duráveis do projeto em `contextkit/memory/preferences/personalization.md`. Preferências estruturadas continuam no JSON já existente `contextkit/memory/preferences/owner-preferences.json`, que é somente recomendatório e nunca autoriza trabalho. Os dois arquivos pertencem ao usuário, são criados apenas quando ausentes e não são sobrescritos por update nem por `--force`. `CLAUDE.md`, `AGENTS.md` e `INSTRUCTIONS.md` apenas apontam para eles por um bloco delimitado; todo texto fora desse bloco é preservado. Instruções atuais de system, developer e user e limites de segurança sempre prevalecem. ## Os 7 níveis | Nível | O que ativa | | --- | --- | | **L1 Memory** | contexto no boot, `/log-session`, ADRs, changelog | | **L2 Ledger** | detecção de drift | | **L3 Multi** | claims, worktrees, índices auto-gerados, git hooks (Conventional Commits + pre-push contra conflito real) | | **L4 Squads** | 35 sub-agentes em 7 squads (devteam, qa-team, design-team com `seo-specialist` + `landing-architect`, security, compliance-LGPD, ops, agent-forge) | | **L5 Proactive** | gate `/simulate-impact`, tech-debt, distill-detect, contract drift | | **L6 Autonomy** | pipeline `/ship`, learning loop `/retro`, métricas, agent-forge ativo | | **L7 Ecosystem** | `/fleet` (multi-repo), `/tune-agents`, testes visuais, playbook runner | Trocar de nível: `/context-level ` (reinicie o Claude Code depois). ## Grok Build O Grok Build é um host nativo próprio do ContextDevKit, não um provider. O instalador compõe `.grok/hooks/contextdevkit.json` para o CLI/TUI/headless oficial e usa `.grok/config.toml` para MCP; valide a descoberta com `grok inspect --json`. O Grok exige confiança explícita na pasta antes de executar hooks ou MCP do projeto; o ContextDevKit não concede essa confiança automaticamente. As operações e workflows permanecem independentes dos workflows de providers. ## Compatibilidade com CompozyOS e Graphify Quando `.compozy/config.toml` existe com segurança, o CompozyOS vira o executor prioritário do trabalho governado. `node cdx.mjs execute --workflow WF-#### --task T-### --objective "..."` valida a tarefa canônica, cria o envelope de autorização, inicia automaticamente o daemon, autoaprova permissões vinculadas ao envelope e devolve evidências limitadas. Falha do Compozy configurado bloqueia a execução; não existe fallback silencioso para outro executor. O Compozy controla somente sessão e execução técnica. O ContextDevKit continua sendo a única autoridade para workflow, política de permissão, testes, QA e conclusão. Sucesso do Compozy é evidência candidata, nunca conclusão automática. O instalador detecta a integração, mas o daemon só inicia após um envelope governado. O Graphify continua sendo um provedor de descoberta sem mutação. A busca de arquivos segue `graphify -> native -> project-map-find`. Evidência insegura, inválida, desatualizada, parcial ou vazia libera automaticamente o próximo provedor. O `/context-doctor` relata detecção e sobreposição de hooks/instruções sem ativá-los. ## Comandos principais - **Setup:** `/aidevtool-from0` (vazio) · `/setupcontextdevkit` (existente) - **Diário:** `/state` · `/log-session` (no fim) · `/new-adr` · `/debate` · `/close-version` · `/context-refresh` · `/bug-hunt` · `/dashboard` · `/watch` · `/playbook` · `/context-stats` · `/distill-sessions` · `/distill-apply` - **Trabalho focado:** `/dev-start` (mostra PRs abertos via sync-check) · `/workflow` · `/ship` · `/resume` - **Coordenação (L3):** `/claim` · `/release` · `/worktree-new` · `/git` - **Qualidade (pack `qa/` + L5):** `/test-plan` · `/scaffold-tests` · `/qa-signoff` · `/visual-test` · `/simulate-impact` · `/tech-debt-sweep` · `/analyze-code-ia-practices` · `/contract-check` · `/context-budget` (`scaffold-tests.mjs plan` detecta Node/JavaScript, Python, Go, Rust e PHP antes do squad escrever testes de domínio; `scaffold --write` cria só harnesses starter) - **Auditoria (pack `audit/`):** `/audit` · `/deep-analysis` · `/security-setup` · `/deps-audit` · **`/seo-audit`** *(novo — SEO + AISO)* - **Landing pages & mídia *(novo na v1.7)*:** `/landing-page` (architect opinionado anti-cookie-cutter) · `/media-gen` (Veo + Nano Banana via `.env`) - **Produto & execução:** `/roadmap` · `/pipeline` · `/runs` · `/retro` · `/squad` · `/claude-md` - **Plataforma:** `/context-doctor` · `/context-config` · `/context-level` · `/fleet` *(L7)* · `/tune-agents` *(L6)* - **Agent-forge** *(L6+)*: 14 comandos `forge-*` para o ciclo de Agent Packages ### Paridade ContextKit (ADR-0060 → ADR-0068) Oito features zero-dep, cientes de nível e *warn-first*: - **Auto-format** (F1): hook PostToolUse formata/lint após cada edit no nível ≥ 4 (consultivo, nunca bloqueia). - **Quality gates** (F2): `pre-push` roda os checks da stack (10 linguagens); avisa abaixo do `strictLevel`, bloqueia nele. Bypass `CONTEXT_SKIP_QGATES=1`. - **Coexistência de hook-manager** (F3): detecta husky/simple-git-hooks/`core.hooksPath` e sugere integração. - **CI Squad** (F5): Action opt-in (`--ci-squad`) issue→PR draft; requer `ANTHROPIC_API_KEY`. - **Promoção de padrões ≥3** (F7): `/distill-sessions` só promove regra com 3+ ocorrências; `/retro` deprecia por strikethrough. - **`/context-budget`** (F6): orçamento de contexto por tarefa + `@`-imports no `CLAUDE.md`. - **`marker-inject`** (F4): injeção idempotente entre ``. - **Bridges** (F8): contexto opt-in (`bridges.enabled`) p/ Cursor, Copilot, Gemini, Windsurf, Aider, Continue — **só contexto, sem enforcement**. ## Workflow spec pack Para features grandes e mudanças arquiteturais, `/workflow new ` cria `contextkit/memory/workflows//` com: - `prd.md` — PDR/PRD: WHAT/WHY, objetivos, usuários, métricas e não-escopo. - `spec.md` — SPEC técnica: HOW, impacto, interfaces, arquivos prováveis e testes. - `decisions.md` e `tasks.md` — índices para ADRs globais e cards do DevPipeline. - `memory.md` — handoffs duráveis que não pertencem a git, ADR, PRD, SPEC ou task. - `reports/YYYY-MM-DD.md` — relatório factual diário com diff summary e verificação. Fluxo canônico: ```text intake -> prd -> spec -> adr -> roadmap(se feature) -> pipeline -> ship -> testing -> conclusion ``` O spec pack não substitui roadmap, ADRs ou DevPipeline. Ele só amarra o contexto e a evidência. Cards podem ser criados com `--workflow ` e `--spec contextkit/memory/workflows//spec.md`; ao mover para `testing`, o pipeline carimba `implemented: YYYY-MM-DD`. ## Squads | Squad | Specialists | Quando | |---|---|---| | **devteam** | architect, code-reviewer, context-keeper, test-engineer | Design + revisão + memória | | **qa-team** | qa-orchestrator + unit/integration/fuzzer/perf/e2e | Testes | | **design-team** | ui-designer, ux-designer, accessibility, **seo-specialist**, **landing-architect** | UI/UX, WCAG AA, SEO+AISO, landing | | **security-team** | security, code-security, infra-security | Auth, deps, IaC | | **compliance-team** | privacy-lgpd, governance-officer | LGPD, políticas | | **ops-team** | devops | CI/CD, deploys | | **agent-forge** *(L6+)* | forge-orchestrator + 7 specialists | Pipeline pra Agent Packages portáveis | ## Engenharia de Domínio (BIZ-0003, ADR-0128) Capacidade determinística que dispara em trabalho de código real: classifica a intenção de mutação (CMIS), a aplicabilidade de domínio (DAS), exige o `implementation-engineer` em código e checa conformidade com o mapa de domínio. **Vem DESLIGADA por padrão** e é *fail-open* (qualquer erro sai 0 — um gate quebrado nunca bloqueia seu trabalho). - **Só quer ver o que o classificador decide?** `/domain ""` — só observação, não muda nada, não precisa ligar nada. - **Ligar:** em `contextkit/config.json` → `domainEngineering.enabled: true`. O `enforcement.rolloutStage` é um TETO que só *abaixa* a escada nível→modo (nunca sobe): avance `shadow → advisory → guarded → strict` conforme a calibração for limpa. - **Escada por nível:** L1–L3 inerte (só classifica) · L4 advisory · L5–L6 guarded · L7 strict. A virada para guarded/strict na frota é decisão **humana**. - **Rollback:** volte `rolloutStage` para `"shadow"` ou `enabled: false` — sem reparo de estado; a capacidade é reversível e absent-safe. - As 8 regras de fitness Classe A ficam armadas mas emitem **zero** findings até um projeto declarar um mapa de domínio — então o gate arch-debt continua verde. Guia completo (EN): `docs/how-to/use-domain-engineering.md`. ## Provider adapters *(novo)* Dois surfaces plugáveis sob `runtime/providers/`: - **`review/`** — adapters de CLI de PR (hoje: `gh`; adicione `glab.mjs` / `bb.mjs` no mesmo contrato). - **`media/`** — geração de mídia (hoje: `nano-banana` para imagem via Imagen 3 e `veo` para vídeo, ambos via `GOOGLE_AI_API_KEY` configurado em `contextkit/.env`). Setup do `/media-gen`: 1. Pega chave em https://aistudio.google.com/apikey 2. Copia `contextkit/.env.example` pra `contextkit/.env`, cola em `GOOGLE_AI_API_KEY=` 3. (Opcional) `CONTEXTDEVKIT_MEDIA_MAX_USD=5.00` pra capar custo por processo 4. Roda com `node --env-file=contextkit/.env contextkit/tools/scripts/media-gen.mjs ...` ## Boas práticas - **Onde começar:** projeto **vazio** → L3; projeto que **já tem código** → L7 (use tudo; os gates ficam inertes até configurar `highRiskPaths`). O instalador escolhe automaticamente. - **ADR antes** de decisão grande (`/new-adr`). ADR aceito é imutável. - **Registre a sessão** (`/log-session`) — veja seu `drift rate` em `/context-stats`. Se perdeu, `/resume`. - Ajuste `contextkit/config.json` → `ledger.*` ao seu stack (ou `/context-config`). - Mantenha o `CLAUDE.md` curto e com as regras imutáveis preenchidas. - Não edite arquivos gerados (`SESSIONS.md`, `WORKSPACE.md`, `tech-debt-board.md`, `dashboard.html`) — são regenerados. - Sessões paralelas → `/worktree-new` (nunca dois chats no mesmo diretório). - **Landing page?** Use `/landing-page` antes de codar — entrevista de estratégia, recusa SPA puro, define fold count e gera por script (`lp-scaffold.mjs` → preencha `lp/content/*.json` → `lp-build.mjs --check`): cookie consent por padrão, GTM sem ID (inerte), pixels só como modelos comentados, política de privacidade + termos gerados como minuta (ADR-0050). Imagery via `/media-gen` (sem stock photos genéricas). ## Manutenção - `/context-doctor` — saúde do install. `/context-stats` — métricas. - `/audit` — auditoria geral (bom agendar via `/loop` ou `/schedule`). - `/dashboard` — visual do estado em HTML; `--watch` em tempo real. - Atualizar o kit: rode o instalador de novo ou `npx contextdevkit@latest --target . --update`. Nunca modifica memória de autoria do usuário (ADRs, sessões, roadmap, regras de negócio, docs do projeto), config, pipeline tasks ou os dois arquivos de personalização. Nos arquivos raiz dos hosts, apenas o bloco delimitado que aponta para esses arquivos pode ser atualizado atomicamente; todo o restante permanece byte a byte. Artefatos derivados como o project-map podem ser gerados de forma transacional quando seguro (adiado com sessões ativas). Use `--allow-active-sessions` para prosseguir com sessões ativas (um snapshot é tirado antes); `--allow-self-update` ao atualizar o próprio repositório do kit. O update também refresca `contextkit/README.md` pelo caminho seguro de manifesto e regenera `docs/README.md`; o `README.md` raiz do seu produto continua sendo seu. Docs completos (inglês): `contextkit/README.md` e a pasta `docs/` do kit (`docs/ARCHITECTURE.md`, `docs/CUSTOMIZING.md`, `docs/SQUADS/design-team.md`, `docs/SQUADS/agent-forge.md`, `docs/LEVELS.md`).