⚡ zark-dev v2.1

Metodologia + CLI para desenvolvimento guiado por IA. Não só um scaffolder — um workflow completo.

Novo na v2.1: a escolha de stack virou uma entrevista guiada (6 perguntas) com recomendação baseada no seu contexto — sem mais "Cloudflare é sempre o default". Veja Fluxo do start abaixo.

Instalação e uso

Requisito: Node ≥ 20.

# Novo projeto (greenfield)
npx zark-dev@latest start <nome-do-projeto>

# Auditar projeto existente (brownfield)
npx zark-dev@latest audit

# Diagnóstico do scaffold instalado
npx zark-dev@latest doctor

# Migrar de v1.x para v2.0
npx zark-dev@latest migrate

# Ajuda
npx zark-dev@latest help

Sem instalação global necessária — npx sempre puxa a versão mais recente.

O que é

zark-dev v2.0 é uma metodologia empacotada em CLI para quem desenvolve software com assistência de IA (Claude, Cursor, Codex, Gemini). Ele consolida:

• 12 episódios de experiência real da série de Rafael Quintanilha sobre desenvolvimento guiado por IA — o que funciona, o que quebra, e por quê.
• Práticas sênior de produção — arquitetura, segurança, orquestração de modelos, discovery estruturado.
• Context files e regras que fazem o assistente de IA entender seu projeto, não um projeto genérico.
• Playbooks executáveis (greenfield e brownfield) que guiam da descoberta ao deploy.

Não é só um scaffold: é um workflow que você instala uma vez e usa todo dia com a IA.

Comandos

⚡ start — Novo projeto (greenfield)

npx zark-dev@latest start minha-saas

O fluxo padrão entrevista você sobre contexto (problema, usuário, proposta de valor) e stack (6 perguntas: experiência, linguagens, tipo de projeto, hosting, orçamento, escala). Com base nas respostas, a CLI recomenda 2–3 combos com prós, contras e custo, você escolhe, e só então o scaffold sai pronto — incluindo ADR-001 justificando a decisão.

Três modos:

# 1. Interativo (default) — entrevista + recomendação + ADR
npx zark-dev@latest start minha-saas

# 2. Stack direta — pula entrevista, escolhe combo por slug
npx zark-dev@latest start minha-saas --stack-combo vercel-next

# 3. Só metodologia — scaffold sem stack; você/IA decidem depois
npx zark-dev@latest start minha-saas --methodology-only

Em qualquer modo você ganha:

• .ai-context/ completo (CONTEXT, RULES, STATE, DECISIONS)
• methodology/ com os 6 playbooks (inclui stack-selection.md)
• PROJECT.md, SPEC.md, INITIAL-PROMPT.md populados com o que você respondeu
• Symlinks CLAUDE.md / AGENT.md / GEMINI.md / .cursorrules apontando para o contexto
• .gitignore e README.md iniciais

E quando escolhe uma stack via entrevista, ganha também:

• Template shippable pronto (ex: monorepo pnpm/turborepo, ou Next.js single-repo)
• docs/decisions/001-stack-choice.md — ADR com as respostas da entrevista + justificativa

Flags principais:

• --stack-combo <slug> — pula entrevista e usa o combo direto
• --methodology-only — scaffold sem stack (deixa IA entrevistar depois via INITIAL-PROMPT.md)
• --skip-interview — alias de --methodology-only
• --problem, --user, --value-prop, --monetization, --level — pré-preenchem a entrevista de produto
• --yes / -y — aceita defaults, pula confirmação final
• --no-git — não inicializa repo git

Slugs P0 disponíveis hoje: cloudflare-next, vercel-next. Slugs planejados: railway-node, cpanel-laravel, supabase-next, vps-coolify, railway-django.

🔍 audit — Projeto existente (brownfield)

cd meu-projeto-existente
npx zark-dev@latest audit

Analisa um repositório já existente e gera apenas os arquivos de contexto e metodologia, sem tocar no código. Ideal para trazer a metodologia para um codebase legado.

Cria/adiciona:

• .ai-context/ (CONTEXT, RULES, STATE, DECISIONS pré-preenchidos com heurísticas do repo)
• methodology/ (playbooks)
• SPEC.md e INITIAL-PROMPT.md no modo brownfield (apontando para o playbook E1–E8 de estabilização)
• Symlinks de IA (sem sobrescrever se já existir)

Flags principais:

• --force — sobrescreve arquivos existentes
• --dry-run — lista o que seria criado, sem escrever

🩺 doctor — Diagnóstico

npx zark-dev@latest doctor

Verifica se o scaffold do projeto atual está íntegro:

• Arquivos de contexto presentes e não vazios
• Symlinks válidos (CLAUDE.md, AGENT.md, GEMINI.md, .cursorrules)
• Playbooks de methodology/ presentes
• Versão do Node e do zark-dev compatíveis

Retorna exit code 0 se tudo ok, 1 com relatório se houver problemas.

🔄 migrate — v1 → v2

npx zark-dev@latest migrate

Migra projetos scaffoldados com zark-dev v1.x para a estrutura v2.0:

