Ir para o conteúdo

00 — Instalação e Setup (pré-requisito de todos os workflows)

Este documento é o ponto de partida obrigatório. Execute-o uma vez por repositório antes de rodar qualquer workflow. Todos os outros docs de workflow assumem que esta etapa foi concluída.

Referência canônica: o README.md na raiz do repo. Este doc é o resumo operacional orientado a "o time vai instalar e começar a usar".

Visão geral da instalação

1. Pré-requisitos        → Node 24.15.0 + ambiente de IA (Claude Code / IDE / browser)
2. Configurar MCP        → conecta agentes ao Azure DevOps OU GitHub  (recomendado)
3. Instalar o kit        → npx ... init  (copia .claude, .ns-flow, .speckit, scripts)
4. Bootstrap do Speckit  → /bootstrap-repo  (popula a base de conhecimento)
        ↓
   Pronto para rodar qualquer workflow

Passo 1 — Escolher o caminho de execução

O kit funciona em três cenários. Escolha conforme as restrições corporativas do time.

Caminho Quando usar Como os agentes são acionados
A — Claude Code (recomendado) Terminal liberado + conta Anthropic Slash commands nativos (/feature, /analyze-bug...)
B — Cursor / VS Code + IA IDE com Claude/Copilot/Gemini Cola o conteúdo do agente em .claude/agents/ no chat
C — IA no browser Terminal/internet restritos Copia o prompt do agente e cola no chat web

Caminho A — Claude Code (automação completa)

# Node.js 24.15.0 (versão esperada)
node --version          # deve retornar v24.15.0

# Instalar o Claude Code
npm install -g @anthropic/claude-code

# Login — requer conta Anthropic (plano Max ou API key)
claude login

# Confirmar
claude --version

Com Claude Code, todos os slash commands rodam nativamente no terminal.

Nos caminhos B e C o fluxo é semi-manual: rode o bootstrap via terminal, abra o arquivo do agente em .claude/agents/, cole no chat da IDE/browser e salve os artifacts em .ns-flow/ manualmente.

Passo 2 — Configurar MCP (recomendado)

MCPs permitem que os agentes leiam e escrevam tickets direto no provider — sem copiar/colar. O kit suporta dois providers, escolhidos por projeto:

Provider MCP Refiner Ticket ID
Azure DevOps (Boards + Repos) @azure-devops/mcp azure-card-refiner ADO-{num}
GitHub (Issues + Repos) @modelcontextprotocol/server-github github-issue-refiner GH-{num}

Setup interativo

npx @nstechhub/corporate-ns-flow-kit setup-mcp
# ou explicitamente:
npx @nstechhub/corporate-ns-flow-kit setup-mcp --provider azure-devops
npx @nstechhub/corporate-ns-flow-kit setup-mcp --provider github

O setup-mcp faz, em ordem:

  1. Detecta conflito de user scope — user scope tem precedência sobre project scope; ele oferece remover o user scope (recomendado) para o .mcp.json do projeto valer.
  2. Pergunta o modo de autenticação:
  3. Azure DevOps: az login (padrão) ou PAT (ambientes com login interativo bloqueado).
  4. GitHub: gh-cli (padrão) ou PAT.
  5. Coleta os valores que alimentam o refiner (organização/owner, caminho-raiz das aplicações locais, diretório de briefings, projetos/repos em ordem de prioridade).
  6. Gera os arquivos:
  7. .mcp.json — valores literais, sem depender de env vars.
  8. .claude/.local-config.json — fonte da verdade de caminhos, projetos e ticketIdPattern.
  9. .gitignore — adiciona os dois acima (evita commit de credencial/caminho pessoal).
  10. Verifica e roda smoke test das credenciais — você descobre problema de acesso antes do primeiro /analyze-bug, não no meio dele.

Verificar se o MCP está ativo

claude mcp list
# deve mostrar o provider com status "Connected" e vir de Project MCPs (não User MCPs)

Segurança: o PAT precisa ser redigitado a cada setup-mcp (só o email é lembrado). O token fica apenas no .mcp.json local, que está no .gitignore — nunca é commitado nem vai para o npm.

(Opcional) Comentários automáticos nos checkpoints

Cada um dos 4 checkpoints humanos pode postar um comentário curto na issue/work-item de origem. Desligado por default. Para habilitar, no .claude/.local-config.json:

{
  "checkpointNotifications": {
    "enabled": true,
    "postToProvider": true,
    "mentions": ["@reviewer-handle"]
  }
}

Passo 3 — Instalar o kit no repositório

Via npx (recomendado)

cd /caminho/do/seu/repo
npx @nstechhub/corporate-ns-flow-kit init
# --force para sobrescrever arquivos existentes

