W3: Claude Code + Cortex

O que é Cortex

Cortex é um sistema de desenvolvimento criado por jsvitolo (GitHub: jsvitolo/cortex-releases) que transforma o Claude Code em uma plataforma de engenharia com memória persistente e orquestração automatizada. Onde o Claude Code Solo resolve uma tarefa por sessão, o Cortex acumula conhecimento entre sessões e coordena agentes especializados em cada fase do ciclo de desenvolvimento.

A arquitetura é composta por três camadas integradas:

• CLI (cx): Binário standalone que gerencia tarefas, inicializa o projeto, abre o dashboard e dispara comandos de alto nível como cx init, cx ui e cx status.
• MCP server: Expõe 65+ ferramentas que o Claude Code consome nativamente para criar tarefas, persistir memória semântica, navegar pelo codebase via LSP e transitar estados no kanban.
• Plugin de skills para Claude Code: Instalado via /plugin install, adiciona slash commands como /cortex:implement, /cortex:plan, /cortex:pr e /cortex:session-end diretamente na REPL.

Quando usar vs. não usar

Instalação

O Cortex é distribuído via Homebrew tap oficial. A instalação completa — incluindo CLI, MCP server e configuração de projeto — leva menos de 5 minutos em uma máquina com Homebrew instalado.

# 1. Instalar o CLI cx via Homebrew
brew tap jsvitolo/tap && brew install cx

# 2. Verificar instalação
cx --version

# 3. Inicializar Cortex no projeto
cd meu-projeto
cx init
# Cria: .cortex/ (DB local), .claude/CLAUDE.md atualizado com regras Cortex,
# e registra o MCP server no settings.json do Claude Code

# 4. Instalar o plugin de skills dentro de uma sessão Claude Code
/plugin marketplace add jsvitolo/cortex-plugins
/plugin install cortex@cortex-plugins
# Adiciona: /cortex:plan, /cortex:brainstorm, /cortex:implement,
#           /cortex:pr, /cortex:merge, /cortex:session-end

# 5. Configurar OpenAI API key (necessário para memória semântica com vetores)
export OPENAI_API_KEY=sk-...
# Ou adicionar ao ~/.zshrc / ~/.bashrc para persistir entre sessões
echo 'export OPENAI_API_KEY=sk-...' >> ~/.zshrc

# Sem OPENAI_API_KEY: Cortex usa apenas FTS5 (busca por texto).
# Com OPENAI_API_KEY: habilita HNSW vectors para busca semântica por similaridade.

# 6. Abrir dashboard visual (kanban + memória + logs de agentes)
cx ui
# Abre no navegador padrão em http://localhost:3737

O que cx init cria no projeto

meu-projeto/
  .cortex/
    cortex.db          # SQLite com FTS5 + HNSW: memória e tarefas
    config.json        # Configuração do MCP server local
  .claude/
    settings.json      # MCP server registrado automaticamente
    CLAUDE.md          # Regras Cortex injetadas (segurança, TDD, padrões)
  CORTEX.md            # Visão geral do projeto para o research agent

Diagrama do Workflow

O workflow Cortex conecta a intenção do desenvolvedor a um pipeline automatizado de 3 agentes, com memória semântica como entrada e saída de cada ciclo. A task é o eixo central — tudo gira em torno de uma referência CX-N rastreável.

Cada transição de estado (task create → progress → review → done) é persistida no banco local do Cortex e exposta no dashboard cx ui. O Claude Code acessa esses estados via MCP tools sem polling manual pelo desenvolvedor.

Os 3 Agentes do /implement

O comando /cortex:implement CX-N é o coração operacional do Cortex. Ele spawna três subagentes em sequência, cada um com contexto isolado e responsabilidade exclusiva. Essa separação é intencional: evita que o implement agent carregue o peso da análise do codebase, e evita que o verify agent seja influenciado pelo viés do implement agent.

Research Agent

Responsabilidade única: compreender o território antes de qualquer linha de código ser escrita.

• Lê o codebase completo usando LSP navigation (go-to-definition, find-references, call hierarchy)
• Busca na memória semântica do Cortex por decisões arquiteturais e padrões do time relacionados à task
• Identifica os arquivos que serão modificados e seus contratos de interface
• Produz RESEARCH.md: contexto compactado passado ao implement agent

# RESEARCH.md — output do research agent (exemplo)
## Task: CX-12 — Adicionar rate limiting no endpoint /api/orders

