Documentação

Cursor / agentes de IA

Como usar Cursor, Claude e outros agentes de IA com o Motoko Base — AGENTS.md, skills e prompting consciente da arquitetura.

Abrir emChatGPT Claude Cursor

O Motoko Base foi feito para desenvolvimento assistido por IA. Os agentes recebem instruções explícitas sobre onde o código vai, quais padrões seguir e como planejar mudanças com OpenSpec — para que a saída combine com um starter SaaS real, não com um tutorial genérico de Next.js.

Funciona com Cursor, Claude Code e outros agentes que leem instruções do projeto e skills.

Instruções do projeto

Dois arquivos definem como os agentes devem se comportar:

Arquivo	Papel
`AGENTS.md`	Posicionamento na arquitetura, padrões a seguir/evitar, demo vs core, comandos de verificação
`openspec/config.yaml`	Filosofia do produto, stack, regras de UI, regras por artefato para OpenSpec

CLAUDE.md aponta para AGENTS.md no Claude Code. O Cursor carrega AGENTS.md via workspace rules.

Antes de qualquer trabalho de feature, os agentes devem saber:

O código vai em src/features/<name>/, não espalhado em src/app/
Banco de dados e auth permanecem no servidor
Mutações usam Server Actions + Zod + ownership por userId
Integrações opcionais falham de forma suave quando o env não está definido

Skills e slash commands

O Motoko Base inclui skills OpenSpec que o agente carrega automaticamente:

.agents/skills/openspec-propose/
.agents/skills/openspec-apply-change/
.agents/skills/openspec-archive-change/
.agents/skills/openspec-explore/
.agents/skills/openspec-update-change/
.agents/skills/openspec-sync-specs/

No Cursor, os slash commands equivalentes ficam em .cursor/commands/:

Comando	Quando usar
`/opsx-explore`	Explorar ideias — sem código
`/opsx-propose`	Começar um novo change
`/opsx-update`	Revisar o plano
`/opsx-apply`	Implementar tarefas
`/opsx-archive`	Finalizar um change

Skills de domínio (Drizzle, Supabase Postgres) ficam em .agents/skills/ para trabalho de schema e queries.

Docs do Cursor: Cursor documentation

Como dar boas tarefas

Enquadre pedidos para que o agente permaneça dentro da arquitetura Motoko:

Fazer

/opsx-propose Add a notes demo under src/features/notes/
Reuse the links feature pattern: queries.ts, actions.ts, schemas.ts,
ownership via session userId, thin route in src/app/dashboard/notes/

/opsx-apply
Follow AGENTS.md — server-first, Zod at boundary, no new UI libraries

Add a nav item for Notes in src/features/dashboard/config/nav.ts

Evitar

Build a notes app with Redux and a separate API server

Put all logic in src/app/dashboard/notes/page.tsx

Skip auth checks for now, we'll add them later

Referências úteis para citar

Padrão	Aponte o agente aqui
Feature demo CRUD	`src/features/links/`
Upload de arquivos	`src/features/storage/`
Settings + sessions	`src/features/dashboard/components/settings/`
Integração de billing	`src/lib/billing/` + `src/features/dashboard/actions/billing.ts`
Nova tabela no banco	Adding a New Table
Auth	Better Auth

Diga se o trabalho é infraestrutura core, um padrão reutilizável ou uma demo removível — os agentes usam isso nas proposals do OpenSpec.

Cursor vs Claude Code

Ferramenta	Como o Motoko Base se conecta
Cursor	Regras do `AGENTS.md` + comandos `/opsx-*` + `.cursor/skills/`
Claude Code	`CLAUDE.md` → `AGENTS.md` + mesmo CLI/skills OpenSpec
Outros agentes	Ler `AGENTS.md`, `openspec/config.yaml`, executar o CLI `openspec` manualmente

Instale o OpenSpec CLI globalmente: installation guide

Verificações que os agentes devem rodar

AGENTS.md exige estas antes de concluir:

pnpm lint
pnpm typecheck
pnpm test
pnpm build

Peça ao agente para executá-las após /opsx-apply ou qualquer edição substancial.

Correções pequenas sem OpenSpec

Typos, mudanças de copy e bugs de uma linha não precisam de uma proposal completa. Use o chat normal:

Fix the typo on the billing page headline

Use OpenSpec quando a mudança tocar vários arquivos, adicionar comportamento ou precisar de requisitos revisáveis.

Fluxo de desenvolvimento com IA — Fluxo completo da ideia ao archive.

OpenSpec — Proposals, tasks, apply e archive.

Estrutura do projeto — Onde o código vive.