Cursor + Spec Kit

Guia completo do dia a dia no Cursor neste monorepo — além do que o README resume em setup Git e pnpm.

Expand table full width

Regras automáticas do agente: .cursor/rules/development-workflow.mdc (go-horse vs spec) · .cursor/rules/server-ssh.mdc (prod/local/SSH/psql)

---

Modelo do dia a dia

Como funciona na prática: você descreve o que quer (texto livre, pt-BR). A IA monta a spec inteira. Depois roda o pipeline de chats abaixo — implement → revisão → browser → você testa no final.

Você atua só no início (spec + revisão) e no fim (teste manual). O meio fica com a IA em chats separados, enfileirados no Cursor.

O que você escreve no Prompt 1 (Chat 1)

Bloco livre. Quanto mais concreto, melhor a spec:

• Nome do módulo (ex.: CRM Kanban)
• Comportamento (drag-and-drop, colunas ordenáveis, etc.)
• Regras de negócio (triggers, tempo em coluna, ações)
• Integrações (chamada API, webhook, e-mail)
• Fora de escopo (o que não entra nesta entrega)

O que a IA entrega de uma vez (antes de codar)

Expand table full width

Regras de arquitetura (a IA aplica ao escrever plan/tasks):

• UI / drag-drop / dashboards → apps/app
• Triggers, filas, execução de ações → apps/service
• Schema, permissions → apps/hasura
• Lógica crítica não só no frontend

Billing/auth sensível: incluir checklist security e cenários de permissão por company.

Teste rápido (10 segundos)

1. Inventa capacidade nova? → Faixa 3 — Prompt 1 abaixo (spec completa de uma vez)
2. Muda contrato (API, permissão, schema, billing)? → Faixa 2–3
3. Só conserta ou melhora o que já existe? → Faixa 1 (go-horse)

Na dúvida entre 1 e 2: go-horse + nota retro na spec se fizer sentido depois.

O que NÃO é go-horse: começar Fase 4 sem specs v1 fechadas; módulo novo sem linha em product/04 e spec; mudar billing/auth/multi-tenant sem revisar spec do módulo.

---

Processo recomendado — pipeline de chats

flowchart LR
    H1[Você — Chat 1<br/>Spec] --> R[Você revisa spec]
    R --> C2[Chat 2 — fila<br/>Implement]
    C2 --> C3[Chat 3 — fila<br/>Revisão código]
    C3 --> C4[Chat 4 — fila<br/>Browser QA]
    C4 --> H2[Você — teste final]

Expand table full width

Enfileirar: abra os chats 2–4, cole os prompts, dispare em sequência. Você não precisa esperar cada um terminar para escrever o próximo — só para validar gates críticos se quiser.

Pré-requisito implement/browser: pnpm cloud:up && pnpm dev (app :3001, service :3002).

---

Prompt 1 — Chat 1: Criar spec (só documentação, sem código)

Modelo: forte para requisitos e edge cases (ex.: Opus).

Exemplo com CRM Kanban (adaptável a qualquer feature):

Crie a spec completa para o módulo CRM Kanban (faixa 3 — feature nova).

Funcionalidade:
- Board estilo Kanban com drag-and-drop de cards entre colunas
- Colunas criadas/editadas/reordenadas pelo usuário (por company)
- Coluna exemplo "Novo lead" — card representa um lead/deal
- Sistema de triggers por coluna, estilo "quando/com":
  - Ex.: se lead permanece em "Novo lead" por 2 horas → disparar ação
  - Ações: chamada HTTP (webhook/API), e-mail, ou ação interna registrada
- Triggers configuráveis por coluna (tempo na coluna, evento de entrada/saída)
- Multi-tenant: dados isolados por company (usar auth + company existentes)

Siga templates .specify/ e specs/_example/:
1. pnpm spec:new com número alinhado a specs/README.md
2. spec.md com user stories P1/P2, FR-xxx, edge cases
3. plan.md e tasks.md completos
4. Atualize product/04 e specs/README.md
5. NÃO implemente código ainda — só artefatos da spec

Versão curta (quando já sabe o escopo):

Crie a spec completa para [descreva a funcionalidade].

Entregue de uma vez: pnpm spec:new, spec.md, plan.md, tasks.md, checklists/requirements.md,
linha em product/04 e specs/README.md. Templates .specify/ + specs/_example/.
NÃO implemente código ainda.

Você: abre specs/NNN-nome/, lê user stories e FR-xxx. Se ok → Chat 2. Se não → ajuste no mesmo chat.

---

Prompt 2 — Chat 2: Implement

Spec pequena/média — um agente, spec inteira:

