Documentação

Fluxo de desenvolvimento com IA

Como construir sobre o Motoko Base com agentes de IA — da ideia à revisão usando OpenSpec e Cursor.

O Motoko Base inclui um fluxo de trabalho com IA orientado a specs. Em vez de pedir a um agente que reescreva o app de uma vez, você planeja em artefatos OpenSpec, revisa o plano e depois implementa tarefa a tarefa. As mudanças permanecem delimitadas, revisáveis e alinhadas à arquitetura do starter.

Esse é um dos diferenciais do starter: você obtém padrões de produção e as ferramentas para estendê-los com segurança com IA.

O fluxo de trabalho

Idea
 ↓
OpenSpec (optional explore)
 ↓
Proposal
 ↓
Design
 ↓
Tasks
 ↓
Cursor / AI Agent (apply)
 ↓
Implementation
 ↓
Review → archive

Fase	O que você faz	Resultado
Idea	Descreve a feature ou correção no chat	Objetivo aproximado
Explore (opcional)	`/opsx-explore` — trade-offs, mapeamento do codebase	Escopo esclarecido, sem código
Proposal	`/opsx-propose` — o quê e por quê, non-goals	`proposal.md`
Design	Criado com o propose — como se encaixa no starter	`design.md`
Tasks	Passos com checkbox para o agente	`tasks.md`
Apply	`/opsx-apply` — implementa tarefas uma a uma	Mudanças de código
Review	Lê o diff, roda checks, testa manualmente	Aprovado ou revisar
Archive	`/opsx-archive` — sincroniza specs, move o change para o archive	`openspec/specs/` atualizado

Planejamento e implementação são passos separados. Propose não escreve código de produto. Apply espera até você iniciá-lo explicitamente.

Quando usar o fluxo completo

Situação	Usar OpenSpec?
Nova feature ou demo	Sim
Refatoração multiarquivo	Sim
Mudança transversal (auth, billing, schema)	Sim
Typo, ajuste de copy, bug de uma linha	Não — edição normal no chat

Exemplo de sessão

/opsx-explore Should team invites be a demo or core feature?

/opsx-propose Add team invites demo with ownership checks

# Review proposal.md, design.md, tasks.md — edit or /opsx-update if needed

/opsx-apply

pnpm lint && pnpm typecheck && pnpm test && pnpm build

/opsx-archive

Pré-requisitos

OpenSpec CLI instalado globalmente (npm install -g @fission-ai/openspec@latest)
Cursor (ou outro agente que carregue .agents/skills/)
Ler AGENTS.md na raiz do repositório — regras de arquitetura que os agentes seguem

O repositório já está inicializado — não é necessário openspec init.

Depois da implementação

Execute as verificações do starter antes de fazer merge:

pnpm lint
pnpm typecheck
pnpm test
pnpm build

Aponte o agente para uma feature existente (ex.: src/features/links/) como modelo para trabalho novo.

OpenSpec — Artefatos, comandos, apply e archive em detalhe.

Cursor / AI Agents — AGENTS.md, skills e como fazer prompts dentro da arquitetura Motoko.