### Padrões encontrados no codebase
- Rate limiting já implementado em /api/auth (src/middleware/rateLimit.ts)
- Padrão: sliding window com Redis, chave composta userId+IP
- Configuração via env: RATE_LIMIT_WINDOW_MS, RATE_LIMIT_MAX_REQUESTS

### Memória semântica relevante
- [ADR-2024-03] Decidimos usar sliding window (não token bucket) por menor jitter
- [Incidente-2024-11] Rate limit por IP apenas causou falso positivo em CG-NAT — sempre incluir userId

### Arquivos a modificar
- src/middleware/rateLimit.ts (adicionar config para /api/orders)
- src/api/orders/route.ts (aplicar middleware)
- src/api/orders/orders.test.ts (testes de integração do rate limit)

Implement Agent

Responsabilidade única: implementar TDD-first usando exclusivamente o contexto do RESEARCH.md. Nunca re-lê o codebase inteiro — parte do mapa já construído pelo research agent.

• Escreve o teste antes da implementação (Red phase)
• Implementa o mínimo para passar (Green phase)
• Refatora mantendo os testes passando (Refactor phase)
• Respeita padrões identificados pelo research agent — sem reinventar wheel
• Produz IMPLEMENT.md: resumo das mudanças e decisões tomadas durante a implementação

# Ciclo TDD dentro do implement agent
# RED: escreve teste que falha
npm test -- src/api/orders/orders.test.ts  # deve falhar

# GREEN: implementa mínimo
# ... código de produção ...
npm test -- src/api/orders/orders.test.ts  # deve passar

# REFACTOR: limpa sem quebrar
npm test -- src/api/orders/orders.test.ts  # ainda deve passar

# Smoke test geral antes de passar ao verify agent
npm test

Verify Agent

Responsabilidade única: validar sem viés. Recebe o código implementado e o IMPLEMENT.md, mas nunca viu o processo de implementação — avalia o resultado como um revisor externo.

• Executa a pirâmide de testes completa: unit, integration, E2E se aplicável
• Realiza code review focado em OWASP Top 10 e SOLID
• Executa npm audit e verifica vulnerabilidades em dependências novas
• Se reprovar: retorna feedback estruturado ao implement agent (loop de debug)
• Se aprovar: transita task para review e sinaliza para /cortex:pr

# Checklist do verify agent (executado automaticamente)
npm test                          # todos os testes
npm run test:integration          # testes de integração
npm audit --audit-level=high      # vulnerabilidades de dependências
# Code review interno via mcp__cortex__review()

Memória Semântica

A memória do Cortex é o diferencial que separa este workflow de qualquer outra automação de Claude Code. Em vez de começar cada sessão do zero, o research agent encontra decisões arquiteturais anteriores, padrões consolidados do time e histórico de incidentes — reduzindo drasticamente perguntas repetidas e retrabalho.

Como funciona internamente

O banco SQLite em .cortex/cortex.db usa dois mecanismos complementares:

• FTS5 (Full-Text Search): Busca lexical rápida por termos exatos, disponível sem OPENAI_API_KEY. Ideal para recuperar entradas com termos técnicos precisos como nomes de função, IDs de incidente ou siglas de padrão.
• HNSW vectors (Hierarchical Navigable Small World): Busca por similaridade semântica usando embeddings OpenAI. Encontra entradas conceitualmente relacionadas mesmo que não compartilhem termos exatos. Requer OPENAI_API_KEY.

O que salvar na memória

# Tipos de entrada recomendados

type: "diary"
  Decisões arquiteturais (por que X em vez de Y)
  Resultado de spike técnico (o que foi testado e concluído)
  Padrões consolidados do time após PR review

type: "security"
  Incidentes OWASP e suas correções
  Auditoria de dependências com vulnerabilidades encontradas
  Decisões de configuração de segurança em produção

type: "pattern"
  Exemplos de implementação de referência no codebase
  Anti-patterns identificados e por que foram eliminados
  Contratos de interface entre módulos críticos

type: "incident"
  Post-mortems de falhas em produção
  Root cause + fix + medidas preventivas

Como salvar via MCP tools