Implemente specs/NNN-nome/ inteira conforme tasks.md.
Marque [x] nas tasks concluídas. Rode pnpm lint nos apps afetados.
Não commite.

Spec grande — multi-agent por faixa de tasks (você define no prompt):

Implemente specs/NNN-crm-kanban/ em multi-agent:

- Agente A: tasks T001–T010 (schema Hasura + service base)
- Agente B: tasks T011–T020 (API triggers + jobs)
- Agente C: tasks T021–T030 (UI Kanban app)

Cada agente: worktree ou branch isolada se necessário. Ao final integrar, lint.
Não commite.

Ver ondas e dependências: specs/README.md · spec-kit-parallel.mdc

---

Prompt 3 — Chat 3: Revisão de implementação

Modelo: robusto — olhar diff e aderência à spec.

Revise a implementação de specs/NNN-nome/ contra spec.md e plan.md.

- Liste FR-xxx não cobertos ou divergentes
- Corrija o que faltar (código + tasks.md [x])
- pnpm lint — zero erros
- Não commite

---

Prompt 4 — Chat 4: Browser QA (usuário de teste)

Modelo: com acesso a browser tool (MCP).

Valide specs/NNN-nome/ no browser com pnpm dev rodando.

- URL: http://localhost:3001
- Login: usuário de testes
- Percorra TODOS os cenários de aceite P1 em spec.md
- Se falhar: corrija (go-horse) e re-teste até passar
- Resumo: o que passou / o que corrigiu

---

Prompt 5 — Chat 5: Aceite humano (você)

Checklist rápido antes de shipped:

• Fluxo principal faz sentido de produto (não só “compila”)
• Multi-tenant / permissões se aplicável
• Pedir commit: feat(app): … (hook gera changelog)
• Atualizar specs/README.md → shipped

Go-horse depois do aceite: polish e bugfix → chat único, sem nova spec.

Depois de validar:

• "Marque specs/NNN-nome/ como shipped em specs/README.md e product/04."
• "Crie commit: feat(app): add CRM kanban with column triggers" — só quando você pedir

---

Atalhos e variantes

Feature pequena (1 chat)

Para escopo pequeno e baixo risco, pode juntar spec + implement:

Desenvolva a funcionalidade [descrição curta]: crie spec completa em specs/NNN-nome/,
implemente, lint, valide no browser. Siga templates .specify/ e CURSOR.md.

Use o pipeline de 4 chats acima para módulos grandes (CRM, billing, auth).

Comandos slash (opcionais)

Para módulos sensíveis (auth, billing): /speckit.clarify → /speckit.checklist security → /speckit.analyze → /speckit.implement.

Spec completa via Prompt 1 ou /speckit.specify (equivalentes).

Modelo resumido

Se a feature for pequena, pode colapsar chats 2–4 num só. Para spec completa (CRM, billing…), use o pipeline de 4 chats acima.

Expand table full width

Correção / polish / hotfix → go-horse — um chat, sem spec.

---

Resumo Spec Kit

• Spec Kit — define specs em specs/NNN-nome/ (spec.md, plan.md, tasks.md via Chat 1 ou /speckit.specify)
• Multi-agent — 1 agente por spec (ou por faixa de tasks); ver pipeline Chat 2 acima
• Regras do agente — .cursor/rules/spec-kit*.mdc (agent-requested) · go-horse → development-workflow.mdc

Cheat sheet — atalhos

Expand table full width

Cheat sheet — comandos

Spec Kit

Expand table full width

Fluxo: Chat 1 (spec completa) → /speckit.implement · Produção (auth, billing): incluir /speckit.clarify, /speckit.checklist security, /speckit.analyze.

Dev local e deploy

Expand table full width

Ops — servidor e banco (prod)

Credenciais em .env na raiz (copie de .env.example). O agente não precisa que você cole connection string no chat — use estes comandos.

Expand table full width

Detalhes, variáveis e novos scripts: scripts/README.md · Regra do agente: .cursor/rules/server-ssh.mdc

---

Ops — servidor, Docker e Postgres

Setup uma vez — depois peça no chat sem repetir IP ou senha.

1. Preencher .env na raiz

Scripts em scripts/ carregam o .env automaticamente (load-root-env.sh → ssh-env.sh monta SSH_TARGET).

cp .env.example .env
# editar .env com SERVER_IP e DATABASE_URL_* (ver .env.example)

Expand table full width

SSH: chave default em ~/.ssh + SERVER_IP no .env. Teste: ./scripts/prod/server-ssh.sh 'echo ok'.

2. O que pedir no Cursor (prompts prontos)

Docker / servidor:

Lista os containers docker em produção e resume status e portas.

