Ambiente de desenvolvimento com Claude Code: seguro e reproduzível

Um computador novo ou um repositório recém-clonado não deveria consumir metade do dia antes do primeiro commit útil. Os problemas se repetem: versão errada do Node.js, mistura de npm e pnpm, .env antigo, volumes do Docker com dados de outro schema e comandos locais que ninguém documentou. Claude Code pode acelerar tudo isso, mas só fica seguro quando o ambiente tem limites claros.

A meta não é pedir “configure tudo” e confiar. A meta é criar um setup reproduzível em que toda pessoa e toda sessão do Claude Code usem as mesmas instruções, o mesmo gerenciador de pacotes, as mesmas regras de segredo e os mesmos comandos de verificação.

Use a documentação oficial como base: Claude Code setup, settings, permissions e hooks. Para continuar no ClaudeCodeLab, veja guia inicial, boas práticas de CLAUDE.md e guia de hooks.

flowchart TD
  A["Verificar ferramentas"] --> B["Fixar Node e gerenciador de pacotes"]
  B --> C["Criar dependências e .env.example"]
  C --> D["Registrar regras em CLAUDE.md"]
  D --> E["Limitar permissões em settings.json"]
  E --> F["Bloquear comandos perigosos com hooks"]
  F --> G["Rodar doctor, env check e testes"]

Política do ambiente

Trate o ambiente de desenvolvimento como código de produção. Se a regra importa, ela deve estar versionada. Se um segredo importa, ele não deve entrar no contexto do agente. Se um comando pode apagar dados ou publicar código, ele deve pedir aprovação humana.