# Salvar uma decisão arquitetural (dentro de uma sessão Claude Code)
mcp__cortex__memory(
  action="save",
  type="diary",
  title="Rate limiting: sliding window escolhida sobre token bucket",
  content="Optamos por sliding window no endpoint /api/orders por menor jitter
           em picos de tráfego. Token bucket causava burst concentrado no
           início de cada janela. Referência: ADR-2024-03.",
  tags=["rate-limiting", "performance", "api"]
)

# Salvar incidente de segurança
mcp__cortex__memory(
  action="save",
  type="security",
  title="OWASP A01 - Rate limit por IP causou falso positivo em CG-NAT",
  content="Usuários em redes corporativas com CG-NAT compartilham IP.
           Rate limit por IP bloqueou 40+ usuários legítimos. Fix: chave
           composta userId+IP. Qualquer novo rate limit deve usar essa chave.",
  tags=["owasp-a01", "rate-limiting", "incident"]
)

Como acessar e buscar

# Listar entradas recentes
mcp__cortex__memory(action="list")

# Busca por termo (FTS5)
mcp__cortex__memory(action="list", search="rate limiting")

# Busca semântica (HNSW — requer OPENAI_API_KEY)
mcp__cortex__memory(action="search", query="como autenticar requests entre serviços")

# Acessar entrada específica por ID
mcp__cortex__memory(action="get", id="mem_abc123")

Task Lifecycle

Cada unidade de trabalho no Cortex é uma task com identificador CX-N — rastreável, persistida no banco local e visível no dashboard. O lifecycle é um pipeline linear com quatro estados, cada transição disparada por uma MCP tool ou slash command.

backlog  →  in-progress  →  review  →  done
   |              |              |         |
task create    implement    verify    cortex:pr
               /cortex:    aprovado    + merge
              implement

Transições via MCP tools

# Criar task (entra em backlog)
mcp__cortex__task(
  action="create",
  title="Adicionar rate limiting em /api/orders",
  description="...",
  priority="high"
)
# Retorna: { id: "CX-12", status: "backlog" }

# Iniciar task (backlog → in-progress)
mcp__cortex__task(action="start", id="CX-12")

# Mover para review (in-progress → review)
mcp__cortex__task(action="review", id="CX-12")

# Concluir (review → done)
mcp__cortex__task(action="done", id="CX-12")

# Listar tasks por status
mcp__cortex__task(action="list", status="in-progress")

# Ver detalhes de task específica
mcp__cortex__task(action="get", id="CX-12")

Dashboard cx ui

O comando cx ui abre um dashboard local em http://localhost:3737 com três painéis principais:

• Kanban: Visão de todas as tasks por status — backlog, in-progress, review, done. Arrastar cards actualiza o status via MCP automaticamente.
• Memória: Interface de busca sobre o banco semântico. Permite criar, editar e desativar entradas de memória sem usar a CLI ou MCP diretamente.
• Logs: Histórico de execução dos agentes — research, implement e verify — com tokens consumidos, duração e resultado de cada ciclo.

TDD + OWASP no Cortex

O Cortex não apenas executa TDD como uma prática recomendada — ele a torna estruturalmente obrigatória ao separar implement agent e verify agent em processos independentes. O mesmo princípio se aplica à segurança: o verify agent executa um scan OWASP-aware em todo ciclo, e incidentes encontrados são salvos na memória para evitar reincidência.

Como o verify agent aplica TDD check

O verify agent recebe o output do implement agent e valida que o ciclo Red-Green-Refactor foi respeitado estruturalmente:

• Verifica que os arquivos de teste existiam antes dos arquivos de implementação (via git log --diff-filter=A)
• Confere que o teste falhou no commit Red (esperado) e passou nos commits subsequentes
• Rejeita PRs onde a implementação foi criada antes do teste — devolve ao implement agent com instrução explícita

# Verificação de ordem TDD executada pelo verify agent
git log --diff-filter=A --name-only --pretty=format: HEAD~5..HEAD \
  | grep -E '\.(test|spec)\.(ts|js)$'
# Deve listar os arquivos de teste ANTES dos arquivos de implementação correspondentes

# Se a ordem estiver errada, o verify agent retorna:
# { status: "rejected", reason: "TDD_ORDER_VIOLATION",
#   detail: "src/api/orders/route.ts criado antes de orders.test.ts" }

CLAUDE.md gerado pelo cx init

O bloco de regras injetado pelo cx init inclui diretivas de segurança que o Claude Code respeita em toda sessão:

## Cortex Rules (geradas por cx init)