Mostra as últimas 100 linhas de log do framework-service em prod.

No servidor de produção, verifica se framework-postgres e framework-hasura estão healthy.

O agente deve usar pnpm server:docker ou ./scripts/prod/server-ssh.sh — não pedir IP/host no chat.

Banco (prod):

Roda em produção: SELECT count(*) FROM users;

Lista as 10 companies mais recentes em prod (created_at DESC).

No banco local, quantos registros existem na tabela plans?

O agente deve usar pnpm db:query -- "…" (prod) ou pnpm db:query -- --local "…".

Investigação combinada:

Em prod: status docker dos containers framework-* e depois SELECT count(*) FROM users no postgres.

2b. Cloud greenfield (primeira vez)

Guia completo com prompts copy-paste: cloud/BOOTSTRAP.md.

Pré-requisito: DIGITALOCEAN_TOKEN no .env raiz (ver .env.example).

Fase 1 — Digital Ocean:

Provisiona a infraestrutura Digital Ocean conforme cloud/BOOTSTRAP.md Fase 1.
Ler packages/brand/src/config.ts para domínios e slug. Usar MCP DO. Não commitar secrets.

Fase 2 — Dokploy + GitHub:

Instala Dokploy e autoriza GitHub no painel conforme cloud/BOOTSTRAP.md Fase 2.
SSH: ./scripts/prod/server-ssh.sh | Browser: GitHub logado no browser tool.

Fase 3 — Deploy completo (modelo forte, ex. Opus + browser):

Configura projeto e todos os serviços no Dokploy conforme cloud/BOOTSTRAP.md Fase 3.
Usar browser tool para confirmar serviços Running e URLs públicas. Rodar pnpm dokploy:health ao final.

3. Usuário de teste (browser QA)

Para Prompt 4 e testes manuais em localhost:

Expand table full width

4. Segurança (prod)

• O agente confirma com você antes de DROP, TRUNCATE, restart em massa ou alteração de volumes
• Nunca colar secrets no chat — mantenha só no .env gitignored
• Preferir pnpm db:query (read-only pontual) a psql interativo quando for só investigação

---

Sempre use pnpm spec:new — nunca mkdir specs/006-... manual.

Passe flags e descrição após -- (ex.: pnpm spec:new -- --short-name "nome" "Descrição").

Nova feature (número automático)

O script escolhe o próximo número (006, 007, …) e cria specs/NNN-nome/ + spec.md template:

pnpm spec:new -- \
  --short-name "core-module" \
  "Core module — main value proposition for the product"

Resultado esperado: specs/006-core-module/ (número pode variar se já existir).

Nova feature (número fixo)

Quando você já sabe o número da spec (ex.: alinhado ao índice em specs/README.md):

pnpm spec:new -- \
  --number 7 \
  --short-name "reports-dashboard" \
  "Reports dashboard for customer accounts"

Resultado: specs/007-reports-dashboard/

Spec retroativa (pasta já existe ou código já shipped)

pnpm spec:new -- \
  --allow-existing-branch --number 1 --short-name "auth-module" \
  "Auth module — registration, login, OAuth, session"

Preview sem criar arquivos

pnpm spec:new:dry-run -- --short-name "core-module" "Core module"

Depois de criar a pasta

O pnpm spec:new cria três coisas:

specs/006-core-module/
├── spec.md          ← template para preencher
└── …

.specify/feature.json   ← aponta para a spec que você acabou de criar (feature ativa)

Feature ativa

Feature ativa = a spec em que o Spec Kit está trabalhando agora.

| Registro | .specify/feature.json → "feature_directory": "specs/006-analyzer-core" | | Atualiza quando | pnpm spec:new (última criada) ou pnpm spec:use (troca manual) | | Usado por | pnpm spec:check, /speckit.implement |

Definir feature ativa por número ou nome:

pnpm spec:use -- 6                              # specs/006-*/
pnpm spec:use -- --number 7
pnpm spec:use -- --short-name storage           # specs/*-storage
pnpm spec:use -- specs/006-storage            # path completo

Um chat / um agente = uma feature ativa.

Trocar de spec no chat (sem terminal):

"Trabalhe em specs/006-storage/"

Multi-agent: cada subagente com pnpm spec:use ou SPECIFY_FEATURE_DIRECTORY ou path no prompt.

Próximos passos (ordem)

Expand table full width

Produção (auth, billing): entre os passos 1 e 3, inclua /speckit.clarify, /speckit.checklist security e /speckit.analyze.

Fechar o ciclo

• Atualize specs/README.md e product/04-features-modules.md
• Quando shipped: marque status no índice e tasks [x] em tasks.md

Documentação relacionada

Expand table full width