• Renomeia artefatos conforme o CHANGELOG
• Cria os novos living docs (STATE.md, DECISIONS.md, PROJECT.md, INITIAL-PROMPT.md)
• Substitui docs/prompts-dev.md por INITIAL-PROMPT.md
• Adiciona GEMINI.md na raiz (mantém .gemini/GEMINI.md por compat)
• Imprime resumo do que mudou

Sempre faz backup antes (.zark-backup-<timestamp>/).

help

npx zark-dev@latest help
npx zark-dev@latest help start

Lista todos os comandos ou mostra detalhes de um comando específico.

Estrutura gerada

Greenfield (zark-dev start):

minha-saas/
├── .ai-context/
│   ├── CONTEXT.md         # O que o projeto é, stack, constraints
│   ├── RULES.md           # Regras de código/arquitetura para a IA
│   ├── STATE.md           # Onde estamos no momento (living doc)
│   └── DECISIONS.md       # ADRs / decisões arquiteturais
├── methodology/
│   ├── METHODOLOGY.md
│   ├── stack-selection.md
│   ├── greenfield-playbook.md
│   ├── brownfield-playbook.md
│   ├── model-orchestration.md
│   └── security-baseline.md
├── docs/
│   └── decisions/
│       └── 001-stack-choice.md  # só se a entrevista rodou
├── PROJECT.md             # Visão, escopo, usuários-alvo
├── SPEC.md                # Especificação funcional
├── INITIAL-PROMPT.md      # Prompt inicial para a IA
├── README.md
├── CLAUDE.md        →  .ai-context/CONTEXT.md  (symlink)
├── AGENT.md         →  .ai-context/CONTEXT.md  (symlink)
├── GEMINI.md        →  .ai-context/CONTEXT.md  (symlink)
├── .cursorrules     →  .ai-context/RULES.md    (symlink)
├── .gitignore
└── (opcional) arquivos da stack escolhida — ex:
    apps/web, apps/api, packages/shared, wrangler.toml  (cloudflare-next)
    src/app, src/db, next.config.ts, drizzle.config.ts   (vercel-next)

Brownfield (zark-dev audit — mesma estrutura, porém sem tocar em código existente, e com SPEC.md / INITIAL-PROMPT.md orientados ao playbook de estabilização E1–E8).

Metodologia incluída

Copiados para methodology/ em cada projeto:

| Arquivo | Conteúdo | |---|---| | METHODOLOGY.md | Princípios: context-first, living docs, model orchestration, security baseline, stack follows context. | | stack-selection.md | Framework de escolha de stack: 6 perguntas, 9 combos, matriz de decisão, template de ADR-001. | | greenfield-playbook.md | Fluxo DISCOVERY → DESIGN → BUILD → HARDEN → LAUNCH para projetos do zero, com M0 mapeado por combo. | | brownfield-playbook.md | Fases E1–E8 de estabilização: mapeamento, testes de rede, refactors seguros, débito técnico, segurança, observabilidade. | | model-orchestration.md | Qual IA usar para cada tarefa: Claude (arquitetura/refactor longo), Codex/Copilot (completar linha), Gemini (análise de imagem/code review), Cursor (edição em contexto). | | security-baseline.md | Checklist de segurança obrigatório por milestone: secrets, authz, input validation, deps, logs. |

Todos são markdown puro — você lê, aplica, e a IA lê junto com você.

⚠️ BREAKING CHANGES vs v1.x

A v2.0 é uma reescrita. Principais mudanças (ver CHANGELOG.md completo):

| v1.x | v2.0 | |---|---| | zark-dev init | zark-dev audit (brownfield) | | zark-dev new | zark-dev start (greenfield) | | docs/prompts-dev.md | INITIAL-PROMPT.md na raiz | | Node ≥ 18 | Node ≥ 20 | | — | Novos living docs: STATE.md, DECISIONS.md, PROJECT.md | | — | GEMINI.md na raiz (além de .gemini/GEMINI.md) | | — | methodology/ com 5 playbooks |

Para migrar um projeto existente:

cd meu-projeto-v1
npx zark-dev@latest migrate

O comando preserva backup completo antes de tocar em qualquer arquivo.

Desenvolvimento do próprio zark-dev

Para hackear no CLI:

git clone https://github.com/mayconjordanr/zark-dev.git
cd zark-dev/zark-dev-v2
pnpm install
pnpm run test         # vitest, 88 testes
pnpm run type-check   # tsc --noEmit
pnpm run lint         # eslint
pnpm run build        # tsup -> dist/
pnpm run dev          # tsup --watch

Para testar o CLI localmente depois do build:

node ./dist/cli.js start meu-teste

Stack:

• TypeScript + ESM (bundle via tsup)
• @inquirer/prompts para o wizard interativo
• handlebars para templating de arquivos
• picocolors para output colorido
• vitest com threshold ≥ 80% de cobertura

Créditos

Baseado na série de vídeos de Rafael Quintanilha sobre desenvolvimento guiado por IA (12 episódios) + práticas sênior de produção.

Mantido por Maycon Jordan.

Licença

MIT © Maycon Jordan