### TDD obrigatório
- NUNCA implementar antes de escrever o teste
- Ciclo obrigatório: Red → Green → Refactor
- Qualquer código sem teste correspondente será rejeitado pelo verify agent

### Segurança (OWASP)
- Parâmetros SQL sempre via prepared statements — nunca string concatenation (A03)
- Secrets e API keys somente via env vars — nunca hardcoded (A02)
- Autenticação obrigatória em todas as rotas — revisar A01 e A07 em cada nova rota
- npm audit --audit-level=high antes de qualquer PR (A06)

### Tasks
- SEMPRE criar task via mcp__cortex__task antes de implementar
- NUNCA pular a fase de research — usar mcp__cortex__memory para buscar contexto

Salvando incidentes OWASP na memória

Quando o verify agent encontra uma vulnerabilidade ou quando um incidente de segurança ocorre em produção, o padrão é salvar na memória do Cortex para que o research agent alerte proativamente em tasks futuras relacionadas:

# Exemplo: verify agent encontrou potencial SQL injection
mcp__cortex__memory(
  action="save",
  type="security",
  title="OWASP A03 - SQL injection detectado em CX-15",
  content="Implement agent usou string concatenation em query de busca de pedidos.
           Rejeitado pelo verify agent. Fix obrigatório: Prisma parameterized queries.
           Padrão correto: prisma.order.findMany({ where: { userId: userId } })
           Nunca: db.query(`SELECT * FROM orders WHERE userId = ${userId}`)",
  tags=["owasp-a03", "sql-injection", "database", "orders"]
)

# O research agent irá encontrar esta entrada em tasks futuras que envolvam
# queries de banco — prevenindo a reincidência antes da implementação.

OWASP Top 10 no pipeline Cortex

Armadilhas

O Cortex é uma ferramenta poderosa mas não universal. Engenheiros que adotam sem entender suas limitações perdem tempo corrigindo problemas que deveriam ter antecipado.

Memória stale — decisões desatualizadas

A memória semântica não tem mecanismo automático de expiração. Uma decisão arquitetural registrada há 8 meses pode estar obsoleta, mas o research agent a recupera com o mesmo peso de uma decisão recente.

Como gerenciar:

• Adicionar campo valid_until nas entradas de memória de decisão arquitetural
• Criar task de manutenção mensal: revisar entradas da memória e desativar as obsoletas via cx ui ou mcp__cortex__memory(action="archive", id="...")
• Usar ADRs versionados no Git como fonte de verdade para decisões críticas — memória do Cortex como cache de acesso rápido, não como fonte autoritativa
• Incluir data explícita no content de entradas de decisão: "Decisão tomada em 2024-11 baseada em Next.js 14 — revisar se atualizar para Next.js 15+"

Overhead de setup não vale para projetos curtos

O cx init leva minutos, mas o benefício real da memória semântica começa a aparecer apenas após semanas de uso — quando há decisões acumuladas suficientes para o research agent recuperar contexto útil. Em projetos com prazo menor que 2 semanas ou proofs-of-concept descartáveis, o overhead de:

• Configurar e manter o MCP server
• Treinar a equipe nas MCP tools do Cortex
• Criar e revisar entradas de memória após cada sessão
• Depurar falhas no pipeline 3-agentes

...supera o benefício. Use Claude Code Solo ou GSD nesses casos.

Conflito com GSD — papéis precisam ser claros

GSD e Cortex podem coexistir no mesmo repositório, mas têm áreas de responsabilidade que se sobrepõem se não forem delimitadas explicitamente:

Regra de coexistência recomendada: Use GSD para planejamento macro (milestones, roadmap, fases) e Cortex para execução micro (tasks individuais, memória semântica, pipeline de implementação). Evite duplicar entidades — uma task não deve existir simultaneamente como GSD phase e CX-N task sem mapeamento explícito entre os dois sistemas.

Hooks neste workflow

No Cortex, os hooks trabalham em conjunto com o verify agent do /cortex:implement. O verify agent faz revisão semântica; os hooks fazem os gates mecânicos determinísticos.

settings.json para W3 Cortex

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{"type": "command", "command": "node scripts/quality-gate.mjs \"$CLAUDE_TOOL_INPUT_FILE_PATH\""}]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{"type": "command", "command": "node scripts/bash-guard.mjs"}]
      }
    ]
  }
}

Scripts completos (quality-gate.mjs, bash-guard.mjs) no Módulo 22 — Fundamentos.