Documentación

Cursor / agentes de IA

Cómo usar Cursor, Claude y otros agentes de IA con Motoko Base — AGENTS.md, skills y prompting consciente de la arquitectura.

Abrir enChatGPT Claude Cursor

Motoko Base está pensado para el desarrollo asistido por IA. Los agentes reciben instrucciones explícitas sobre dónde va el código, qué patrones seguir y cómo planificar cambios con OpenSpec — para que la salida coincida con un starter SaaS real, no con un tutorial genérico de Next.js.

Funciona con Cursor, Claude Code y otros agentes que leen instrucciones del proyecto y skills.

Instrucciones del proyecto

Dos archivos definen cómo deben comportarse los agentes:

Archivo	Rol
`AGENTS.md`	Ubicación en la arquitectura, patrones a seguir/evitar, demo vs core, comandos de comprobación
`openspec/config.yaml`	Filosofía del producto, stack, reglas de UI, reglas por artefacto para OpenSpec

CLAUDE.md apunta a AGENTS.md para Claude Code. Cursor carga AGENTS.md vía workspace rules.

Antes de cualquier trabajo de feature, los agentes deben saber:

El código va en src/features/<name>/, no disperso en src/app/
La base de datos y la auth permanecen en el servidor
Las mutaciones usan Server Actions + Zod + ownership por userId
Las integraciones opcionales fallan de forma suave cuando falta el env

Skills y slash commands

Motoko Base incluye skills de OpenSpec que el agente carga automáticamente:

.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/

En Cursor, los slash commands equivalentes viven en .cursor/commands/:

Comando	Cuándo usarlo
`/opsx-explore`	Explorar ideas — sin código
`/opsx-propose`	Empezar un change nuevo
`/opsx-update`	Revisar el plan
`/opsx-apply`	Implementar tareas
`/opsx-archive`	Finalizar un change

Los skills de dominio (Drizzle, Supabase Postgres) viven en .agents/skills/ para trabajo de schema y queries.

Docs de Cursor: Cursor documentation

Cómo dar buenas tareas

Enmarca las peticiones para que el agente se mantenga dentro de la arquitectura Motoko:

Hacer

/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

Referencias útiles a citar

Patrón	Señala al agente aquí
Feature demo CRUD	`src/features/links/`
Subidas de archivos	`src/features/storage/`
Settings + sessions	`src/features/dashboard/components/settings/`
Integración de billing	`src/lib/billing/` + `src/features/dashboard/actions/billing.ts`
Nueva tabla de base de datos	Adding a New Table
Auth	Better Auth

Indica si el trabajo es infraestructura core, un patrón reutilizable o un demo eliminable — los agentes lo usan en las proposals de OpenSpec.

Cursor vs Claude Code

Herramienta	Cómo se engancha Motoko Base
Cursor	Reglas de `AGENTS.md` + comandos `/opsx-*` + `.cursor/skills/`
Claude Code	`CLAUDE.md` → `AGENTS.md` + mismo CLI/skills de OpenSpec
Otros agentes	Leer `AGENTS.md`, `openspec/config.yaml`, ejecutar el CLI `openspec` a mano

Instala OpenSpec CLI globalmente: installation guide

Comprobaciones que deben ejecutar los agentes

AGENTS.md exige estas antes de terminar:

pnpm lint
pnpm typecheck
pnpm test
pnpm build

Pide al agente que las ejecute tras /opsx-apply o cualquier edición sustancial.

Correcciones pequeñas sin OpenSpec

Errores tipográficos, cambios de copy y bugs de una línea no necesitan una proposal completa. Usa el chat normal:

Fix the typo on the billing page headline

Usa OpenSpec cuando el cambio toque varios archivos, añada comportamiento o necesite requisitos revisables.

Flujo de desarrollo con IA — Flujo completo de la idea al archive.

OpenSpec — Proposals, tasks, apply y archive.

Estructura del proyecto — Dónde vive el código.