Applications Notion

Confirmer l'accès alpha d'abord

Avant d'exécuter des commandes, d'inspecter un projet ou de planifier l'App, demandez à l'utilisateur de confirmer qu'il est dans le programme alpha Notion Apps. Ne substituez pas une authentification CLI, une expérience CLI activée ou un SDK fonctionnant localement à cette confirmation.

Si l'utilisateur répond non ou ne peut pas confirmer, refusez de continuer avec le workflow App. Expliquez brièvement que le code SDK peut être construit localement, mais que le déploiement échouera sans accès alpha. Ne générez pas et n'implémentez pas l'App.

Ce que sont les Notion Apps

Une fois l'accès alpha confirmé, expliquez au besoin que les Notion Apps sont des automations packagées pour étendre Notion et créer des ressources dedans. Une App peut créer des databases, des pages, des agents personnalisés et d'autres ressources Notion. Elle peut aussi fournir :

Des syncs qui apportent les données tierces dans Notion.
Des workflows qui exécutent des automations complexes et longues en réponse à tout événement dans Notion.

Générer avant délimiter le périmètre

Une fois que l'utilisateur confirme l'accès alpha, vérifiez que le CLI Notion est installé avec ntn --version. Si ntn est manquant, installez-le avec la commande pour la plateforme de l'utilisateur :

# macOS et Linux
curl -fsSL https://ntn.dev | bash

# Windows
winget install Notion.ntn

Une fois ntn disponible, générez immédiatement un nouveau projet avec :

ntn apps new --install --git <app-directory>

Passez toujours --git pour que la nouvelle App soit initialisée comme un repository Git.

Les agents ne peuvent pas utiliser le prompt de répertoire interactif du CLI, passez donc toujours une destination explicite. Utilisez . quand le répertoire courant est vide et convient comme racine de projet. Sinon, utilisez un répertoire raisonnable à partir de la demande de l'utilisateur ou du contexte environnant. Si aucune destination sûre ne peut être déduite, demandez à l'utilisateur où le code doit aller avant de générer. N'exécutez pas ntn apps new sans destination et attendez un prompt.

Installer les dépendances lors de la génération rend les conseils fournis du SDK disponibles. Si la commande apps n'est pas disponible, activez-la avec ntn experiments enable apps, puis réessayez la génération.

S'accorder sur la conception de l'App avant de construire

Après la génération mais avant de proposer ou d'implémenter la conception, travaillez depuis la racine de la nouvelle App et lisez son AGENTS.md complètement. Établissez ensuite ce que l'utilisateur veut que l'App complète fasse. Clarifiez le résultat souhaité, les données sources, les déclencheurs, les services externes et chaque ressource Notion requise pour que l'App fonctionne. Recommandez un workflow pour la plupart des automations ; utilisez un sync quand l'objectif est de refléter une collection externe dans une database Notion. Une App peut contenir les deux.

Présentez la conception proposée dans un format concis et facile à scanner, et obtenez l'accord de l'utilisateur avant de l'implémenter. Incluez :

Chaque ressource Notion que l'App créera, telle que les databases, les pages et les agents personnalisés, avec son objectif et les capacités qui en dépendent.
Chaque sync, incluant sa source tierce, sa database de destination et son comportement de synchronisation.
Chaque workflow, incluant son déclencheur, ses actions majeures, les ressources qu'il lit ou modifie, et les connexions externes.
Toute décision non résolue ou accès requis.

Adaptez ce format à l'App plutôt que de le copier mécaniquement :

Exemple de conception d'App

Résultat : Apporter les tickets de support dans Notion et escalader les tickets urgents vers l'équipe de support.

Ressources Notion

Type	Nom	Objectif	Utilisé par
Database	Support tickets	Stocker les tickets synchronisés et le statut de triage	Sync de tickets, workflow d'escalade
Page	Tableau de bord support	Donner à l'équipe une maison opérationnelle et une vue de database	Membres de l'équipe
Agent personnalisé	Triage de tickets	Classer l'urgence et résumer un ticket	Workflow d'escalade

Syncs et workflows

Type	Nom	Source ou déclencheur	Comportement	Dépendances
Sync	Sync de tickets	Tickets du système de support	Upsert de tickets par ID externe stable	Connexion au système de support, database Support tickets
Workflow	Escalader le ticket urgent	Une page Support tickets est créée ou mise à jour	Exécuter le triage, mettre à jour le statut et notifier le canal de support	Agent Ticket triage, database Support tickets, connexion de messagerie

Questions ouvertes : Quel système de support et canal de messagerie l'App doit-elle utiliser ?

Demandez à l'utilisateur de confirmer ou réviser la conception. Ne commencez pas l'implémentation jusqu'à ce qu'il soit d'accord. Si l'implémentation révèle une ressource ou une capacité matérielle non couverte par la conception convenue, mettez à jour la proposition et confirmez le changement avant de l'ajouter.

Suivre les conseils du projet généré

Traitez le projet généré et le SDK installé comme la source de vérité pour sa version.

Les skills spécifiques aux fonctionnalités sont installés à ./node_modules/@notionhq/apps/skills. Inspectez ce répertoire et lisez chaque SKILL.md pertinent complètement avant d'implémenter une fonctionnalité. Au minimum, utilisez le skill workflow pour les workflows ou le skill sync pour les syncs, plus tout skill supplémentaire vers lequel ils acheminent, comme les connexions ou Notion as Code. Ne vous fiez pas aux APIs SDK mémorisées quand les déclarations ou skills installés peuvent répondre à la question.

Conservez la structure du template et les exemples sauf si l'App de l'utilisateur requiert un changement. Utilisez les commandes check et build documentées du projet après les modifications. Déployez avec ntn apps deploy uniquement quand le déploiement fait partie de la demande de l'utilisateur, et signalez le succès de la construction locale séparément du succès du déploiement.

notion-apps