Área	Arquivo ou comando	Por que importa
Runtime	.nvmrc, packageManager, Corepack	Evita divergência de Node e pnpm
Segredos	.env.example, .gitignore, permissions.deny	Mantém credenciais fora de prompts e commits
Memória do projeto	CLAUDE.md	Carrega as regras em cada sessão
Permissões	.claude/settings.json	Controla leitura, Bash e modo padrão
Hooks	.claude/hooks/*	Aplica bloqueios determinísticos
Verificação	doctor, check:env, test	Troca impressão por evidência

Bootstrap para copiar

O script funciona em Git Bash, WSL, macOS ou Linux. Ele cria um projeto TypeScript mínimo, valida variáveis de ambiente, fixa pnpm, nega leitura de segredos e adiciona um hook PreToolUse.

#!/usr/bin/env bash
set -euo pipefail

APP_DIR="${1:-claude-dev-lab}"
mkdir -p "$APP_DIR"
cd "$APP_DIR"

command -v node >/dev/null || { echo "Node.js é obrigatório"; exit 1; }
command -v claude >/dev/null || { echo "Claude Code CLI é obrigatório"; exit 1; }

corepack enable
corepack prepare pnpm@9.15.4 --activate

cat > package.json <<'JSON'
{
  "name": "claude-dev-lab",
  "private": true,
  "type": "module",
  "packageManager": "pnpm@9.15.4",
  "scripts": {
    "doctor": "node --version && pnpm --version && claude --version",
    "check:env": "tsx src/env.ts",
    "test": "vitest run --passWithNoTests"
  },
  "dependencies": {
    "dotenv": "latest",
    "zod": "latest"
  },
  "devDependencies": {
    "@types/node": "latest",
    "tsx": "latest",
    "typescript": "latest",
    "vitest": "latest"
  }
}
JSON

mkdir -p src .claude/hooks .vscode
printf "22\n" > .nvmrc
cat > .gitignore <<'EOF'
node_modules
.env
.env.*
!.env.example
dist
coverage
EOF

cat > .env.example <<'EOF'
NODE_ENV=development
DATABASE_URL=postgresql://app:app@localhost:5432/app
REDIS_URL=redis://localhost:6379
EOF

cat > src/env.ts <<'TS'
import { config } from "dotenv";
import { z } from "zod";

config();

const Env = z.object({
  NODE_ENV: z.enum(["development", "test", "production"]).default("development"),
  DATABASE_URL: z.string().url(),
  REDIS_URL: z.string().url().optional()
});

const parsed = Env.safeParse(process.env);
if (!parsed.success) {
  console.error(parsed.error.flatten().fieldErrors);
  process.exit(1);
}

console.log("env ok", {
  nodeEnv: parsed.data.NODE_ENV,
  hasRedis: Boolean(parsed.data.REDIS_URL)
});
TS

cat > CLAUDE.md <<'EOF'
# Instruções do projeto

## Configuração do ambiente
- Use a versão de Node indicada em `.nvmrc`.
- Use pnpm via Corepack. Não troque para npm nem yarn.
- Copie `.env.example` para `.env` localmente e edite os valores manualmente.
- Nunca leia, imprima ou faça commit de `.env` ou arquivos secretos.
- Antes de alterar código, rode `pnpm run doctor` e `pnpm run check:env`.
- Depois de alterar código, rode o teste mais específico e registre o resultado.

## Regras de trabalho
- Comece explorando e propondo um plano curto.
- Não execute comandos destrutivos nem deploys sem aprovação humana explícita.
- Mantenha mudanças de setup em arquivos reproduzíveis, não apenas no histórico do terminal.
EOF

cat > .claude/hooks/block-dangerous.mjs <<'JS'
import { readFileSync } from "node:fs";

const input = JSON.parse(readFileSync(0, "utf8") || "{}");
const command = String(input.tool_input?.command ?? "");

const blockedPatterns = [
  /rm\s+-rf\s+(\/|~|\$HOME)/,
  /git\s+push\b/,
  /curl\b.+\|\s*(bash|sh)/,
  /Invoke-WebRequest\b.+\|\s*iex/i
];

if (blockedPatterns.some((pattern) => pattern.test(command))) {
  console.log(JSON.stringify({
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Comando perigoso bloqueado. Uma pessoa deve revisar objetivo e alvo."
    }
  }));
} else {
  console.log("{}");
}
JS

cat > .claude/settings.json <<'JSON'
{
  "defaultMode": "plan",
  "permissions": {
    "allow": [
      "Read",
      "Bash(pnpm install)",
      "Bash(pnpm run *)",
      "Bash(git status *)",
      "Bash(claude --version)",
      "Bash(claude doctor)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push *)",
      "Bash(rm -rf *)"
    ]
  },
  "env": {
    "CLAUDE_CODE_SUBPROCESS_ENV_SCRUB": "1"
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node .claude/hooks/block-dangerous.mjs"
          }
        ]
      }
    ]
  }
}
JSON

pnpm install
cp .env.example .env
pnpm run doctor
pnpm run check:env
pnpm test

No Windows nativo, valide a cadeia de ferramentas:

winget install Anthropic.ClaudeCode
claude --version
claude doctor
node --version
corepack enable
pnpm --version

Se pnpm --version falhar, corrija Node/Corepack antes de mexer no projeto. Se claude doctor apontar proxy, certificado ou login, salve o erro exato e peça um diagnóstico com essa restrição.

Prompt mais seguro

claude -p "
Audite e complete a configuração do ambiente de desenvolvimento deste repositório.

Regras:
- Não leia .env, .env.* nem arquivos em secrets/
- Siga packageManager; não troque pnpm por npm ou yarn
- Não apague volumes Docker nem execute git push

Permitido:
- Ler README, package.json, CLAUDE.md e .claude/settings.json
- Executar pnpm install, pnpm run doctor, pnpm run check:env e pnpm test

Retorne um recibo curto com comandos executados, arquivos alterados, falhas encontradas e passos manuais restantes.
"

Casos de uso

Caso	Como ajuda
Novo protótipo SaaS	Adiciona PostgreSQL e Redis com Docker Compose mantendo o setup reproduzível
Repositório de equipe	Claude Code lê docs, roda checks permitidos e melhora onboarding
Site de conteúdo ou produto	Protege CTA, analytics, OGP e páginas sensíveis para AdSense
Ferramenta interna	Padroniza seed de banco, filas, mocks e testes

Para projetos com Docker, continue em Docker Compose. Para colaboração, leia trabalho em equipe com Claude Code. Para CI, conecte esses comandos ao setup de CI/CD.

Falhas comuns

Não misture gerenciadores de pacotes. Se existe pnpm-lock.yaml, não deixe o agente rodar npm install. Registre a regra em CLAUDE.md e mantenha packageManager no package.json.

Não deixe Claude Code ler .env. O arquivo revisável é .env.example; valores reais ficam locais. Use .gitignore e permissions.deny juntos.

Cuidado com volumes Docker. Um volume antigo pode fazer uma migração correta parecer quebrada. Antes de apagar, peça a explicação do alvo, do risco e da alternativa.

Evite bypassPermissions na máquina principal. Use apenas em contêiner ou VM isolados. Revise hooks de repositórios não confiáveis antes de iniciar a sessão.

Checklist

• claude --version e claude doctor funcionam
• Existe .nvmrc ou .node-version
• package.json contém packageManager
• Há apenas um lockfile
• .env.example está atualizado e .env é ignorado
• CLAUDE.md documenta setup, proibições e checks
• .claude/settings.json bloqueia segredos, git push e comandos destrutivos
• O recibo final inclui comandos e resultados

CTA e resultado

Um ambiente instável pode quebrar links de compra, formulários, analytics ou páginas com anúncios. Para transformar isso em fluxo reutilizável, comece pela cola gratuita, veja produtos ou leve o processo ao time com treinamento.

Testei o fluxo criando o projeto mínimo, instalando dependências, copiando .env.example e rodando pnpm run doctor, pnpm run check:env e pnpm test. As proteções mais úteis foram negar leitura de .env e bloquear git push ou comandos destrutivos via hook. Na rotina de Masa, falhas de setup quase sempre vêm de pressupostos não documentados, não de comandos difíceis.