Documentation

Cursor / agents IA

Comment utiliser Cursor, Claude et d’autres agents IA avec Motoko Base — AGENTS.md, skills et prompting conscient de l’architecture.

Ouvrir dansChatGPT Claude Cursor

Motoko Base est conçu pour le développement assisté par IA. Les agents reçoivent des instructions explicites sur où placer le code, quels patterns suivre et comment planifier les changements via OpenSpec — pour que le résultat corresponde à un vrai starter SaaS, pas à un tutoriel Next.js générique.

Fonctionne avec Cursor, Claude Code et d’autres agents qui lisent les instructions du projet et les skills.

Instructions du projet

Deux fichiers définissent le comportement des agents :

Fichier	Rôle
`AGENTS.md`	Emplacement d’architecture, patterns à suivre/éviter, démo vs core, commandes de contrôle
`openspec/config.yaml`	Philosophie produit, stack, règles UI, règles par artefact pour OpenSpec

CLAUDE.md pointe vers AGENTS.md pour Claude Code. Cursor charge AGENTS.md via les workspace rules.

Avant tout travail de feature, les agents doivent savoir :

Le code va dans src/features/<name>/, pas dispersé dans src/app/
La base de données et l’auth restent côté serveur
Les mutations utilisent Server Actions + Zod + ownership via userId
Les intégrations optionnelles échouent en douceur si l’env est absent

Skills et slash commands

Motoko Base inclut des skills OpenSpec que l’agent charge automatiquement :

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

Dans Cursor, les slash commands correspondantes vivent dans .cursor/commands/ :

Commande	Quand l’utiliser
`/opsx-explore`	Explorer des idées — pas de code
`/opsx-propose`	Démarrer un nouveau change
`/opsx-update`	Réviser le plan
`/opsx-apply`	Implémenter les tâches
`/opsx-archive`	Terminer un change

Les skills de domaine (Drizzle, Supabase Postgres) vivent dans .agents/skills/ pour le travail de schema et de queries.

Docs Cursor : Cursor documentation

Comment donner de bonnes tâches

Cadrez les demandes pour que l’agent reste dans l’architecture Motoko :

À faire

/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

À éviter

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

Références utiles à citer

Pattern	Pointer l’agent ici
Feature démo CRUD	`src/features/links/`
Uploads de fichiers	`src/features/storage/`
Settings + sessions	`src/features/dashboard/components/settings/`
Intégration billing	`src/lib/billing/` + `src/features/dashboard/actions/billing.ts`
Nouvelle table de base de données	Adding a New Table
Auth	Better Auth

Indiquez si le travail est de l’infrastructure core, un pattern réutilisable ou une démo amovible — les agents s’en servent dans les proposals OpenSpec.

Cursor vs Claude Code

Outil	Comment Motoko Base s’y branche
Cursor	Règles `AGENTS.md` + commandes `/opsx-*` + `.cursor/skills/`
Claude Code	`CLAUDE.md` → `AGENTS.md` + mêmes CLI/skills OpenSpec
Autres agents	Lire `AGENTS.md`, `openspec/config.yaml`, exécuter le CLI `openspec` manuellement

Installez OpenSpec CLI globalement : installation guide

Checks que les agents doivent lancer

AGENTS.md exige ceux-ci avant de terminer :

pnpm lint
pnpm typecheck
pnpm test
pnpm build

Demandez à l’agent de les lancer après /opsx-apply ou toute modification substantielle.

Petits correctifs sans OpenSpec

Typos, changements de copy et bugs d’une ligne n’ont pas besoin d’une proposal complète. Utilisez le chat normal :

Fix the typo on the billing page headline

Utilisez OpenSpec quand le changement touche plusieurs fichiers, ajoute du comportement ou nécessite des exigences revues.

Flux de développement IA — Flux complet de l’idée à l’archive.

OpenSpec — Proposals, tasks, apply et archive.

Structure du projet — Où vit le code.