O comando aplica chmod +x scripts/*.sh automaticamente no Linux/macOS.

O que é instalado

Pasta/Arquivo Função
.claude/ Agentes, comandos, políticas e contexto operacional
.ns-flow/ Onde os artifacts de cada ticket são salvos
.speckit/ Base de conhecimento do sistema (preenchida no Passo 4)
scripts/ Bootstrap, update e inicialização de tickets
migrations/ Templates para scripts de banco versionados
CLAUDE.md Instruções lidas automaticamente pelo Claude Code

Passo 4 — Bootstrap do Speckit

O Speckit é a base de conhecimento institucional que todos os workflows consultam. Sem ele, os agentes investigam do zero a cada ticket.

/bootstrap-repo SISTEMA [--stack dotnet|node|java|...]

Gera: Speckit completo + CLAUDE.md + ARCHITECTURE.md + PATTERNS.md + context docs.

Para projetos de security, rode também /bootstrap-security (popula cwe-catalog.md e os wrappers SAST em tools/). Pré-requisito do Vulnerability Flow.

Para manter a base atualizada periodicamente: /update-speckit SISTEMA [--since data].

Passo 5 — Configurar a Esteira de Qualidade (opcional, recomendado)

Para os gates de qualidade rodarem (cobertura · smoke · E2E · security), preencha o bloco quality no .claude/.local-config.json com os comandos reais do seu stack — ver exemplo em .local-config.example.json:

"quality": {
  "coverageThresholds": { "P1": 100, "P2": 100, "P3": 90, "P4": 80 },
  "stackCommands": { "test": "...", "coverage": "...", "smoke": "...", "e2e": "" },
  "e2e": { "engine": "playwright", "hmlBaseUrls": {}, "credentialsEnv": { "user": "...", "pass": "..." } }
}

Sem isso, os gates reportam "não configurado" (não passam silenciosamente). Credenciais sempre por env var (referência por nome), nunca literais. Detalhes em Quality Layer e no Guia do QA Owner.

Credenciais do E2E (Gate 3). Os nomes das variáveis vão em quality.e2e.credentialsEnv; os valores ficam num .env local (gitignorado) — copie de .env.example e preencha com um usuário de homologação (nunca produção nem pessoal). O qa-expert nunca digita a senha: um script de login local lê o .env, autentica uma vez e salva o storageState em .qa-auth/ (também gitignorado), que o Gate 3 reutiliza. No CI, os valores vêm do secret store da pipeline (Azure DevOps Library / Key Vault). Ver Login e credenciais.

Passo 6 — Instalar plugins (opcional)

Plugins estendem o kit com capacidades opcionais: - ns-flow-obsidian-mind — cofre de conhecimento compartilhado (git). - ns-flow-movidesk — integração read-only com o Movidesk. - ns-flow-aws — MCP da AWS (foco SQS). Pré-req: uv/uvx (Python) + credenciais AWS. - ns-flow-azure-cloud — MCP do Azure (foco Service Bus; ≠ azure-devops). Pré-req: az login.

O caminho recomendado é via marketplace do Claude Code:

/plugin marketplace add nstechhub/corporate-ns-flow-kit
/plugin install ns-flow-obsidian-mind@ns-flow-kit
/plugin install ns-flow-movidesk@ns-flow-kit
/plugin install ns-flow-aws@ns-flow-kit
/plugin install ns-flow-azure-cloud@ns-flow-kit

Como alternativa, instale via CLI do kit: npx @nstechhub/corporate-ns-flow-kit install-plugin <nome>. Catálogo e detalhes na seção Plugins do README.

Checklist de prontidão

Antes de iniciar o primeiro ticket, confirme:

  • [ ] claude --version responde (Caminho A) ou IDE/browser com IA disponível (B/C)
  • [ ] claude mcp list mostra o provider Connected (se usar MCP)
  • [ ] .claude/, .ns-flow/ e .speckit/ existem no repo
  • [ ] .claude/.local-config.json tem ticketIdPattern correto (ADO- ou GH-)
  • [ ] /bootstrap-repo rodou e .speckit/ está populado (não só [DRAFT])
  • [ ] .mcp.json e .claude/.local-config.json estão no .gitignore

✅ Tudo marcado → siga para o workflow desejado no índice.

Onde definir variáveis por projeto

No CLAUDE.md do projeto, sem alterar o framework:

ARTIFACTS_DIR: .ns-flow     # diretório de artifacts gerados por ticket
SPECKIT_DIR:   .speckit     # base de conhecimento institucional

O ticketIdPattern (ADO-{num} / GH-{num}) vive em .claude/.local-config.json.

Voltar ao topo